diff --git a/readme.md b/readme.md index 8881d4c..d20262a 100644 --- a/readme.md +++ b/readme.md @@ -3,67 +3,44 @@ Easily serialize forms in your Backbone.Views into a JSON representation. [![Build Status](https://travis-ci.org/marionettejs/backbone.syphon.svg)](https://travis-ci.org/marionettejs/backbone.syphon) +## About Backbone.Syphon -Working with form elements in a Backbone view can become -very tedious very quickly. You will either end up writing -a lot of repetitive code to read values from the form, -or end up using a key-value-observer or data-binding -solution that automatically populates your model for you. -While these are valid options and I highly recommend -understanding how they work, there are times when these -options are not the best choice for your application. - -Backbone.Syphon aims to make it easy to serialize the -form inputs of a Backbone.View in to a simple JSON object +Backbone.Syphon aims to make it easy to serialize the form inputs of a Backbone.View in to a simple JSON object that contains all of the values from the form. -## Source Code And Downloads - -You can download the raw source code from the "src" -folder above, or grab one of the builds from the -"lib" folder. - -To get the latest stable release, use these links -which point to the 'master' branch's builds: - -### Standard Builds - -Development: [backbone.syphon.js](https://raw.github.com/derickbailey/backbone.syphon/master/lib/backbone.syphon.js) +Working with form elements in a Backbone view can become very tedious very quickly. You will either end up writing +a lot of repetitive code to read values from the form, or end up using a key-value-observer or data-binding +solution that automatically populates your model for you. While these are valid options and it is highly recommended to +understand how they work, there are times when these options are not the best choice for your application. -Production: [backbone.syphon.min.js](https://raw.github.com/derickbailey/backbone.syphon/master/lib/backbone.syphon.min.js) +## Documentation -### AMD/RequireJS Builds +This readme file contains [basic usage examples](#basic-usage). -Development: [backbone.syphon.js](https://raw.github.com/derickbailey/backbone.syphon/master/lib/amd/backbone.syphon.js) +If you need to modify the behaviors of Syphon, see the [API document](https://github.com/marionettejs/backbone.syphon/blob/master/apidoc.md). +It contains the documentation for the core APIs that Syphon exposes, with examples on how to change the behaviors of Syphon. -Production: [backbone.syphon.min.js](https://raw.github.com/derickbailey/backbone.syphon/master/lib/amd/backbone.syphon.min.js) +### [View The API Documentation](https://github.com/marionettejs/backbone.syphon/blob/master/apidoc.md) -## Documentation +## Source Code And Downloads -This readme file contains basic usage examples. +You can download the raw source code from the "src" folder above, or grab one of the builds from the "lib" folder. -### Extensibility / API Documentation +To get the latest stable release, use these links which point to the 'master' branch's builds: -If you need to modify the behaviors of Syphon, see the API document. It -contains the documentation for the core APIs that Syphon exposes, with -examples on how to change the behaviors of Syphon. +### Standard Builds -##### [View The API Documentation](https://github.com/derickbailey/backbone.syphon/blob/master/apidoc.md) +Development: [backbone.syphon.js](https://raw.github.com/marionettejs/backbone.syphon/master/lib/backbone.syphon.js) -### Annotated Source Code +Production: [backbone.syphon.min.js](https://raw.github.com/marionettejs/backbone.syphon/master/lib/backbone.syphon.min.js) -Syphon has annotated source code using the Docco tool to turn -comments in to documentation. This provides an in-depth look -at what each section of is doing. -##### [View The Annotated Source Code](http://derickbailey.github.com/backbone.syphon/docs/backbone.syphon.html) +## Basic Usage -## Basic Usage : Serialize +### Serialize -When the data from a form is needed, you can call the -`serialize` method of `Backbone.Syphon` to retrieve an -object literal that contains the data from your view's -form. +When the data from a form is needed, you can call the `serialize` method of `Backbone.Syphon` to retrieve an object +literal that contains the data from your view's form. ```js Backbone.View.extend({ @@ -88,8 +65,7 @@ Backbone.View.extend({ ### Keys Retrieved By "name" Attribute -The default behavior for serializing fields is to use the field's "name" -attribute as the key in the serialized object. +The default behavior for serializing fields is to use the field's "name" attribute as the key in the serialized object. ```html
@@ -102,7 +78,7 @@ attribute as the key in the serialized object. ```js Backbone.Syphon.serialize(view); -// will produce => +// will produce => { a: "", @@ -111,14 +87,12 @@ Backbone.Syphon.serialize(view); } ``` -For information on how to change this behavior, see the Key Extractors -section of the -[API Documentation](https://github.com/derickbailey/backbone.syphon/blob/master/apidoc.md). +For information on how to change this behavior, see the Key Extractors section of the +[API Documentation](https://github.com/marionettejs/backbone.syphon/blob/master/apidoc.md). ### Values Retrieved By jQuery `.val()` Call -The default behavior for serializing fields is to use jQuery's `.val()` -to get the value of the input element. +The default behavior for serializing fields is to use jQuery's `.val()` to get the value of the input element. ```html @@ -130,7 +104,7 @@ to get the value of the input element. ```js Backbone.Syphon.serialize(view); -// will produce => +// will produce => { a: "a-value", @@ -138,14 +112,12 @@ Backbone.Syphon.serialize(view); } ``` -For information on how to change this behavior, see the Input Readers -section of the -[API Documentation](https://github.com/derickbailey/backbone.syphon/blob/master/apidoc.md). +For information on how to change this behavior, see the Input Readers section of the +[API Documentation](https://github.com/marionettejs/backbone.syphon/blob/master/apidoc.md). ### Checkboxes -By default, a checkbox will return a boolean value signifying whether or -not it is checked. +By default, a checkbox will return a boolean value signifying whether or not it is checked. ```html @@ -157,7 +129,7 @@ not it is checked. ```js Backbone.Syphon.serialize(view); -// will produce => +// will produce => { a: false, @@ -165,14 +137,13 @@ Backbone.Syphon.serialize(view); } ``` -For information on how to change this behavior, see the Input Readers -section of the -[API Documentation](https://github.com/derickbailey/backbone.syphon/blob/master/apidoc.md). +For information on how to change this behavior, see the Input Readers section of the +[API Documentation](https://github.com/marionettejs/backbone.syphon/blob/master/apidoc.md). ### Radio Button Groups -Radio button groups (grouped by the input element "name" attribute) will -produce a single value, from the selected radio button. +Radio button groups (grouped by the input element "name" attribute) will produce a single value, from the selected +radio button. ```html @@ -186,25 +157,24 @@ produce a single value, from the selected radio button. ```js Backbone.Syphon.serialize(view); -// will produce => +// will produce => { a: "2" } ``` -This behavior can be changed by registering a different set of Key -Extractors, Input Readers, and Key Assignment Validators. See the full -[API Documentation](https://github.com/derickbailey/backbone.syphon/blob/master/apidoc.md). +This behavior can be changed by registering a different set of Key Extractors, Input Readers, and Key Assignment +Validators. See the full +[API Documentation](https://github.com/marionettejs/backbone.syphon/blob/master/apidoc.md). for more information on these. ## Basic Usage : Deserialize -Syphon also allows you to deserialize an object's values back on to a -form. It uses the same conventions and configuration as the serialization -process, with the introduction of Input Writers to handle populating the -form fields with the values. See the full -[API Documentation](https://github.com/derickbailey/backbone.syphon/blob/master/apidoc.md). +Syphon also allows you to deserialize an object's values back on to a form. It uses the same conventions and +configuration as the serialization process, with the introduction of Input Writers to handle populating the +form fields with the values. See the full +[API Documentation](https://github.com/marionettejs/backbone.syphon/blob/master/apidoc.md). for more information on Input Writers. ```html @@ -223,32 +193,27 @@ var data = { Backbone.Syphon.deserialize(this, data); ``` -This will populate the form input elements with the correct values from -the `data` parameter. +This will populate the form input elements with the correct values from the `data` parameter. ## Ignored Input Types -The following types of input are ignored, and not included in -the resulting JavaScript object: +The following types of input are ignored, and not included in the resulting JavaScript object: * `` buttons * ` buttons * standard `