Customise and Create Elements

Each Element is given a unique identifier name to distinguish it from other Elements but also has a user-friendly name which is displayed in the Studio's Elements gallery to identify the Element to users. The identifier should use hyphens (or dashes) to separate words and be valid for use within HTML, e.g. ndl-address-finder, whereas the friendly name can include spaces, e.g. Address Finder. Each Element includes a version number so that you can keep a check on which version of an Element has been used when Elements are updated or customised.

The Elements gallery looks for available Elements in the Studio's Elements folder. This folder contains a subfolder for each Element, which holds the files defining the Element and its operation. The subfolders are given the same names as the Elements' unique identifiers. The Elements folder is located below Form Studio's installation folder under the following path:

<Digitise Forms install folder>\Frameworks\AngularJS18_Bootstrap\Elements

If you have installed Digitise Forms to the default folder, the Elements folder's full path will be:

C:\Program Files (x86)\NDL Software\Digitise Forms\Frameworks\AngularJS18_Bootstrap\Elements

The Elements folder contains the standard Elements supplied with Form Studio, e.g. the standard Text Box Element has an identifier of ndl-textbox and is stored in a folder called:

<Digitise Forms install folder>\Frameworks\AngularJS18_Bootstrap\Elements\ndl-textbox

Easy access to the Elements folder is available by clicking the Elements button in the Resources group on the Ribbon's Developer tab, which will load the Windows File Explorer and automatically display the contents of this folder.

 

Each Digitise Forms project is stored in a set of folders on your development PC. By default your project folders will be under:

C:\Users\<username>\Documents\NDL Software\Form Studio\Projects\<project name>

These folders include the project's own Elements subfolder.

When you add an Element to a form for the first time, the Element's folder is copied from the Studio's Elements folder to the project's Elements folder. The copied folder has the same name as the original folder except that the Element's version number is appended to the end of the folder name. With complex Elements, any other Elements on which it depends, i.e. any Elements which it imports, are also copied to the project's Elements folder, if they are not already in it. If you subsequently add further instances of an Element to the same form, the Element is taken from the project's Elements folder rather than the Studio's Elements folder, which means that you will always be using the same version of an Element within a particular form.

Each Element definition is divided between a number of files. As a minimum, you need the following files:

• config.json

  Configuration file used by Form Studio to specify the Element's properties. The contents of this file are formatted using JSON and the file is always called config.json.

• <identifier>.html

  HTML template used to define the Element's appearance within the form.

• <identifier>.css

  Optional CSS file supplying additional styles to be used to specify the Element's appearance. Styles in this file are fixed and cannot be changed in the Element's properties.

• <identifier>.js

  JavaScript file containing the Element's AngularJS directive and additional code defining the Element's behaviour.

• <identifier>-32.png and <identifier>-48.png

  Image files providing an icon for the Element to be displayed in the Elements gallery.

 

All the files, with the exception of the config.json file, have the same name as the Element's unique identifier.

In addition to the files listed above, you can include additional JavaScript and CSS files along with image files or other resource files as required to define your Element - see Create a new Element below.

To create a new Element:

Decide upon a unique identifier name to identify this Element. Choose a name which will easily identify the Element to you later.

Create a new folder under the Elements folder and give it the same name as your unique identifier.

Generally, you may find it easier to use one or more existing Element as the basis for your new Element, rather than building it completely from scratch. Identify the Element(s) most suitable to act as your starting point and copy their files in to this folder. If you are copying more than one Element's files, rename the config.json file after copying each Element otherwise it will be overwritten when you copy in the next Element. If you are intending to create a complex Element, which will import other Elements, you don't need to copy the imported Element(s) into this folder, these will be picked up from their original folder(s).

After copying in the files you will need to change the file names to use your new Element's unique identifier. If you have copied in multiple Elements' files, choose the most appropriate '.html' and '.js' file to rename and if relevant a '.css' file. You may also need to rename the config.json file you intend to use back to config.json. Alternatively, you can create new files and cut and paste relevant sections from the example files into your new files, if you prefer. Remember to name your files using the unique identifier with the appropriate file extension, except for the config.json file, which must be called config.json.

You can now edit the files in your new folder, to create your new Element:

Edit the config.json file - you will need to edit this file to update the unique identifier and version number and specify any properties you want to make available for your new Element within Form Studio's Properties Pane.

Edit the <identifier>.html file - this file provides the HTML template which will be used to define the appearance of the Element within the browser. You can edit or create an optional CSS file which can provide additional styling for the Element.

Edit the <identifier>.js file - this file provides JavaScript code to define the Element's behaviour.

Edit the icon files - these are the <identifier>-32.png and <identifier>-48.png files providing the icons to display in the Elements gallery in Form Studio.

 

In addition to basing your new Element on existing Elements within Form Studio, you may be able to find a suitable example of a similar Element to the one you want to create by searching online, e.g. on GitHub. The Element's files must be able to fit into the structure of Form Studio Elements and you will still need to create appropriate config.json, HTML template, JavaScript and icon files as for any other Form Studio Element. Any other files required by the Element can simply be copied into the Element's folder along with the standard Form Studio Element files.

Any JavaScript or CSS files which you put in an Element's folder will automatically be included with your Element when Form Studio generates the form's HTML and can be accessed within the custom Element's JavaScript and HTML. Image and other resource files, copied into the Element's folder, can be referenced from within your HTML or JavaScript using their URLs to identify them.

The standard Slider Element is an example of incorporating a downloaded Element within the Form Studio Element framework.

Before modifying an existing Element, consider whether you want to be able to use both the current version and your updated version on the same form. If you do want to be able to use both, you will need to create a new Element to contain your changes. Copy the current Element to a new folder within the Studio's Elements folder. Give the copied version a new unique identifier name and rename the folder and files accordingly. You can then edit the new Element.

If you don't need to use the two versions on the same form, you can edit the existing Element. In this case either take a backup of the current Element before making any changes or copy the Element to a temporary folder to be worked on there.

Note that you cannot have two versions of the same Element in the Studio's or project's Elements folders.

Refer to the section on creating a new Element for information about the contents of the different files which make up the Elements to enable you to modify your Element. Remember to update the version number of the Element in the config.json file.

When you have finished, if you have been editing the Element in a temporary working folder, take a backup of the original version of the Element and then copy your new files to the appropriate folder beneath the Form Studio Element's folder. If you want to update existing forms with the new version of the Element, see Adding new Elements to existing forms and updating Elements with later versions below for information on how to upgrade existing forms.

Once you have created a new Element and tested it, you can share it with other developers, if required, by simply giving them a copy of the Element's folder and its files, which they can copy into the Elements folder of their own Form Studio software.

When you create a new Element or customise an existing Element, your finished Element should be stored in the Studio's Elements folder (see above). This will make it potentially available to any form you edit or create within the Studio.

Each Digitise Forms project creates its own set of folders on your development PC. By default these will be under:

C:\Users\<username>\Documents\NDL Software\Form Studio\Projects\<project name>

These folders include an Elements folder.

When you add an Element to a form for the first time, the Element's folder is copied from the Studio's Elements folder to the project's Elements folder. The copied folder has the same name as the original folder except that the Element's version number is appended to the end of the folder name. With complex Elements, any other Elements on which it depends, i.e. any Elements which it imports, are also copied to the project's Elements folder, if they are not already in it. If you subsequently add further instances of an Element to the same form, the Element is taken from the project's Elements folder rather than the Studio's Elements folder, which means that you will always be using the same version of an Element within a particular form.

 

Once you have added a new Element to the Studio's Elements folder, either by creating your own Element or modifying an existing Element, the new Element can be used on your forms.

If you are creating a brand new form, your new Element is available to use immediately.

If you want to add your new Element to an existing form, however, you may need to update your form in order to be able to use the new Element.

For simple Elements, if the Element hasn't previously been used on a form, you can add the new Element to that form without requiring any further actions.

If your form already uses a previous version of a new simple Element, you first need to delete that Element's folder from the project's Elements folder. You then have to update each instance of the Element on the form by deleting the Element and re-adding it from the Elements gallery and reconfiguring its properties. Your new Element will be copied in to the project's Elements folder.

For complex Elements, the situation is similar to simple Elements. Brand new Elements can simply be added to your form but updated Elements require you to delete the current version of the Element from the projects Element folder and then, for each instance of the Element on the form, delete the Element and re-add it to your form. However, for complex Elements you will also need to consider whether you have modified any of the dependent Elements, i.e. the other Elements which are used by the complex Element, or any dependants of the Element's dependants.

If you have changed any of the dependent Elements, you will need to update these as well as the complex Element itself. For example, if your complex Element includes the standard Text Box Element and you were to modify the Text Box, you would need to delete the Text Box Element from the project's Elements folder as well as the complex Element and update any instances of the Text Box used outside of the complex Element. If you modify an existing Element, we recommend you increase the version number within the Element's config.json file, so that you can more easily keep track of which Elements are in use on any particular form.

Note, that you can only have one version of an Element within the project's Elements folder at any one time. This means that when you modify an Element you will need to consider whether it is used as a dependent Element within any complex Elements, in which case you may need to update the complex Element(s) as well. You may want to update all relevant complex Elements as a matter of course, or you may choose to only update those which will be used on the same form as the newly modified Element. Even if you don't make any changes to the complex Element itself, in order to use it on the same form as an updated dependent Element, you will need to update the version number of the dependent Element within the complex Element's config.json file. Having done that, you will need to delete the current versions of the complex Element and the newly updated dependent Element and replace them on any relevant forms, as described earlier. You may be able to avoid having to update otherwise unchanged complex Elements by using a copy of the dependent Element to create a new Element to be used outside of the complex Elements, allowing the complex Elements to retain the original dependent Element without needing any changes.

 

If you make changes to a complex Element which doesn't involve making changes to any of its dependent Elements, you can retain the original dependent Elements and you do not, therefore, need to update them on your forms.

 

You can check which version of an Element is available in the Element gallery by hovering your mouse pointer over the Element. The tooltip displayed includes the version number of the Element in brackets.

You can check the version number of any Element used on a form by selecting the Element in the Form Design workspace and then checking the Element's Type property in the Properties Pane - the version number appears in brackets.