diff --git a/docs/content/cookbook/form.ngdoc b/docs/content/cookbook/form.ngdoc
index 2aeafc4d..c74b203b 100644
--- a/docs/content/cookbook/form.ngdoc
+++ b/docs/content/cookbook/form.ngdoc
@@ -24,25 +24,26 @@ allow a user to enter data.
});
it('should validate zip', function(){
- expect(using('.example').element(':input[name="user.address.zip"]').prop('className'))
- .not().toMatch(/ng-validation-error/);
+ expect(using('.example').
+ element(':input[ng\\:model="user.address.zip"]').
+ prop('className')).not().toMatch(/ng-invalid/);
using('.example').input('user.address.zip').enter('abc');
- expect(using('.example').element(':input[name="user.address.zip"]').prop('className'))
- .toMatch(/ng-validation-error/);
+ expect(using('.example').
+ element(':input[ng\\:model="user.address.zip"]').
+ prop('className')).toMatch(/ng-invalid/);
});
it('should validate state', function(){
- expect(using('.example').element(':input[name="user.address.state"]').prop('className'))
- .not().toMatch(/ng-validation-error/);
+ expect(using('.example').element(':input[ng\\:model="user.address.state"]').prop('className'))
+ .not().toMatch(/ng-invalid/);
using('.example').input('user.address.state').enter('XXX');
- expect(using('.example').element(':input[name="user.address.state"]').prop('className'))
- .toMatch(/ng-validation-error/);
+ expect(using('.example').element(':input[ng\\:model="user.address.state"]').prop('className'))
+ .toMatch(/ng-invalid/);
});
@@ -94,7 +97,7 @@ available in
* For debugging purposes we have included a debug view of the model to better understand what
is going on.
* The {@link api/angular.widget.HTML input widgets} simply refer to the model and are auto bound.
-* The inputs {@link api/angular.validator validate}. (Try leaving them blank or entering non digits
+* The inputs {@link guide/dev_guide.forms validate}. (Try leaving them blank or entering non digits
in the zip field)
* In your application you can simply read from or write to the model and the form will be updated.
* By clicking the 'add' link you are adding new items into the `user.contacts` array which are then
diff --git a/docs/content/cookbook/helloworld.ngdoc b/docs/content/cookbook/helloworld.ngdoc
index 8018a399..9562aaff 100644
--- a/docs/content/cookbook/helloworld.ngdoc
+++ b/docs/content/cookbook/helloworld.ngdoc
@@ -5,9 +5,16 @@
- Your name:
-
- Hello {{name}}!
+
+
+ Your name:
+
+ Hello {{name}}!
+
it('should change the binding when user enters text', function(){
diff --git a/docs/content/guide/dev_guide.compiler.directives.ngdoc b/docs/content/guide/dev_guide.compiler.directives.ngdoc
index 0f99e46b..3b233551 100644
--- a/docs/content/guide/dev_guide.compiler.directives.ngdoc
+++ b/docs/content/guide/dev_guide.compiler.directives.ngdoc
@@ -16,7 +16,7 @@ directives per element.
You add angular directives to a standard HTML tag as in the following example, in which we have
added the {@link api/angular.directive.ng:click ng:click} directive to a button tag:
-
+
In the example above, `name` is the standard HTML attribute, and `ng:click` is the angular
directive. The `ng:click` directive lets you implement custom behavior in an associated controller
diff --git a/docs/content/guide/dev_guide.expressions.ngdoc b/docs/content/guide/dev_guide.expressions.ngdoc
index 177a5e87..ab5a897b 100644
--- a/docs/content/guide/dev_guide.expressions.ngdoc
+++ b/docs/content/guide/dev_guide.expressions.ngdoc
@@ -51,9 +51,15 @@ You can try evaluating different expressions here:
-
+
+
Expression:
-
+
@@ -84,9 +90,18 @@ the global state (a common source of subtle bugs).
-
- Name:
-
+
+
+ Name:
+
@@ -158,7 +173,7 @@ Extensions: You can further extend the expression vocabulary by adding new metho
{name:'Mike', phone:'555-4321'},
{name:'Adam', phone:'555-5678'},
{name:'Julie', phone:'555-8765'}]">
- Search:
+ Search:
Name
Phone
diff --git a/docs/content/guide/dev_guide.forms.ngdoc b/docs/content/guide/dev_guide.forms.ngdoc
new file mode 100644
index 00000000..6849ff4e
--- /dev/null
+++ b/docs/content/guide/dev_guide.forms.ngdoc
@@ -0,0 +1,610 @@
+@ngdoc overview
+@name Developer Guide: Forms
+@description
+
+# Overview
+
+Forms allow users to enter data into your application. Forms represent the bidirectional data
+bindings in Angular.
+
+Forms consist of all of the following:
+
+ - the individual widgets with which users interact
+ - the validation rules for widgets
+ - the form, a collection of widgets that contains aggregated validation information
+
+
+# Form
+
+A form groups a set of widgets together into a single logical data-set. A form is created using
+the {@link api/angular.widget.form <form>} element that calls the
+{@link api/angular.service.$formFactory $formFactory} service. The form is responsible for managing
+the widgets and for tracking validation information.
+
+A form is:
+
+- The collection which contains widgets or other forms.
+- Responsible for marshaling data from the model into a widget. This is
+ triggered by {@link api/angular.scope.$watch $watch} of the model expression.
+- Responsible for marshaling data from the widget into the model. This is
+ triggered by the widget emitting the `$viewChange` event.
+- Responsible for updating the validation state of the widget, when the widget emits
+ `$valid` / `$invalid` event. The validation state is useful for controlling the validation
+ errors shown to the user in it consist of:
+
+ - `$valid` / `$invalid`: Complementary set of booleans which show if a widget is valid / invalid.
+ - `$error`: an object which has a property for each validation key emited by the widget.
+ The value of the key is always true. If widget is valid, then the `$error`
+ object has no properties. For example if the widget emits
+ `$invalid` event with `REQUIRED` key. The internal state of the `$error` would be
+ updated to `$error.REQUIRED == true`.
+
+- Responsible for aggregating widget validation information into the form.
+
+ - `$valid` / `$invalid`: Complementary set of booleans which show if all the child widgets
+ (or forms) are valid or if any are invalid.
+ - `$error`: an object which has a property for each validation key emited by the
+ child widget. The value of the key is an array of widgets which fired the invalid
+ event. If all child widgets are valid then, then the `$error` object has no
+ properties. For example if a child widget emits
+ `$invalid` event with `REQUIRED` key. The internal state of the `$error` would be
+ updated to `$error.REQUIRED == [ widgetWhichEmitedInvalid ]`.
+
+
+# Widgets
+
+In Angular, a widget is the term used for the UI with which the user input. Examples of
+bult-in Angular widgets are {@link api/angular.widget.input input} and
+{@link api/angular.widget.select select}. Widgets provide the rendering and the user
+interaction logic. Widgets should be declared inside a form, if no form is provided an implicit
+form {@link api/angular.service.$formFactory $formFactory.rootForm} form is used.
+
+Widgets are implemented as Angular controllers. A widget controller:
+
+- implements methods:
+
+ - `$render` - Updates the DOM from the internal state as represented by `$viewValue`.
+ - `$parseView` - Translate `$viewValue` to `$modelValue`. (`$modelValue` will be assigned to
+ the model scope by the form)
+ - `$parseModel` - Translate `$modelValue` to `$viewValue`. (`$viewValue` will be assigned to
+ the DOM inside the `$render` method)
+
+- responds to events:
+
+ - `$validate` - Emitted by the form when the form determines that the widget needs to validate
+ itself. There may be more then one listener on the `$validate` event. The widget responds
+ by emitting `$valid` / `$invalid` event of its own.
+
+- emits events:
+
+ - `$viewChange` - Emitted when the user interacts with the widget and it is necessary to update
+ the model.
+ - `$valid` - Emitted when the widget determines that it is valid (usually as a response to
+ `$validate` event or inside `$parseView()` or `$parseModel()` method).
+ - `$invalid` - Emitted when the widget determines that it is invalid (usually as a response to
+ `$validate` event or inside `$parseView()` or `$parseModel()` method).
+ - `$destroy` - Emitted when the widget element is removed from the DOM.
+
+
+# CSS
+
+Angular-defined widgets and forms set `ng-valid` and `ng-invalid` classes on themselves to allow
+the web-designer a way to style them. If you write your own widgets, then their `$render()`
+methods must set the appropriate CSS classes to allow styling.
+(See {@link dev_guide.templates.css-styling CSS})
+
+
+# Example
+
+The following example demonstrates:
+
+ - How an error is displayed when a required field is empty.
+ - Error highlighting.
+ - How form submission is disabled when the form is invalid.
+ - The internal state of the widget and form in the the 'Debug View' area.
+
+
+
+
+
+
+