Skip to content
This repository has been archived by the owner on Sep 19, 2020. It is now read-only.
/ mcsub Public archive

πŸ” McSub (MailChimp Subscription) – An ES6 client side implementation for MailChimp subscribe forms.

Notifications You must be signed in to change notification settings

panoply/mcsub

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

43 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

npm version

πŸ” McSub – Client Side MailChimp Subscriptions

McSub (Mailchimp Subscriptions) is a tiny < 1.4kb (gzipped) vanilla JavaScript ES6 implementation that acts a simple wrapper for client side email subscriptions with Mailchimp. McSub enables an ajax-like integration for email subscriptions using MailChimp and is a drop-in replacement to the jQuery dependant, monolothic embedded form script that MailChimp requires you to include.

View Demo

Feature Requests

McSub is approaching v1.0 with additional features, bug fixes and more. If you have a feature request or something you would like to see in v1 please submit an issue.

Install

yarn add mcsub

HTML

McSub will automatically add a robot input to your form and dynamically modify it to fit the prerequisites MailChimp requires in their embedded forms which this means you will only need the bare minimum boiler HTML subscription form when you're using McSub, example:

    <div id="form-wrapper-id">
       <form action="https://*.list-manage.com/subscribe/post">
          <input type="email" name="EMAIL" placeholder="Email">
          <button type="submit" name="subscribe">
             Submit
          </button>
          <div id="response" style="display:none"></div>
       </form>
    </div>

As you can see, the McSub embedded subscribe form is vastly different to the standard HTML form that Mailchimp requires from you. The McSub approach enables you to customise the style of the form to best fit your integration.

As an added bonus McSub will also re-write your form to the Mailchimp defaults as a fallback.

Please Note:

  • The from action does not require the full list path. End your action list path at /post.
  • Always ensure the https protocol is used in the form action.
  • The response div element should should have style="display:none; attribute.
  • The form does not use <input type="button"> so instead use <button type="submit">.
  • The name of the email input should be capitalized as EMAIL for the API response to work correctly.

Initialise

Simply add McSub to your build import Mcsub from 'mcsub'; and initialise it according to your requirements.

    new Mcsub('#form-wrapper-id', {
	    user:  'abcdefghijklmnopqrstuvwxyz',
	    list:  '123456789',
	    callback:  'cb',
	    reponse:  '#response',
        onInit(){
            console.log(this.element) // Example
        },
        onSubmit(){
            console.log(this.button); // Example
        },
        onSuccess(){
            console.log('Subscribe Sucess'); // Example
        },
        onError(){
            console.log('Subscribe Error'); // Example
        },
        complete(){
            console.log(this.inputs); // Example
        }
    });

Options

element
The element option is a required option that is the selector of the form wrapper. You must always wrap your form within a div.

user
The user option is a required option of the user id for your Mailchimp account. You can obtain your user id in the copy/paste section of the embedded form generators form action in your Mailchimp account.

list
The list option is a required option that is your subscription email list id. The email list id is the list in which your subscriptions will be saved to. You can obtain this id in the copy/paste section of the embedded form generators form action of your Mailchimp account

callback
The callback option allows you to define a custom callback parameter. It defaults to cb but you can change it incase cb is being used by something else.

response
The response option defaults to an element within your <form> with the id of #response. Mailchimp will return responses which show up within this element and depending on the response type, a class of either .error or .success will be added to the element giving you additional styling. For best practice always add a style="display:none;" attribute to the response element. McSub will remove this upon response callback by default.

onInit()
The onInit() callback option function is run on init after the form subit listener is applied.

onSubmit()
The onSubmit() callback option function is run on form submission. Access the Forms elements via this to get things like the form submit button, inputs etc.

onSuccess()
The onSuccess() callback option function is run if subscription was successful.

onError()
The onError() callback option function is run if subscription was unsuccessful and/or encounted an error.

complete()
The complete() callback option function is run after form submission has completed and validation text has been appended within the response element. Access the form via this to get things like the form submit button, inputs etc. The reason complete runs after validation text is appended is because only then are we sure that we have received the response from MailChimp.

Option Functions

The 3 option functions onInit(), onSubmit() and complete() can be used to access elements within the form. Using this within the each function gives to access these additional elements.

Callback Description
this.element Returns the wrapper element (#from-wrapper-id)
this.inputs Returns an array of input fields within the form
this.button Returns the the submit button element
this.response Returns the response div element

Todo

  • Better Documentation
  • Tests

Contributions

Contributions and feedback are welcome.

License

MIT.

About

πŸ” McSub (MailChimp Subscription) – An ES6 client side implementation for MailChimp subscribe forms.

Topics

Resources

Stars

Watchers

Forks