├── .editorconfig
├── .gitignore
├── .jshintignore
├── .jshintrc
├── changelog.markdown
├── formium.js
├── lib
    └── state.js
├── license
├── package.json
└── readme.markdown


/.editorconfig:
--------------------------------------------------------------------------------
 1 | # editorconfig.org
 2 | root = true
 3 | 
 4 | [*]
 5 | indent_style = space
 6 | indent_size = 2
 7 | end_of_line = lf
 8 | charset = utf-8
 9 | trim_trailing_whitespace = true
10 | insert_final_newline = true
11 | 
12 | [*.md]
13 | trim_trailing_whitespace = false
14 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | npm-debug.log
3 | .DS_Store
4 | Thumbs.db
5 | 


--------------------------------------------------------------------------------
/.jshintignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | bower_components
3 | dist
4 | example
5 | 


--------------------------------------------------------------------------------
/.jshintrc:
--------------------------------------------------------------------------------
 1 | {
 2 |   "curly": true,
 3 |   "eqeqeq": true,
 4 |   "newcap": true,
 5 |   "noarg": true,
 6 |   "noempty": true,
 7 |   "nonew": true,
 8 |   "sub": true,
 9 |   "undef": true,
10 |   "unused": true,
11 |   "trailing": true,
12 |   "boss": true,
13 |   "eqnull": true,
14 |   "strict": true,
15 |   "immed": true,
16 |   "expr": true,
17 |   "latedef": "nofunc",
18 |   "quotmark": "single",
19 |   "validthis": true,
20 |   "indent": 2,
21 |   "node": true,
22 |   "browser": true
23 | }
24 | 


--------------------------------------------------------------------------------
/changelog.markdown:
--------------------------------------------------------------------------------
 1 | # 1.0.3 Speed Bump
 2 | 
 3 | - Bumped `dominus@5.0.1`
 4 | 
 5 | # 1.0.2 Cheese: Optional
 6 | 
 7 | - Fixed a bug where the `qs` option would be required
 8 | 
 9 | # 1.0.0 IPO
10 | 
11 | - Initial Public Release
12 | 


--------------------------------------------------------------------------------
/formium.js:
--------------------------------------------------------------------------------
  1 | 'use strict';
  2 | 
  3 | // jshint scripturl:true
  4 | 
  5 | var $ = require('dominus');
  6 | var queso = require('queso');
  7 | var safeson = require('safeson');
  8 | var state = require('./lib/state');
  9 | var transformers = [];
 10 | var formium = {
 11 |   submit: submit,
 12 |   transform: transform,
 13 |   configure: state.configure
 14 | };
 15 | 
 16 | function noop () {}
 17 | 
 18 | function transform (fn) {
 19 |   transformers.push(fn);
 20 | }
 21 | 
 22 | /* AJAX form submissions use an intermediary <iframe> to help browsers remember
 23 |  * autocompletion suggestions. We submit the form against the <iframe> and then
 24 |  * grab the response as plain-text JSON that we need to parse into JSON.
 25 |  * Afterwards we can hand that JSON to the response handler, business as usual.
 26 |  * Since we've submitted the form "organically", the browser stores suggestions.
 27 |  */
 28 | function frame (form) {
 29 |   var name = 'ff-' + new Date().valueOf();
 30 |   $(form)
 31 |     .attr('autocomplete', 'on')
 32 |     .attr('target', name);
 33 |   return $('<iframe>')
 34 |     .css('display', 'none')
 35 |     .attr('id', name)
 36 |     .attr('name', name)
 37 |     .attr('src', 'javascript:void 0')
 38 |     .afterOf(form);
 39 | }
 40 | 
 41 | function submit (form, done) {
 42 |   var textareaCloneValue = 'data-clone-value';
 43 |   var iframe = frame(form);
 44 |   var content = iframe[0].contentWindow;
 45 |   var restore = transformers.map(run);
 46 |   var textareas = $('textarea', form);
 47 |   textareas.forEach(preserveValue);
 48 |   var formClone = form.cloneNode(true);
 49 |   var textareaClones = $('textarea', formClone);
 50 |   disable(form);
 51 |   $('button', form).forEach(disable);
 52 |   $('[autofocus]', formClone).attr('autofocus', null);
 53 |   textareaClones.forEach(updateValue);
 54 |   textareas.forEach(restoreTextarea);
 55 |   var formCloneId = 'f' + iframe[0].id;
 56 |   formClone.id = formCloneId;
 57 |   iframe.once('load', grabResponse);
 58 |   content.document.body.appendChild(formClone);
 59 |   var frameForm = content.document.getElementById(formCloneId);
 60 |   var amp;
 61 |   if (state.qs) {
 62 |     amp = frameForm.action.indexOf('?') !== -1;
 63 |     frameForm.action += queso.stringify(state.qs(form), amp);
 64 |   }
 65 |   frameForm.onsubmit = null;
 66 |   frameForm.submit();
 67 |   restore.forEach(run);
 68 |   function preserveValue (textarea) {
 69 |     var ta = $(textarea);
 70 |     ta.attr(textareaCloneValue, ta.value());
 71 |   }
 72 |   function updateValue (textarea) {
 73 |     var ta = $(textarea);
 74 |     ta.value(ta.attr(textareaCloneValue)).attr(textareaCloneValue, null);
 75 |   }
 76 |   function restoreTextarea (textarea) {
 77 |     $(textarea).attr(textareaCloneValue, null);
 78 |   }
 79 |   function grabResponse () {
 80 |     var html = readResponse(content);
 81 |     if (!html) {
 82 |       gotResponse(new Error('Internal Server Error')); return;
 83 |     }
 84 |     var json = decodeResponse(html);
 85 |     var err = json ? null : new Error('Malformed response');
 86 |     gotResponse(err, json);
 87 |     function gotResponse (err, data) {
 88 |       $('button', form).forEach(enable);
 89 |       enable(form);
 90 |       iframe.remove();
 91 |       (done || noop).call(form, err, data);
 92 |       $(form).emit('formium', { error: err, data: data });
 93 |     }
 94 |   }
 95 |   function readResponse (content) {
 96 |     try {
 97 |       return content.document.body.innerHTML;
 98 |     } catch (e) { // failure to read (most likely) means server crashed or response timed out
 99 |     }
100 |   }
101 |   function decodeResponse (html) {
102 |     try {
103 |       return safeson.decode(html);
104 |     } catch (e) {
105 |     }
106 |   }
107 |   function run (fn) {
108 |     return (fn || noop)(form);
109 |   }
110 |   function disable (el) {
111 |     el.disabled = true;
112 |   }
113 |   function enable (el) {
114 |     el.disabled = false;
115 |   }
116 | }
117 | 
118 | module.exports = formium;
119 | 


--------------------------------------------------------------------------------
/lib/state.js:
--------------------------------------------------------------------------------
 1 | 'use strict';
 2 | 
 3 | var state = {
 4 |   configure: configure
 5 | };
 6 | 
 7 | function configure (options) {
 8 |   state.qs = options.qs;
 9 | }
10 | 
11 | module.exports = state;
12 | 


--------------------------------------------------------------------------------
/license:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright © 2015 Nicolas Bevacqua
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of
 6 | this software and associated documentation files (the "Software"), to deal in
 7 | the Software without restriction, including without limitation the rights to
 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 9 | the Software, and to permit persons to whom the Software is furnished to do so,
10 | subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "formium",
 3 |   "version": "1.0.3",
 4 |   "description": "Automated progressive enhancement for <form> elements",
 5 |   "main": "formium.js",
 6 |   "repository": {
 7 |     "type": "git",
 8 |     "url": "https://github.com/taunus/formium.git"
 9 |   },
10 |   "author": "Nicolas Bevacqua <nicolasbevacqua@gmail.com> (http://bevacqua.io/)",
11 |   "license": "MIT",
12 |   "bugs": {
13 |     "url": "https://github.com/taunus/formium/issues"
14 |   },
15 |   "homepage": "https://github.com/taunus/formium",
16 |   "dependencies": {
17 |     "dominus": "5.0.1",
18 |     "queso": "1.0.0",
19 |     "safeson": "1.0.0"
20 |   },
21 |   "devDependencies": {}
22 | }
23 | 


--------------------------------------------------------------------------------
/readme.markdown:
--------------------------------------------------------------------------------
 1 | # formium
 2 | 
 3 | > Automated progressive enhancement for `<form>` elements
 4 | 
 5 | # Install
 6 | 
 7 | ```shell
 8 | npm install formium --save
 9 | ```
10 | 
11 | # Usage
12 | 
13 | Formium is a progressive enhancement facility that allows you to seamlessly submit plain old HTML forms via AJAX and handle the response in a conventional manner.
14 | 
15 | ### `formium.submit(form, done?)`
16 | 
17 | Exactly as you would expect, this method will submit a `<form>` asynchronously via AJAX.
18 | 
19 | ```js
20 | form.addEventListener('submit', function handler (e) {
21 |   e.preventDefault();
22 |   formium.submit(form, function responded (err, data) {
23 |     // handle the response
24 |   });
25 | });
26 | ```
27 | 
28 | The form submission mechanism provided by `formium` will:
29 | 
30 | - Run any [transformers](#formiumtransformfn) on the `<form>` elements before submission
31 | - Submit the `<form>` from within an `<iframe>`
32 |   - The form submission is effectively AJAX
33 |   - Browser loading indicator while the form is being posted _(unlike AJAX)_
34 |   - Form auto-fill values are persisted by the browser _(unlike AJAX)_
35 | - Run the restoration callback for each one of the previously applied [transformers](#formiumtransformfn)
36 | - Disable the `<form>` and `<button>`s inside it while the form loads
37 | - Grab the response once the `<iframe>` finishes loading
38 | - Call `done(err, data)` with `this` set to the `form`
39 | 
40 | For maximum usefulness, we recommend that you come up with some conventions to handle forms submitted via `formium`. For example, you could make it so responses like `{ redirect: '/foo' }` end up redirecting the user to `/foo` (or rendering that view with a client-side view rendering engine). That convention alone should simplify your application so that you don't have to treat individual forms differently from one another.
41 | 
42 | ### `formium.configure(options)`
43 | 
44 | You can set a `qs` option that will be used to construct a query string appended to each AJAX form request.
45 | 
46 | ```js
47 | formium.configure({
48 |   qs: function (form) {
49 |     return {
50 |       foo: 'bar'
51 |     };
52 |   }
53 | });
54 | ```
55 | 
56 | ### `formium.transform(fn)`
57 | 
58 | This method allows you to register a `fn(form)` callback that gets called whenever a `form` is submitted. You can prepare the form for submission in any way you want. You can optionally return a callback that restores the form to its original state.
59 | 
60 | The use case for Formium transforms is for those cases when you have a UX enhancement that breaks the state of the form, say if you were using [insignia][1]. In those cases, you can turn the field's value into something plain, and restore the more complex [insignia][1] tag editor right afterwards.
61 | 
62 | ```js
63 | formium.transform(function fix (form) {
64 |   $(form).find('.nsg-input').forEach(function (input) {
65 |     input.attr('data-prev', input.value());
66 |     input.value(insignia(input).value());
67 |   });
68 |   return function restore () {
69 |     $(form).find('.nsg-input').forEach(function (input) {
70 |       input.value(input.attr('data-prev'));
71 |     });
72 |   };
73 | });
74 | ```
75 | 
76 | # Events
77 | 
78 | A synthetic custom `formium` event is submitted on `<form>` DOM elements whenever we get complete a submission. It'll contain details about the response. Use this for advanced cases where you need to handle the response in a specialized way.
79 | 
80 | ```js
81 | formium.submit(form);
82 | form.addEventListener('formium', function (e) {
83 |   console.log(e.detail.error);
84 |   console.log(e.detail.data);
85 | });
86 | ```
87 | 
88 | # License
89 | 
90 | MIT
91 | 
92 | [1]: https://github.com/bevacqua/insignia
93 | 


--------------------------------------------------------------------------------