openmct/platform/forms
Victor Woeltjen fd63aa30ea [Forms] Add test for date-time controller
Add test case to complete coverage of date-time controller;
done in the context of WTD-884 (albeit unrelated) to improve
code coverage.
2015-06-10 14:31:34 -07:00
..
lib [Forms] Get date-time as UNIX timestamp 2014-11-28 13:35:24 -08:00
res/templates [Forms] Allow date-time controls to be optional 2015-06-04 09:15:04 -07:00
src [Forms] Show initial value in datetime control 2015-06-04 09:16:25 -07:00
test [Forms] Add test for date-time controller 2015-06-10 14:31:34 -07:00
bundle.json [Fixed Position] Add text, image properties 2015-02-23 19:16:09 -08:00
README.md [Forms] Document mct-toolbar 2015-01-15 15:43:20 -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>

Using toolbars is similar:

<mct-toolbar ng-model="myModel" structure="myStructure" name="myToolbar">
</mct-toolbar>

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.

Toolbar structure

A toolbar's structure is described similarly to forms, except that there is no notion of rows; instead, there are items.

{
    "name": ... title to display for the form, as a string ...,
    "sections": [
        {
            "name": ... title to display for the section ...,
            "items": [
                {
                    "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 ...
                    ],
                    "disabled": ... true if control should be disabled ...
                    "size": ... size of the control (for textfields) ...
                    "click": ... function to invoke (for buttons) ...
                    "glyph": ... glyph to display (for buttons) ...
                    "text": ... text withiin control (for buttons) ...
                },
                ... 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.
  • color: A color picker.
  • button: A button.
  • 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.