openmct/platform/forms
Victor Woeltjen 4b51c37067 [Forms] Allow textfield size to be specified
Allow specification of size per-textfield from toolbar
structure definitions; WTD-684.
2015-01-15 15:10:57 -08:00
..
lib [Forms] Get date-time as UNIX timestamp 2014-11-28 13:35:24 -08:00
res/templates [Forms] Allow textfield size to be specified 2015-01-15 15:10:57 -08:00
src [Forms] Copy mct-form to mct-toolbar 2015-01-15 14:23:01 -08:00
test [Forms] Copy mct-form to mct-toolbar 2015-01-15 14:23:01 -08:00
bundle.json [Forms] Remove obsolete templates 2015-01-15 14:24:12 -08:00
README.md [Forms] Add usage documentation 2014-11-28 15:58:19 -08:00

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.