Templates

Templates allow you to define the generic document structure (such as a welcome email message or a quote PDF), which is then converted into an actual document based on the provided data.

If you wish to learn more about a specific topic, refer to the subsections under Low-Code Platform Developer Guide Templates.

Creating a Template

Templates are created and managed in the Corteza Admin.

Navigate to the System Templates and click on the New button in the top-right corner.

Enter the basic information; short name, handle, description, and template type. The template type determines the template format and implicitly entails what document types the template can render to.

A partial template is used as part of another template (for example, a generic header or a footer) and can not be rendered independently. You can convert the template from and to a partial template.

Click on the Submit button to prepare your template.

After you submit the base parameters, three new sections will appear.

Toolbox

The toolbox provides snippets for the most common operations, HTML template sample, and partial inclusion samples.

Template content

The template content editor provides a simple code editor to edit your template. The HTML template editor implements syntax highlighting and some other useful tools such as auto completion.

Preview

The preview section allows you to test how your templates will look when rendered into an actual document.

Refer to the PDF Renderer to configure PDF document rendering.

The Content

Advanced users are welcome to check out the plain text template full reference, the html template full reference, and the extended function docs.

Let’s start by copying the default HTML sample from the toolbox.

<!DOCTYPE html>
<html>
<head>
  <meta charset='utf-8'>
  <meta http-equiv='X-UA-Compatible' content='IE=edge'>
  <title>Title</title>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
</head>
<body>
  <h1>Hello, world!</h1>
</body>
</html>

If you don’t need any dynamic content (different name for different contacts), you can stop after this step. The above template is valid and can already be used.

In case you need dynamic content, more topics need to be covered.

Value Interpolation

Value interpolation allows you to define some placeholder that is then replaced with an actual value when the template is rendered.

In this case, this placeholder looks like this:

{{.name}}

The value replaces the above placeholder under the name property from the provided value object.

Let’s look at some examples. Each example first defines the value object and then the placeholder.

Example with a basic property:

{
  "name": "Jane"
}

{{.name}}

Example with a nested property:

{
  "contact": {
    "details": {
      "name": "Jane"
    }
  }
}

{{.contact.details.name}}

A complete example would look like this:

The provided data:

{
  "contact": {
    "details": {
      "firstName": "Jane",
      "lastName": "Doe"
    }
  }
}

The template:

<!DOCTYPE html>
<html>
<head>
  <meta charset='utf-8'>
  <meta http-equiv='X-UA-Compatible' content='IE=edge'>
  <title>Title</title>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
</head>
<body>
  <h1>Hello, {{.contact.details.firstName}} {{.contact.details.lastName}}!</h1>
</body>
</html>

Conditional Rendering

Conditional rendering allows you to show or hide sections of the rendered document based on the input parameters.

if statement:

{{if condition}}
  The condition was true.
{{end}}

if-else statement:

{{if condition}}
  The condition was true.
{{else}}
  The condition was false.
{{end}}

if-else if-else statement:

{{if condition}}
  The condition was true.
{{else if condition}}
  The other condition was true.
{{else}}
  Neither conditions were true.
{{end}}

The condition part is an expression that returns a single boolean value. An example of an expression:

{{if .lead.cost > 1000}}
  The lead {{.lead.name}} was expensive!
{{end}}

Table 1. Logic operators:
AND	Syntax: `a && b` Notes: Results as true if both `a` and `b` evaluate to `true`.
OR	Syntax: `a \|\| b` Notes: Results as true if either `a` or `b` evaluates to `true`.
NOT	Syntax: `!a` Notes: Results as true if `a` is `false` and vice-versa.
Equal	Syntax: `a == b` Notes: Results as true if `a` is equal to `b`.
Not equal	Syntax: `a != b` Notes: Results as true if `a` is not equal to `b`.
Less than	Syntax: `a < b` Notes: Results as true if `a` is less than `b`.
Greater than	Syntax: `a > b` Notes: Results as true if `a` is greater than `b`.
Less equal than	Syntax: `a <= b` Notes: Results as true if `a` is less or equal to `b`.
Greater equal than	Syntax: `a >= b` Notes: Results as true if `a` is greater or equal to `b`.

Handling Lists

Our templates make it quite easy to work with lists. For example, you would like to generate a quote with lots of line items.

The syntax for iterating over a list looks like this:

{{range .listOfItems}}
  {{.itemName}}; {{.itemCost}}$
{{end}}

If you prefer to specify what variable the current item is stored into, use this syntax:

{{range $index, $item := .ListOfItems}}
  {{$item.itemName}}; {{$item.itemCost}}$
{{end}}

Using Functions

Sometimes you need to process the data further before it is rendered to the document.

Some lighter processing can be handled directly by the template engine. More complex processing should be handled by the code that is requesting to render the template.

A function is called upon as shown below:

{{functionName arg1 arg2 ... argN}}

The passed argument can be a constant or a property from the provided data.

You can also chain functions. When two functions are chained, the left function’s output is passed into the argument of the right function.

{{funcA | funcB | ... | funcN}}

Table 2. Most common function reference:
Length of	Syntax: `{{len listOfThings}}` Notes: Returns the number of items in the given `listOfThings`.
Format string	Syntax: `{{printf "pattern goes here" arg1 arg2 … argn}}` Notes: Returns the formatted string, following the provided pattern using the values provided as arguments.
Inline remote file	Syntax: `{{inlineRemote "url goes here"}}` Notes: Returns the base64 encoded file denoted by the URL. The string is formatted in the form of `data:{mime-type};base64,\{encoded remote file}`. Useful when attaching images to PDF documents.
Trim string	Syntax: `{{trim "string goes here"}}` Notes: Removes any spaces from the start/end of the provided string.
Trim suffix from a string	Syntax: `{{trimSuffix "suffix to remove here" "string goes here"}}` Notes: Removes the suffix from the given string.
Trim prefix from a string	Syntax: `{{trimPrefix "prefix to remove here" "string goes here"}}` Notes: Removes the prefix from the given string.
To uppercase	Syntax: `{{upper "string goes here"}}` Notes: Converts string to upper case.
To lowercase	Syntax: `{{lower "string goes here"}}` Notes: Converts string to lower case.

Using Partials

Partials allow you to keep your documents consistent by using common headers and footers. Partials can also be useful when displaying Corteza’s resources, such as displaying a record in a table.

Partials are included like shown below:

{{template "partial_handle"}}

The partial_handle is the handle you used when you defined the partial. For example:

{{template "email_general_header"}}

If your partial needs to access some data that you provided to the current template (the one that uses the partial), you need to provide the second argument to the partial inclusion process.

{{template "email_general_header" .property.to.pass}}

See the example below:

{
  "contact": {
    "values": {...}
  },
  "account": {
    "values": {...}
  }
}

If you want to pass the contact to the partial, you should include your partial like shown below:

{{template "partial_handle" .contact}}

If you want to pass all of the data to your partial, you should include your partial like shown below:

{{template "partial_handle" .}}

You would access the contact in your partial like shown below:

{{/* In case of the first example */}}
Hello {{.values.FirstName}}

{{/* In case of the second example */}}
Hello {{.contact.values.LastName}} of the {{.account.values.Name}}

The Preview

The preview section at the bottom of the page allows you to check how your documents will look like once the template is rendered.

The input box should contain a valid JSON object (render payload) with two root properties; variables and options:

{
  "variables": {},(1)
  "options": {}(2)
}

1	The `variables` parameter defines what data will be available one the document is rendered. The structure is not defined.
2	The `options` parameter defines the rendering options and is currently only available for PDFs.

An example of the render payload:

{
  "variables": {
    "param1": "value1",
    "param2": {
      "nestedParam1": "value2"
    }
  },
  "options": {
    "documentSize": "A4",
    "contentScale": "1",
    "orientation": "portrait",
    "margin": "0.3"
  }
}

The options marked with PDF only can only be used with PDF documents and are ignored elsewhere.

variables

Type: Object<any>
Description: The variables you wish to apply to the template. For example, if you wish \{{testing}} to work, you must pass {"variables": {"testing": "some value"}}.

options.marginBottom

PDF only.

Type: string< float; 0 >= n; inches >
Description: Controls the margin on the bottom of the page.

options.marginLeft

PDF only.

Type: string< float; 0 >= n; inches >
Description: Controls the margin on the left side of the page.

options.marginRight

PDF only.

Type: string< float; 0 >= n; inches >
Description: Controls the margin on the right side of the page.

options.marginTop

PDF only.

Type: string< float; 0 >= n; inches >
Description: Controls the margin on the top of the page.

options.marginY

PDF only.

Type: string< float; 0 >= n; inches >
Description: Controls the margin on the top and bottom of the page.

options.marginX

PDF only.

Type: string< float; 0 >= n; inches >
Description: Controls the margin on the left and right of the page.

options.margin

PDF only.

Type: string< float; 0 >= n; inches >
Description: Controls the margin on the left, right, top, and bottom of the page.

options.documentSize

PDF only.

Type: string<A0…A10, B0…B10, C0…C10, ANSI A, ANSI B, ANSI C, ANSI D, ANSI E, junior legal, letter, legal, tabloid>
Description: The size of the document following the ISO216 standard for the A, B, and C series; ANSI standard for ANSI A, B, C, and D; and NA standards for the last few.

options.documentWidth

PDF only.

Type: string< float; 0 >= n; inches >
Description: Specifies the document width if none of the presets fit your needs.

options.documentHeight

PDF only.

Type: string< float; 0 >= n; inches >
Description: Specifies the document height if none of the presets fit your needs.

options.contentScale

PDF only.

Type: string< float; 0 >= n >
Description: At what scale the document should be rendered; bigger number ⇒ bigger content.

PDF documents are limited to 0 >= n <= 8

options.orientation

PDF only.

Type: string<landscape,portrait>
Description: What orientation to render the document in.