Edit the HTML Files

The HTML files for an Element consist of an HTML file and an optional CSS file. The HTML file provides an HTML template used to define the Element's appearance and the CSS file can be used to provide additional styling, if required. Styling provided within a CSS file can't be changed using Styles within the Studio but can be used for aspects of the Element which don't need to be customisable. For example, the Text Box Element uses the CSS file to position the hide/show eye icon displayed when the Text Box is set to password mode:

Picture showing Password box.

Note that all Elements share the same namespace, so all style names within your CSS files must be unique within the project. One way to achieve this is to prefix the style name with the unique identifier of the Element to which the style relates, e.g. ndl-textbox-redtext.

 

You can use the HTML files for the standard Digitise Forms Elements supplied with Form Studio as a guide when creating new Elements. For example, the following shows the HTML used to define the standard Text Box Element. This is a simple Element consisting of a label and an edit box. Click on individual lines to drop-down an explanation of the HTML used:

 

form-group row

Bootstrap styles which determine spacing around Elements and divide Elements into 12 equal columns, respectively. The grid can be used to specify relative sizes of different parts of the Element - see below.

 

ndl-denote-required" ng-class="{true: 'required'}[ndlRequired == true]"

The ndl-denote-required class and ng-class attribute must be included if you want this Element to support 'Required' as a validation type. The ng-class must be included as shown here. If you include these items and then specify that the Element is a required field within the Studio, a red asterisk will be displayed in the browser against this Element and a red border will be displayed around the Element if the user doesn't enter something in this field.

If included, both the Bootstrap styles and 'Required' validation items must be included in the outermost container of the Element's HTML.

 

col-sm-n

The row class in the previous line divides the Element into 12 equal columns. The col-sm-n class is a Bootstap style which allows you to assign 'n' columns out of the 12 to be used for this container. col-sm-3 allocates 3 of the 12 columns, to be used by whatever is contained within this div. In this case, the following line defines the Label part of the text box and so the Label will take up 3 of the 12 columns when the Element is displayed in a browser. Note it is the Element which is divided in to 12 columns and not the width of the form, i.e. if you put two Elements on a single line the width of the form will be divided into 24 columns and each Element will still comprise 12 columns.

 

class="{{labelStyle}}"

Applies the Label Style defined in Form Studio. Items surrounded by {{...}} are AngularJS scope properties and are defined in the Element's JavaScript file. All the properties available to you in the Studio's Properties pane are accessed in your HTML as AngularJS scope properties and must be enclosed in {{ ... }}. Within simple Elements, the property name must be written in camel case between the brackets, but note that within complex Elements this may not always be the case - see below.

The AngularJS scope properties must all be defined in the Element's JavaScript file.

 

label for="{{::UNIQUE_ID}}

Uses the standard HTML label tag to provide the label for the Element. The for attribute links the label to the input field defined below. The unique ID of this Element is created within the Element's JavaScript file.

 

class="control-label"

A Bootstrap style.

 

ndl-design-richtext="label" ndl-design-richtext-mode="simple" ng-bind-html="label | trusted"

These attributes provide inline editing for the HTML element for which they are included. Inline editing allows you to edit the item directly within the Form Studio workspace as well as by editing the property in the Studio's Properties pane. In the ndl-design-richtext and ng-bind-html attributes where it says label, this represents the property whose value you want to be able to use the inline editing with. The ndl-design-richtext-mode attribute can be set to simple or advanced. This setting affects the tool bar displayed when you select text within an Element which has inline editing enabled. The advanced setting displays more buttons on the toolbar than the simple setting - for examples in the standard Elements supplied with Form Studio the paragraph Element has advanced inline editing enabled whereas the Text Box Element, as seen here, uses simple inline editing.

</div>

</div>

This container contains the definition of the edit box part of the Text Box, i.e. the box in which a user can type and which can be mapped to a Dataset field. col-sm-9 here allocates 9 columns for the horizontal width of this part of the Element. You don't have to stretch an Element across all 12 columns, if you don't want to. Any unused columns will display as white space.

<div>

This style is defined in the ndl-textbox.css file.

 

input

Uses the standard HTML input tag to provide the edit box for the Element. The id attribute provides an identifier for this input element and uses the same unique ID described earlier under the label element.

Other tags can be used here, e.g. the Button Element uses a button tag instead of the input tag and the Image Element uses an img tag. On the other hand, a Checkbox also uses the input tag but in this case it is qualified by a type attribute with a value of "checkbox".

 

name="{{name}}" placeholder="{{placeholder}}"

Pass in the values set in Form Studio in the name and placeholder properties. Items surrounded by {{...}} are AngularJS scope properties and are defined in the Element's JavaScript file. All the properties available to you in the Studio's Properties pane are accessed in your HTML as AngularJS scope properties and must be enclosed in {{ ... }}. Within simple Elements, the property name must be written in camel case between the brackets, but note that within complex Elements this may not always be the case - see below.

The AngularJS scope properties must all be defined in the Element's JavaScript file.

 

class="form-control

A Bootstrap style.

 

ndl-validation {{textboxStyle}}

This style is used to change the appearance of an Element at runtime, when it fails its validation rule(s), e.g. an Element marked as required but which the user hasn't completed. You only need to include this style if you allow validation to be set in Form Studio for this Element. The styling displays a red border around the Element when invalid and is fixed - you can't change the style in Form Studio.

 

ng-model="value"

Uses the standard AngularJS ng-modal attribute to effect a bi-directional binding between the value of the HTML input element and the property specified here, in this case the value property. For a text box, this means that at runtime when the user types something into the text box, the string they enter will be placed into the value property and, if the property is mapped to a Dataset field in Form Studio, the text box can be updated with data read from the database or the input value can be written to the database.

 

ndl-change="changed(ev)"

Specifies that this element has a changed Event, i.e. allows you to specify actions to be performed when the Element’s value changes. If you specify a changed event property in the config.json file, you must include this attribute. The default format for this attribute is as shown here, which means that when the Element's value changes any actions specified for this Event in Form Studio's Properties pane will be actioned and if no actions are specified, nothing will happen. If you want to specify your own function to be run instead, you can replace the "changed(ev)" by an AngularJS scope property containing your own JavaScript function name.

Note that the Button Element has a clicked Event, rather than a changed Event, and this uses the standard HTML click event, represented in the HTML as ng-click="clicked({ev:$event})" instead.

 

ng-disabled="ndlDisabled"

Specifies that this Element has a Disabled property allowing you to enable and disable the Element within the form. By default, all Elements have a Disabled property, and in order to enable/disable the Element you must include this attribute and it must be exactly as shown here.

 

ng-required="ndlRequired==true

This attribute must be included if you want this Element to support 'Required' as a validation type. This is in addition to the ndl-denote-required class and ng-class attribute specified in the outermost container - see above.

This span tag provides styling for the eye icon displayed within a Text Box Element when set to password mode. It is used in conjunction with the JavaScript in the Element's JavaScript file.

</div>

<div ng-repeat="errorMessage in ndlErrorMessages">

<div ng-message="{{errorMessage.type}}">{{errorMessage.text}}

</div>

</div>

</div>

These lines display the validation error message(s) specified in the Element's properties in Form Studio. If you want to display the validation error message(s), you must include this section as it is shown here in an appropriate position within the HTML.

Items surrounded by {{...}} are AngularJS scope properties and are defined in the Element's JavaScript file. All the properties available to you in the Studio's Properties pane are accessed in your HTML as AngularJS scope properties and must be enclosed in {{ ... }}. Within simple Elements, the property name must be written in camel case between the brackets, but note that within complex Elements this may not always be the case - see below.

If you want to include these lines in your Element, ndlErrormessageStyle and ndlErrorMessages must be included in the scope member within the Element's JavaScript file.

</div>

</div>

</div>

 

Complex Elements can combine multiple items within a single Element. For example, the Address Finder Element contains a number of text boxes, a checkbox, a drop-down list and two buttons.

To simplify creating complex Elements, you can import other Elements into a complex Element to prevent the need to recode the imported components within the complex Element. Using the Address Finder as an example again, the text boxes are not individually coded within the Address Finder but the existing standard Text Box Element is imported each time a text box is needed within its display. On the other hand, the Capita Pay360 Cart Item is a complex Element but this doesn't import any existing Elements and when, e.g., it needs a button it uses the standard HTML button tag to provide one rather than import the standard Button Element.

 

The basics of a complex Element are the same as for simple Elements and you can use the Address Finder, Navbars, Capita Pay360 Cart Item and Capita Pay360 Cart Elements as guides when creating your own complex Elements.

When editing the HTML file for a complex Element, where you want to import a dependent Element you insert a tag using the unique identifier of the Element you want to import, in place of a tag using the standard HTML input, button, img etc. You then provide attributes for this tag to configure the dependent Element.

For example, the following lines from the Address Finder Element's HTML insert a text box using the standard Digitise Forms Text Box to allow users to enter the first line of an address:

<div>

<ndl-textbox name="Addressline1" id="Addressline1" value ="addressline1.value" label="{{addressline1label}}" childlabel ="addressline1label" is-numeric ="False" is-password="False"

ndl-required="ndlRequired"

ndl-validation-attributes='[]'

ndl-submitted="ndlSubmitted"

ndl-error-messages='[{ "type" : "required", "text" : "Please enter the first line of your address"}]'

ndl-errormessage-style="{{ndlErrormessageStyle}}"

ndl-control="ndlAddressFinderContainer.Addressline1"

ndl-maxlength="{{addressline1Maxlength}}" />

</div>

 

ndl-textbox

This tag inserts a standard Digitise Forms Text Box by using the Element's unique identifier. You can insert a different Element by inserting a tag using the unique identifier of the required Element instead, e.g. the tag <ndl-droplist ...> would insert a standard Digitise Forms Drop List Element.

 

name="Addressline1" id="Addressline1"

The name and id attributes identify this instance of the text box. You can give the text box a name and id of your choice but they should be unique within the form.

The remainder of the attributes configure the Text Box's properties and bind properties in your new Element to properties in the Text Box. The attribute names are the properties of the dependent Element.

The property names for both dependent and complex Elements are taken from the property definitions in the respective Element's config.json file. Note that, when specifying property names here, you must follow the standard AngularJS rules for passing property values into HTML attributes to decide how to format property names.

 

value="addressline1.value"

This attribute maps the complex Element's addressline1.value property to the Text Box's value property. Within the Text Box's HTML, the ng-model attribute is mapped to the value property, so this is the Text Box's property which will contain the value entered into the Text Box by the user. Within your complex Element, therefore, you need to bind the Text Box's value property to a property of your complex Element, through which you can access the Text Box's value within the complex Element's HTML and JavaScript.

Since the Text box's value property is mappable, your complex Element property must be a member of an object and not a primitive value (see Edit the config.json file), hence the property used is addressline1.value and not just value. Note that although in this example both the Text Box and complex Element's properties have the same name, value, this is not a requirement and the names can be different, if you prefer.

 

label="{{addressline1label}}" childlabel="addressline1label"

These attributes relate to the label which will be displayed for this Text Box within the complex Element. You need to include both the label and childlabel attributes and both must include the same property name, in this case addressline1label. The childlabel attribute allows in-line editing to reference the correct property when working with your complex Element in Form Studio.

 

is-numeric="False" is-password="False"

These attributes pass values through to the Text Box's is-numeric and is-password properties.

 

You may not need to map all properties of the dependent Element, e.g. where you are happy to use the dependent Element's default value for a property . Some Elements, however, may have compulsory properties which you must include and you might need to experiment in order to get your complex Element to work as required.

The next 6 attributes configure validation for this Text Box. If you want to include validation for your imported Element, you will need to include all these attributes within the tag.

 

ndl-validation-attributes='[]'

This attribute allows you to specify the type of validation you want to perform on this sub-Element. You can specify all the validation criteria available to you when configuring an Element within Form Studio. However, when importing an Element, you will need to specify the validation required manually here - see below for more information.

 

ndl-error-messages='[{ "type" : "required", "text" : "Please enter the first line of your address"}]'

This attribute allows you to specify an error message to be displayed when the sub-Element fails a validation check. You can include a different message for each type of validation you specify in the ndl-validation-attributes attribute - see below for more information about specifying the value for this attribute.

 

ndl-errormessage-style="{{ndlErrormessageStyle}}"

This attribute allows you to specify a Style to be used to display the validation error message(s), if you have specified any in the ndl-error-messages attribute.

 

The easiest way to determine what you need to enter in the three validation attributes above is to configure a Text Box Element in Form Studio and then use the embedded browser's dev tools to check the value of the attributes generated by the Studio and copy and paste the values from there into your HTML. The values available for this attribute are the same for all Elements, so you can configure the required validation using a Text Box whichever Element you are actually using.

 

ndl-maxlength="{{addressline1Maxlength}}"

This attribute allows you to specify a value for the Text Box's Max Length property.

 

Open Form Studio.

Create a new Project.

Add a Text Box onto the page.

Select the text Box to display its properties in the Properties Pane.

Configure the validation as you would like it to be in your complex Element.

Reload the Form.

Deselect the Design Mode option in the Editor group on the Ribbon's Home tab.

Right-click in the grey area outside the page within the Form Design workspace and click on Show Dev Tools or choose Show Dev Tools from the Editor group on the Ribbon's Developer tab. The dev tools will load in a separate window.

Make sure the Elements tab is selected in the dev tools window.

Click on the button in the tab bar of the dev tools window.

Click on the edit box part of the Text Box in the Form Design workspace.

HTML will be displayed in the dev tools.

Scroll up the HTML to find the <ndl-textbox ... /> tag.

Within this tag look for the relevant attributes and copy the values from them into the relevant places within your HTML.

 

ndl-control="ndlAddressFinderContainer.Addressline1"

You will need to edit the value of this attribute to be <ng-form name>.<sub-Element's id>. The ng-form name is specified in the name attribute of the ng-form tag which would usually be the first line of the complex Element's HTML template. The sub-Element's id is the id you have specified in the id attribute for this instance of the imported Element.

 

If you don't want to provide validation for this sub-Element, simply omit all the validation attributes, e.g. the Address Finder Element's HTML for the second line of an address is simply:

<div>

<ndl-textbox name="Addressline2" id="Addressline2" value ="addressline2.value" label="{{addressline2label}}" childlabel ="addressline2label" is-numeric="False" is-password ="False" ndl-maxlength="{{addressline2Maxlength}}" />

</div>