Newsletter signup integration

[vgoel]

Thanks for the good work on the starter. I am using it and it "just works". Do you know if it is possible to integrate an email newsletter signup using something like Formspree?

[styxlab]

Thanks for the positive feedback :smile:

A newsletter signup is definitely on my feature list. As this is also a "good first issue" for first time contributors, I will write down some instructions on how such a feature should be implemented in order to fit into this project. Maybe you hear the call :wink:?

[vgoel]

A newsletter signup is definitely on my feature list. As this is also a "good first issue" for first time contributors, I will write down some instructions on how such a feature should be implemented in order to fit into this project. Maybe you hear the call wink?

I can have a crack at it. I am a JS and Gatsby novice but am willing to give it a shot if you put together some initial instruction.

[styxlab]

That's great! I'll put some thorough instructions together later today.

In the meantime, have a look at package gatsby-theme-ghost-contact which contains all the elements needed for a newsletter signup.

I suggest you start by installing gatsby-theme-ghost-contact on your blog (instructions are in the README) and once you got the contact page up and running, you'll have a look at the code.

[vgoel]

Will do. Funnily enough , I was just looking at that plugin a few mins ago. It makes sense that the elements would overlap

[styxlab]

Newsletter Feature

Here are some instructions on how to start developing this feature.

Frontend

1. A subscribe button should be added to the top right nav bar as seen on the Ghost Demo.
2. If the subscribe button is clicked, a new modal page opens where users can enter their email address (same as on Ghost Demo page).

Backend

1. Upon submit a verification email is sent back to the user.
2. After user has visited the confirmation link, you get an subscribe email for that user.
3. An unsubscribe link should be automatically generated, which needs to be placed in every newsletter.

Guide for Development

General

1. Fork repo https://github.com/styxlab/gatsby-theme-try-ghost.git

   • clone your fork locally
   • cd into the cloned directory

2. Create a new package as follows (use gatsby-theme-ghost-contact as a template)

   • cp packages/gatsby-theme-ghost-contact packages/gatsby-theme-ghost-newsletter
   • Rename "ghost-contact" into "ghost-newsletter" in README, package.json and other files
   • change version in package.json to 1.0.0

Frontend

1. Add Button to top right navbar: Look at package dark-mode and inspect how this package adds the sun/moon icon to the top right navbar. Use the same for "Subscribe button".

2. Design the modal page. I have not done that with Gastby so far (so you need to figure it out yourself). A starting point might be:

   • https://markoskon.com/modals-in-gatsby/
   • The markup for that page should look similar to subscribe-form.hbs
   • This needs to be changed into a component similar to (https://github.com/styxlab/gatsby-theme-try-ghost/blob/master/packages/gatsby-theme-ghost-contact/src/components/common/ContactForm.js - should look a lot simpler as the form is simpler)
   • This markup wil be styled correctly as the global css already includes code for that!

Note: Difficult part may be the modal window. An alternative could be to make a separate page, but the modal should be preferrable.

Backend

A first implementation should integrate with the external service MailChimp (as it seems to be the most commonly used option). This integration needs to be explored, maybe this is a good starting point:

email-signup-forms-with-gatsby-and-mailchimp

1. The component should be designed similar to ContactForm which contains the code that sends a post request to the backend (here mailchimp).

2. Mailchimp should do the backend work for you, but it should also be possible to connect to different service. Therefore, make the endpoint and encodings configurable. Look at the ghost-contact plugin to see how this is achieved.

3. In addition to Mailchimp, it should be possible to run your own server with Node.js and Express. Read the micro-service part of this tutorial to see an implementation for a contact form.

However, the microserver should be extended to handle: Sending Verification emails, generate Subscribe/unsubscribe tokens and links, only sends you an email after verification.

Merging

1. When everything is working: Make sure no code except in packages/gatsby-theme-ghost-newsletter has been changed, so this can be published as an addon-package.

2. Also make sure, everything is working, if the package is not installed.

3. Issue a PR from your fork to the main repo: I will then review and merge into the main branch.

As always

Make sure you break development into parts. I'm happy to look at finished parts, so they are complete before moving on. Don't hesitate to contact me, whenever you get stuck or just want to discuss details or strategy.

While putting these instructions together, I realize that this feature has some elements that go beyond the ghost-contact from package.

Happy coding :keyboard: :wink:

[vgoel]

Looks good.

One thing I didnt see in the description above is a subscribe "Widget" (sorry, I am coming from the WP world and not sure how Ghost terms these elements") which are at the bottom of a post: (examples: https://demo.ghost.io/welcome/ https://demo.ghost.io/the-editor/)

I am guessing thats put into the Casper theme maybe through code injection? (the class is "subscribe-form" and I didnt see that in any of the available Integrations).

When you click the "Subscribe" button at the top right in the navbar, in the Overlay, it also initiates the "subscribe-form" class.

Any ideas on how the "widget" below the post should be handled?

[styxlab]

Yes, it's the same form which is sourced in from post.hbs:

// post.hbs
...
{{!-- Email subscribe form at the bottom of the page --}}
{{#if @labs.members}}
   {{> subscribe-form}}
{{/if}}
...

You can do the same here. I will provide you with the anchors from the base theme for this integration and the one for the button later.

[styxlab]

This feature is under active development. Note that the above implementation guide is out of date and that we have come up with a much easier approach.

[styxlab]

First implementation finished and published. Further improvements will follow.