Template

The template function is used to generate a base64 document based on an already existing DocuMotor template.

Syntax

string template(string $id, string $stage, any $inputData)

Generates a base64-encoded document, which results from parsing the $inputData through a DocuMotor template. The template is specified by its $id and, if applicable, its $stage.

Parameters

$id: The id of the DocuMotor template that will be used to generate a base64-encoded document.
$stage: The stage of the versioned template. In case the template is not a versioned template then `null` or '' can be used for this parameter.
$inputData: The data that will be parsed through the DocuMotor template, before it gets converted to a base64 string. There are no specific restrictions when it comes to the shape of the data. It can be a json_object, an array, a simple value, or nothing at all.

Example

Below, a simple case where the template function is used is presented. It is worth mentioning that the sample data will only be used for the $inputData parameter. The rest of the parameteres will be manually inserted.

{
    "People": [  //This array will be used as the input data
        {
            "first_name": "Pyotr",
            "last_name": "Brophy",
            "email": "pbrophy0@twitpic.com"
        },
        {
            "first_name": "Vivyanne",
            "last_name": "McLeoid",
            "email": "vmcleoid1@cyberchimps.com"
        },
        {
            "first_name": "Esme",
            "last_name": "MacIlhagga",
            "email": "emacilhagga2@ucoz.com"
        }
    ]
}

In the transformation below, a placeholder template id is used and the $stage parameter is set to null, as that particular template isn’t versioned. Keep in mind that template ids are specific to each DocuMotor tenancy. The data is inserted as {KeyName: People}, as in this case using just “People” would not result in a valid jason. This, as well as how to retrieve a template’s id, will be clarified later in this article.

{
    "TemplatePath": template('62f366cb65189c6e35c8cbee', `null`, {KeyName: People})
}

As seen in the Output block below, the template function results in a base64 string of document that is generated when the $inputData is parsed through the template.

{
    "TemplatePath": "UEsDBBQABggIAAAAIQCn7zB05w..." //for space reasons the base64 string has been truncated
}

The key that holds the generated base64 string can be used to insert the corresponding document into the current template. This can be achieved using the Text Element binding.

Notes

Finding the template id

There are two ways of finding a template id. The simplest one is to retrieve it from the template’s URL, where the template id is the last part of the link.

Alternatively, it can be found by pressing the “Get Snippet” (step 1) button on the top right corner of the editor. In the appearing window, the template id can be easily spotted, as seen in the image below (step 2).

Finding the template’s stage

It is possible to find the different stages available in the unit in the unit’s management page.

The stage needs to be defined exactly as it is defined in the corresponding unit and has to be the stage that is active on the template. To see the wanted template’s active stage go to the templates page in the unit and find the template. Before entering the template’s editor it is possible to see all the different versions of the template. Here it is easy to see which stage the wanted version of the template is, since it is bolded.

Input Data

In order to determine how the $inpuData parameter needs to be defined, one must think of whether or not the used data will produce a valid json structure. In order to further clarify this, the sample data from above will be used as an example.

{
    "TemplatePath": template('62f366cb65189c6e35c8cbee', `null`, People)
}

If $inputData is defined like in the transformation block above, an error will be triggered, as the data that is inserted into the external template’s sample data isn’t a valid JSON structure. In this case, the external template is the one that is specified in the template function.

{
    "People": [  //This array is used as the input data
        {
            "first_name": "Pyotr",
            "last_name": "Brophy",
            "email": "pbrophy0@twitpic.com"
        },
        {
            "first_name": "Vivyanne",
            "last_name": "McLeoid",
            "email": "vmcleoid1@cyberchimps.com"
        },
        {
            "first_name": "Esme",
            "last_name": "MacIlhagga",
            "email": "emacilhagga2@ucoz.com"
        }
    ]
}

[  //Not a valid JSON structure
    {
        "first_name": "Pyotr",
        "last_name": "Brophy",
        "email": "pbrophy0@twitpic.com"
    },
    {
        "first_name": "Vivyanne",
        "last_name": "McLeoid",
        "email": "vmcleoid1@cyberchimps.com"
    },
    {
        "first_name": "Esme",
        "last_name": "MacIlhagga",
        "email": "emacilhagga2@ucoz.com"
    }
]

Hovewer, if the $inputData parameter is defined as it is defined in the transformation below, then the sample data of the external template will have a valid JSON structure.

{
    "TemplatePath": template('62f366cb65189c6e35c8cbee', `null`, {KeyName: People})
}

{
    "KeyName": [  //Valid JSON Structure
        {
            "first_name": "Pyotr",
            "last_name": "Brophy",
            "email": "pbrophy0@twitpic.com"
        },
        {
            "first_name": "Vivyanne",
            "last_name": "McLeoid",
            "email": "vmcleoid1@cyberchimps.com"
        },
        {
            "first_name": "Esme",
            "last_name": "MacIlhagga",
            "email": "emacilhagga2@ucoz.com"
        }
    ]
}

Lastly, it is worth mentioning that the KeyName can be defined by the user, and usually it is named in order to facilitate a binding in the external template.