ReportingCloud provides an extensive API to manage templates. You can upload, list, count, delete and download templates from the ReportingCloud template storage. But it also provides endpoints to retrieve data structure information from a template.
The endpoint template/info returns information about the template including the merge field and merge block structure in a hierarchical form.
https://api.reporting.cloud/v1/templates/info
After calling this method with the template name as a request parameter, it returns a JSON string with the template information similar to this:
| { | |
| "templateName": "sample_invoice.tx", | |
| "mergeBlocks": [ | |
| { | |
| "name": "item", | |
| "mergeFields": [ | |
| { | |
| "dateTimeFormat": "", | |
| "name": "qty", | |
| "numericFormat": "", | |
| "preserveFormatting": false, | |
| "text": "«qty»", | |
| "textAfter": "", | |
| "textBefore": "" | |
| } | |
| ], | |
| "mergeBlocks": [] | |
| } | |
| ], | |
| "mergeFields": [ | |
| { | |
| "dateTimeFormat": "", | |
| "name": "yourcompany_companyname", | |
| "numericFormat": "", | |
| "preserveFormatting": false, | |
| "text": "«YOURCOMPANY_COMPANYNAME»", | |
| "textAfter": "", | |
| "textBefore": "" | |
| }, | |
| { | |
| "dateTimeFormat": "", | |
| "name": "invoice_no", | |
| "numericFormat": "", | |
| "preserveFormatting": false, | |
| "text": "«invoice_no»", | |
| "textAfter": "", | |
| "textBefore": "#" | |
| } | |
| ] | |
| } |
The returned object is of type TemplateInfo which contains all fields at root level and all nested merge blocks including contained merge fields:
TemplateInfo Object
| Key | Value Type | Value Description |
|---|---|---|
| templateName | String | The filename of the template in the template storage. |
| mergeBlocks | List of ReportingCloud MergeBlock objects | Contains all merge blocks in the template. |
| mergeFields | List of ReportingCloud MergeField objects | Contains all merge fields in the template. |
MergeBlock Object
| Key | Value Type | Value Description |
|---|---|---|
| name | String | The name of the MergeBlock. |
| mergeBlocks | List of ReportingCloud MergeBlock objects | Contains all merge blocks in the template. |
| mergeFields | List of ReportingCloud MergeField objects | Contains all merge fields in the template. |
MergeField Object
| Key | Value Type | Value Description |
|---|---|---|
| dateTimeFormat | String | Specifies a string format which is applied to date / time values. |
| name | String | Gets and sets the name of the field. |
| numericFormat | String | Specifies a string format which is applied to numeric values. |
| preserveFormatting | Boolean | Specifies whether the formatting is preserved. |
| text | String | Gets and sets the text of the field. |
| textAfter | String | Gets and sets the text after the field. |
| textBefore | String | Gets and sets the text before the field. |
In most cases, hierarchical data is used to design the template. But there are also use cases where data is shaped based on the data structure in a template. The work flow would be similar to this:
- Retrieve template information
- Create data object based on contained data structure
- Merge template with newly created pre-shaped data object
To illustrate how to iterate through the hierarchical data, the following code shows how to fill a tree view in .NET using the .NET ReportingCloud wrapper:
| private void addBlockToTreeView(List<MergeBlock> blocks, TreeNode node) | |
| { | |
| foreach (MergeBlock block in blocks) | |
| { | |
| TreeNode curNode; | |
| if (node == null) | |
| curNode = treeView1.Nodes.Add(block.Name); | |
| else | |
| curNode = node.Nodes.Add(block.Name); | |
| foreach (MergeField field in block.MergeFields) | |
| { | |
| curNode.Nodes.Add(field.Name); | |
| } | |
| if (block.MergeBlocks != null) | |
| addBlockToTreeView(block.MergeBlocks, curNode); | |
| } | |
| } |
The following screenshot shows the populated tree view in a sample .NET Windows Forms application:
If you want to test this on your own, register today for a free 30-day trial license.
Happy coding!
