mDIS User Documentation

Editing a form field

Developer page

Template manager page

Extra Filters for Selection Boxes

Basics

  • Every form field is based on the data model column with the same name.
  • Depending on the data model column
    • only some input types are available,
    • the form field can be disabled or required,
    • the input type validators are automatically set,
    • some attributes are preset (i.e. the label and description)
  • Depending on the selected input type of the form field, some additional attributes can show up.

Edit a form template in the template manager and expand a column.

edit form field

Label

The label is permanently shown in the form.

  • Attribute in JSON file: "label"

Description

The description is an extended label text, rendered underneath most text fields, in a tiny font size. The description is only displayed when the form field has the input focus.

Thus, the description is never visible for fields that are disabled. Remember this when you design your forms. For a disabled field, choose a main label that is particularly clear.

  • Attribute in JSON file: "description"

Formatters for form text fields

This section is about "display-formatters", such as rounding numbers for easier viewing on screen.

Related: Article about form field validators which perform more complex calculations, which can also be made persistent. TODO add pseudo-fields. These are complex calculations, which are not persistent, (but still searchable?).

Display-Formatters are snippets of JavaScript code, typically used to format the value of a form field. They usually take the form of one-liners of JavaScript.

The formatter allows you to customize the display of a column value in the data table, e.g. for rounding, converting units of measurement, applying correction factors. You can use formatters to create hyperlinks to certain values.

Enter a valid JavaScript expression. For more complex calculations, you can use multiple expressions concatenated with “;”. The return value of the last expression will be displayed in the data table.

You can access column values in the calculation as follows:

  • this.$value: Get the value of the current column.
  • this.<columnName>: Get the value of the current column, or of any other column <columnName> (e.g. this.top_depth).
  • this.<relationColumn>.<columnName>: Get the value of the column <columnName> of a related record (lookup from a child/parent table). The relation is determined by the name of the related column.

The expression entered cannot be syntactically validated by mDIS. If there is a syntax error in the expression, you may see the text “ERROR in formatter” in the data table. In the console of your browser, you will find the error message of the problem.

The formatter is only used in the display of the data table. It is not used in the form or any reports, and the displayed value cannot be searched for!

Inline calculations with formatters

Given a value with lots of decimals:
let this.$value = 5.123499999

You could use a formatter to do this calculation, i.e. round the value:
this.$value.toPrecision(5)

Result displayed is:
5.1235

Conditional formatting of values

You could highlight values by appending some text to it:
this.$value + (this.top_depth > 4 ? ' (!)' : '')

The calculated value of the expression can contain JSON strings with HTML snippets, so you could, i.e., conditionally format values differently if they exceed a threshold value:
(this.$value > 70 ? '<span style="font-weight:bold">' + this.$value + '</span>' : this.$value).

If the calculated value of the expression starts with “http”, a link with this target will be created:
'https://igsn.org/' + this.$value

On click, the link will be opened in a separate browser tab.

If you want to create a link and format the displayed value, you have to provide the full HTML for the HTML a tag:
'<a href="https://igsn.org/"' + this.$value + '>' + this.$value + '</a>'

Where are the formatters stored, physically?

  • They are stored in the file system. They are editable in the form's JSON file.
  • See oldName Attribute in JSON file in directories dis_templates/forms and dis_templates/default/forms.
  • This Attribute was recycled, obviously, so the whole concept of mDIS formatters is a bit of a "hack". You have been warned.

Standard Text Fields

Type

The type of the form field determines what and how a user can enter data values. Which types are available depends on the type of the underlying model type, which in itself depends on the corresponding column datatype in the database.

Text

Normal input field for texts, but also for numbers.

form Input text

Textarea

Input for longer texts. Most browsers allow changing the size of the text area.

form Input text

Switch

Switch to toggle a boolean value. Displays as a select input with the values "yes" and "no". Can only be used for data model columns of type "Boolean".

form Input text

Date

Input to enter or select a date value:

form Input text

Datetime

Input to enter or select a date with a time.

form Input text

Select

Input to select one or multiple values from a list. (The button next to the form input is only available for a "value list" data source.)

form Input text

When this type is selected, several additional inputs are displayed. There are three possible data sources for a select input:

Value list

Please read the chapter on value lists.

Form Input - select source (ValueList)

You can select one of the existing value lists or enter a name for a new value list. In the generated form, you can edit the entries of the value list and lock it if you want to avoid that normal users can change the values.

Optionally, the users can enter values that are not contained in the value list.

You can filter the entries of the value list using an Extra filter.

Linked data model

Form Input - select source (Linked model)

  1. Select the data model to use as the data source for the select input.
  2. Select the column whose value shall be stored in the data model column when a record is selected.
  3. Select the column to display for selecting the record.

You can filter the records of the linked data model using an Extra filter.

Form Input - select source (related model)

For a data model column created for a relation to a different model, the input type "select" and the list source as well as the related data model are preset and cannot be changed.

Only the display column of the related model can be changed.

Disabled

The user can only see but not modify the data. This can be applied to all input types.

  • Attribute in JSON file: "disabled"

Required

This column must have a value. If it is empty, the record cannot be saved.

  • Attribute in JSON file: "required"

Calculate

The value of a form input field can be calculated based on other column values or data from related records like the parent relation.

This calculation takes place in the browser, so it can update as soon as a value used in the calculation changes.

You can use the same syntax as in the Formatter for data table.

Continue by reading the Extra Filters for Selection Boxes article.