Initial Development

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+build

README.md

@@ -2,50 +2,50 @@ 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 the contents of the `/dist` directory into your project's assets 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.min.js">` into your page, and make sure you update the `src` attribute to point to wherever you saved the module.
 
+Alternatively, you can bundle the module along with the rest of your projects assets using a tool like [Browserify](http://browserify.org/), [Grunt](http://gruntjs.com/), [Gulp](http://gulpjs.com/), etc.
 
-# 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 placeholder element where you want to include the form on the page. You can use any block-level HTML element, given that it has a unique way to select it;
 
-## Quick Start
+`<div id="subscribe-form"></div>`
 
-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;
+2) Create a new `SubscribeEmail` instance somewhere in the page's JavaScript. The only parameters that are required are `element`, which is a DOM element, jQuery element, or selector string to refer to the placeholder element and `service` which is the name of mailing list platform you are using.
 ```
   new SubscribeEmail({
-    element: subscribe-form
+    element: '#subscribe-form',
+    service: 'mailchimp'
   });
 ```
 
-## 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`.
+- `template`: A string of the name of the compiled handlebars template to use to render the form. Available templates are `'BEM-with-messaging'` or `'BEM-minimal'` (default). See "Customizing the Templates" below for more information.
+- `async`: Whether the form with be submitted asynchronously (defaults to false).
 
 ## 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.
+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 module's root directory to build the module from source and compile the template (note: this may require running `npm install` first to install subscribe-email's devDependencies).
 
 ## 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;
 
-`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.
+- `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.

demo/index.html

@@ -0,0 +1,35 @@
+<html>
+  <head>
+    <title>Subscribe Email Demo</title>
+    <script src="../build/subscribe-email.js"></script>
+  </head>
+  <body>
+    <p>Here's a MailChimp subscribe form!</p>
+    <div id="subscribe-form1">1</div>
+    <p>Here's a SendGrid subscribe form!</p>
+    <div id="subscribe-form2">2</div>
+    <p>Here's a Universe subscribe form!</p>
+    <div id="subscribe-form3">3</div>
+    <script>
+      new SubscribeEmail({
+        element: '#subscribe-form1',
+        submitText: 'Sign Up',
+        service: 'mailchimp'
+      });
+    </script>
+    <script>
+      new SubscribeEmail({
+        element: '#subscribe-form2',
+        submitText: 'Subscribe',
+        service: 'sendgrid'
+      });
+    </script>
+    <script>
+      new SubscribeEmail({
+        element: '#subscribe-form3',
+        submitText: 'Send',
+        service: 'universe'
+      });
+    </script>
+  </body>
+</html>

gulp/browserify.js

@@ -0,0 +1,38 @@
+var browserify   = require('browserify');
+var bundleLogger = require('./util/bundleLogger');
+var gulp         = require('gulp');
+var handleErrors = require('./util/handleErrors');
+var source       = require('vinyl-source-stream');
+
+gulp.task('browserify', function() {
+  var bundler = browserify({
+    // Required watchify args
+    cache: {}, packageCache: {}, fullPaths: true,
+    // Specify the entry point of your app
+    entries: ['./src/subscribe-email.js'],
+    // Add file extentions to make optional in your requires
+    extensions: ['.hbs'],
+    // Enable source maps!
+    debug: true
+  });
+
+  var bundle = function() {
+    // Log when bundling starts
+    bundleLogger.start();
+
+    return bundler
+      .bundle()
+      // Report compile errors
+      .on('error', handleErrors)
+      // Use vinyl-source-stream to make the
+      // stream gulp compatible. Specifiy the
+      // desired output filename here.
+      .pipe(source('subscribe-email.js'))
+      // Specify the output destination
+      .pipe(gulp.dest('./build/'))
+      // Log when bundling completes!
+      .on('end', bundleLogger.end);
+  };
+
+  return bundle();
+});

gulp/util/bundleLogger.js

@@ -0,0 +1,21 @@
+/* bundleLogger
+   ------------
+   Provides gulp style logs to the bundle method in browserify.js
+*/
+
+var gutil        = require('gulp-util');
+var prettyHrtime = require('pretty-hrtime');
+var startTime;
+
+module.exports = {
+  start: function() {
+    startTime = process.hrtime();
+    gutil.log('Running', gutil.colors.green("'bundle'") + '...');
+  },
+
+  end: function() {
+    var taskTime = process.hrtime(startTime);
+    var prettyTime = prettyHrtime(taskTime);
+    gutil.log('Finished', gutil.colors.green("'bundle'"), 'in', gutil.colors.magenta(prettyTime));
+  }
+};

gulp/util/handleErrors.js

@@ -0,0 +1,15 @@
+var notify = require("gulp-notify");
+
+module.exports = function() {
+
+  var args = Array.prototype.slice.call(arguments);
+
+  // Send error to notification center with gulp-notify
+  notify.onError({
+    title: "Compile Error",
+    message: "<%= error.message %>"
+  }).apply(this, args);
+
+  // Keep gulp from hanging on this task
+  this.emit('end');
+};

gulpfile.js

@@ -0,0 +1,19 @@
+/*
+  gulpfile.js
+  ===========
+  Rather than manage one giant configuration file responsible
+  for creating multiple tasks, each task has been broken out into
+  its own file in `/gulp`. Any file in that folder gets automatically
+  required below.
+
+  To add a new task, simply add a new task file to the `/gulp` directory.
+*/
+var gulp = require('gulp');
+var requireDir = require('require-dir');
+
+// Require all tasks in gulp/tasks, including subfolders
+requireDir('./gulp', { recurse: true });
+
+// Task groups
+gulp.task('default', ['build']);
+gulp.task('build', ['browserify']);

package.json

@@ -0,0 +1,22 @@
+{
+  "name": "subscribe-email",
+  "version": "0.0.0",
+  "private": true,
+  "main": "subscribe-email.js",
+  "browserify": {
+    "transform": [
+      "hbsfy"
+    ]
+  },
+  "devDependencies": {
+    "browserify": "^5.11.1",
+    "gulp": "^3.8.7",
+    "gulp-notify": "^1.5.1",
+    "gulp-util": "^3.0.1",
+    "handlebars": "1.3.x",
+    "hbsfy": "^2.1.0",
+    "pretty-hrtime": "^0.2.1",
+    "require-dir": "^0.1.0",
+    "vinyl-source-stream": "^0.1.1"
+  }
+}

src/subscribe-email.js

@@ -0,0 +1,45 @@
+// This JavaScript module is exported as UMD following the pattern which can be
+// found here: https://github.com/umdjs/umd/blob/master/returnExports.js
+
+(function (root, factory) {
+  if (typeof define === 'function' && define.amd) {
+    define(['handlebars'], factory);
+  } else if (typeof exports === 'object') {
+    module.exports = factory(require('./templates/BEM-with-messaging.hbs'));
+  } else {
+    root.SubscribeEmail = factory(root.handlebars);
+  }
+}(this, function (template) {
+
+  this.SubscribeEmail = function(options){
+    var placeholder = document.querySelector(options.element);
+    var serviceConfig = {};
+    switch (options.service) {
+      case 'mailchimp':
+        serviceConfig = {
+          formAction: 'http://mailchimp-api.com/route',
+          formMethod: 'POST',
+          emailName: 'EMAIL'
+        };
+        break;
+      case 'sendgrid':
+        serviceConfig = {
+          formAction: 'http://sendgrid-api.com/route',
+          formMethod: 'POST'
+        };
+        break;
+      default:
+        serviceConfig = {
+          formAction: '',
+          formMethod: ''
+        };
+        break;
+    }
+    //Merge the serviceConfig object into the template options
+    for (var attrname in serviceConfig) { options[attrname] = serviceConfig[attrname]; }
+
+    placeholder.innerHTML = template(options);
+  };
+
+  return this.SubscribeEmail;
+}));

src/templates/BEM-with-messaging.hbs

@@ -0,0 +1,4 @@
+<form action="{{formAction}}" method="{{formMethod}}">
+  <input type="email" value="" name="{{emailName}}">
+  <input type="submit" value="{{submitText}}" name="{{submitName}}">
+</form>