Initial Development

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+build/*
+test/mocha/tests.js

README.md

@@ -1,51 +1,70 @@
-Subscribe Email is a UMD JavaScript module for rendering a mailing list sign up form quickly on a webpage.
+Subscribe Email is a standalone UMD JavaScript module for rendering a mailing list sign up form quickly on a webpage.
 
-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.
+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. It currently supports 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 the Module
+You can get the module in any one of the following ways;
+- Download [the latest release](https://github.com/blocks/subscribe-email/releases) from GitHub
+- Or install with npm; `npm install subscribe-email`
+- Or install with Bower; `bower install subscribe-email`
 
-**If you use bower (recommended):**
-`bower install subscribe-email --save`
+# Quick Start
+To get started, you'll need to include the script on your page, create a `<form>` element, and initialize the module. After you include subscribe-email.js in your project, here's some minimal code you can use to get started quickly;
 
-**If you use npm:**
-`npm install subscribe-email --save`
+```
+<form id="subscribe-form"></form>
+```
 
-**If you're not using a package manager:**
-Just copy and paste the `/dist` directory to wherever you want it in your project.
 
+```
+<script>
+new SubscribeEmail({
+  element: '#subscribe-form',
+  service: 'universe',
+  key: 'your-api-key-here'
+});
+</script>
+```
 
-# Wiring Things Up
-Once you've got the module included in your project, getting started using it is simple.
+At a minimum, you'll need to change the `service` and `key` parameters to match your needs. *(Note: MailChimp uses `url` instead of `key`).*
 
-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>`.
+# Advanced Usage
 
-## Quick Start
+## Options
+The module can be configured with several optional parameters passed to it's constructor. Here is the full list of options:
 
-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`
+**(Required)** A DOM element, jQuery element, or selector string to refer to the placeholder element.
 
-## Advanced Options
+### `prependMessagesTo`
+By default, responses from the different mailing list platforms will be prepended to the SubscribeEmail `element` as a dismissable alert, but you can use this option to override which element the alerts are prepended to. Accepts a query string or a jQuery object.
 
-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
-  });
-```
+### `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. *(This is not required for MailChimp. Instead, you'll have to use `url`).*
+
+### `url`
+**(Required for MailChimp)** A string of the `<form action="">` attribute generated by MailChimp which contains MailChimp authentication information. You can get this from MailChimp under "Signup forms > Embedded form code > Naked" and copying just the value from the `<form action="">` attribute. It should follow this format: `http://{username}.{data center}.list-manage.com/subscribe/post?u={user id}&id={list id}`.
+
+### `submitText`
+A string to be used on the form's submit button (defaults to "Subscribe").
 
-## 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.
+### `template`
+If you want to customize the markup, you can override the default markup by passing in a *compiled* handlebars template using this option. See the default template for a starting point to work from. A custom template will not work without a form tag that contains `id="{{id}}"` and an email input that contains `name="{{emailName}}"`. (Defaults to `false`).
+
+### `namespace`
+Out of the box, the module will generate BEM markup with the namespace `subscribe-email`, but you can use this option to override the default without passing in a custom template.
 
 ## 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;
+You can easily integrate the messages into other parts of your page by listening for the following events to be emitted from the SubscribeEmail instance;
+
+### `subscriptionMessage`
+Fires whenever the mailing list provider returns a response (both success and failure). The message will be passed to this event as a string.
+
+### `subscriptionError`
+This event will fire if the mailing list provider returns an error. Specific details about the error will be passed to the event as a payload object.
 
-`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.
+### `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 passed to the event as a payload object.

gulpfile.js

@@ -0,0 +1,104 @@
+var gulp = require('gulp');
+var runSequence = require('run-sequence');
+var browserify = require('browserify');
+var hbsfy = require('hbsfy');
+var source = require('vinyl-source-stream');
+var derequire = require('gulp-derequire');
+var http = require('http');
+var ecstatic = require('ecstatic');
+var BrowserStackTunnel = require('browserstacktunnel-wrapper');
+var mocha = require('gulp-spawn-mocha');
+
+function handleError(err) {
+  console.log(err.message);
+  this.emit('end');
+}
+
+// Task groups
+gulp.task('default', ['build', 'build-tests', 'start-server']);
+
+gulp.task('test', function(cb) {
+  runSequence(
+    ['build', 'build-tests', 'start-server', 'start-browserstack-tunnel'],
+    'run-selenium',
+    ['stop-test-server', 'stop-browserstack-tunnel'],
+    cb
+  );
+});
+
+gulp.task('manual-test', ['default', 'start-browserstack-tunnel'])
+
+gulp.task('build', function() {
+  var bundler = browserify({
+    entries: ['./src/subscribe-email.js'],
+    standalone: 'SubscribeEmail'
+  });
+  var bundle = function() {
+    return bundler
+      .transform(hbsfy)
+      .bundle()
+      .pipe(source('subscribe-email.js'))
+      .pipe(derequire())
+      .pipe(gulp.dest('./build/'));
+  };
+  return bundle();
+});
+
+gulp.task('build-tests', function() {
+  var bundler = browserify({
+    entries: ['./test/tests.js']
+  });
+  var bundle = function() {
+    return bundler
+      .transform({global: true}, hbsfy)
+      .bundle()
+      .pipe(source('tests.js'))
+      .pipe(derequire())
+      .pipe(gulp.dest('./test/mocha/'));
+  };
+  return bundle();
+});
+
+var devServer;
+gulp.task('start-server', function(cb) {
+  devServer = http.createServer(
+    ecstatic({ root: './' })
+  ).listen(8080);
+  console.log('Listening on :8080');
+  cb();
+});
+
+gulp.task('stop-test-server', function(cb) {
+  devServer.close(cb);
+});
+
+var browserStackTunnel;
+gulp.task('start-browserstack-tunnel', function(cb) {
+  browserStackTunnel = new BrowserStackTunnel({
+    key: '',
+    hosts: [{
+      name: 'localhost',
+      port: 3000,
+      sslFlag: 0
+    }],
+    v: true
+  });
+  browserStackTunnel.start(function(error) {
+    if (error) {
+      console.log(error);
+    } else {
+      console.log('BrowserStack Tunnel Started');
+      cb();
+    }
+  });
+});
+
+gulp.task('stop-browserstack-tunnel', function(cb) {
+  browserStackTunnel.stop(cb);
+});
+
+gulp.task('run-selenium', function () {
+  return gulp.src('test/selenium-driver.js', {read: false})
+    .pipe(mocha({timeout: 55000}))
+    .on('error', handleError);
+});

package.json

@@ -0,0 +1,44 @@
+{
+  "name": "blocks-subscribe",
+  "version": "1.0.0",
+  "description": "Subscribes an email address to a list. Supports a selection of email marketing services.",
+  "keywords": [
+    "email",
+    "subscription"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blocks/subscribe-email.git"
+  },
+  "homepage": "https://github.com/blocks/subscribe-email",
+  "bugs": "https://github.com/blocks/subscribe-email/issues",
+  "license": "MIT",
+  "author": "Josiah Sprague <[email protected]>",
+  "main": "src/subscribe-email.js",
+  "devDependencies": {
+    "browserify": "^5.11.1",
+    "browserstack-webdriver": "^2.41.1",
+    "browserstacktunnel-wrapper": "~1.3.0",
+    "ecstatic": "^0.5.4",
+    "gulp": "^3.8.7",
+    "gulp-derequire": "^1.1.0",
+    "gulp-notify": "^1.5.1",
+    "gulp-spawn-mocha": "^0.4.1",
+    "handlebars": "1.3.x",
+    "hbsfy": "^2.1.0",
+    "istanbul": "^0.3.2",
+    "jquery": "^2.1.1",
+    "mocha": "^1.21.5",
+    "mocha-clean": "^0.3.0",
+    "object-merge": "~2.5.1",
+    "pretty-hrtime": "^0.2.1",
+    "require-dir": "^0.1.0",
+    "run-sequence": "~0.3.7",
+    "vinyl-source-stream": "^0.1.1"
+  },
+  "dependencies": {
+    "blocks-alerter": "^1.0.2",
+    "form-serialize": "^0.3.0",
+    "inherits": "^2.0.1"
+  }
+}