The `newsletter` packages

I’m currently working on the Chakra UI Theme (), which has support for a newletter subscription. I believe it’s a common pattern in most websites & blog to include a newsletter form.

I’d like to propose that we add support for newsletter package within frontity. Perhaps this can be a separate library that users can install and configure.

Here’s what I have in mind:

Draft package name: frontity-plugin-newsletter

Draft API Spec

import { init } from "frontity-plugin-newsletter"

// initialize & configure
const mailchimp = init({ client: "mailchimp", apiKey: ""})

// keep track of subscription status 
state: {
  theme: {
   subscribeStatus: null, // "pending" | "complete" | "failed" | null 
 }
},

// The `mailchimp` has access to methods specific to mailchimp's API 
actions: {
  theme: {
     subscribe: ({state, actions}) => {
       state.subscribeStatus = "pending"
       mailchimp.addToList("subscribers").then(() => {
         state.subscribeStatus = "complete"
      })
     }
} 
}

Let me know what you guys think about this. Feel free to suggestion possible solutions if you think it can be better.

This is a nice idea, thanks @Segun!

Maybe, instead of doing it “the npm way”, we can do it “the frontity way” and create a new newsletter namespace.

The main difference is:

  • With “the npm way”, users of the theme need to change the code.
  • With “the frontity way”, users of the theme just need to install and configure a package.

That may not seem like a great difference now, but we are already thinking about the moment when Frontity users can install and configure packages from an Admin UI. Once that moment comes, we want them to be able to install the theme they want, then search for a “newsletter” package for their platform, for example MailChimp, install it, add the apiKey to the configuration and they are good to go. Just like they are used to do it today in the WordPress dashboard.

User Stories

As a Frontity theme user
I want to integrate any newsletter platform with a theme using Frontity packages
so that I don’t have to write the integration myself

Posible solution

These are some ways it could be built. Feel free to add your feedback.

Newsletter packages can use theme slots

This is similar to what ads packages do. The theme exposes “slots” and the package “fills” one of the slots.

// Theme.
const Footer = () => {
  return (
    <>
      <Slot id="above-the-footer" />
      { /* more stuff */ }
    </>
  );
};

The slot id could be configurable via settings:

state: {
  newsletter: {
    slot: "above-the-footer"
  }
}
// Newsletter package.
const NewsletterFill = ({ state }) => {
  return (
    <Fill id={state.newsletter.slot}>
      <Newsletter />
    <Fill />
  );
};

Newsletter packages can expose their own component

This is similar to what comments packages do.

// Theme
const Footer = ({ libraries }) => {
  const Newsletter = libraries.newsletter.Newsletter || null;
  return (
    <>
      <Newsletter />
      { /* more stuff */ }
    </>
  );
};

Newsletter packages can expose actions

This is in case the theme developer want to control the style of the form:

// Theme.
const Newsletter = ({ actions }) => {
  return (
    <form onSubmit={actions.newsletter.subscribe} >
      <Input name="name" />
      <Input name="email" />
      <SendButton />
    <form />
  );
};

const Footer = ({ actions }) => {
  return (
    <>
      { /* Check if there is a newsletter package */ }
      {actions.newsletter && <Newsletter />}   
    </>
  );
};

Type of newsletter namespace

This is only a suggestion of how the types could look like.

interface Subscribe {
  name?: string;
  email: string;
}

interface Newsletter {
  state: {
    newsletter: {
      isSubscribing: false;
    }
  };
  actions: {
    newsletter: {
       subscribe: AsyncAction<Newsletter, Subscribe>;
    }
  };
  libraries: {
    newsletter: {
      Newsletter: React.ReactType;
    }
  }
}

Type of a MailChimp newsletter package

Again, this is only a suggestion.

interface MailChimp extends Newsletter {
  state: Newsletter["state"] & {
    newsletter: {
      apiKey: string;
      listId: string;
    }
  }
}

Then, the actions.newsletter.subscribe method can add those fields before sending the request to the MailChimp server.


Feel free to add your opinion.

cc: @orballo, you’ve worked with a newsletter. Would something like this make sense for you?

2 Likes

I haven’t worked with a newsletter before that I remember. In my current project I opted for keeping the same call the original WP theme was doing because it seemed quite simple that way.

So I’m afraid I have nothing to contribute to this conversation :blush:

What I meant was: you are creating a theme that has a newsletter widget. What do you think about the methods explained here? Do they make sense to you for your theme?

Well, the workflow makes sense. Having a subscribe action and a current status seems useful (though I think it should cover three states: before subscribing, subscribing and subscribed). Maybe it should implement some kind of validation/sanitation of the fields.

Though using it with services as mailchimp I don’t know if it’s useful, because I don’t know if they need private keys to subscribe or can indeed be used on the client side.

Thanks @orballo.

Yes, they usually have a tool to export HTML forms you can copy and paste on your site, so they should work without problems.

Please tell me if there is any progress on this topic?
Do we have the package?

I need to implement one on my website https://componentity.com

We haven’t done an Implementation Proposal for this namespace yet.

What service do you want to integrate?

Subscription to newsletter! Just like frontity’s, where people come and submit there email and you send them weekly updates!

Sorry, I meant which newsletter service, like Mailchimp or GetResponse.

mailchimp