Data Structure

Docxpresso JSON Data Schema

All input/output data exchange within Docxpresso or with third party tools is carried out in JSON format.

Although many of the specific details of the Docxpresso JSON schema may result of not much interest for developers, the purpose of this section is to give a complete rendering of it making special emphasis in those bits that may be of particular relevance for the integration of Docxpresso with third party tools or other web apps.

To start with let us defined the different “subschemas” that are used within the most general JSON:

• User document data: this block stores all the required data to generate the final document integrating all required data,
  • “attachments”
  • “blocks”
  • “dependencies”
  • “merge”
  • “remove”
  • “share”
  • “specialVarValues”
  • “varValues”
• Template info: this block is used to store template data,
  • “attachments”
  • “data”
  • “groups”
  • “rpcs”
  • “settings”
  • “signatures”
  • “special”

In order to simplify the access to the most relevant parts of the schema we will only concentrate on the most potentially relevant part for developers that we have highlighted in red.

User document data

Although Docxpresso allows for the complete programmatic customization of all template data, in the majority of cases the required exchange of data will need exclusively the varValues section and only in more sophisticated cases the blocks and remove subschemas would be needed.

VarValues

Let us a start with a trivial example of a template with just one editable variable {{name}} and let us further assume that this variable is of the plain text type and it is a “global variable”, i.e. we expect every single appearance of the variable in the document should render the same value.

For this particularly simple case the JSON that will allow us to load the value “John Smith” on the template will be as simple as:

{
    "varValues": { "name": ["John%20Smith"]}
}

Notice: all Docxpresso data is offered URL encoded and should be equally consumed as URL encoded.

In the case that the variable name appears more than once and we expect that their values should be independent and we expect the first appearance to be “John Smith” and next appearance to be “Hellen Smith” we just simply need to modify the above JSON as:

{
    "varValues": { "name": ["John%20Smith", "Hellen%20Smith"]}
}

The generalization to multiple variables is obvious:

{
    "varValues": { 
        "name": ["John%20Smith"],
        "othervar":["value"],
        "yetanothervar":["otherval1", "otherval2"]
    }
}

blocks

So far so good but things get slightly more complicated when the template includes “cloneable blocks” like for example table rows that may be replicated.

For the sake of the argument let us assume that the template includes a set of table rows that may be replicated:

First of all we should get the identifier of that cloneable group.

Within the template edition interface by clicking in the gear button:

The following pop up opens with info about that cloneable group:

From here we get that the inner identifier of this table group is “table=1” so if we want this group to be programmatically cloned twice we should generated the following JSON:

{
    "blocks":{
         "table:table=1::0":{
            "tb_table:table=1::0": {},
            "tb_table:table=1::1":{}
    }
},
    "varValues": { 
        "product": ["Camera", "Phone"],
        "Price":["120.00", "450.50"],
    }
}

In order to obtain the following result:

The reason for that recursive structure is to allow for multiple nestings, i.e. tables within tables with cloneable lists and/or bookmarked content in any possible combination.

Like things may get quite messy when different type of blocks are nested we recommend to generate a sample document with the requested structure and check what is the JSON generated by Docxpresso.

For example, in a document that has been filled and we “resend to the browser” thanks to a URL generated within the Docxpresso interface we may check in the developers console under the “document data” literal:

Where we can check which is the structure generated by Docxpresso that should be replicated. In this particular case we are cloning not only some table rows but a list that has been labeled like: list-item=1.

remove

Through the Docxpresso interface is also possible to remove blocks of content depending on the value of an associated variable.

In order to so programmatically one should use the subschema associated with the “remove” key of the JSON.

The procedure is similar to the one of cloning though fortunately much more simple. For example to remove the table tagged as table=1 one only need to include in the JSON:

{
    "remove":["table:table=1"]
}

If more than one group should be removed they should be added to the array. Once again if you have multiple blocks of content the easier way to do some example within Docxpresso and see the resulting structure of the remove key generated by the Docxpresso interface.

specialVarValues

The structure of this subschema is in all similar to the one of varValues but restricted to special variables that are tagged like [[variable_name]] within the Docxpresso templates.

The values of this variables are computed depending on the values of standard “numeric” variables but they can be preloaded in case we want to precompute them or because the associated variables on which it depends have been preloaded via varValues.

merge

This keeps track of potential annexes to the document. Whenever a document holds more than one possible annex we may preload one of them with the following JSON:

{
    "merge":["token"]
}

Where the token value for a particular annex can be found by clicking on the annex name under the Resources > Browse annexes of the main Docxpresso backoffice menu.

attachments, share & dependencies

These subschemas just keep track of internal Docxpresso info that it is not, in principle, susceptible to be currently customized so we will not enter into any detail to this respect.

Template data

In most cases developers will not have the need to customize programmatically the template data although that is possible via a custom service that may be called via the “configDataURI” property.

The call to this external service can be carried out both from the Docxpresso backoffice:

Or directly via de SDK.

The data subscheme includes an array that incorporates all the variable options that have been previously configured in the backoffice as can be checked by inspecting any Docxpresso document in the browser:

And expanding one particular entry is an object that contains several properties:

If we would like to change, for example, the variable treatment by modifying its label, the available options and declaring it compulsory we should call a script that returns the following JSON structure:

<?php
echo '{"treatment":{"label": "Choose a treatment", "options":"Prof.;Dr.", "compulsory": true"}}';

This can be done for any of the template variables to change any of their properties as we would do directly from the Docxpresso backoffice web interface.