Skip to main content
Version: 9.4

Includes

HF-Includes are blocks defined in a template HTML file referenced by the HTML form definition file. While developing with the FormDev environment HF-Includes are automatically included in the form definition file.
To use form definitions with includes in production you have to export these form definitions to one valid Form definition (i.e. the HTML file and all associated images and files).

The "Template Exporter" merges the main form definition folder and files with the HF-Includes and generates valid form definitions ready for upload/usage:

  • the exported HTML form definition file contains the HF-Blocks that are defined in the template file
  • and the exported form definition folder contains all linked scripts and style files from the template file as well as all files present in the source form definition folder.

Usage​

Inside the HTML form definition file:

<form>
    <ol>
        <li data-hf-title="PageTitle">
            <ol>
                <li data-hf-title="TabTitle">
                    <!-- *** HF-Include ***-->
                    <a href="../Demorepair.templ/demo-repair.templ.html#operation-block-template-1"></a>
                    <!-- ****************** -->
                    <a href="#operation-block2"></a>
                </li>
            </ol>
        </li>
    </ol>
</form>

A reference of the HF-Include block consists of two parts

  • the template file link:
    • the relative path to the template file, eg "../Demorepair.templ/demo-repair.templ.html"
Note

The example shows the path to the folder inside the "formdefinitons" folder. Please ensure that your template folder is located inside this folder. Both - folder and file name - must conform to our naming convention:

  • Folders : *.templ, eg Demorepair.templ/
  • Files: *.templ.html), eg demo-repair.templ.html
  • the block id:
    • this is the html id-tag, eg: "#operation-block-template-1"

... and is declared in the block link section the same way as "normal" blocks defined in the main HTML file:

  • <a href="../Demorepair.templ/demo-repair.templ.html#operation-block-template-1"></a>

Complex config attributes​

...
<form>
    <ol>
        <li data-hf-title="PageTitle">
            <ol>
                <li data-hf-title="TabTitle">
                    <!-- *** HF-Include ***-->
                    <a href="../Demorepair.templ/demo-repair.templ.html#operation-block-template-1"
                        data-change-ctrl-ids='{ 
                            "customcontrol_1": "id_that_has_been_changed", 
                            "operation_id": "my_changed_id" 
                        }' 
                        data-include-css="false"
                        data-ph-mylabel="My block label"></a>
                    <!-- ****************** -->
                    <a href="#operation-block2"></a>
                </li>
            </ol>
        </li>
        ...
    </ol>
</form>

There are several config attributes:

  • data-include-css:
    • takes a boolean value to prevent exporter to include style definitions, default value equals "true".
  • data-id-prefix:
    • adds to each control- and block-id in the template a prefix. For example this can be used to add the same template block multiple times in your formdefinition.
  • data-change-ctrl-ids:
    • takes a list of ids of your template to change them, e.g: "data-change-ctrl-ids='{"customcontrol_1": "id_that_has_been_changed", "operation_id": "my_changed_id"}'"
  • data-ph-[customValue]:
    • free selectable placeholders, which are used in your template, and are replaced with the value assigned to this property in the HTML template. These properties are so called blockPlaceholders. Enclose the blockPlaceholders in the template within two brackets: {{customValue}}.
      Only lowercase customValue-names are allowed!
      For Example the attribute data-ph-mylabel="My block label" replaces the strings {{label}} in the given template block with the value of the date-ph-mylabel-value My block label. This is also used for including the same template block multiple times in your formdefinition.

Include-Files-Tag​

<head>
    [...]
    <includefiles 
        data-include-url="../TemplateFolder.templ"
        data-include-files="['file01.css','file02.jpg','file03.js']"></includefiles>
</head>

The Include-Files-Tag controls what files are copied from the template folder to the formdefinition folder. This is a way to organize all of your assets (logos, css-files, js-files etc.) in your template folder and to define the files your formdefinition needs in the formdefinition html file. The data-include-url-attribute defines the relative path to the the template folder and th data-include-files-attribute defines the files that should be included in the output fordefinition folder. It is possibe to define multiple includefiles-tags if you want to include files from different template folders.

Include HTML-Fragments​

Besides blocks it is also possible to include HTML fragments ("rows" and "columns") at any position inse your HTML file.

Note

Keep in mind the result must be a valid and parseable HTML file.

Provide the fragment in your .templ.html file:

<div id="operation-includeFragment_1">
    <div class="grid column2">
        <div class="r1 c1">
            <div id="operation_date2"
                data-win-control="HFWinJSCtrl.DatePicker"
                data-win-options="{
                    required: true,
                    label: '{{DateLabel}}',
                    defaultValue: 'now',
                    emptyContent : 'Wählen...',
                }"></div>
        </div>
        <div class="r1 c2">
            <input type="text"
                id="operation_id2"
                data-win-control="HFWinJSCtrl.TextField"
                class="show_disabled"
                data-win-options="{
                    list: true,  
                    label: '{{OperationLabel}}'
                }">
        </div>
    </div>
</div>
Note

The HTML-tag referenced in the HTML file (i.e. <div id="operation-includeFragment_1">...</div>) is only a container of the HTML-snippet included in the merged HTML File.

Exclude-Structure-Attribute​

<li>[...]</li>
<li data-hf-title="Optional Page"
    data-exclude-structure="true"
    id="optionalPage">
    <ol>
        <li data-hf-title="tabs">
            <a href="#block01"></a>
            <a href="#block02"></a>
        </li>
    </ol>
</li>

The data-exclude-structure-tag allows to exclude certain structural elements (pages, tabs and blockes) from an exported html formdefinition. Define it on the structural element, a page, tab or block, that should be excluded. Default = false.

If-Attributes​

There is another possibilty to exclude structures in the exported formdefinition. The attribute data-hf-if is used to conditionally render contents of a template block. The defined html parts within a block will only be rendered if the attribute is set to true. You can utilize template placeholders to assign a boolean value to the data-hf-if-attributes. Here is an example how this is defined:

The source html form definition file with a placeholder that defines a boolean value

 <li data-hf-title="{{@Tab_2.Title}}"
    <a href="../ExampleTemplate.templ/example-template.templ.html#blockWithIfContent"
        data-ph-includeHtml="false"></a>
        [...]
 </li>

In the example above the html part with data-hf-if-attribute is NOT outputed to the exported file because the source file assigns a false value to the if-attribute.

Notice the data-hf-else-attribute! You can use a else-block to render content if the if-attribute is not fullfilled. A data-hf-else-element must immediately follow a data-hf-if-element - otherwise it will not be recognized.

HF-Templates​

HF-Templates must be complete and valid HTML5 Files - no HTML snippets:
They must include Doctype-declarations, a head and a body-tag and please stick to the naming convention:

  • the template file should end with *.templ.html
  • the template folder
Example
<!DOCTYPE html>
<html>
<head>
    <title>Example Template</title>
    <script data-hf-src="ExampleControl.js"></script>
    
    <link rel="stylesheet" data-hf-href="aircompressor-template-style.css">
    <style>
        .foo{
            background-color: red;
        }
    </style>
</head>

<body>
    <div id="operation-block-template-1" data-win-control="WinJS.Binding.Template">
        <div class="grid column3">
            <div class="r1 c1">
                <div id="customcontrol_1" 
                     data-win-control="HFFormdefinition.Templates.ExampleControl">
                </div>
            </div>
            <div class="r1 c2">
                <input  type="text" 
                    id="operation_id" 
                    data-win-control="HFWinJSCtrl.TextField"
                    data-win-options="{
                        label: {{mylabel}}
                    }">
            </div>
            ...
    </div>
</body>
</html>

The HF-Templates contain:

  • the block template(s)
  • all scripts and styles needed for the block templates.
    Please define these scripts and styles in the head section of the html template.

Placeholders​

Placeholders (not to be confused with blockPlaceholders) are global key-value pairs, defined in a json file and used in your source or template HTML file. Global Placeholders are mostly used to generate different outputs of your formdefinition depending on a global "switch"-variable that you can provide when exporting the form.

placeholder.json
    {
        "myPlaceholder": "Some Text",  
        "ComboBoxLabel": "Label for Combobox",
        "backendUrl": {
            "Backend_01": "backend_01/liste",
            "Backend_02": "backendqa_02/liste",
            "default": "Backend_02"
        },    
        "nestedCondition": {
            "Backend_01": {"op": "and", "cond": [{"type": "field","id": "support_required","val": true},{"type": "stage","id": "ST2","val": true}],"else": "readonly"},
            "Backend_02": {"op": "and","cond": [{"type": "field","id": "support_required","val": true}, {"op": "or","cond": [{"type": "stage","id": "ST2","val": true}, {"type": "stage","id": "ST4","val": true}]}],"else": "readonly"},
            "default": "Backend_01",
            "type": "htmlJSON"
        }
    }

As you can see, the Placeholder is allways enclosed within two brackets and contsists of three parts:

  1. the relative path to the json file where the placeholder key is defined, eg. ../TemplateFolder.templ/placeholder.json
  2. followed by a hash, #
  3. and the placeholder key, eg: ComboBoxLabel

{{../FormDefinition.templ/placeholder.json#ComboBoxLabel}}

In the example these are the backendUrl or the nestedCondition placeholders.

If you for example want to generate two different html-formdefinitions for different backends, where some parts of the html formdefinition file should differ you can use global placeholders with a switch. By defining keys with a nested object that provides the "switch"-keys and the different values for different html formdefinitions you can export different outputs - as you can see in our example above (the backendUrl or the nestedCondition-placeholders). Global placeholders with a switch are key-value pairs which values are itself an object with keys that present the different switches that you provide when exporting the form. Lets assume that we want to export the form for two different backends, with different urls to connect to. In this scenario you can use a switch and tell the exporter or your form-dev environment (via default setting) what switch to use. This is the way you export a formdefinition for the "Backend_01":

npm run export -- --formDefPath=relPath/to/your/formdefinition-folder --outputPostfix="Backend_01" --switch="Backend_01"

The nested switch objects have two special keys: default and type. The default key defines the default switch that is also used in the formDev environment. The type key supports two values: string(default) or htmlJSON. The latter is a special case where a json object has to be provided for a html attribute (as this is the case for the data-hf-condition attribute).

Export in FormDev​

Projects with Includes functionality have to be exported to merge all the content in one HTML FormDefinition file.

For more information on the export please refer to page "Dev Tools".