Skip to content
This repository has been archived by the owner. It is now read-only.
Turn forms into nested Javascript objects
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE
README.md
objectify.js

README.md

Objectify

Objectify converts forms to complex objects using the [PHP/Ruby name-attribute convention][so]. The reason for this is to decouple the value of a form serialization from its presentation to a user. Getting data from your forms should not be tightly-coupled to your markup.

For more information about this parameter format, see [guides.rubyonrails.org][params]. [so]: http://stackoverflow.com/questions/7578269/where-did-this-ruby-parameter-convention-come-from [params]: http://guides.rubyonrails.org/form_helpers.html#understanding-parameter-naming-conventions

Objectify requires jQuery, although it is not a jQuery plugin per se.

The Objectify Parameter Convention

Objectify uses the HTTP parameter convention popularized by PHP & Ruby:

Nested objects are written inside square-brackets: [ ]

<!-- an input named like this -->
<input type="text" name="person[email]" value="some.dude@test.com" />
// would be converted to this
{
  person: {
    email: "some.dude@test.com"
  }
}

Objects can be nested to arbitrary depth:

<input type="text" name="person[phone_numbers][0][extension]" value="214" />
{
  person: {
    phone_numbers: {
      "0": {
        extension: "214"
      }
    }
  }
}

Form fields that need to be combined into an array end in '[]'

<input type="text" name="person[phone_numbers][]" value="555-2178" />
<input type="text" name="person[phone_numbers][]" value="555-8634" />
{
  person: {
    phone_numbers: ['555-2178', '555-8634']
  }
}

Converting a form

Given a form with the id 'person', you simply pass it into Objectify.convert() in one of two ways:

var person1 = Objectify.convert('#person'),      // jQuery selector string
    person2 = Objectify.convert( $('#person') ), // jQuery instance works too
    person3 = $('#person').objectify();          // jQuery prototype method

That's it!

Useful helper methods

Objectify.pack

Objectify.pack('user', 'address', 'street_address') //=> 'user[address][street_address]'
Objectify.pack('user', 'phone_numbers', []) //=> 'user[phone_numbers][]'

Objectify.unpack

Objectify.unpack('user[address][street_address]') //=> ['user', 'address', 'street_address']

Objectify.normalize

Objectify.normalize({ 'person[address][street_address]': '123 Nowhere st.' })
//{
//  person: {
//    address: {
//      street_address: '123 Nowhere st.'
//    }
//  }
//}

Objectify.denormalize

Objectify.denormalize({ foo: { bar: 'baz' } }) //=> { 'foo[bar]': 'baz' }

Objectify.walk

var obj = Objectify.convert('#user_form');
Objectify.walk(obj, 'user', 'address', 'street_address') //=> '123 Nowhere st.'

jQuery plugin

With no arguments, behaves like convert. With arguments, behaves like walk.

$('#user_form').objectify() //=> { user: { address: { street_address: '123 Nowhere st.' } } }
$('#user_form').objectify('user', 'address', 'street_address') //=> '123 Nowhere st.'

API status

The Objectify API has been stable for some time now, and I have been using it in production successfully. I don't foresee any major changes.

You can’t perform that action at this time.