Documentation and test updates

daffl · Mar 18, 2012 · 8bad7e6 · 8bad7e6
1 parent 58fb7af
commit 8bad7e6
Show file tree

Hide file tree

Showing 5 changed files with 216 additions and 182 deletions.
diff --git a/readme.markdown b/readme.markdown
@@ -5,65 +5,71 @@ __Some things you can do:__
 
 * use JavaScript and JSON instead of HTML markup since your page doesn't run without JS anyway
 * naturally generate JavaScript enhanced markup with your own extensions and custom types
-* have an easy way to include jQuery UI elements and other popular jQuery plugins (some supported out of the box)
+* have an easy way to include jQuery UI elements and other jQuery plugins (some supported out of the box)
 * scaffold forms from business objects of your server side framework
 
-## Get started:
+## Get started
 
 [Download](http://github.com/downloads/daffl/jquery.dform/jquery.dform-0.1.4.tar.gz)
 the latest version 0.2.0 (6 Kb minified)
 
-Then try this JavaScript snipped:
-
-	$("#myform").dform({
-	    "action" : "index.html",
-	    "method" : "get",
-	    "html" :
-	    [
-	        {
-	            "type" : "p",
-	            "html" : "You must login"
-	        },
-	        {
-	            "name" : "username",
-	            "id" : "txt-username",
-	            "caption" : "Username",
-	            "type" : "text",
-	            "placeholder" : "E.g. [email protected]"
-	        },
-	        {
-	            "name" : "password",
-	            "caption" : "Password",
-	            "type" : "password"
-	        },
-	        {
-	            "type" : "submit",
-	            "value" : "Login"
-	        }
-	    ]
-	});
+Include it in your jQuery powered page and try this:
+
+	<script type="text/javascript">
+		$(function() {
+			$("#myform").dform({
+			    "action" : "index.html",
+			    "method" : "get",
+			    "html" :
+			    [
+			        {
+			            "type" : "p",
+			            "html" : "You must login"
+			        },
+			        {
+			            "name" : "username",
+			            "id" : "txt-username",
+			            "caption" : "Username",
+			            "type" : "text",
+			            "placeholder" : "E.g. [email protected]"
+			        },
+			        {
+			            "name" : "password",
+			            "caption" : "Password",
+			            "type" : "password"
+			        },
+			        {
+			            "type" : "submit",
+			            "value" : "Login"
+			        }
+			    ]
+			});
+		});
+	</script>
+	<form id="myform"></form>
 
 __Learn more:__
 
-* Check out the JSFiddle examples or the get started page for more examples
+* Play around with this example as a JSFiddle
+* Check out the get started page for more examples
 * Visit the [jQuery.dForm Google Group](http://groups.google.com/group/jquery-dform)
-* Fork the project on [GitHub](http://github.com/daffl/jquery.dform/)
+* Watch and fork the project on [GitHub](http://github.com/daffl/jquery.dform/)
 * Follow [@daffl](http://twitter.com/daffl) on Twitter
 * Read on in this documentation
 
 ## Types
 
-Type Generators are functions that return a new jQuery DOM object for a specific type. If there is no Type Generator
-with a given name, a basic HTML element with that tag name will be created. Every other key in the JavaScript or JSON object
-you pass will be used as an HTML attribute. An exception is, if there is a Subscriber registered for that key (more about
-this in the next section). A plugin call like this:
+Type generators are functions that return a new jQuery DOM object for a specific type. If there is no type generator
+for that type, a basic HTML tag the type name will be created. Every other key in the JavaScript or JSON object
+you pass (the dForm object) will be used as an HTML attribute, except if there is a [subscriber](#subscribers)
+registered for that key. A plugin call like this:
 
 	$('#my-div').dform({
 		type : "span",
 		id : "the-span"
 	});
 
-Will append an empty `<span id="the-span"></span>` tag to the selected element.
+Will append an empty `<span id="the-span"></span>` to the selected element.
 
 ### Core types
 
@@ -100,7 +106,7 @@ Creates a checkbox
 Creates a group of radiobuttons (uses options subscriber explained below)
 
 **checkboxes** `{ "type" : "checkboxes" }`<br />
-Creates a group of checkboxes
+Creates a group of checkboxes (uses options subscriber explained below)
 
 **number** `{ "type" : "number" }`<br />
 Creates an HTML 5 number input field
@@ -116,7 +122,41 @@ Creates an HTML 5 email input field
 
 ### Add your own
 
-You can add your own types :)
+You can add your own types by calling  *$.dform.addType* and pass the type name and a function
+that takes the dForm object as a parameter and returns a new jQuery DOM element:
+
+	$.dform.addType("hellobutton", function(options) {
+		// Return a new button element that has all options that
+		// don't have a registered subscriber as attributes
+		return $("<button>").dform('attr', options).html("Say hello");
+	});
+
+The type generator uses the *attr* [plugin method](#plugin-methods)) to add the proper HTML attributes to the button.
+Now the new type can be used:
+
+	$('#myform').dform({
+		"type" : "hellobutton",
+		"id" : "my-button"
+	});
+
+And generates:
+
+	<button id="my-button" class="ui-dform-hellobutton">Say hello</button>
+
+Type generators can be chained. That means, that if you add an already existing type, *this* in the generator function
+will refer to the element returned by its previous generator (otherwise it will refer to the *window* object):
+
+	$.dform.addType("text", function(options) {
+		return $(this).addClass('my-textfield-class');
+	});
+
+	$('#myform').dform({
+		type : 'text'
+	});
+
+Now generates
+
+	<input type="text" class="ui-dform-text my-textfield-class" />
 
 ## Subscribers
 
@@ -139,7 +179,7 @@ Generates:
 	<input type="text" class="ui-dform-text" />
 
 **class** *{String}*<br />
-Adds a class to the current element (instead of setting the attribute)
+Adds a class to the current element (instead of setting the attribute) using [.addClass()](http://api.jquery.com/addClass).
 
 	{
 		"type" : "div",
@@ -152,7 +192,7 @@ Generates:
 
 **html/elements** *{String|Array|Object}*<br />
 Based on the options it either sets the HTML string content of the current element or appends one or an array
-of dForm objects (the elements subscriber does the same but is kept for backwards compatibility).
+of dForm objects. The *elements* subscriber does the same but is kept for backwards compatibility.
 
 	{
         "type" : "div",
@@ -192,7 +232,7 @@ Generates:
 	</div>
 
 **value** *{String|Function}*<br />
-Sets the value of the element using .val()
+Sets the value of the element using [.val()](http://api.jquery.com/val/)
 
 	{
 		"type" : "text",
@@ -204,7 +244,7 @@ Generates:
 	<input type="text" value="Text content" />
 
 **css** {Object}<br />
-Sets CSS properties on an element:
+Sets CSS properties on an element with [.css()](http://api.jquery.com/css/):
 
 	{
 		"type" : "div",
@@ -222,9 +262,6 @@ Generates:
 Generates a list of options from a value to text (or dForm Object) mapping for elements of type *select*, *radiobuttons*
 or *checkboxes*.
 
-> *Note:* The Google Chrome JavaScript engine V8 orders object keys that can be cast to numbers by their value and
-> not by the order of their definition.
-
 	{
 		"type" : "select",
 		"options" : {
@@ -261,12 +298,17 @@ Generates:
 
 	// TODO
 
+> *Note:* The Google Chrome JavaScript engine V8 orders object keys that can be cast to numbers by their value and
+> not by the order of their definition.
+
 **caption** *{String|Object}*<br />
-Adds a caption to the element. The type used for it depends on the element type:
+Adds a caption to the element. The type used depends on the element type:
+
 * A *legend* on *fieldset* elements
 * A *label* next to *radio* or *checkbox* elements
 * A *label* before any other element
-If the element has its id set the for attribute of the label will be set as well.
+
+If the element has its id set the *for* attribute of the label will be set as well.
 
 	{
 		"type" : "text",
@@ -298,7 +340,32 @@ TODO
 
 ### Add your own
 
-You can add your own subscribers
+It is easy to add your own subscribers. Similar to a type generator you just pass the key name you want to subscribe
+to and a function that takes the options and the type name as a parameter to *$.dform.subscribe*. *this* in the
+subscriber function will refer to the current element. That way it e.g. would be possible to add an alert to the
+*hellobutton* created in the [types section](#subscribers/add-your-own):
+
+	$.dform.subscribe("alert", function(options, type) {
+		if(type === "hellobutton") { // Just run if the type is a hellobutton
+			this.click(function() {
+				alert(options);
+			});
+		}
+	});
+
+And then you can use the plugin like this:
+
+	$("#mydiv").dform({
+		"type" : "hellobutton",
+		"alert" : "Hello world!"
+	});
+
+Which generates:
+
+	<button class="ui-dform-hellobutton">Say Hello</button>
+
+And alerts "Hello world!" when the button is clicked. Like type generators, subscribers will also be chained.
+You can therefore add multiple subscribers with the same name adding behaviour or reacting to different types.
 
 ### Special subscribers
 
@@ -322,15 +389,30 @@ ajax<br />
 
 ## jQuery UI
 
+jQuery.dForm adds automatic support for jQuery UI if it is available. If the form has the *ui-widget* class
+the plugin will automatically turn buttons into jQuery UI buttons and add corners to *text*, *textarea*, *password*
+and *fieldset* elements.
+
 ### Types
 
+Most jQuery UI widgets have an appropriate type generator implemented. Each take the same options as described
+in [the jQuery UI documentation](http://jqueryui.com/demos/).
+
+**progressbar** `{ "type" : "progressbar" }`<br />
+**slider** `{ "type" : "slider" }`<br />
+**accordion** `{ "type" : "accordion" }`<br />
+**tabs** `{ "type" : "tabs" }`<br />
+
 ### Subscribers
 
+Some other features have been implemented as subscriber, e.g. adding entries to an accordion or making an element
+resizable:
+
 ## Other plugins
 
-### jQuery form plugin
+### Form plugin
 
-### Form validation plugin
+### Form validation
 
 ### jQuery Globalize
 
@@ -345,47 +427,51 @@ ajax<br />
 
 **0.1.4**
 
-- Merged pull request [#30](https://github.com/daffl/jquery.dform/pull/30): Wrap 'type' as an array so it doesn't break jQuery 1.7.1's $.inArray() when running in IE8
-- Added first QUnit tests
-- Fixed issue #22 with jQuery UI accordion causing problems with captions
-- Removed placeholder plugin. Use HTML 5 placeholders or the jQuery [placeholder plugin](https://github.com/danielstocks/jQuery-Placeholder)
-- Updated documentation engine to DocumentJS and build system to StealJS
-- Merged pull request [#19](https://github.com/daffl/jquery.dform/pull/19) and [#20](https://github.com/daffl/jquery.dform/pull/20), support to set up a validate options for validate() in "form" type
-- Merged pull request [#26](https://github.com/daffl/jquery.dform/pull/26) to support HTML 5 input types
-- Added simple getting started example
+* Merged pull request [#30](https://github.com/daffl/jquery.dform/pull/30):
+Wrap 'type' as an array so it doesn't break jQuery 1.7.1's $.inArray() when running in IE8
+* Added first QUnit tests
+* Fixed issue #22 with jQuery UI accordion causing problems with captions
+* Removed placeholder plugin. Use HTML 5 placeholders or the jQuery
+[placeholder plugin](https://github.com/danielstocks/jQuery-Placeholder)
+* Updated documentation engine to DocumentJS and build system to StealJS
+* Merged pull request [#19](https://github.com/daffl/jquery.dform/pull/19) and
+[#20](https://github.com/daffl/jquery.dform/pull/20),
+support to set up a validate options for validate() in "form" type
+* Merged pull request [#26](https://github.com/daffl/jquery.dform/pull/26) to support HTML 5 input types
+* Added simple getting started example
 
 **0.1.3**
 
-- Created some public [JSFiddles for trying the plugin](http://jsfiddle.net/user/Daff/fiddles)
-- Created [jQuery.dForm Google Group](http://groups.google.com/group/jquery-dform)
-- Added *form* type, unified *buildForm* usage
-- Fixed [issue #14](https://github.com/daffl/jquery.dform/issues/closed#issue/14), setting type attribute properly in IE
-- Added *getValueAt*
-- Added *i18n* support using the [jQuery globalize](https://github.com/jquery/jquery-global) plugin
-- Fixed minor bugs in dform plugins
+* Created some public [JSFiddles for trying the plugin](http://jsfiddle.net/user/Daff/fiddles)
+* Created [jQuery.dForm Google Group](http://groups.google.com/group/jquery-dform)
+* Added *form* type, unified *buildForm* usage
+* Fixed [issue #14](https://github.com/daffl/jquery.dform/issues/closed#issue/14), setting type attribute properly in IE
+* Added *getValueAt*
+* Added *i18n* support using the [jQuery globalize](https://github.com/jquery/jquery-global) plugin
+* Fixed minor bugs in dform plugins
 
 **0.1.2**
 
-- Added *dformAttr* to add HTML attributes to elements
-- Moved *placeholder* into a separate plugin
-- Added *reset* button type
-- Added dynamic form definition loading by passing a URL to the *buildForm* plugin function
-- Added *ajax* subscriber using the *jQuery form plugin at http://jquery.malsup.com/form*
-- Added the *defaultType* method to create any HTML element without having to register a type
-- Improved build process
+* Added *dformAttr* to add HTML attributes to elements
+* Moved *placeholder* into a separate plugin
+* Added *reset* button type
+* Added dynamic form definition loading by passing a URL to the *buildForm* plugin function
+* Added *ajax* subscriber using the *jQuery form plugin at http://jquery.malsup.com/form*
+* Added the *defaultType* method to create any HTML element without having to register a type
+* Improved build process
 
 **0.1.1**
 
-- Separated type and subscriber functions
-- Added types *file*, *container*, *hidden*, *accordion*, *checkboxes* and *radiobuttons*
-- Added auto class generation based on element type
-- Finished jQuery UI *accordion* and unified with *tabs* usage
-- Switched documentation to *Natualdocs at http://naturaldocs.org*
-- Added build.xml for generating documentation and minifying JavaScript
+* Separated type and subscriber functions
+* Added types *file*, *container*, *hidden*, *accordion*, *checkboxes* and *radiobuttons*
+* Added auto class generation based on element type
+* Finished jQuery UI *accordion* and unified with *tabs* usage
+* Switched documentation to *Natualdocs at http://naturaldocs.org*
+* Added build.xml for generating documentation and minifying JavaScript
 
 **0.1**
 
-- Initial release
+* Initial release
 
 ## License