Using Velocity Templates - Request Body Examples

This page provides examples how to use REST services related to using templates. Currently, the following services are available:

Apply template - /tribefire-services/api/v1/access.adx.content.default/v1/convert/apply-template
Merge templates - /tribefire-services/api/v1/access.adx.content.default/v1/convert/merge-templates

Both of these endpoints only require a sessionId (see Authenticating to ADx via REST) and a request body with JSON data structure containing the following items:

Template specifications
IDs of the templates you work with (note that in ADx 2.x templates are treated as any other contents, hence the contentId in the examples below)
Information about action to be performed (resultAction - either NEW_CONTENT or CONTENT_REPRESENTATION)

See the examples below to get an idea of how the request body could look like.

Templates

Examples shown later in this page are based on the following Velocity templates, which you can copy to a text editor, save as .vm file, and upload to ADx:

Simple template with one variable (let's call it simple.vm):

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>ADx template</title>
  </head>
  <body>
    Hello ${replacement}!
  </body>
</html>

More complex template with a for loop (let's call it loop.vm):

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Complex ADx template</title>
</head>
<body>
  $simple
  #foreach( $entry in $list.getValues() )
    <li>$entry.get("name")</li>
  #end
</body>
</html>

Template Specification for Text Replacement

Use the JSON snippets below to develop your own text replacement body.

Text Replacement - Apply Template

This is an example of a request body where the source template has one variable - replacement. When you send the request below to /apply-template, a new document called ADx template will be generated, with Replacement text being assigned to replacement and rendered in the document.

{
  "contentId": "simple-vm-ID-goes-here",
  "templateSpecifications": [
    {
      "variables": {
        "replacement": "Replacement text"
      }
    }
  ],
  "priority": 0,
  "resultAction": "NEW_CONTENT",
  "targetName": "ADx template"
}

Text Replacement - Merge Templates

When you send the following request body to /merge-templates endpoint, two templates (identified by contentIds array) are merged into a new document. replacement variable in both templates is replaced by Replacement text.

{
  "contentIds": ["simple-vm-ID-goes-here", "simple-vm-ID-goes-here"],
  "templateSpecifications": [
    {
      "variables": {
        "replacement": "Replacement text"
      }
    }
  ],
  "priority": 0,
  "resultAction": "NEW_CONTENT",
  "targetName": "Merged Template"
}

Template Specifications with Map Records

These examples show how to use template specifications with a map record, which bundles multiple variables.

Apply Template

Examples below demonstrate how you could work with simple.vm and loop.vm via the /apply-template endpoint.

Simple Template

When we send the following request to /apply-template, target document will be rendered from simple.vm:

{
    "contentId": "simple-vm-ID-goes-here",
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "replacement": "ADx replacement text"          
                }
            }
        }
    ]
}

Loop Template

When we send the following request to /apply-template, target document will be rendered from loop.vm:

{
    "contentId": "loop-vm-ID-goes-here",
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "simple": "ADx templates",
                    "list": {
                        "_type": "com.braintribe.model.record.ListRecord",
                        "values": [
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 1"
                                }
                            },
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 2"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ]
}

Merge Templates

Examples below demonstrate how you could work with simple.vm and loop.vm via the /merge-templates endpoint.

Simple Template

This request will merge two simple.vm templates into one document.

{
    "contentIds": [
        "simple-vm-ID-goes-here", "simple-vm-ID-goes-here"
    ],
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "replacement": "ADx replacement text"          
                }
            }
        }
    ]
}

Loop Template

This request will merge two loop.vm templates into one document.

{
    "contentIds": [
        "loop-vm-ID-goes-here","loop-vm-ID-goes-here"
    ],
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "ADx template",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "simple": "ADx templates",
                    "list": {
                        "_type": "com.braintribe.model.record.ListRecord",
                        "values": [
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 1"
                                }
                            },
                            {
                                "_type": "com.braintribe.model.record.MapRecord",
                                "values": {
                                    "name": "ADx templates loop value 2"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ]
}

Nesting and Back-Linking Velocity Templates

ADx enables you to nest velocity templates inside each other. This allows to you import templates into other ones before the original template is evaluated. You can also import images.

When nesting templates, be aware of the following:

ContentIDs of imported templates and images are defined in the JSON body of the /merge-template request.
Both the imported templates and the images must be contents in your ADx repository.

Directives

The following table shows the main directives.

Directive	Description
`<<doc [context.openRemoteResourceByRefEval("path")] >>`	Inserts the content of the resource identified by the path.
`<<doc [context.openRemoteResourceById("accessId", "resourceId")] >>`	Inserts the content of the resource identified by the actual access ID and resource ID.
`<<image [context.openRemoteResourceByRefEval("path")] >>`	Inserts the specified image in Base64-encoding in the form `data:_imageMimeType_;base64,_theActualImageDataEncodedInBase64_`.
`<<image [context.openRemoteResourceById("accessId", "resourceId"))] >>`	Inserts the specified image contained in the resource identified by the actual access ID and resource ID.

If the access ID is blank, the default access ID (which is the access ID where the original template is stored) is used. The path denotes the location within the input JSON's mapRecord. If you need to access deeper structures within the mapRecord, you can use multiple path elements separated by ->.

Importing mapRecords into TemplateSpecifications

ADx enables you to import mapRecords into a TemplateSpecification. This is helpful when you want to use the same mapRecord in more than one request, for example. To import a mapRecord, use the mapRecordImports property inside your template specification. Be aware of the following:

If the main template specification contains a key with a value different from the value of the same key inside the mapRecordImports, then the value in the main template specification takes precedence.
You can import more than one mapRecord.

Try It Out in Swagger

Simple and Loop Templates

Log in to ADx.
On the landing page, click the API link under repository where you want to use template services:

OpenAPI page opens.
Consider switching to Swagger 2.0 before executing requests - it is more mature than OpenAPI, which is still in experimental phase.
Expand endpoints under Conversion. You will find both /apply-template and /merge-templates.
Click Try it out! to activate the fields.
Paste your template specification into the Request body field.
Click Execute and check the response. You should get the job duration in the response, and your service should be executed. Check ADx Explorer to verify that your content was indeed rendered or merged.

Nesting Templates

To follow this example, do the following:

Upload , , , and an image to your ADx repository.
In Swagger, find the Merge templates - /tribefire-services/api/v1/access.adx.content.default/v1/convert/merge-templates end point.
Copy the and make sure you replace contentId with the write ID of your contents.
Run the request. The result is a new content called html-template-test.

ParentTemplate.vm

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Parent ADx template</title>
</head>
<body>
<h1>Test template IMPORT1<h1/>
  <<doc [context.openRemoteResourceByRefEval("IMPORT1")] >>
  <hr />
  <<doc [context.openRemoteResourceByRefEval("IMPORT2")] >>
  <br/>
  An image: <<doc [context.openRemoteResourceByRefEval("IMAGE")] >>
</body>
</html>

Import1.html

<b>This is the bold content of "import1.html"</b>

Import2.html

This is the  content of "import2.html"
Importing import3:   <<doc [context.openRemoteResourceByRefEval("IMPORT3")] >>

Import3.html

In the year of ${year}.

JSON Body

{
    "contentIds": [
        "d4062fce-cd7b-4659-9252-750d0bb940d3"
    ],
    "priority": 0,
    "resultAction": "NEW_CONTENT",
    "targetName": "html-template-test",
    "templateSpecifications": [
        {
            "mapRecord": {
                "_type": "com.braintribe.model.record.MapRecord",
                "values": {
                    "year": "2020",
                    "IMPORT1": {
                        "_type" : "tribefire.adx.model.content.service.v1.request.conversion.ContentReference",
                        "contentId" : "b800cc84-f210-4b3d-84d0-1e47ac682936"
                    },
                    "IMPORT2": {
                        "_type" : "tribefire.adx.model.content.service.v1.request.conversion.ContentReference",
                        "contentId" : "18d7a885-ae63-4929-a6c9-be27a8652fcc"
                    },
                    "IMPORT3": {
                        "_type" : "tribefire.adx.model.content.service.v1.request.conversion.ContentReference",
                        "contentId" : "59f4ad63-7a7a-445f-a6cc-4d6dfb2f40ca"
                    },
                    "IMAGE": {
                        "_type" : "tribefire.adx.model.content.service.v1.request.conversion.ContentReference",
                        "contentId" : "2388c9ab-94b1-4d3c-b1c8-f5ce8abe5db9"
                    }
                }
            }
        }
    ]
}

Using Velocity Templates - Request Body Examples

On this page

Templates

Template Specification for Text Replacement

Text Replacement - Apply Template

Text Replacement - Merge Templates

Template Specifications with Map Records

Apply Template

Simple Template

Loop Template

Merge Templates

Simple Template

Loop Template

Nesting and Back-Linking Velocity Templates

Directives

Importing mapRecords into TemplateSpecifications

Try It Out in Swagger

Simple and Loop Templates

Nesting Templates

ParentTemplate.vm

Import1.html

Import2.html

Import3.html

JSON Body