Updated docs, deps and known limitations

Author: davidlgj

README.md

@@ -22,10 +22,10 @@ Schema Form uses convention over configuration, so it comes packaged with some s
 
 JSON Form
 ---------
-Schema Form is inspired by the nice [JSON Form](https://github.com/joshfire/jsonform) library and aims to be roughly compatible with it, especially its form definition. So what sets Schema Form apart from JSON Form? 
+Schema Form is inspired by the nice [JSON Form](https://github.com/joshfire/jsonform) library and aims to be roughly compatible with it, especially its form definition. So what sets Schema Form apart from JSON Form?
 
-1. Schema Form integrates deeply with AngularJS and uses AngularJS conventions to handle forms. 
-2. Schema Form uses [tv4](https://github.com/geraintluff/tv4) for validation, making it compatible with version 4 of the JSON schema standard. 
+1. Schema Form integrates deeply with AngularJS and uses AngularJS conventions to handle forms.
+2. Schema Form uses [tv4](https://github.com/geraintluff/tv4) for validation, making it compatible with version 4 of the JSON schema standard.
 3. By default, Schema Form generates Bootstrap 3-friendly HTML.
 
 
@@ -79,27 +79,41 @@ Installation
 
 ### Bower
 
-It's simplest to install Schema Form using [Bower](http://bower.io/) since it will come packaged with all of its dependencies.
+It's simplest to install Schema Form using [Bower](http://bower.io/).
 
 ```bash
 bower install angular-schema-form
 ```
 
+This will install the latest release and basic dependencies. See
+[dependecies section below](#dependencies).
+
 ### Manual
 
 You can also just download the contents of the `dist/` folder and add dependencies manually.
 
 ### Dependencies
 
+Schema form has a lot of dependencies, most of which are optional. Therefor
+
 Schema Form depends on:
 
-1. [AngularJS](https://angularjs.org/) (duh!)
+1. [AngularJS](https://angularjs.org/) version 1.3.x is recomended. Version 1.2.x
+   has some limitation. See [known limitations](docs/knownlimitations.md).
 2. [angular-sanitize](https://docs.angularjs.org/api/ngSanitize)
-3. [bootstrap 3](http://getbootstrap.com/)
-4. [tv4](https://github.com/geraintluff/tv4)
-5. If you want to use the date picker, you'll also need [jQuery](https://github.com/jquery/jquery) and [pickadate.js](http://amsul.ca/pickadate.js/)
-7. If you'd like to use drag-and-drop reordering of arrays, you'll also need [ui-sortable](https://github.com/angular-ui/ui-sortable) and its [jQueryUI](http://jqueryui.com/) dependencies. See the *ui-sortable* documentation for details about which parts of jQueryUI are needed. You can safely ignore these if you don't need reordering.
-8. Schema Form provides tabbed arrays through the form type `tabarray`. Tab arrays default to tabs on the left side. For these to work, you'll need to include the CSS from [bootstrap-vertical-tabs](https://github.com/dbtek/bootstrap-vertical-tabs). However, you won't need Bootstrap Vertical Tabs for horizontal tabs (the `tabType: "top"` option).
+3. [tv4](https://github.com/geraintluff/tv4)
+4. [objectpath](https://github.com/mike-marcacci/objectpath)
+5. [bootstrap 3](http://getbootstrap.com/)
+
+If you install via bower you get all of the above except bootstrap since we
+don't want to push a certain version or flavor on you. Also make
+sure you got the angular version you actually want.
+
+#### Additional dependecies
+
+1. If you want to use the date picker, you'll also need [jQuery](https://github.com/jquery/jquery) and [pickadate.js](http://amsul.ca/pickadate.js/)
+2. If you'd like to use drag-and-drop reordering of arrays, you'll also need [ui-sortable](https://github.com/angular-ui/ui-sortable) and its [jQueryUI](http://jqueryui.com/) dependencies. See the *ui-sortable* documentation for details about which parts of jQueryUI are needed. You can safely ignore these if you don't need reordering.
+3. Schema Form provides tabbed arrays through the form type `tabarray`. Tab arrays default to tabs on the left side. For these to work, you'll need to include the CSS from [bootstrap-vertical-tabs](https://github.com/dbtek/bootstrap-vertical-tabs). However, you won't need Bootstrap Vertical Tabs for horizontal tabs (the `tabType: "top"` option).
 
 The minified files include templates - no need to load additional HTML files.
 

docs/index.md

@@ -1,6 +1,7 @@
 Documentation
 =============
 
+1. [Basic Usage](#basic-usage)
 1. [Form types](#form-types)  
 1. [Default form types](#default-form-types)
 1. [Form definitions](#form-definitions)
@@ -22,6 +23,61 @@ Documentation
     1. [tabarray](#tabarray)
 1. [Post process function](#post-process-function)
 
+Basic Usage
+-----------
+
+First, expose your schema, form, and model to the $scope.
+
+```javascript
+function FormController($scope) {
+  $scope.schema = {
+    type: "object",
+    properties: {
+      name: { type: "string", minLength: 2, title: "Name", description: "Name or alias" },
+      title: {
+        type: "string",
+        enum: ['dr','jr','sir','mrs','mr','NaN','dj']
+      }
+    }
+  };
+
+  $scope.form = [
+    "*",
+    {
+      type: "submit",
+      title: "Save"
+    }
+  ];
+
+  $scope.model = {};
+}
+```
+
+Then load them into Schema Form using the `sfSchema`, `sfForm`, and `sfModel` directives.
+
+```html
+<div ng-controller="FormController">
+    <form sf-schema="schema" sf-form="form" sf-model="model"></form>
+</div>
+```
+
+The `sfSchema` directive doesn't need to be on a form tag, in fact it can be quite useful
+to set it on a div or some such inside the form instead. Especially if you like to prefix or suffix the
+form with buttons or fields that are hard coded.
+
+Example with custom submit buttons:
+```html
+<div ng-controller="FormController">
+  <form>
+    <p>bla bla bla</p>
+    <div sf-schema="schema" sf-form="form" sf-model="model"></div>
+    <input type="submit" value="Submit">
+    <button type="button" ng-click="goBack()">Cancel</button>
+  </form>
+</div>
+```
+
+
 Form types
 ----------
 Schema Form currently supports the following form field types out of the box:
@@ -332,7 +388,7 @@ of the titleMap can be HTML.
 }
 ```
 
-The submit button has btn-primary as default. The button has btn-default as default. 
+The submit button has btn-primary as default. The button has btn-default as default.
 We can change this with ```style``` attribute:
 ```javascript
 {
@@ -342,7 +398,7 @@ We can change this with ```style``` attribute:
     { type: 'button', style: 'btn-info', title: 'Cancel', onClick: "cancel()" }
   ]
 }
-``` 
+```
 
 ### button
 
@@ -357,14 +413,14 @@ the ```sf-schema``` directive.
 [
 ```
 
-The submit button has btn-primary as default. The button has btn-default as default. 
+The submit button has btn-primary as default. The button has btn-default as default.
 We can change this with ```style``` attribute:
 ```javascript
 [
   { type: 'button', style: 'btn-warning', title: 'Ok', onClick: function(){ ...  } }
   { type: 'button', style: 'btn-danger', title: 'Cancel', onClick: "cancel()" }
 [
-``` 
+```
 
 ### radios and radiobuttons
 Both type *radios* and *radiobuttons* work the same way, they take a titleMap
@@ -397,7 +453,7 @@ function FormCtrl($scope) {
 }
 ```
 
-With *radiobuttons*, both selected and unselected buttons have btn-primary as default. 
+With *radiobuttons*, both selected and unselected buttons have btn-primary as default.
 We can change this with ```style``` attribute:
 ```javascript
 function FormCtrl($scope) {
@@ -523,7 +579,7 @@ The *form* definition has the option ```ìtems``` that should be a list
 of form objects.
 
 The rendered list of subforms each have a *"Remove"* button and at the bottom there
-is an *"Add"* button. The default *"Add"* button has class btn-default and text Add. Both 
+is an *"Add"* button. The default *"Add"* button has class btn-default and text Add. Both
 could be changed using attribute ```add```, see example below.
 
 If you like to have drag and drop reordering of arrays you also need
@@ -640,10 +696,10 @@ By default the tabs are on the left side (follows the default in JSON Form),
 but with the option ```tabType``` you can change that to eiter *"top"* or *"right"*
 as well.
 
-Every tab page has a *"Remove"* button. The default *"Remove"* button has class btn-default 
-and text Remove. Both could be changed using attribute ```remove```, see example below. 
+Every tab page has a *"Remove"* button. The default *"Remove"* button has class btn-default
+and text Remove. Both could be changed using attribute ```remove```, see example below.
 
-In this case we have an *"Add"* link, not an *"Add"* button. Therefore, the attribute ```add``` 
+In this case we have an *"Add"* link, not an *"Add"* button. Therefore, the attribute ```add```
 only changes the text of the link. See example below.
 
 Bootstrap 3 doesn't have side tabs so to get proper styling you need to add the

docs/knownlimitations.md

@@ -0,0 +1,33 @@
+Known Limitations
+=================
+
+### Angular Version
+Schema Form works with AngularJS version 1.2.x or above, but version 1.3.x is recomended.
+
+This is because a bug in AngularJS 1.2 [#8039](https://github.com/angular/angular.js/issues/8039),
+which means that the ```ng-model``` directive has problem with values that uses a bracket notation instead of dot notation.
+```html
+<!-- dot notation -->
+<input ng-model="foo.bar.baz">
+
+<!-- bracket notation -->
+<input ng-model="foo['bar']['baz']">
+```
+
+So what does that mean for you as a user of Schema Form? Basically it boils down to that if you use AngularJS 1.2.x
+Schema Form uses dot notation, which means your property names in the JSON schema *must not contain any hyphens or other
+characters dot notation cannot handle*.
+
+Example schema that only works in 1.3
+```javascript
+{
+  "type": "object",
+  "properties": {
+    "key-with-hyphen": { "type": "string" },
+  }
+}
+```
+
+The "complex keys" example schema illustrates this as well.
+For more background check out issue [#41](https://github.com/Textalk/angular-schema-form/issues/41) and the PR that fixed
+it, [PR 43](https://github.com/Textalk/angular-schema-form/pull/43). Thanks to @mike-marcacci for his excellent work!