View Types

View types

Each object in the viewModel element above should have the following structure:

{
    "type":<view type. On of the supported view types described below>
    "source":<reference to the name field in a dataType definition or a literal string>
    "items":<array of nested view items or literals>
    "title":<Label displayed for the element>
    "boxed":<boolean. If true will display this element within a box> 
}

View types categories

An element can be a display element or a view of an item in the dataModel.

Layout elements are used to format or layout the form and group elements in a more readable fashion.

The layout elements are row, col, template, section, repeat, table and grid

The literal type element can be used to display fixed text or HTML and is not tied to a source data type.

Any other element type is used to render a data type.

General view type parameters

Each view type parameter is described in the section Supported view types below with the particulars of its use however parameters that are applicable to every view type are described here and are called general parameters.

• class
• width
• title
• readonly
• source
• title
• displayOptions

class

String. Used to specify the CSS class to be added to the HTML rendered for a view type.

When using this parameter you must ensure that the classes are defined in the web application hosting the form.

width

String. This parameter will translate to width HTML attribute, as such it must be used with the sporadically, class would be preferred).

It will be handy usually for the columns view types for a table where more precise control of the column widths is required.

title

String. The name of the field.

readonly

Boolean. Whether the field should be readonly when the form is in edit mode. Useful for computed fields.

source

String. Name of the data type bound to this view type. In the case of nested view types, like a table, source must be a type that allow nested data types like list.

displayOptions

Object. Contains custom configuration specific to the view type.

Supported view types

• literal
• row
• col
• section
• repeat
• table
• text
• textarea
• readOnlyText
• selectOne
• selectManyCombo (text)
• select2 (text)
• link (text)
• selectMany (stringList)
• select2Many (stringList)
• selectManyCombo (stringList)
• number (number)
• currency (number)
• wordCloud (set)
• image (image)
• imageDialog (image)
• embeddedImage (image)
• document (document)
• autocomplete (species)
• speciesSelect (species)
• speciesSearchWithImagePreview (species)
• date (date)
• time (date)
• geoMap (geoMap)
• feature (feature)
• boolean (boolean)

literal

Purpose

Display text in source element, including html verbatim

Supported model types

None. This view type does not use any backing data type.

Parameters

mode

String. If absent or the value is 'edit' the value won't be displayed in read only mode. Thi is designed to allow to display instructional text when filling in forms, such instructions ase not required while viewing forms.

Example

{
              "source": "<a href='https://www.ala.org.au/faq/species-identification/' target='_blank'>Species identification FAQ</a>",
              "type": "literal"
            }

row

Purpose

Contained items for this type will be displayed in a separate row. It corresponds with Bootstrap row-fluid element.

Supported model types

None. This view type does not use any backing data type.

Parameters

items

List of view types to be displayed each in a separate row

Example

        {
          "computed": null,
          "type": "row",
          "items": [
            {
              "source": "<a href='https://www.ala.org.au/faq/species-identification/' target='_blank'>Species identification FAQ</a>",
              "type": "literal"
            }
          ]
        }

col

Purpose

Contained items for this type will be displayed in a separate column. To achieve its intended purpose, a col type should be nested within a row type. It corresponds with Bootstrap span-n element. The actual value for n will be calculated by the parent row divided by the number of siblings (items) for this col.

Supported model types

None. This view type does not use any backing data type.

Parameters

items

List of view types to be displayed each in a separate column

Example

{
  "type": "row",
  "items": [{
    "type": "col",
    "items": [{
      "type": "row",
      "items": [{
        "type": "col",
        "items": [{
          "preLabel": "Recorded by",
          "source": "recordedBy",
          "type": "text"
        }]
      }]
    }, {
      "type": "row",
      "items": [{
        "type": "col",
        "items": [{
          "preLabel": "Date",
          "source": "surveyDate",
          "type": "date"
        }]
      }]
    }, {
      "type": "row",
      "items": [{
        "type": "col",
        "items": [{
          "preLabel": "Time",
          "source": "surveyStartTime",
          "type": "time"
        }]
      }]
    }, {
      "type": "row",
      "items": [{
        "type": "col",
        "items": [{
          "preLabel": "Individuals",
          "source": "individualCount",
          "type": "number"
        }]
      }]
    }]
  }, {
    "type": "col",
    "items": [{
      "preLabel": "Notes",
      "source": "notes",
      "type": "textarea",
      "rows": 5
    }]
  }]
}

section

Purpose

Contained items for this type will be displayed within a box.

The purpose of this type is to facilitate grouping different elements of the form into "visual" groups or sections.

Depending on whether boxed parameter is available and set to true it will change the CSS styles for the generated HTML output.

Supported model types

None. This view type does not use any backing data type.

Parameters

items

List of view types contained within this section

boxed

Boolean. Display a border for this section.

Example

Example 1

    {
      "boxed": true,
      "title": "Location",
      "type": "section",
      "items": [{
        "computed": null,
        "type": "row",
        "items": [{
          "orientation": "horizontal",
          "source": "location",
          "type": "geoMap",
        }]
      }]
    }

In Example 1, given that boxed is true the form generated will have a containing div element with CSS style boxed-heading the title will be contained in the attribute data-content that can be used by the style to output the style as it suits.

The HTML output for the above example will look like this below:

<div class="boxed-heading" data-content="Location">
...
</div>

Example 2

    {
      "boxed": false,
      "title": "Location",
      "type": "section",
      "items": [{
        "computed": null,
        "type": "row",
        "items": [{
          "orientation": "horizontal",
          "source": "location",
          "type": "geoMap",
        }]
      }]
    }

In Example 2, given that boxed is false the form generated will have a containing div element with CSS style row-fluid output-section the title will be prepended in an HTML h4 element. As with the previous example the CSS styles can be customised to suit your needs.

The HTML output for the above example will look like this below:

<h4>Location</h4>
<div class="row-fluid output-section">
...
</div>

repeat

Purpose

repeat is used to display a data list of elements and when in edit mode it provides controls to add and remove elements.

Supported model types

list

Parameters

userAddedRows

Boolean that controls whether elements can be added/removed to its data model list

removeRowText

Text to display for remove button, only applicable when userAddedRows is set to true and form is in edit mode. Default value Remove Section

addRowText

Text to display for remove button, only applicable when userAddedRows is set to true and form is in edit mode. Default value Add

Example

    {
      "source": "outcomes",
      "items": [
        {
          "items": [
            {
              "items": [
                {
                  "source": "outcome",
                  "preLabel": {
                    "computed": "\\'Outcome \\' || (index + 1)"
                  },
                  "type": "text",
                  "readonly": true
                },
                {
                  "source": "status",
                  "preLabel": "Status of outcome",
                  "type": "selectOne"
                },
                {
                  "source": "outcomeNotAchievedReason",
                  "preLabel": "If the outcome was not achieved, what are the reasons?",
                  "type": "textarea"
                },
                {
                  "source": "outcomeResult",
                  "preLabel": "Describe the state of change detected between the baseline established at the commencement and follow-up monitoring",
                  "type": "textarea"
                }
              ],
              "type": "col"
            }
          ],
          "class": "output-section",
          "type": "row"
        }
      ],
      "type":"repeat"
    }

table

Purpose

table is used to display a data list of elements in a tabular fashion. Each element of source list will be displayed in a separate row. What columns get displayed are specified by the columns section. A table can optionally display additional rows, used as summary for example, by using the footer parameter.

Finally a table can display a footer.

Supported model types

list

Parameters

columns

It's an array of nested view model elements.

The elements source refer to nested elements of the source domain model for the table.

The columns parameter will drive 2 aspects of the table:

1. Table Headers
2. Contents for each column

Table Headers

For each element of columns array the following will be used to display a header for a column:

• title Is the text for the header
• width Is the column width expressed as percentage. The sum for all elements should add up to 100%
• The tooltip text for the help is sourced from the description property for the source dataType.

Contents for each column

The columns for each row will be displayed as per the standard format used for each view type.

It is worth nothing that data layout types can't be used as a column element.

footer

The only element of footer is the element array rows

footer

####### columns Very similar to the top level columns parameter for a table, this is an array of view types. The type of each element should not be a layout element.

More often than not each entry in columns will be a literal type or a type that can be computed in order for example to display and store aggregate data.

printRows

Integer. Number of rows to print when printing a blank form.

editableRows

Boolean. Enable buttons to edit rows.

allowRowDelete

Boolean. Add controls to delete rows.

If the form itself is in read only mode this parameter has no effect.

disableTableUpload

Boolean. Hides button at the bottom of the table to load data into a table from a file.

userAddedRows

Boolean. Shows button at the bottom of the table to add rows to the table.

Example

TBC

Table View Type Example

text

Purpose

Display a text box.

Supported model types

text.

Parameters

This view type has no specific parameters

Example

Test Output Form

textArea

Purpose

Display a text area.

This view type has no specific parameters

Supported model types

text.

Parameters

rows

Integer. Number of rows to display. Applicable only in edit mode.

cols

Integer. Number of rows to display. Applicable only in edit mode.

Example

Textarea View Type Example

readonlyText

Purpose

Display the value of a text data model.

This is useful when displaying computed fields.

The difference between using readonlyText and literal is that the later is only for static text not bound to a data model field.

Supported model types

text.

Parameters

This view type has no specific parameters

Example

TBC Example does not show anything, possibly defaultValue need some KO trigger/event to be fired to be shown in the form.

Readonly View Type Example

selectOne

Purpose

Allows to select a value from a text list.

The source must specify the list of accepted values as part of the constraints parameter.

Supported model types

text.

Parameters

This view type has no specific parameters

Example

SelectOne View Type Example