Permalink
Browse files

More README edits, finished first pass

  • Loading branch information...
joshprice committed Apr 20, 2009
1 parent 99acad5 commit 76355f1390db4a58b4e3a49918520d0c1b9b552d
Showing with 53 additions and 55 deletions.
  1. +53 −55 README.textile
View
@@ -1,6 +1,6 @@
-Coconut is a *jQuery plugin* designed to simplify working with complex forms. It provides an *Object-Oriented* encapsulation of forms and their field groups using a straighforward declarative syntax. It enables some very powerful ways for decomposing forms into conceptual parts, and provides meaningful abstractions for these parts.
+h1. Coconut
-h1. Get Started
+Coconut is a *jQuery plugin* designed to simplify working with complex forms. It provides an *Object-Oriented* encapsulation of forms and their field groups using a straighforward declarative syntax. It enables some very powerful ways for decomposing forms into conceptual parts, and provides meaningful abstractions for these parts.
h2. Two Minute Tour
@@ -85,52 +85,56 @@ Set the original state to the part with @resetState()@
</pre>
-h3. Binding and Event Operations
+h3. Showing the field values somewhere else
+
+Let's say you want to have a @label@ element update with changes in the value of a field. Use the @bindState()@ method passing in the CSS selector:
<pre>
- person.name.bindState("#id_of_a_label");
+ person.firstname.bindState("#first_name_label");
</pre>
-Any change of name will update the value of target label specified by jQuery selector.
+Now any change of @firstname@ will update the value of the label you specified.
+
+But what if you wanted a single label to reflect all of the fields? Simply pass a transformation function as the second argument to @bindState()@ like so. The state will be passed in as a parameter to this function so you can easily extract what you need.
<pre>
- person.bindState("#id_of_summary_span", function(s){
- return "summary: " + s.title + " " + s.name + " (" + s.gender + ")";
+ person.bindState("#id_of_summary_span", function(s) {
+ return s.title + " " + s.firstname + " " + s.lastname;
});
</pre>
-Any field change in person will update the summary span by applying a converter function.
+Any changes to person fields will now update the summary span using the specified transformation function.
<pre>
- person.name.change(function(){ /* custom logic */});
- person.change(function(){ /* custom logic */});
+ person.firstname.change(function() { /* custom logic */});
+ person.change(function() { /* custom logic */});
</pre>
-Change of field or person part will trigger custom handlers.
+Change of the @firstname@ field or @person@ part will trigger the custom handlers.
h2. Learn More
h3. Mixin Behaviors
-You can extend part by mixing in behavior(s).
+You can extend a part by mixing in new behaviour.
<pre>
- function Person(){
- this.summary = function(){
- var s = this.state();
- return s.title + " " + s.name + " (" + s.gender + ")";
- }
+ function Person() {
+ this.summary = function() {
+ var s = this.state();
+ return s.title + " " + s.firstname + " " + s.lastname;
+ }
}
var person = $("#person").part(Person);
- var summary = person.summary();
+ person.summary();
</pre>
-Define behavior @Person@ as a function, build part with the behavior, and @summary()@ method is mixed into the part.
+Define behaviour @Person@ as a function, build part with the behaviour, and the @summary()@ method will be mixed into the part.
-_**Behavior is actually the place you should arrange custom client side logic about person part.**_
+_**Behaviour mixins are the recommended way to include custom logic for a specific part.**_
-You can also specify the behavior(function) in Dom element by setting the custom @part@ property:
+You can also specify the behaviour function in the containing DOM element by supplying a @part@ attribute:
<pre>
<div id="person" part="Person">
@@ -142,23 +146,23 @@ Then:
<pre>
var person = $("#person").part();
- var summary = person.summary();
+ person.summary();
</pre>
-Coconut will pick the behavior up and apply it for you automatically.
+Coconut will mixin the @Person@ behaviour for you automatically.
-h3. Build a Composite Part
+h3. Building Composite Parts
-You are allowed to build a composite part with another part as field by setting up @part@ property on any Dom element which can be used as a container.
+You can build a composite part with another part as field by setting up @part@ property on any DOM element which can be used as a container (typically _div_s, _fieldset_s, etc).
-With this Dom:
+With this HTML:
<pre>
<div id="person">
...
<div part="" name="contact">
- <input type="text" name="number"/>
- <input type="text" name="type"/>
+ <input type="text" name="number" value="+61 2 9555 0123" />
+ <input type="text" name="type" value="work" />
</div>
</div>
</pre>
@@ -167,27 +171,24 @@ Then:
<pre>
var person = $("#person").part();
-
- var personState = person.state();
- var contactState = person.contact.state();
- var numberState = person.contact.number.state();
-</pre>
-@personState@ is @{ name: "luning", title: "Mr", contact: {number: "", type: ""} }@.
+ person.state(); #=> { title: "Mr", firstname: "John", lastname: "Smith", contact: { number: "+61 2 9555 0123", type: "work" } }
-@contactState@ is @{number: "", type: ""}@.
+ person.contact.state(); #=> { number: "+61 2 9555 0123", type: "work" }
+
+ person.contact.number.state(); #=> "+61 2 9555 0123"
+</pre>
-@numberState@ is @""@.
-Build a part with a field containing an array of sub-fields with the same name (e.g. person may have multiple emails) by setting @fieldtype@ property to @array@ on Dom element.
+Build a part with a field containing an array of sub-fields with the same name (e.g. person may have multiple emails) by setting @fieldtype@ property to @array@ on the first field element.
-With this Dom:
+Given this HTML:
<pre>
<div id="person">
...
- <input type="text" fieldtype="array" value="a@my.com" name="email"/>
- <input type="text" value="b@my.com" name="email"/>
+ <input type="text" name="email" fieldtype="array" value="a@my.com" />
+ <input type="text" name="email" value="b@my.com" />
</div>
</pre>
@@ -196,22 +197,19 @@ Then:
<pre>
var person = $("#person").part();
- var personState = person.state();
- var emailsState = person.emails.state();
- var firstEmailState = person.emails[0].state();
-</pre>
+ person.state(); #=> { title: "Mr", firstname: "John", lastname: "Smith", emails: ["a@my.com", "b@my.com"] }
-@personState@ is @{ name: "", title: "Mr", emails: ["a@my.com", "b@my.com"] }@.
+ person.emails.state(); #=> ["a@my.com", "b@my.com"]
-@emailsState@ is @["a@my.com", "b@my.com"]@.
+ person.emails[0].state(); #=> "a@my.com"
+</pre>
-@firstEmailState@ is @"a@my.com"@.
-h3. Dynamic Behavior (Sync Between Dom and Part)
+h3. Dynamic Behaviour (Syncing between the DOM and the Part)
-Adding Dom element(s) dynamically will add corresponding field(s) as well, any event registered on part works for the newly added field(s).
+Adding a new DOM element dynamically will add the corresponding field. Any event registered on a part works for the newly added field too. (Pretty much like jQuery live events).
-Given two emails in Dom already, then:
+Given two emails in the DOM already, then:
<pre>
var person = $("#person").part();
@@ -225,11 +223,11 @@ Given two emails in Dom already, then:
@emailCount@ is @3@, reflects the added email.
-Coconut extends jQuery with @sync()@ method, call it after Dom is added.
+*Coconut* extends jQuery with the @sync()@ method. Just call it after the new elements are added.
-The same thing happens when removing Dom element(s) from Dom, field(s) will be removed.
+The same thing happens when removing DOM elements, the fields will be removed.
-Given two emails in Dom already, then:
+Say we have two emails in the DOM already, and we remove the last one:
<pre>
var person = $("#person").part();
@@ -240,9 +238,9 @@ Given two emails in Dom already, then:
var emailCount = person.emails.length;
</pre>
-@emailCount@ is @1@, reflects the removal.
+@emailCount@ is now @1@, reflecting the removal.
-Call @sync()@ on part after removing Dom.
+Call @sync()@ on a part after removing DOM elements.
h1. Rationale

0 comments on commit 76355f1

Please sign in to comment.