Updated readme to include a "Getting started" example.

Also added an example.html file that matches the "Getting started" example.
christianbundy · Jun 4, 2012 · 62de530 · 62de530
1 parent cb0b955
commit 62de530
Show file tree

Hide file tree

Showing 2 changed files with 118 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -2,32 +2,96 @@ JSON Form
 =========
 
 The JSON Form library is a JavaScript client-side library that takes a
-structured data model defined as a [JSON Schema](http://json-schema.org/) as
+structured data model defined using [JSON Schema](http://json-schema.org/) as
 input and returns a [Bootstrap](http://twitter.github.com/bootstrap/)-friendly
 HTML form that matches the schema.
 
-The layout of the generated HTML form may be fine-tuned and completed through
-a simple declarative mechanism. The generated HTML form includes client-side
-validation logic that provides direct inline feedback to the user upon form
-submission.
+The generated HTML form includes client-side validation logic that provides direct inline feedback to the user upon form submission (provided a JSON Schema validator is available). If values are valid, the JSON Form library uses submitted values to create the JavaScript data structure that matches the data model.
+
+The layout of the generated HTML form may be entirely fine-tuned through
+a simple declarative mechanism.
+
+
+Getting started
+---------------
+
+The example below creates a form that asks for the user's name and age. The user's name is a required field, while the age is optional.
+
+```<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Getting started with JSON Form</title>
+    <link rel="stylesheet" style="text/css" href="deps/opt/bootstrap.css" />
+  </head>
+  <body>
+    <h1>Getting started with JSON Form</h1>
+    <form></form>
+    <div id="res" class="alert"></div>
+    <script type="text/javascript" src="deps/jquery.min.js"></script>
+    <script type="text/javascript" src="deps/underscore.js"></script>
+    <script type="text/javascript" src="deps/opt/jsv.js"></script>
+    <script type="text/javascript" src="lib/jsonform.js"></script>
+    <script type="text/javascript">
+      $('form').jsonForm({
+        schema: {
+          name: {
+            type: 'string',
+            title: 'Name',
+            required: true
+          },
+          age: {
+            type: 'number',
+            title: 'Age'
+          }
+        },
+        onSubmit: function (errors, values) {
+          if (errors) {
+            $('#res').html('<p>I beg your pardon?</p>');
+          }
+          else {
+            $('#res').html('<p>Hello ' + values.name + '.' +
+              (values.age ? '<br/>You are ' + values.age + '.' : '') +
+              '</p>');
+          }
+        }
+      });
+    </script>
+  </body>
+</html>```
+
+Loading this page in a browser renders a form with two input fields and a submit button. The ```onSubmit``` function is called upon form submission. If you press "Submit" without entering values or if the age you enter is not a number, error messages appear next to the input fields.
+
+NB: Paths in this example are relative to the root of the JSON Form project.
 
 
 Documentation
 -------------
-Reference documentation for the JSON Form library is available on the
-[Joshfire Developer Web site](http://developer.joshfire.com/doc/dev/ref/jsonform)
+
+You can do much more with the JSON Form library. You may define a more complex data model that includes arrays and objects for instance, or you may control the layout of the form to include fieldsets, expandable sections or tabs. For more information, check the [reference documentation for JSON Form](http://developer.joshfire.com/doc/dev/ref/jsonform) on Joshfire's Developer Web site.
 
 
 Dependencies
 ------------
-The JSON Form library depends on:
-- [jQuery](http://jquery.com/) (the library should also work with
-[Zepto.js](http://zeptojs.com/))
+
+At a minimum, the JSON Form library depends on:
+- [jQuery](http://jquery.com/)
 - The [Underscore.js](http://documentcloud.github.com/underscore/) utility belt
-- The [JSON Schema Validator](https://github.com/garycourt/JSV) for validation
-purpose (optional)
+
+The JSON Form library may require further libraries, depending on the features you need for the forms you need to render. In particular:
+- [Bootstrap](http://twitter.github.com/bootstrap/) v2.0.3 or above is more or less needed (unless you enjoy ugly forms, that is) if you don't provide your own styles. JSON Form only needs the ```bootstrap.css``` file.
+- The [JSON Schema Validator](https://github.com/garycourt/JSV) is used to detect and report validation errors upon form submission. The [deps/opt](deps/opt) folder contains a "build" of the JSON Schema Validator for use in JSON Form.
+- [jQuery UI Sortable](http://jqueryui.com/demos/sortable/) v1.8.20 or above is required for drag-and-drop support within arrays and tabarrays. Note the plugin itself depends on jQuery IU Core, jQuery UI Mouse, and jQuery UI Widget.
+- [wysihtml5](http://jhollingworth.github.com/bootstrap-wysihtml5/) is required if the form uses ```wysihtml5``` textarea fields.
+
+All of these libraries are in the [deps](deps) folder, although you might want to check their respective Web site for more recent versions.
+
+NB: JSON Form also uses ```JSON.parse``` and ```JSON.stringify``` which is normally already natively supported by all modern browsers. You may use a JSON library otherwise.
 
 
 License
 -------
+
 The JSON Form library is licensed under the [MIT license](LICENSE).
+
+All the libraries that JSON Form may depend on are licensed under the MIT license, except for the JSON Schema Validator, licensed under the BSD 3 Clause license.
diff --git a/example.html b/example.html
@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Getting started with JSON Form</title>
+    <link rel="stylesheet" style="text/css" href="deps/opt/bootstrap.css" />
+  </head>
+  <body>
+    <h1>Getting started with JSON Form</h1>
+    <form></form>
+    <div id="res" class="alert"></div>
+    <script type="text/javascript" src="deps/jquery.min.js"></script>
+    <script type="text/javascript" src="deps/underscore.js"></script>
+    <script type="text/javascript" src="deps/opt/jsv.js"></script>
+    <script type="text/javascript" src="lib/jsonform.js"></script>
+    <script type="text/javascript">
+      $('form').jsonForm({
+        schema: {
+          name: {
+            type: 'string',
+            title: 'Name',
+            required: true
+          },
+          age: {
+            type: 'number',
+            title: 'Age'
+          }
+        },
+        onSubmit: function (errors, values) {
+          if (errors) {
+            $('#res').html('<p>I beg your pardon?</p>');
+          }
+          else {
+            $('#res').html('<p>Hello ' + values.name + '.' +
+              (values.age ? '<br/>You are ' + values.age + '.' : '') +
+              '</p>');
+          }
+        }
+      });
+    </script>
+  </body>
+</html>