Document Generator Tags

A "tag" refers to an expression that the Document Generator can replace in a document template using JSON data.

Data

The JSON data can be stored in Object Storage or specified inline in a Request.

Example - Stored in Object Storage

  "data": {    
    "source": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/names.json"
  }

Example - Specified inline in data.content

  "data": {
    "source": "INLINE",
    "content": [{"name":"John"},{"name":"Monica"}]
  }

{basic} Tag

Used to inject text or numbers.

Examples


Tag	Data	Result
`{basic}`	`{"basic":"Hello!"}`	Hello!
`{number}`	`{"number": 7}`	7

Formatting

{basic} tags can be formatted. See Number Formatting for more details.

Sample documents


MS Word Template	JSON Data	Output
Word-Basic.docx	Word-Basic.json	Word-Basic-output.docx

{#loop}...{/loop} Tag

A {#loop} tag is used to produce copies of a section of text vertically.

List Example

Data

{
  "class_list": [
    {
      "name": "Sue",
      "student_id": 1
    },
    {
      "name": "Bob",
      "student_id": 2
    },
    {
      "name": "Jean",
      "student_id": 3
    }
  ]
}

Template

Class List
{#class_list}* {student_id}: {name}
{/class_list}

Result

Class List
* 1: Sue
* 2: Bob
* 3: Jean

Table Example

Data

{
  "class_list": [
    {
      "name": "Sue",
      "student_id": 1
    },
    {
      "name": "Bob",
      "student_id": 2
    },
    {
      "name": "Jean",
      "student_id": 3
    }
  ]
}

Template


Id	Name
`{#class_list}{student_id}`	`{name}{/class_list}`

Result


Id	Name
1	Sue
2	Bob
3	Jean

Sample documents


MS Word Template	JSON Data	Output
Word-VLoop.docx	Word-VLoop.json	Word-VLoop-output.docx

Array Operations

Filter

The filter operation takes three arguments:

The property to filter on
The comparison to perform
The value to compare against

Currently, filtering is only supported on numeric types.

To use a filter, you must specify a new list, called {#filtered}...{/filtered} inside of the parent array doing the filtering.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|filter:price:>=:2}


Category	Name	Price
`{#filtered}{category}`	`{name}`	`{price}{/filtered}`

{/products|filter:price:>=:2}

Result


Category	Name	Price
Clothing	Shirt	3
Accessory	Hat	2

Sort

The sort operation takes two arguments:

The name of the property to use for sorting
asc or desc to sort the list in ascending or descending order.

To use a sort, you must specify a new list, called {#sorted}...{/sorted} inside of the parent array being sorted.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|sort:price:desc}


Category	Name	Price
`{#sorted}{category}`	`{name}`	`{price}{/sorted}`

{/products|sort:price:desc}

Result


Category	Name	Price
Clothing	Shirt	3
Accessory	Hat	2
Accessory	Belt	1

Distinct

The distinct operation takes a single argument:

The name of the property to select distinct values of.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

Categories:
{#products|distinct:category}

* {category}
  {/products|distinct:category}

Result

Categories:

* Accessory
* Clothing

Break

The break operator groups items together based on a shared property. It takes one argument:

The name of the property to group items on.

To use a break, you must specify a new list, called {#break}...{/break} inside of the parent array being broken into groups.

Example

In this example note that the "Belt" and "Hat" items shared a category ("Accessory"), but they are not grouped in the array ("Belt" is the first item in the array and "Hat" is the last item).

Once the break operator has been applied, the items are grouped together in the output.

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|break:category}
{#break}* Category:{category}, Product:{name}
{/break}
{/products|break:category}

Result

* Category:Clothing, Product:Shirt
* Category:Accessory, Product:Belt
* Category:Accessory, Product:Hat

Group

Splits an array into sub arrays of the given size. A single argument is required:

An integer specifying the group size.

To use a group, you must specify a new list, called {#group}...{/group} inside of the parent array being broken into groups.

If the array does not split perfectly into groups, the last group will be of smaller size. For example, if you have an array of 5 items, and you use group:2 on it, then two groups of two items and one group of one item will be created.

Example

Data

{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}

Template

{#products|group:2}Items
{#group}* {name}
{/group}
{/products|group:2}

Result

Items
* Belt
* Shirt
Items
* Hat

Sample documents


MS Word Template	JSON Data	Output
Word-VLoop-Arrays.docx	Word-VLoop-Arrays.json	Word-VLoop-Arrays-output.docx

{:loop}...{/loop} Tag

A {:loop} tag is used to produce copies of a section of text horizontally.

Table Example

Data

{
  "weekdays": [
    {
      "name": "Monday"
    },
    {
      "name": "Tuesday"
    },
    {
      "name": "Wednesday"
    },
    {
      "name": "Thursday"
    },
    {
      "name": "Friday"
    }
  ]
}

Template


Days	`{:weekdays}{name}{/weekdays}`

Result


Days	Monday	Tuesday	Wednesday	Thursday	Friday

Sample documents


MS Word Template	JSON Data	Output
Word-HLoop.docx	Word-HLoop.json	Word-HLoop-output.docx

Aggregators

Sum

The Sum Aggregator is used to calculate the sum of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Total Price: {items|sum:price}

Result

Total Price: 6

Average

The Average Aggregator is used to calculate the average of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Average Price: {items|avg:price}

Result

Average Price: 2

Max

The Max Aggregator is used to find the maximum value of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Max Price: {items|max:price}

Result

Average Price: 3

Min

The Min Aggregator is used to find the minimum value of an array.

Example

Data

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Template

Minimum Price: {items|min:price}

Result

Minimum Price: 1

Sample documents


MS Word Template	JSON Data	Output
Word-Aggregators.docx	Word-Aggregators.json	Word-Aggregators-output.docx

{%image} Tag

An {%image} tag is used to inject an image into a document. Images can be provided from an OCI Object Storage Bucket, or from a URL. Images must be provided as an object, for example:

{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png"
  }
}

The specific schema for each source type is described below. Additionally, the following properties may be (optionally) included in the image object to control formatting of the image:

width: A string of digits, followed by px. E.G. 200px. Sets the width of the image.
height: A string of digits, followed by px. E.G. 200px. Sets the height of the image.
alt_text: A string. This will be set as the alternative text of the image.

Default size of inserted images:

Smaller images: If an image is smaller than the page size, the original size is preserved.
Larger images: If an image is larger than the page size, it is resized to fit within the page width and height. The aspect ratio of the image is maintained.

Supported Formats

Document Generator supports the following image formats:

Schemas

OCI Object Storage

source: must be set to OBJECT_STORAGE
objectName: The path and name of the file
namespace: The namespace of your object storage bucket
bucketName: The name of the bucket that contains the file
mediaType: The Media Type (MIME) of the image

Example

Data

{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png",
    "width": "400px",
    "height": "200px"
  }
}

Template

{%my_image}

Result

URL

source: must be set to URL
url: the image URL in string format

Note: to use images from the Internet, Document Generator needs outbound access to the Internet. For example, if Document Generator is running in a private subnet in OCI, you could set up a NAT Gateway to allow Document Generator to connect to the Internet.

Example

Data

{
  "my_image": {
    "source": "URL",
    "url": "https://www.oracle.com/.../.jpg"
  }
}

Template

{%my_image}

Result

Data URL

Document Generator also supports the ability to pass images inside of Data URLs. The image must be Base64 encoded.

source: must be set to URL
url: the image URL in string format

Example

Data

{
  "my_image": {
    "source": "URL",
    "url": "data:image/png;base64,iVBORw0KG...go"
  }
}

Template

{%my_image}

Result

Sample documents


MS Word Template	JSON Data	Output
Word-Images.docx	Word-Images.json	Word-Images-output.docx

{?pagebreak} and {?columnbreak} Tags

A pagebreak tag is used to introduce a page break. There are four variations of these tags:

{?pagebreak} and {?page} both create page breaks.
{?columnbreak} and {?column} both create column breaks.

Sample documents


MS Word Template	JSON Data	Output
Word-Breaks.docx	Word-Breaks.json	Word-Breaks-output.docx

{*hyperlink} Tag

A {*hyperlink} tag is used to insert a clickable hyperlink (including email addresses) into a document.

A hyperlink must be provided as an object with the following properties:

url: a URL in string format
url_text (optional): a string to be displayed instead of the URL

Example

Data

{
  "link": {
    "url": "https://www.oracle.com/",
    "url_text": "Click me!"
  }
}

Template

Follow the link: {*link}

Result

Follow the link: Click me!

Sample documents


MS Word Template	JSON Data	Output
Word-Hyperlinks.docx	Word-Hyperlinks.json	Word-Hyperlinks-output.docx

Number Formatting

If a value being supplied to a {basic} tag is a number, Document Generator supports the ability to format it.

A formatter is specified as follows: {input_number|format:[format]:[separators]:[currency_symbol]} where:

[format] is a supported number format
[separators] (optional) is a 2 character string. The first character indicates the decimal separator, the second character indicates the comma separator
[currency_symbol] (optional) the currency symbol to apply if L is present in [format]

Number formats must be specified in one of the following Oracle Number Formats:

FML999G999G999G999G990D00
FML999G999G999G999G990
999G999G999G999G990D00
999G999G999G999G990D0000
999G999G999G999G999G999G990
999G999G999G999G990D00MI
999G999G999G999G990D00MI
S999G999G999G999G990D00
999G999G999G999G990D00S
S999G999G999G999G990D00
999G999G999G999G990D00PR
FML999G999G999G999G990PR
999G999G999G999G990D00PR

Examples

The following table is given to share examples of these formats, given a number:


Template	unit_price: 1234.5	unit_price: -1234.5
`{unit_price\|format:"FML999G999G999G999G990D00":"<>":"$"}`	$1>234<50	-$1>234<50
`{unit_price\|format:"999G999G999G999G999G999G990"}`	1,234	-1,234
`{unit_price\|format:"999G999G999G999G990D00MI"}`	1,234.50	1,234.50-
`{unit_price\|format:"S999G999G999G999G990D00"}`	+1,234.50	-1,234.50
`{unit_price\|format:"999G999G999G999G990D00PR"}`	1,234.50	<1,234.50>
`{unit_price\|format:"FML999G999G999G999G990PR"}`	$1,234	<$1,234>

Tag - Advanced Examples

Loop in Loop

In this example, we have 2 levels of loops. One for the movies and another for the actors.


MS Word Template	JSON Data	Output
Word-LoopInLoop.docx	Word-LoopInLoop.json	Word-LoopInLoop-output.docx

Aggregation and Formatting combination

In this example, the Total of the Invoice uses both Aggregation (sum) and Number Formatting.


MS Word Template	JSON Data	Output
Word-AggregationAndFormat.docx	Word-AggregationAndFormat.json	Word-AggregationAndFormat-output.docx

Oracle Cloud Infrastructure Documentation

Document Generator Tags

Data

Tags

{basic} Tag

Examples

Formatting

Sample documents

{#loop}...{/loop} Tag

List Example

Data

Template

Result

Table Example

Data

Template

Result

Sample documents

Array Operations

Filter

Example

Data

Template

Result

Sort

Example

Data

Template

Result

Distinct

Example

Data

Template

Result

Break

Example

Data

Template

Result

Group

Example

Data

Template

Result

Sample documents

{:loop}...{/loop} Tag

Table Example

Data

Template

Result

Sample documents

Aggregators

Sum

Example

Data

Template

Result

Average

Example

Data

Template

Result

Max

Example

Data

Template

Result

Min

Example

Data

Template

Result

Sample documents

{%image} Tag

Supported Formats

Schemas

OCI Object Storage

Example

Data

Template