Edit the config.json File

Value Description

Leave the specified value as it is.

Provide a name of your choice to identify this Element. The name should be all lower-case without spaces and use hyphens to separate words for readability. Examples of identifiers used with the standard Elements supplied with Digitise Forms include "label" and "ndl-address-finder".

The name must be unique within the Form Studio Elements folder and must match the name given to the folder storing this Element. If you decide to give the Element a different name than that of its current folder name, you will need to change the folder name to match the new id.

Allows you to specify a version number for this iteration of your Element. The version number can be a single number or a dotted notation, e.g. 0.1 Note, however, that although the version must be numeric, non-numeric characters are not allowed (apart from '.'), the value is actually a string and must be enclosed in double quotes, e.g. "0.1.1". The number can have up to 4 parts, i.e. n.n.n.n

The version number is displayed in Form Studio in the Element gallery tooltips and an Element's Type property in the Properties Pane.

We recommend that you always increase the version number when making changes to an Element, especially once you have used the Element on a published form, so that you can check whether a form is using the latest version of an Element.

Enter a name of your choice to be displayed in the Element gallery to identify this Element to users of Form Studio.

The group name is used to group Elements in the Elements gallery. All Elements with the same group name will be displayed together in the gallery under the group name. You can specify an existing group name or start a new group by entering a new name here.

Allows you to enter a description of the Element to be displayed in the tooltip which displays when you hover your mouse pointer over the Element in the Elements gallery.

This must be the same name as specified in the id property above.

Specifies the name of the JavaScript file defining the Element's behaviour.

We recommend that you name this file the same as the name in the id property above with a '.js' file extension and that you store it in the same folder as the config.json file so you don't need to include a path with the file name.

Specifies the name of the HTML template file defining the Element's appearance.

We recommend that you name this file the same as the name in the id property above with a '.html' file extension and that you store it in the same folder as the config.json file so you don't need to include a path with the file name.

Specifies the name of a CSS file containing standard CSS styles. The styles included in a CSS file are accessible throughout the form by any Element's HTML, so you should be careful when choosing your selector names to prevent unexpected results occurring in other Elements.

We recommend that you name this file the same as the name in the id property above with a '.css' file extension and that you store it in the same folder as the config.json file so you don't need to include a path with the file name.

Styles specified in a CSS file are not editable within Form Studio.

This property allows you to exclude this Element from the Elements gallery. If you don't want this Element to appear in the gallery, include this property and set the value to true.

You might want to exclude an Element from the Elements Gallery where you are creating an Element which will only be a dependent Element within a complex Element and you don't want to use it on its own on your forms.

This key is only used with complex Elements and must be included when configuring a complex Element which imports other Elements.

It lists the dependent Elements used by the Element you are configuring and specifies the version of the dependent Element which this Element uses.

Exclude this key for simple Elements or complex Elements which don't import any other Elements.

The value takes the form of nested arrays, each array providing the name of a dependent Element and its version number, e.g.:

"dependencies":

[

[

"ndl-textbox",

"0.4"

],

[

"ndl-button",

"0.6"

],

[

"ndl-droplist",

"0.5"

],

[

"ndl-checkbox",

"0.7"

]

],

You need to specify all Elements which are used within the complex Element. The dependent Elements are identified by their unique identifier, as specified in the id property of their individual config.json files. The version number must match that specified in the version property of the same file.

If you later change the version number of a dependent Element, the complex Element will continue to work in forms that have already been published. If you want to use the complex Element with the new version of the dependent Element on a new form or to update an existing form, you will first need to edit the version number here in the complex Element's config.json.

Specifies the images to be used for this Element in the Elements gallery within Form Studio.

Two images are required - one 32x32 pixels and one 48x48 pixels. The smaller image will be displayed in the Element gallery itself and the larger one is displayed in the tooltip displayed by hovering your mouse pointer over the Elements in the gallery.

The name of both files must be the same as the name in the id property above, followed by '-32' or '-48' according to the size of the image. The files should be 'png' format. For example, ndl-address-finder-32.png and ndl-address-finder-48.png. We recommend that you store these files in the same folder as the config.json file and so you don't need to include a path with the file name.

The properties object allows you to define configurable properties for this Element to appear in Form Studio's Properties Pane.

All Elements automatically have Name, Code Name, Visible and Disabled Properties. The properties object allows you to add extra properties of your choice giving you the ability to configure the Element within Form Studio.

Each property is defined within a name/value pair in which the name identifies the property and the value takes the form of an object containing one or more further name/value pairs defining the property.

For complex Elements, properties of an Element which will be bound to mappable properties within their dependent Elements must be defined as objects containing at least one member. Here in the config.json file, therefore, the property name will be in the form <object name>.<member name>. For example, the Address Finder Element imports several standard Digitise Forms Text Box Elements, each of which has a value property storing the current value and which can be input and output mapped. The Address Finder itself needs properties which will bind to the value property of each imported text box. If you look in the Address Finder's config.json file you will see these properties are called addressline1.value, addressline2.value, addressline3.value etc. The object and member names can be anything of your choosing and in the Address Finder the properties could have all been members of the same object, e.g. value.addressline1, value.addressline2 etc.

For properties in simple Elements or properties in complex Elements which won't be bound to mappable properties in dependent Elements, the properties don't need to be defined as objects in this way.

For example, you could define the following properties:

"properties":

{

"label":

{

"type": "string",

"name": "Label",

"category": "Standard",

"description": "The label text for ...",

"defaultValue": "Textbox",

"multiline": true,

},

"value":

{

"type": "string",

"name": "Value",

"category": "Data",

"description": "The text to be ...",

"dataType": "String"

"direction": "out"

"validates": true,

},

"changed":

{

"type": "event",

"name": "Changed",

"category": "Events",

"description": "The event that is ..."

"parameters":

[

"ev"

]

}

"errormessage-style":

{

"type": "style",

"name": "Error Message",

"category": "Advanced",

"group": "Styles",

"description": "The style applied ...",

},

}

In the above example, the first property defines a configurable label for the Element which will provide a multi-line text box in the Properties Pane for you to specify the label text.

The second property, defines a property which can be mapped to a Datasource allowing output mapping only and which can be configured to validate the user input. Form Studio will automatically provide mapping and validation options within the Properties Pane to configure this property.

The third property provides a Changed Event allowing you to determine what should happen when the Element's content changes. Again, Form Studio will automatically provide the Event configuration options for you in the Properties Pane.

The final property defines a property to apply a style to error messages for this Element. Form Studio will automatically provide a drop-down box listing the available styles in the Properties Pane.

Note that property names should be written in dash case, i.e. using '-' to separate words instead of spaces.

 

The type name/value pair determines how the Properties Pane will present the property:

"string"

Displays a single-line text box for the property's value to be viewed and edited.

 

"bool" or "boolean"

Displays a checkbox.

 

"style"

Displays a drop-down list listing all the available styles.

 

"recordset"

Used with Elements which require a table of data, such as the standard Check List, Radio List and Recordset Elements supplied with Form Studio. Specifying this type for a property will display options in the Properties Pane which allow you to define a mapping to an existing Datasource mappings or create a new Dataset. The standard Check List, Drop List and Radio List Elements use this property type to define a property (list items) which will provide the data to populate the list of available choices and have a separate value property which is used to handle the current selection. The Recordset Element, on the other hand, has a single value property, with a type of recordset, which can be used to both display input data and output data entered or edited by the user. See below for more information about using the recordset type.

 

"event"

Displays the event configuration options in the Properties Pane and also requires you to include the parameters name/value pair exactly as shown in the example above.

 

The dataType name/value pair determines whether a property requires the Properties Pane to display data mapping options, allowing the property to be input/output mapped to a Dataset field within a Datasource.

Note that this is a separate data mapping to that used when you specify the type name/value pair described above with a value of recordset. For example, the standard Check List and Radio List Elements have a recordset property (list item) used to populate the list of available choices and a separate value property, defined with a dataType of "String", to handle the input /output mappings of the current selection. On the other hand, the standard Recordset Element has a value property which has a type of "recordset" and which handles the input and output mappings for the Element and doesn't have any property using the dataType name/value pair.

If you include the dataType name/value pair, with a value of "String", the data mapping options will be displayed. The direction name/value pair can then be used to determine in which direction mapping will be allowed. Specify "in" for input mapping only, or "out" for output mapping only. To allow mapping in both directions, either specify a value of "both" or omit this name/value pair.

Data mapped properties can be used inside the AngularJS directive, directly or indirectly, as the value for an ng-model attribute. Ng-model will effect a bi-directional binding between the value of the HTML input element and the datavariable specified by this mapped property. Digitise Forms will generate this datavariable, together with code mapping it to fields in datasources as appropriate.

 

If you include the validates name/value pair with a value of true, the Properties Pane will add the options to specify validation rules for the property. You can only specify validation for one property and normally this would be a data mapping property, as shown in the example above.

 

The category and group name/value pairs specify which tab within the Properties Pane this property will appear under.

The category name/value pair specifies the tab and can take one of the following values: "Standard", "Appearance", "Rules", "Data", "Events" or "Advanced". "Standard" means the property will be displayed at the top of the Pane above the tab bar with the Name and Code Name properties.

The other values match the names of the Properties Pane tabs and will position the property on the tab specified.

The group name/value pair allows you to divide the properties into groups, or categories, within a tab. You can specify an existing group name to add the property into that group or enter a new name to add a new group to the tab. Alternatively, you can omit the group name/value pair if you don't want to place the property within a group. Generally, properties in the Standard Category and those under the Appearance, Rules, Data and Events tabs aren't divided into groups, but those under the Advanced tab often are.

Groups are displayed alphabetically within a tab and properties are displayed within their group in the order in which they appear within the config.json file. Properties which have no group, will be displayed in the order in which they appear in the config.json file above any groups.

 

If you specify a type of recordset, the Properties Pane will provide options to allow you to configure the property's data mapping. It requires two additional name/value pairs within the property definition - "metadata" and "columns". "columns" is used where you know how many columns the Dataset will have and the type of data which will be stored in each column. It's value consists of an object providing a definition of each column. "metadata" is used where you don't know the number and type of columns that will be required. Its value consists of an object defining the information you want to collect about each potential column. This information is defined using name/value pairs which specify the properties of each column. You must include both objects, but whichever one you don't use should be left empty. The standard Drop List Element provides an example of using the columns object and the standard Recordset Element an example of using the metadata object.

 

Look in the element-schema.json file, mentioned earlier, for a list of all possible name/value pairs which can be included within the properties object. The values which can be included are the same for both simple and complex Elements.