RubyGems - draiodoir - Versions diffs - 0.0.1 - Mend

draiodoir 0.0.1

Files changed (11) hide show

data/README.md ADDED

@@ -0,0 +1,74 @@
+Draíodóir
+=========
+A javascript that turns web-pages into Wizards.
+Usage
+-----
+  - Include (in a `<script>` tag) on your *HTML5* page
+  - Make the form a Wizard, with `new Wizard("my_form");`
+Example
+-------
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <meta content-type='UTF-8'>
+        <script type='text/javascript' src='wizard.js'></src>
+        <script>
+          addEventListener('load', function(e) {
+            new Wizard('my_form');
+          }, false);
+        </script>
+        <title>Draíodóir Test</title>
+      </head>
+      <body>
+        <form id='my_form' action='javascript:alert("Submitting form");'>
+          <fieldset>
+            <label for='name'>Name</label>
+            <input id='name' type='text' required>
+          </fieldset>
+          <fieldset>
+            <label for='age'>Age</label>
+            <input id='age' type='number' minimum='18' maximum='80' required>
+          </fieldset>
+          <input type='submit' value='Go'>
+        </form>
+      </body>
+    </html>
+Caveats
+-------
+*Draíodóir* relies on [validation][validation] being fully implemented by
+the browser. This is almost never the case (as of this writing), so you'll
+probably need to include another library which performs validation properly,
+such as [Bailitheoir][bailitheoir].
+The library is targeted, therefore, at the [more][firefox] [modern][chrome]
+[browsers][safari], so don't expect it to work out of the box in [those][ie]
+that are, err, less [standards][w3c] compliant.
+Author(s)
+---------
+  - JJ Buckley <jj@bjjb.org>
+Copyright
+---------
+This software is released under the [GPL][gpl], so feel free to steal and
+destroy - just comply with the terms of that license. I accept no
+responsibilty for anything.
+[validation]: http://www.w3.org/TR/html5/association-of-controls-and-forms.html#constraints
+[bailitheoir]: http://jjbuckley.github.com/bailitheoir
+[firefox]: http://www.mozilla.com/firefox
+[chrome]: http://www.google.com/chrome
+[safari]: http://www.apple.com/safari
+[ie]: http://www.microsoft.com/ie
+[w3c]: http://www.w3.org
+[gpl]: http://www.gnu.org/licenses/gpl.html

data/Rakefile ADDED

	@@ -0,0 +1,2 @@
1	+ require 'bundler'
2	+ Bundler::GemHelper.install_tasks

data/draiodoir.gemspec ADDED

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "draiodoir/version"
+Gem::Specification.new do |s|
+  s.name        = "draiodoir"
+  s.version     = Draiodoir::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["JJ Buckley"]
+  s.email       = ["jj@bjjb.org"]
+  s.homepage    = "http://jjbuckley.github.com/draiodoir"
+  s.summary     = %q{A JavaScript multi-step form helper}
+  s.description = %q{Draíodóir lets you take a regular HTML5 page, and turn it
+    into a multi-step wizard.}
+  s.rubyforge_project = "draiodoir"
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/example/account_wizard.css ADDED

@@ -0,0 +1,78 @@
+/**
+ * Example account signup form.
+ */
+body {
+  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+  min-width: 620px;
+}
+form {
+  display: block;
+  width: 500px;
+  padding: 50px;
+  margin: auto;
+  background-color: #ccddaa;
+  background-image: -webkit-gradient(linear, 0% 0%, 0% 100%, from(rgba(255,255,235,0.9)), to(rgba(20,20,20,0.0)));
+  background-image: -moz-linear-gradient(90deg, rgba(255,255,235,0.9), rgba(20,20,0,0.0));
+  border: 5px solid #889966;
+  -webkit-border-radius: 10px;
+  -moz-border-radius: 10px;
+  -o-border-radius: 1em;
+  border-radius: 10px;
+  -webkit-box-shadow: 0 0 5px #112200;
+  -moz-box-shadow: 0 0 0.5em #112200;
+  -o-box-shadow: 0 0 5px #112200;
+  box-shadow: 0 0 5px #112200;
+}
+label {
+  float: left;
+  height: 2em;
+  line-height: 2em;
+  width: 150px;
+  text-align: right;
+}
+input,select {
+  margin-left: 170px;
+  display: block;
+  clear: right;
+  padding: 5px;
+  font-weight: bold;
+}
+input:invalid,select:invalid {
+  color: red;
+  -webkit-box-shadow: inset 1px 1px 7px red;
+  -moz-box-shadow: inset 0 0 7px red;
+  box-shadow: inset 0 0 7px red;
+}
+fieldset {
+  border: none;
+  margin: 0;
+  padding: 0;
+  position: relative;
+  display: block;
+}
+fieldset[hidden] {
+  display: none;
+}
+legend {
+  display: block;
+  padding: 5px;
+  border: 5px solid #889966;
+  border: 5px solid #889966;
+  -webkit-border-radius: 10px;
+  -moz-border-radius: 10px;
+  -o-border-radius: 1em;
+  border-radius: 10px;
+  position: absolute;
+  font-size: 30px;
+  font-weight: bold;
+  color: #334400;
+  text-shadow: 0px 0px 4px #999999;
+  top: -77px;
+  background-color: #ccddaa;
+}

data/example/account_wizard.html ADDED

@@ -0,0 +1,76 @@
+<html>
+  <head>
+    <title>New Account</title>
+    <script type="text/javascript" src="validator.js"></script>
+    <script type="text/javascript" src="../draiodoir.js"></script>
+    <script type="text/javascript">
+      addEventListener('load', function(event) {
+        var form = document.getElementById('new_account');
+        new Validator(form);
+        new Wizard(form, {
+          labels: {
+            next: {
+              personal: "That's me...",
+              tastes: "That all I'm telling you."
+            }
+          }
+        });
+      }, false);
+    </script>
+    <link rel="stylesheet" type="text/css" href="account_wizard.css">
+  </head>
+  <body>
+    <h1>New Account</h1>
+    <form id="new_account" name="account" method="POST"
+          action="javascript:alert('Submitting form!');"
+          enctype="application/x-www-form-urlencoded">
+      <!-- The fields here are required, so the submit button does nothing
+            (except retrigger validation) until validation passes. -->
+      <fieldset name="personal">
+        <legend>Personal Details</legend>
+        <label for="account_name">Name</label>
+        <input type="text" id="account_name" name="account[name]"
+                placeholder="Your full name" required="required" />
+        <br />
+        <label for="account_dob">Date of Birth</label>
+        <input type="date" id="account_dob" name="account[dob]"
+                placeholder="YYYY-mm-dd" required="required"
+                min="1900-01-01" max="1990-12-12" />
+      </fieldset>
+      <!-- Everything in this fieldset is optional. It will be shown, but the
+            submit button should be enabled already. -->
+      <fieldset name="tastes">
+        <legend>Some additional info</legend>
+        <label for="account_favourite_film">Your favourite film</label>
+        <select id="account_favourite_film" name="account[favourite_film]">
+          <option value="">Pick one...</option>
+          <option value="1">Fight Club</option>
+          <option value="2">True Romance</option>
+        </select>
+        <label for="account_favourite_music">Your favourite music</label>
+        <select id="account_favourite_music" name="account[favourite_music]">
+          <option value="">Select from...</option>
+          <option value="1">Skip James</option>
+          <option value="2">Pond</option>
+          <option value="3">Antonio Vivaldi</option>
+        </select>
+      </fieldset>
+      <!-- This is the last step, so it should trigger the submit! -->
+      <fieldset name='plan'>
+        <legend>Select your plan</legend>
+        <select id="account_plan" name="account[plan]" required='required'>
+          <option value="">Please Choose...</option>
+          <option value="1">Bronze</option>
+          <option value="2">Silver</option>
+          <option value="3">Gold</option>
+        </select>
+      </fieldset>
+      <input type='submit' value="Continue" />
+    </form>
+  </body>
+</html>

data/example/validator.js ADDED

@@ -0,0 +1,92 @@
+/**
+ * A basic implementation of the W3's HTML5 constraints.
+ * (http://www.w3.org/TR/html5/association-of-controls-and-forms.html#constraints)
+ *
+ * Usage
+ * -----
+ *
+ *   new Validator(form);
+ *   form.addEventListener('invalid', function() {
+ *     alert("Detected an invalid field!");
+ *   }, false);
+ *
+ * Copyright
+ * ---------
+ *
+ * Copyright (c) 2010 JJ Buckley (jj@bjjb.org)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+function Validator(form) {
+  var fields = [];
+  function Validator(field) {
+    function Validity() {
+      this.valueMissing = false;
+      this.typeMismatch = false;
+      this.patternMismatch = false;
+      this.tooLong = false;
+      this.rangeUnderflow = false;
+      this.rangeOverflow = false;
+      this.stepMismatch = false;
+      this.customError = false;
+      this.valid = true;
+    };
+    field.willValidate = !!(~['INPUT', 'SELECT', 'TEXTAREA'].indexOf(field.tagName));
+    field.setCustomValidity = function(message) {
+      if (message == "") {
+        field.validity.customError = false;
+      }
+      else {
+        field.validity.customError = true;
+        field.validationMessage = message;
+      }
+    };
+    field.checkValidity = function() {
+      if (this.willValidate) {
+        this.validity.valueMissing = (this.hasAttribute('required') && this.value.trim() == "");
+        this.validity.typeMismatch = ((this.type == 'email' && this.value && !this.value.match(/.+@.+\..+/)) ||
+          (this.type == 'number' && this.value && !this.value.match(/^\d+/)) ||
+          (this.type == 'date' && false && this.value && !this.value.match(/\d{4}-\d{2}-\d{2}/)) ||
+          (this.type == 'url' && this.value && !this.value.match(/.+\..+/)));
+        this.validity.tooLong = (this.hasAttribute('maxlength') && this.value > this.getAttribute('maxlength'));
+        this.validity.rangeUnderflow = (this.hasAttribute('min') && this.value < this.getAttribute('min'));
+        this.validity.rangeOverflow = (this.type == 'number' && this.hasAttribute('max') && this.value < this.getAttribute('max'));
+        this.validity.stepMismatch = false; // TODO
+        this.valid = !(this.validity.valueMissing ||
+            this.validity.typeMismatch ||
+            this.validity.tooLong ||
+            this.validity.rangeUnderflow ||
+            this.validity.rangeOverflow ||
+            this.validity.stepMismatch ||
+            this.validity.customError);
+        if (!this.valid) {
+          var event = document.createEvent('Events');
+          event.initEvent('invalid', true, true);
+          field.dispatchEvent(event);
+          return false;
+        }
+      }
+      return true;
+    };
+    field.validity = new Validity();
+    console.debug("Added a validator (%o) on %o", this, field);
+  }
+  ['input', 'select', 'textarea'].forEach(function(tag) {
+    var elements = form.getElementsByTagName(tag);
+    for (var i = 0; i < elements.length; i++) {
+      new Validator(elements[i]);
+    }
+  });
+}

data/lib/draiodoir.rb ADDED

	@@ -0,0 +1,2 @@
1	+ module Draiodoir
2	+ end

data/lib/draiodoir/version.rb ADDED

@@ -0,0 +1,3 @@
+module Draiodoir
+  VERSION = "0.0.1"
+end

data/src/wizard.js ADDED

@@ -0,0 +1,252 @@
+/**
+ * Draíodóir
+ * =========
+ *
+ * Turns a HTML5 <form> into a wizard.
+ *
+ * The form *must* be marked up in a particular way, but it's pretty standard
+ * HTML. Basically, each fieldset is a step in the form, and (by default) the
+ * submit button is used as the control for moving forward. If the elements in
+ * a fieldset don't validate (either on a modern browser, or using a compatible
+ * JavaScript validation library, such as
+ * bailitheoir(http://jjbuckley.github.com/bailitheoir), then the Wizard won't
+ * allow you to progress.
+ *
+ * To hide all steps except the current, *Draíodóir* sets the "hidden"
+ * attribute on the fieldset. Since most browsers can't handle this properly
+ * yet, you need to either add a CSS rule such as
+ *
+ *   fieldset[hidden] { display: none; }
+ *
+ * or listen for the `wizard:step:show` and `wizard:step:hide` events, and
+ * take appropriate action, such as setting a style attribute, on the event's
+ * target.
+ *
+ * Usage
+ * -----
+ *
+ *   form = document.getElementById('my_form');
+ *   new Wizard(form);
+ *
+ * A new Wizard immediately hides all steps except the first one.
+ *
+ * You can pass in an options object as a second argumens (all optional):
+ *
+ * Options
+ * -------
+ *
+ * next:: Identifies the control used to move forwards in the form. The
+ *        default is the first "submit".
+ * previous:: Identifies the control to be used to move backwards in the form.
+ *            If a suitable element can't be found, it is created (as a
+ *            <button>), and given the value "Back" (though you can override
+ *            this with a label for any or all steps). An auto-generated
+ *            previous control is inserted immediately before the "next"
+ *            control.
+ * labels:: Used to display text (or HTML) in certain elements at various
+ *          steps. Valid values are "next" and "previous", which indicate the
+ *          next and previous controls. Each value can either be a string
+ *          (which is applied to the control for every step), or an object
+ *          containing keys for the step names. For example:
+ *
+ *            new Wizard(form, {
+ *              previous: 'back_button',
+ *              labels: {
+ *                next: {
+ *                  step1: "To Step 2", step2: "Step 3, please", step3: "Go!",
+ *                },
+ *                previous: "Back"
+ *              }
+ *            });
+ *
+ *          The wizard has 3 steps, fieldsets with names "step1", "step2" and
+ *          step3.  On step1, the next button says "To Step 2", and on step2,
+ *          it says "Step 3, please". On the last step, it says "Go!". If this
+ *          were left blank, it would revert to the original value of the
+ *          submit field.
+ *          On all steps (besides the first), the 'previous' control says
+ *          "Back". It's hidden and disabled on the first step.
+ *
+ * Hook into the wizard by listening for the events it generates, or by using
+ * its "next()", "previous()", "first()" and "last()" methods.
+ *
+ * Caveats
+ * -------
+ *
+ * *Draíodóir* has been tested on Google Chrome 6.0.472.63, Mozilla Firefox
+ * 3.6.10, and Sarari on iPhone OS v4.1. I hardly expect it to work in any
+ * current version of Microsoft Explorer, but that will hopefully change.
+ * For more information, see the *Draíodóir* homepage at
+ * http://jjbuckley.github.com/draiodoir. And feel free to fork the project,
+ * and improve it!
+ *
+ * Events
+ * ------
+ *
+ * These Events are fired by a Wizard:
+ *
+ * wizard:load::  the wizard is set up
+ * wizard:next::  the next step is being shown
+ * wizard:previous::  the previous step is being shown
+ * wizard:first:: the first step is being shown
+ * wizard:last::  the last step is being shown
+ * wizard:invalid:: validation failed on the current step
+ * wizard:valid::  validation passed on all steps
+ * wizard:submit::  the form is being submitted
+ * wizard:step:show:: a step is being shown
+ * wizard:step:hide:: a step is being hidden
+ *
+ * Copyright
+ * ---------
+ *
+ * Copyright (c) 2010 JJ Buckley (jj@bjjb.org)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+function Wizard(form, options) {
+  if (typeof(form) == "string") {
+    form = document.getElementById(form);
+  }
+  var self = this;
+  form.addEventListener('submit', function(event) {
+    if (!self.submit()) {
+      event.preventDefault();
+      return false;
+    }
+  }, false);
+  form.addEventListener('wizard:step:hide', function(event) {
+    // A step has been hidden.
+  }, false);
+  form.addEventListener('wizard:step:show', function(event) {
+    for (var i = 0; i < steps.length; i++) {
+      if (i !== index) {
+        steps[i].hide();
+      }
+    }
+  }, false);
+  function getSubmit() {
+    elements = form.getElementsByTagName('input');
+    for (var i = 0; i < elements.length; i++) {
+      if (elements[i].type == 'submit') {
+        return elements[i];
+      }
+    }
+  }
+  function Step(fieldset, options) {
+    this.name = fieldset.getAttribute('name');
+    this.toString = function() {
+      return "Step:" + this.name;
+    };
+    var fields = [];
+    ['input', 'select', 'textarea'].forEach(function(tag) {
+      elements = fieldset.getElementsByTagName(tag);
+      for (var i = 0; i < elements.length; i++) {
+        elements[i].addEventListener('invalid', function(event) {
+          console.debug("%o is invalid! (%o)", this, this.validity);
+          fieldset.valid = false;
+        }, false);
+        fields.push(elements[i]);
+      }
+    });
+    this.hide = function() {
+      fieldset.setAttribute('hidden', 'hidden');
+      var event = document.createEvent('Events');
+      event.initEvent('wizard:step:hide', true, true);
+      event.step = this;
+      return fieldset.dispatchEvent(event);
+    };
+    this.show = function() {
+      fieldset.removeAttribute('hidden');
+      var event = document.createEvent('Events');
+      event.initEvent('wizard:step:show', true, true);
+      event.step = this;
+      return fieldset.dispatchEvent(event);
+    };
+    this.validate = function() {
+      return fields.every(function(field) {
+        return field.checkValidity();
+      });
+    };
+  }
+  var steps = [];
+  var index = 0;
+  var submit = getSubmit();
+  var submit_text = submit.value;
+  var fieldsets = form.getElementsByTagName('FIELDSET');
+  for (var i = 0; i < fieldsets.length; i++) {
+    var step = new Step(fieldsets[i]);
+    steps.push(step);
+  }
+  function showStep(index) {
+    // TODO - set the label
+    if (steps[index]) {
+      steps[index].show();
+    }
+  };
+  showStep(0);
+  this.next = function() {
+    if (steps[index]) {
+      if (steps[index].validate()) {
+        var event = document.createEvent('Events');
+        event.initEvent('wizard:next', true, true);
+        event.step = steps[index];
+        event.index = index;
+        event.wizard = this;
+        form.dispatchEvent(event);
+        showStep(++index);
+      }
+      else {
+        var event = document.createEvent('Events');
+        event.initEvent('wizard:complete', true, true);
+        event.step = steps[index];
+        event.index = index;
+        event.wizard = this;
+        form.dispatchEvent(event);
+      }
+    }
+    else {
+      var event = document.createEvent('Events');
+      event.initEvent('wizard:invalid', true, true);
+      event.step = steps[index];
+      event.index = index;
+      event.wizard = this;
+      form.dispatchEvent(event);
+      return false;
+    }
+  };
+  this.submit = function() {
+    this.next();
+    if (index == steps.length) {
+      var event = document.createEvent('Events');
+      event.initEvent('wizard:submit', true, true);
+      event.wizard = this;
+      event.index = index;
+      event.step = steps[index];
+      form.dispatchEvent(event);
+      return true;
+    }
+    return false;
+  };
+};