Form editor

The form editor supports development of HTML forms associated with Zero Resource Model models.

The Form Editor creates artifacts that require the zero.dojo runtime dependency

The form editor is a WYSIWYG ZRM form development environment, in which you can create / edit ZRM forms. The form editor work in conjunction with the Zero resource model editor,which comes to realiation in the following ways:

Top-down approach - A form is created in the form editor is it acts as a base from which a model is derived. If you choose to use this approach, the generating form wil be automatically mapped to the first model that was derived from the form
Bottom-up approach - A model is created in the model editor is it acts as a base from which a form is derived. If you choose to use this approch, all the generated forms will be mapped to the initial model

Working in the form editor

The following example shows the form model file.

In order to understand how to work with the form editor, let's look at it's main components:
From editor top level components

The form editor include two main areas:

On the right hand side a palette. In order to add fields it is possible either to click on the appropriate entry in the palete or simply to drag it onto the editing area
On the left hand side an editing area. The editing area is devided to two parts:
1. On the top there are the form`s title and desciption. In order to edit them all you need to do is click on the element you'd to edit.
2. The main editing area holds all the fields. It is possible to reorder the fields by draging and droping them onto the needed position in the form. Also, for each field the following elements can be edited:
  - Title: by clicking on the field`s title area
  - Hint: by clicking on the field`s hint area
  - Required: by clicking on the field`s required marker (the *) you toggle this property`s value between required and not required
  - Default Value: by setting the value of the field (for example typing in a text field or selecting in a dropdown field
  For each field the following actions can be performed:
  - Open properties - by clicking on the properties button
  - Delete - by clicking on the delete button

By pressing the properties button, you open the properties dialog, which is built of two tabs:

Basic properties:

Allows you to edit all the field`s basic properties - these properties are similar to almost of the fields.
Advanced properties:

Allows you to edit the field`s advanced properties - each field has its own set of advanced properties.

The content is a JSON document that describes an HTML form. The editor manipulates this file; the form widget in the zero.dojo module uses this file at run time to render a form in the browser.

Form editor fields` properties

The following sections contain details about the supported form fields that can be described in a form model file.

Text field

The Text field allows the application user to input text values to the form. The following properties can be defined for this field:

title
required
hint
description
width
ID (short name)
Immutable
default_value

Number field

The Number field allows the application user to input number values to the form. The following properties can be defined for this field:

title
required
hint
description
width
ID (short name)
Immutable
default_value
type
range

Date field

Date field allows the application user to input date values to the form. The following properties can be defined for this field:

title
required
hint
description
ID (short name)
Immutable
default_value
range

Time field

The Time field allows the application user to input time values to the form. The following properties can be defined for this field:

title
required
hint
description
range
ID (short name)
Immutable
default_value

Checkbox field

The Checkbox field allows the application user to input Boolean values to the form. The following properties can be defined for this field:

title
hint
description
ID (short name)
Immutable
default_value

Combo field

The Combo field allows the application user to input time values into the form, but only from a list that you define. The following properties can be defined for this field:

title
required
hint
description
ID (short name)
Immutable
default_value
options

Field properties

The application user can set the following properties for the form fields:

Title: An identifying title or name.
Description: Explains to the application user the purpose of the field and how it is to be used.
Required: Specifies whether the user is required to fill in the field. (To change it, you can also click the asterisk on the left of the field name.) When the field is not mandatory, the asterisk is semi-opaque.
Hint: You can type text that the user sees when entering data. This text is always visible to the user. By default, there is no hint text.
default_value: The default value of the field as it would appear when the ZRM form is used during run time
Immutable: A boolean property that states whether the field`s value can be edited after it was submitted for the first time
Range: Some fields allow you to specify a range of values where you define a minimum value and a maximum value. The user is then limited to entering a value that falls within this range. Specifying the range is optional. For example, use a number field to specify someone's age (in years), where the minimum age is 0 (in this case, a negative number is not allowed) and the maximum is 120.
Width: For some fields you can set the width of the field displayed on the screen to short, medium, or long. The display width depends on your definitions, for example your font size and screen resolution.
Type: A number can be integer or decimal.
Options: The list of options from which the user can select.
dataId: Maps between the form fields and the relevant resource model fields.
ID (short name): The field`s identifier, this identifier is used to access the field in a JavaScipt code that is ivnoked by the event handler

Form editor fields` events

Each field has an event handler and it is possible to define JavaScript code that would be invoked after a certain event is fired. The code itself can be entered only in the source tab, and it is possible to invoke code that resides in other .js files, as long as they are included in the .html page

The list of events is as follows:

OnChange - this event is invoked whenever the field`s value gets changed
onMouseOut - this event is invoked whenever the cursor leaves the field`s area
onMouseOver - this event is invoked whenever the cursor is over the field`s area
onClick - this event is invoked whenever the field is clicked
onValid - this event is invoked whenever the field`s value gets valid
onInvalid - this event is invoked whenever the field`s value gets invalid

To illustrate this, we'll show an example of a form that uses the event handler. The form itself is built of three fields, one for the person`s name, other is for the person`s gender and the third one is to specify whether the person is pregnant. We would like to disable the third field if the person`s gender is male. The first example shows how to embed code within the form`s model file - see it in the "onChange" event of the Gender field. Note that if you write the code within the form model's file, the this keyword refers to the field.

{
   "model": "person",
   "title": "Person",
   "description": "Person details",
   "fields": [
      {
         "dataId": "name",
         "title": "Name",
         "shortName": "name_id",
         "required": true,
         "type": "Text",
         "description": "",
         "default_value": "",
         "immutable": false,
         "onValid": "",
         "onInvalid": "",
         "onMouseOut": "",
         "onChange": "",
         "onMouseOver": "",
         "onClick": ""
      },
      {
         "dataId": "gender",
         "title": "Gender",
         "shortName": "gender_id",
         "required": true,
         "type": "Select",
         "description": "",
         "default_value": "",
         "immutable": false,
         "options": [
            {
               "opt": "Male",
               "val": "Male"
            },
            {
               "opt": "Female",
               "val": "Female"
            }
         ],
         "selected_option": "Female",
         "onMouseOut": "",
         "onChange": "this.containingForm.formFields.pregnant_id.setDisabled(this.getValue() === 'Male');",
         "onMouseOver": "",
         "onClick": ""
      },
      {
         "dataId": "pregnant",
         "title": "Pregnant",
         "shortName": "pregnant_id",
         "required": true,
         "type": "Checkbox",
         "description": "",
         "default_value": "false",
         "immutable": false,
         "onMouseOut": "",
         "onChange": "",
         "onMouseOver": "",
         "onClick": ""
      }
   ]
}

The second example shows how to do the exact same thing when using an external .js file.

The .js file`s content:

function disablePregnantField(genderField){
    genderField.containingForm.formFields.pregnant_id.setDisabled(genderField.getValue() === 'Male');
}

The form's model content - look at the "onChange" in the event gender field

{
   "model": "person",
   "title": "Person",
   "description": "Person details",
   "fields": [
      {
         "dataId": "name",
         "title": "Name",
         "shortName": "name_id",
         "required": true,
         "type": "Text", 
         "description": "",
         "default_value": "",
         "immutable": false,
         "onValid": "",
         "onInvalid": "",
         "onMouseOut": "",
         "onChange": "",
         "onMouseOver": "",
         "onClick": ""
      },
      {
         "dataId": "gender",
         "title": "Gender",
         "shortName": "gender_id",
         "required": true,
         "type": "Select",
         "description": "",
         "default_value": "Female",
         "immutable": false,
         "options": [
            {
               "opt": "Male",
               "val": "Male"
            },
            {
               "opt": "Female",
               "val": "Female"
            }
         ],
         "selected_option": "Female",
         "onMouseOut": "",
         "onChange": "disablePregnantField(this);",
         "onMouseOver": "",
         "onClick": ""
      },
      {
         "dataId": "pregnant",
         "title": "Pregnant",
         "shortName": "pregnant_id",
         "required": true,
         "type": "Checkbox",
         "description": "",
         "default_value": "false",
         "immutable": false,
         "onMouseOut": "",
         "onChange": "",
         "onMouseOver": "",
         "onClick": ""
      }
   ]
}

Form properties

The form properties are as follows:

Title - the title of the form
Description - the description of the form
Model - the name of the ZRM json file that this form is mapped to