Skip to content

Templates

In the previous chapter on documents we introduced the concept of a 'systemHeader.systemType', and mentioned 'systemHeader.systemType' of 'template'. We also mentioned 'systemHeader.templateId'

The 'template' concept is the foundation of the Formbird environment.

  • Templates can generate documents.
  • Templates hold the JSON data which control the fields displayed to the user.
  • Templates are also used to 'view' documents.

There is a bit there! Let's go into more detail:

1 - Templates Can Generate Documents

The following (abridged) document was generated by a template with the id of '80e75b50-bb5c-11e6-943f-8deecc4f8938': 

{
    "systemHeader":{
        "systemType": "document",
        "templateId": "80e75b50-bb5c-11e6-943f-8deecc4f8938",
        ..... (abridged)
    },
    "documentId": "efdd7440-e942-11e6-9c38-1d12f3fd75a7",
    "reproducibility": "Always"
}

The diagram below details the Template / Document Relationship. When a template is 'saved' by the user, the template creates a document capturing the values entered by the user into the template. - You can see that the template has a documentId which is written to the "systemHeader.templateId" that the template creates. - The system creates a new documentId for the resulting document. - The system sets the 'systemHeader.systemType' to document in the resulting document - The image shows and abridged version of the systemHeader field. We'll cover the systemHeader in more detail in a later chapter.

              alt text

 

2 - Templates hold the JSON data which control the fields displayed to the user.

When a template is created, you can add a 'components' array. The 'components' array contains small JSON objects which define how the system is to display and/or capture data.

              alt text

The above diagram shows a components array with the definition for a 'text box' 

      {
            "componentName": "sc-text-box”,
            "label": “Reproducibility”,
            "name": “reproducibility”
        },

When the user opens the document, the 'sc-text-box' component will display a text box which the user can enter data:
              alt text
We'll cover component definitions later, but briefly you can see that the 'label' is defined as 'Reproducibility' and is displayed on the form, and the 'name' field becomes the key which is written to the document. The value entered into the component becomes the value. Looking back at the diagram, you can see the document contains a field 'reproducibility':'Always'

3 - Templates are also used to 'view' documents.

When the user opens the document produced by the template, the system gets the systemHeader.templateId, and displays the value in the component with the key name. In this instance, the system is looking for the components.name field 'reproducibility' - when it finds the component with that name, it displays 'Always' on the screen.

.... Teaser

As a bit of a teaser of what formbird is capable of .... - the system can 'redirect' users to a different template to view data .... the document can be displayed in many different ways, including or excluding data based on the presence of the corresponding named component - components can display data written by different components ... the view of the data can be changed by which component you select to display it.

Full Template Definition

The examples / images in the previous topic showed abridged versions of the template / document Let's look at a few other items that we recommend be included on a template:

{
    "documentId": "e1dd9940-ba26-11e8-9aef-99f092bfb6a5",
    "systemHeader": {
        "templateId": "54d96f610bc006eb84369a8b",
        "systemType": "template",
        "createdWith": "74746c80-8378-11e6-99b1-71ee944cf59f",
        "keyIds": [],
        "versionId": "f7ba5980-ba38-11e8-8690-bdece58e9366",
        "excludeGeneralSearch": false,
        "currentVersion": true,
        "createdDate": "2018-09-17T05:17:27.192Z",
        "createdBy": "5435d78388968497030106d0",
        "summaryName": "TEST TEMPLATE",
        "summaryDescription": "TEST TEMPLATE Description",
        "serverUpdatedDate": "2018-09-17T05:17:27.219Z",
        "serverCreatedDate": "2018-09-17T05:17:27.219Z",
        "previousVersionId": "eeec0420-ba38-11e8-8690-bdece58e9366"
    },
    "components": [
        {
            "componentName": "sc-static-value",
            "name": "appTags",
            "value": [
                "myApplication",
                "myCategory"
            ],
            "visible": false
        },
        {
            "componentName": "sc-date-time",
            "label": "Date Submitted",
            "name": "dateSubmitted"
        },
        {
            "componentName": "sc-text-box",
            "label": "Reproducibility",
            "name": "reproducibility"
        },
        {
            "componentName": "sc-drop-down",
            "label": "Severity",
            "name": "issueSeverity",
            "dropDownList": [
                "Trivial",
                "Minor",
                "Major",
                "Critical"
            ]
        }
    ],
    "summaryDescriptionRule": "TEST DOCUMENT DESCRIPTION",
    "summaryNameRule": "Example Rule: {{{reproducibility}}}",
    "formColor": "#fefefe",
    "appTags": [
        "myApplication",
        "myCategory"
    ],
    "name": "This is my template name"
}

Parameters to note: - systemHeader.summaryName - displays the value in the application framework and is used to display the name of the document in search results and grids - systemHeader.summaryDescription - optional additional information - displayed in full global search results - summaryDescriptionRule - this is used to write to the systemHeader.summaryDescription of the document produced by the template when saved. - summaryNameRule - as with the summaryDescription rule - this is used to write to the systemHeader.summaryName field of the document produced by the template. Note the use of 'handlebars' {{{reproducibility}}}. Handlebars are used throughout the application to access values entered into the document. This example will take the text that is entered into the component with the 'name':'reproducibility' parameter and use it as input to the systemHeader.summaryName on the document. So if for example the user enters 'Yes' into the field, the resulting systemHeader.summaryName of the document will be 'Example Rule: Yes' - formColor - this can be either a html colour name or a hex colour. This sets the background colour of the template and document.

Special Note on 'appTags': - appTags:[ .... ] - appTags is a convention that Formbird application developers created early on. It is not mandatory, but it is recommended.
It is quite easy to 'lose' documents if you're not careful. The appTags array is one way to group all of the documents for an application. If everything is tagged, then it's a simple matter of searching for the tag name in a grid or in the database.
For example: I could construct a query that says 'get me all documents with 'myApplication' on them and display their summaryName fields in a grid.
If the array contains multiple entries it is then possible to categorise the documents quite easily. Example:
You may have one set of documents with a field of "appTags":["myApplication","category1"] and another with "appTags":["myApplication","category2"] You can then construct a search for all documents with 'myApplication' and it will return both category1 and category2 documents, You can also construct a search for all documents with 'myApplication' AND 'category1' which will return the category 1 subset of all the documents.

  • corresponding to the appTags array is the 'sc-static-value' component. The sc-static-value component writes the 'value' field to the document. It can be used to write any value to a document, but in this case it will write "appTags":["myApplication","myCategory"] to the document at the root level, ensuring that any search for 'myApplication' will return the document.

You may notice that in this example we would have 'templates' and 'documents' both with the same appTags - if I needed only the documents I could search for 'systemHeader.systemType':'document' AND 'appTags':["myApplication"] and return only documents.

This is the template displayed as per the definition above: Note the systemHeader.summaryName field "TEST TEMPLATE" displayed on the right of the 'New' button and the 'name' field of the template displayed on the left of the 'Print' button;

              alt text

Resulting Document

{
    "documentId": "112cdbc0-ba2c-11e8-b241-7568144d4841",
    "systemHeader": {
        "templateId": "e1dd9940-ba26-11e8-9aef-99f092bfb6a5",
        "systemType": "document",
        "createdWith": "e1dd9940-ba26-11e8-9aef-99f092bfb6a5",
        "keyIds": [],
        "versionId": "d7d84550-ba38-11e8-907d-4b32807e54a5",
        "excludeGeneralSearch": false,
        "currentVersion": true,
        "createdDate": "2018-09-17T05:16:33.701Z",
        "createdBy": "5435d78388968497030106d0",
        "summaryName": "Example Rule: Yes",
        "summaryDescription": "TEST DOCUMENT DESCRIPTION",
        "serverUpdatedDate": "2018-09-17T05:16:33.741Z",
        "serverCreatedDate": "2018-09-17T05:16:33.741Z",
        "previousVersionId": "19147aa0-ba2c-11e8-ad0c-7b1e920f059f"
    },
    "dateSubmitted": "2018-09-17T03:45:11.974Z",
    "reproducibility": "Yes",
    "issueSeverity": "Trivial",
    "appTags": [
        "myApplication",
        "myCategory"
    ]
}

Note - the appTags array at the root level of the document - the systemHeader.summaryName using the data entered by the user - the systemHeader.summaryDescription field on the document

              alt text

Note: - the template 'name' field to the left of the 'Print' button - the systemHeader.summaryName field to the right of the 'New' button