From 3a7f35487d0a1740bb1ea6306292fc64f086e519 Mon Sep 17 00:00:00 2001
From: Victor Woeltjen <victor.woeltjen@nasa.gov>
Date: Fri, 28 Nov 2014 15:58:19 -0800
Subject: [PATCH] [Forms] Add usage documentation

Add documentation for using the mct-form directive
introduced for WTD-530.
---
 platform/forms/README.md | 90 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 87 insertions(+), 3 deletions(-)

diff --git a/platform/forms/README.md b/platform/forms/README.md
index cc81b4ca86..d435b023fd 100644
--- a/platform/forms/README.md
+++ b/platform/forms/README.md
@@ -1,3 +1,87 @@
-This bundle contains a general implementation of forms in Open MCT Web. 
-This allows forms to be expressed using a reasonably concise declarative 
-syntax, and rendered as Angular templates in a consistent fashion. 
+# Overview
+
+This bundle contains a general implementation of forms in Open MCT Web.
+This allows forms to be expressed using a reasonably concise declarative
+syntax, and rendered as Angular templates in a consistent fashion.
+
+# Usage
+
+To include a form with a declarative definition, use the `mct-form`
+directive, e.g.:
+
+    <mct-form ng-model="myModel" structure="myStructure" name="myForm">
+    </mct-form>
+
+The attributes utilized by this form are as follows:
+
+* `ng-model`: The object which should contain the full form input. Individual
+  fields in this model are bound to individual controls; the names used for
+  these fields are provided in the form structure (see below).
+* `structure`: The structure of the form; e.g. sections, rows, their names,
+  and so forth. The value of this attribute should be an Angular expression.
+* `name`: The name in the containing scope under which to publish form
+  "meta-state", e.g. `$valid`, `$dirty`, etc. This is as the behavior of
+  `ng-form`. Passed as plain text in the attribute.
+
+## Form structure
+
+A form's structure is described as a JavaScript object in the following form:
+
+    {
+        "name": ... title to display for the form, as a string ...,
+        "sections": [
+            {
+                "name": ... title to display for the section ...,
+                "rows": [
+                    {
+                        "name": ... title to display for this row ...,
+                        "control": ... symbolic key for the control ...,
+                        "key": ... field name in ng-model ...
+                        "pattern": ... optional, reg exp to match against ...
+                        "required": ... optional boolean ...
+                        "options": [
+                            "name": ... name to display (e.g. in a select) ...,
+                            "value": ... value to store in the model ...
+                        ]
+                    },
+                    ... and other rows ...
+                ]
+            },
+            ... and other sections ...
+        ]
+    }
+
+Note that `pattern` may be specified as a string, to simplify storing
+for structures as JSON when necessary. The string should be given in
+a form appropriate to pass to a `RegExp` constructor.
+
+## Adding controls
+
+Four standard control types are included in the forms bundle:
+
+* `textfield`: An area to enter plain text.
+* `select`: A drop-down list of options.
+* `checkbox`: A box which may be checked/unchecked.
+* `datetime`: An input for UTC date/time entry; gives result as a
+  UNIX timestamp, in milliseconds since start of 1970, UTC.
+
+New controls may be added as extensions of the `controls` category.
+Extensions of this category have two properites:
+
+* `key`: The symbolic name for this control (matched against the
+  `control` field in rows of the form structure).
+* `templateUrl`: The URL to the control's Angular template, relative
+  to the resources directory of the bundle which exposes the extension.
+
+Within the template for a control, the following variables will be
+included in scope:
+
+* `ngModel`: The model where form input will be stored. Notably we
+  also need to look at `field` (see below) to determine which field
+  in the model should be modified.
+* `ngRequired`: True if input is required.
+* `ngPattern`: The pattern to match against (for text entry.)
+* `options`: The options for this control, as passed from the
+  `options` property of an individual row.
+* `field`: Name of the field in `ngModel` which will hold the value
+  for this control.
\ No newline at end of file