'use strict';

/**
 * @ngdoc widget
 * @name angular.widget.form
 *
 * @description
 * Angular widget that creates a form scope using the
 * {@link angular.module.ng.$formFactory $formFactory} API. The resulting form scope instance is
 * attached to the DOM element using the jQuery `.data()` method under the `$form` key.
 * See {@link guide/dev_guide.forms forms} on detailed discussion of forms and widgets.
 *
 *
 * # Alias: `ng:form`
 *
 * In angular forms can be nested. This means that the outer form is valid when all of the child
 * forms are valid as well. However browsers do not allow nesting of `<form>` elements, for this
 * reason angular provides `<ng:form>` alias which behaves identical to `<form>` but allows
 * element nesting.
 *
 *
 * @example
    <doc:example>
      <doc:source>
       <script>
         function Ctrl() {
           this.text = 'guest';
         }
       </script>
       <div ng:controller="Ctrl">
         <form name="myForm">
           text: <input type="text" name="input" ng:model="text" required>
           <span class="error" ng:show="myForm.text.$error.REQUIRED">Required!</span>
         </form>
         <tt>text = {{text}}</tt><br/>
         <tt>myForm.input.$valid = {{myForm.input.$valid}}</tt><br/>
         <tt>myForm.input.$error = {{myForm.input.$error}}</tt><br/>
         <tt>myForm.$valid = {{myForm.$valid}}</tt><br/>
         <tt>myForm.$error.REQUIRED = {{!!myForm.$error.REQUIRED}}</tt><br/>
       </div>
      </doc:source>
      <doc:scenario>
        it('should initialize to model', function() {
         expect(binding('text')).toEqual('guest');
         expect(binding('myForm.input.$valid')).toEqual('true');
        });

        it('should be invalid if empty', function() {
         input('text').enter('');
         expect(binding('text')).toEqual('');
         expect(binding('myForm.input.$valid')).toEqual('false');
        });
      </doc:scenario>
    </doc:example>
 */
angularWidget('form', function(form){
  this.descend(true);
  this.directives(true);
  return ['$formFactory', '$element', function($formFactory, formElement) {
    var name = formElement.attr('name'),
        parentForm = $formFactory.forElement(formElement),
        form = $formFactory(parentForm);
    formElement.data('$form', form);
    formElement.bind('submit', function(event) {
      if (!formElement.attr('action')) event.preventDefault();
    });
    if (name) {
      this[name] = form;
    }
    watch('valid');
    watch('invalid');
    function watch(name) {
      form.$watch('$' + name, function(scope, value) {
        formElement[value ? 'addClass' : 'removeClass']('ng-' + name);
      });
    }
  }];
});

angularWidget('ng:form', angularWidget('form'));

@@ -743,24 +743,1618 @@
 ting.%0A *%0A *%0A
+ * # Submitting a form and preventing default action%0A *%0A * Since the role of forms in client-side Angular applications is different than in old-school%0A * roundtrip apps, it is desirable for the browser not to translate the form submission into a full%0A * page reload that sends the data to the server. Instead some javascript logic should be triggered%0A * to handle the form submission in application specific way.%0A *%0A * For this reason, Angular prevents the default action (form submission to the server) unless the%0A * %60%3Cform%3E%60 element has an %60action%60 attribute specified.%0A *%0A * You can use one of the following two ways to specify what javascript method should be called when%0A * a form is submitted:%0A *%0A * - ng:submit on the form element (add link to ng:submit)%0A * - ng:click on the first button or input field of type submit (input%5Btype=submit%5D)%0A *%0A * To prevent double execution of the handler, use only one of ng:submit or ng:click. This is%0A * because of the following form submission rules coming from the html spec:%0A *%0A * - If a form has only one input field then hitting enter in this field triggers form submit%0A * (%60ng:submit%60)%0A * - if a form has has 2+ input fields and no buttons or input%5Btype=submit%5D then hitting enter%0A * doesn't trigger submit%0A * - if a form has one or more input fields and one or more buttons or input%5Btype=submit%5D then%0A * hitting enter in any of the input fields will trigger the click handler on the *first* button or%0A * input%5Btype=submit%5D (%60ng:click%60) *and* a submit handler on the enclosing form (%60ng:submit%60)%0A *%0A * @param %7Bstring=%7D name Name of the form.%0A *%0A
  * @example%0A

add docs about form submission