--- /dev/null
+// Backbone.Syphon, v0.4.1
+// Copyright (c)2012 Derick Bailey, Muted Solutions, LLC.
+// Distributed under MIT license
+// http://github.com/derickbailey/backbone.syphon
+Backbone.Syphon = (function(Backbone, $, _){
+ var Syphon = {};
+
+ // Ignore Element Types
+ // --------------------
+
+ // Tell Syphon to ignore all elements of these types. You can
+ // push new types to ignore directly in to this array.
+ Syphon.ignoredTypes = ["button", "submit", "reset", "fieldset"];
+
+ // Syphon
+ // ------
+
+ // Get a JSON object that represents
+ // all of the form inputs, in this view.
+ // Alternately, pass a form element directly
+ // in place of the view.
+ Syphon.serialize = function(view, options){
+ var data = {};
+
+ // Build the configuration
+ var config = buildConfig(options);
+
+ // Get all of the elements to process
+ var elements = getInputElements(view, config);
+
+ // Process all of the elements
+ _.each(elements, function(el){
+ var $el = $(el);
+ var type = getElementType($el);
+
+ // Get the key for the input
+ var keyExtractor = config.keyExtractors.get(type);
+ var key = keyExtractor($el);
+
+ // Get the value for the input
+ var inputReader = config.inputReaders.get(type);
+ var value = inputReader($el);
+
+ // Get the key assignment validator and make sure
+ // it's valid before assigning the value to the key
+ var validKeyAssignment = config.keyAssignmentValidators.get(type);
+ if (validKeyAssignment($el, key, value)){
+ var keychain = config.keySplitter(key);
+ data = assignKeyValue(data, keychain, value);
+ }
+ });
+
+ // Done; send back the results.
+ return data;
+ };
+
+ // Use the given JSON object to populate
+ // all of the form inputs, in this view.
+ // Alternately, pass a form element directly
+ // in place of the view.
+ Syphon.deserialize = function(view, data, options){
+ // Build the configuration
+ var config = buildConfig(options);
+
+ // Get all of the elements to process
+ var elements = getInputElements(view, config);
+
+ // Flatten the data structure that we are deserializing
+ var flattenedData = flattenData(config, data);
+
+ // Process all of the elements
+ _.each(elements, function(el){
+ var $el = $(el);
+ var type = getElementType($el);
+
+ // Get the key for the input
+ var keyExtractor = config.keyExtractors.get(type);
+ var key = keyExtractor($el);
+
+ // Get the input writer and the value to write
+ var inputWriter = config.inputWriters.get(type);
+ var value = flattenedData[key];
+
+ // Write the value to the input
+ inputWriter($el, value);
+ });
+ };
+
+ // Helpers
+ // -------
+
+ // Retrieve all of the form inputs
+ // from the form
+ var getInputElements = function(view, config){
+ var form = getForm(view);
+ var elements = form.elements;
+
+ elements = _.reject(elements, function(el){
+ var reject;
+ var type = getElementType(el);
+ var extractor = config.keyExtractors.get(type);
+ var identifier = extractor($(el));
+
+ var foundInIgnored = _.include(config.ignoredTypes, type);
+ var foundInInclude = _.include(config.include, identifier);
+ var foundInExclude = _.include(config.exclude, identifier);
+
+ if (foundInInclude){
+ reject = false;
+ } else {
+ if (config.include){
+ reject = true;
+ } else {
+ reject = (foundInExclude || foundInIgnored);
+ }
+ }
+
+ return reject;
+ });
+
+ return elements;
+ };
+
+ // Determine what type of element this is. It
+ // will either return the `type` attribute of
+ // an `<input>` element, or the `tagName` of
+ // the element when the element is not an `<input>`.
+ var getElementType = function(el){
+ var typeAttr;
+ var $el = $(el);
+ var tagName = $el[0].tagName;
+ var type = tagName;
+
+ if (tagName.toLowerCase() === "input"){
+ typeAttr = $el.attr("type");
+ if (typeAttr){
+ type = typeAttr;
+ } else {
+ type = "text";
+ }
+ }
+
+ // Always return the type as lowercase
+ // so it can be matched to lowercase
+ // type registrations.
+ return type.toLowerCase();
+ };
+
+ // If a form element is given, just return it.
+ // Otherwise, get the form element from the view.
+ var getForm = function(viewOrForm){
+ if (_.isUndefined(viewOrForm.$el) && viewOrForm.tagName.toLowerCase() === 'form'){
+ return viewOrForm;
+ } else {
+ return viewOrForm.$el.is("form") ? viewOrForm.el : viewOrForm.$("form")[0];
+ }
+ };
+
+ // Build a configuration object and initialize
+ // default values.
+ var buildConfig = function(options){
+ var config = _.clone(options) || {};
+
+ config.ignoredTypes = _.clone(Syphon.ignoredTypes);
+ config.inputReaders = config.inputReaders || Syphon.InputReaders;
+ config.inputWriters = config.inputWriters || Syphon.InputWriters;
+ config.keyExtractors = config.keyExtractors || Syphon.KeyExtractors;
+ config.keySplitter = config.keySplitter || Syphon.KeySplitter;
+ config.keyJoiner = config.keyJoiner || Syphon.KeyJoiner;
+ config.keyAssignmentValidators = config.keyAssignmentValidators || Syphon.KeyAssignmentValidators;
+
+ return config;
+ };
+
+ // Assigns `value` to a parsed JSON key.
+ //
+ // The first parameter is the object which will be
+ // modified to store the key/value pair.
+ //
+ // The second parameter accepts an array of keys as a
+ // string with an option array containing a
+ // single string as the last option.
+ //
+ // The third parameter is the value to be assigned.
+ //
+ // Examples:
+ //
+ // `["foo", "bar", "baz"] => {foo: {bar: {baz: "value"}}}`
+ //
+ // `["foo", "bar", ["baz"]] => {foo: {bar: {baz: ["value"]}}}`
+ //
+ // When the final value is an array with a string, the key
+ // becomes an array, and values are pushed in to the array,
+ // allowing multiple fields with the same name to be
+ // assigned to the array.
+ var assignKeyValue = function(obj, keychain, value) {
+ if (!keychain){ return obj; }
+
+ var key = keychain.shift();
+
+ // build the current object we need to store data
+ if (!obj[key]){
+ obj[key] = _.isArray(key) ? [] : {};
+ }
+
+ // if it's the last key in the chain, assign the value directly
+ if (keychain.length === 0){
+ if (_.isArray(obj[key])){
+ obj[key].push(value);
+ } else {
+ obj[key] = value;
+ }
+ }
+
+ // recursive parsing of the array, depth-first
+ if (keychain.length > 0){
+ assignKeyValue(obj[key], keychain, value);
+ }
+
+ return obj;
+ };
+
+ // Flatten the data structure in to nested strings, using the
+ // provided `KeyJoiner` function.
+ //
+ // Example:
+ //
+ // This input:
+ //
+ // ```js
+ // {
+ // widget: "wombat",
+ // foo: {
+ // bar: "baz",
+ // baz: {
+ // quux: "qux"
+ // },
+ // quux: ["foo", "bar"]
+ // }
+ // }
+ // ```
+ //
+ // With a KeyJoiner that uses [ ] square brackets,
+ // should produce this output:
+ //
+ // ```js
+ // {
+ // "widget": "wombat",
+ // "foo[bar]": "baz",
+ // "foo[baz][quux]": "qux",
+ // "foo[quux]": ["foo", "bar"]
+ // }
+ // ```
+ var flattenData = function(config, data, parentKey){
+ var flatData = {};
+
+ _.each(data, function(value, keyName){
+ var hash = {};
+
+ // If there is a parent key, join it with
+ // the current, child key.
+ if (parentKey){
+ keyName = config.keyJoiner(parentKey, keyName);
+ }
+
+ if (_.isArray(value)){
+ keyName += "[]";
+ hash[keyName] = value;
+ } else if (_.isObject(value)){
+ hash = flattenData(config, value, keyName);
+ } else {
+ hash[keyName] = value;
+ }
+
+ // Store the resulting key/value pairs in the
+ // final flattened data object
+ _.extend(flatData, hash);
+ });
+
+ return flatData;
+ };
+
+ return Syphon;
+})(Backbone, jQuery, _);
+
+// Type Registry
+// -------------
+
+// Type Registries allow you to register something to
+// an input type, and retrieve either the item registered
+// for a specific type or the default registration
+Backbone.Syphon.TypeRegistry = function(){
+ this.registeredTypes = {};
+};
+
+// Borrow Backbone's `extend` keyword for our TypeRegistry
+Backbone.Syphon.TypeRegistry.extend = Backbone.Model.extend;
+
+_.extend(Backbone.Syphon.TypeRegistry.prototype, {
+
+ // Get the registered item by type. If nothing is
+ // found for the specified type, the default is
+ // returned.
+ get: function(type){
+ var item = this.registeredTypes[type];
+
+ if (!item){
+ item = this.registeredTypes["default"];
+ }
+
+ return item;
+ },
+
+ // Register a new item for a specified type
+ register: function(type, item){
+ this.registeredTypes[type] = item;
+ },
+
+ // Register a default item to be used when no
+ // item for a specified type is found
+ registerDefault: function(item){
+ this.registeredTypes["default"] = item;
+ },
+
+ // Remove an item from a given type registration
+ unregister: function(type){
+ if (this.registeredTypes[type]){
+ delete this.registeredTypes[type];
+ }
+ }
+});
+
+
+
+
+// Key Extractors
+// --------------
+
+// Key extractors produce the "key" in `{key: "value"}`
+// pairs, when serializing.
+Backbone.Syphon.KeyExtractorSet = Backbone.Syphon.TypeRegistry.extend();
+
+// Built-in Key Extractors
+Backbone.Syphon.KeyExtractors = new Backbone.Syphon.KeyExtractorSet();
+
+// The default key extractor, which uses the
+// input element's "id" attribute
+Backbone.Syphon.KeyExtractors.registerDefault(function($el){
+ return $el.prop("name");
+});
+
+
+// Input Readers
+// -------------
+
+// Input Readers are used to extract the value from
+// an input element, for the serialized object result
+Backbone.Syphon.InputReaderSet = Backbone.Syphon.TypeRegistry.extend();
+
+// Built-in Input Readers
+Backbone.Syphon.InputReaders = new Backbone.Syphon.InputReaderSet();
+
+// The default input reader, which uses an input
+// element's "value"
+Backbone.Syphon.InputReaders.registerDefault(function($el){
+ return $el.val();
+});
+
+// Checkbox reader, returning a boolean value for
+// whether or not the checkbox is checked.
+Backbone.Syphon.InputReaders.register("checkbox", function($el){
+ var checked = $el.prop("checked");
+ return checked;
+});
+
+
+// Input Writers
+// -------------
+
+// Input Writers are used to insert a value from an
+// object into an input element.
+Backbone.Syphon.InputWriterSet = Backbone.Syphon.TypeRegistry.extend();
+
+// Built-in Input Writers
+Backbone.Syphon.InputWriters = new Backbone.Syphon.InputWriterSet();
+
+// The default input writer, which sets an input
+// element's "value"
+Backbone.Syphon.InputWriters.registerDefault(function($el, value){
+ $el.val(value);
+});
+
+// Checkbox writer, set whether or not the checkbox is checked
+// depending on the boolean value.
+Backbone.Syphon.InputWriters.register("checkbox", function($el, value){
+ $el.prop("checked", value);
+});
+
+// Radio button writer, set whether or not the radio button is
+// checked. The button should only be checked if it's value
+// equals the given value.
+Backbone.Syphon.InputWriters.register("radio", function($el, value){
+ $el.prop("checked", $el.val() === value);
+});
+
+// Key Assignment Validators
+// -------------------------
+
+// Key Assignment Validators are used to determine whether or not a
+// key should be assigned to a value, after the key and value have been
+// extracted from the element. This is the last opportunity to prevent
+// bad data from getting serialized to your object.
+
+Backbone.Syphon.KeyAssignmentValidatorSet = Backbone.Syphon.TypeRegistry.extend();
+
+// Build-in Key Assignment Validators
+Backbone.Syphon.KeyAssignmentValidators = new Backbone.Syphon.KeyAssignmentValidatorSet();
+
+// Everything is valid by default
+Backbone.Syphon.KeyAssignmentValidators.registerDefault(function(){ return true; });
+
+// But only the "checked" radio button for a given
+// radio button group is valid
+Backbone.Syphon.KeyAssignmentValidators.register("radio", function($el, key, value){
+ return $el.prop("checked");
+});
+
+
+// Backbone.Syphon.KeySplitter
+// ---------------------------
+
+// This function is used to split DOM element keys in to an array
+// of parts, which are then used to create a nested result structure.
+// returning `["foo", "bar"]` results in `{foo: { bar: "value" }}`.
+//
+// Override this method to use a custom key splitter, such as:
+// `<input name="foo.bar.baz">`, `return key.split(".")`
+Backbone.Syphon.KeySplitter = function(key){
+ var matches = key.match(/[^\[\]]+/g);
+
+ if (key.indexOf("[]") === key.length - 2){
+ lastKey = matches.pop();
+ matches.push([lastKey]);
+ }
+
+ return matches;
+}
+
+
+// Backbone.Syphon.KeyJoiner
+// -------------------------
+
+// Take two segments of a key and join them together, to create the
+// de-normalized key name, when deserializing a data structure back
+// in to a form.
+//
+// Example:
+//
+// With this data strucutre `{foo: { bar: {baz: "value", quux: "another"} } }`,
+// the key joiner will be called with these parameters, and assuming the
+// join happens with "[ ]" square brackets, the specified output:
+//
+// `KeyJoiner("foo", "bar")` //=> "foo[bar]"
+// `KeyJoiner("foo[bar]", "baz")` //=> "foo[bar][baz]"
+// `KeyJoiner("foo[bar]", "quux")` //=> "foo[bar][quux]"
+
+Backbone.Syphon.KeyJoiner = function(parentKey, childKey){
+ return parentKey + "[" + childKey + "]";
+}
git://git.onelab.eu / plstackapi.git / commitdiff