Initial Development

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+build/*
+!build/subscribe-email.js

README.md

@@ -2,50 +2,56 @@ Subscribe Email is a UMD JavaScript module for rendering a mailing list sign up
 
 It allows developers to quickly include an email collection form on a page without being concerned with the implementation details of a specific mailing list platform. We're currently aiming to support mailing lists on SendGrid, MailChimp and Universe.
 
-# Including the Module in Your Project
-You can include the module any way that fits with your workflow;
+# Getting Started
 
-**If you use bower (recommended):**
-`bower install subscribe-email --save`
+## 1) Get the Module
+If you're doing things manually, you can download the ZIP and extract `/build/subscribe-email.js` into your project's scripts folder.
 
-**If you use npm:**
-`npm install subscribe-email --save`
+If you're using a package manager like [npm](https://www.npmjs.org/) or [Bower](http://bower.io/), you can install the module to your `devDependencies`.
 
-**If you're not using a package manager:**
-Just copy and paste the `/dist` directory to wherever you want it in your project.
+## 2) Include the Module in Your Page
+If you're doing things manually, just drop `<script src="subscribe-email.js">` into your page, pointing the `src` attribute to wherever you saved the file.
 
+Alternatively, you can require the module with [Browserify](http://browserify.org/), [RequireJS](http://requirejs.org/) or one of many other JavaScript module loaders.
 
-# Wiring Things Up
-Once you've got the module included in your project, getting started using it is simple.
+## 3) Use the Module
+After you've gotten the module and included it in your page, you can start using it.
 
-1. Include subscribe-email.js in your page. You can use your preferred script loader, concatenate it with the rest of your scripts during your build process, or just drop `<script src="subscribe-email.min.js">` into your page. Just make sure you update the path to point to wherever you've saved or included it.
-2. Create an empty placeholder element for the subscription form on the page; `<div id="subscribe-form"></div>`.
+1) Create an empty `<form>` element wherever you want it on the page. This will serve as a placeholder.
 
-## Quick Start
+`<form id="subscribe-form"></form>`
+
+2) Create a new `SubscribeEmail` instance somewhere in the page's JavaScript. The required parameters are `element`, which is a DOM element, jQuery element, or selector string to refer to the placeholder element, `service` which is the name of mailing list platform you are using, and `key` which is the API key for that service.
 
-Create a new `SubscribeEmail` instance somewhere in the page's JavaScript. The only parameter that's required is the `element`. You can either use the ID of the placeholder HTML element you created or pass in a jQuery object;
 ```
   new SubscribeEmail({
-    element: subscribe-form
+    element: '#subscribe-form',
+    service: 'universe',
+    key: 'your-api-key-here'
   });
 ```
 
-## Advanced Options
+3) Profit?
 
-There are also some advanced configuration options available.
-```
-  new SubscribeEmail({
-    element: subscribe-form, //required
-    template: 'minimal-BEM', //defaults to 'minimal-BEM'
-    async: true //defaults to false
-  });
-```
+# Advanced Usage
+
+## Options
+The module can be configured with several optional parameters passed to it's constructor. Here is the full list of options:
+
+- `element`: **(Required)** A DOM element, jQuery element, or selector string to refer to the placeholder element.
+- `service`: **(Required)** The mailing list platform you are using. Available options are `mailchimp`, `sendgrid` and `universe`.
+- `key`: **(Required)** A string of the API key for your mailing list platform.
+- `submitText`: A string to be used on the form's submit button. Defaults to "Subscribe".
+- `overrideTemplate`: Set this to true to override the markup that is automatically generated by the plugin. See "Customizing the Template" below (defaults to `false`).
+- `responseElement`: A selector string for the element you want to display response (validation, errors, confirmation) messages from your platform's API (defaults to `'.subscribe-email__response'`).
+- `async`: Whether the form with be submitted asynchronously (defaults to `true`).
 
 ## Customizing the Template
-The Subscribe Email module comes with some compiled Handlebars templates that you can choose from. If you want to create custom HTML template(s), you can add a Handlebars template to `/src/templates` and run `gulp build` from the project directory to build the module from source and compile the template.
+Out of the box, the Subscribe Email module will generate BEM markup with the namespace `subscribe-email` that contains all of the elements your form needs. If you want to customize the markup, set `overrideTemplate: true` when you initialize the module to use the markup from the target element instead. This gives you full control over the markup, but you'll have to make sure that your form contains all of the required fields.
 
 ## Events
-Some mailing list platforms may send response messages for things like confirmation or validation errors. The default template will display these messages along-side the form, but alternatively you can easily integrate the messages into other parts of your page by listening for the following events to fire;
+Some mailing list platforms may send response messages for things like confirmation or validation errors. The default template will display these messages along-side the form, but alternatively you can easily integrate the messages into other parts of your page by listening for the following events to fire on the form element;
 
-`subscriptionError`: This event will fire if the mailing list provider returns an error and fails to add the email address to the list. Specific details about the error will be included in a payload object when available.
-`subscriptionSuccess`: This event will fire if the mailing list provider returns a confirmation that the email address has been added to the list. Specific details will be included in a payload object when available.
+- `subscriptionMessage`: Fires whenever the mailing list provider returns a response (both success and failure).
+- `subscriptionError`: This event will fire if the mailing list provider returns an error. Specific details about the error will be included in a payload object when available.
+- `subscriptionSuccess`: This event will fire if the mailing list provider returns a confirmation that the email address has been added to the list. Specific details will be included in a payload object when available.