External services

The goal of this section is to explain how a developer should prepare an external service that is to be hooked to a Docxpresso variable.

Here we will not explain how to define an external service within Docxpresso and how to associate it with a document/variable. If you are looking for this type of info, please refer to: path to web page.

Let us assume that an external service has been previously defined in the Docxpresso interface with:

Whenever a end user will click on the button that links to this external service in the Docxpresso end user interface an iframe will be loaded with a src, the predefined service url together with the following GET parameters:

  • refvar: the name of the variable associated with the external service.
  • custom: any string of data that has been preloaded in the options variable of the URL that has been used to access the Docxpresso interface (see how to load custom data with the help of the SDK or directly from the Docxpresso backoffice interface).
  • vardata: a JSON encoded object with the current values in the interface of the parameters variable1 and variable2: {“variable1”:[“value1”], “variable2”:[“value2”]}. Notice that each array may have more than one value if the corresponding variable appears more than once in the document.

With all this info the external service via its internal logic and/or queries to a data source is supposed to generate a JSON encoded object with data that will be loaded on the corresponding Docxpresso Document.

How to load data in the Docxpresso document

We are going to assume, for the sake of the argument, that we want to load into the Document the data associated with the variables var1 and var2 (these variables should, of course, be defined in the underlying document).

Whenever de data is ready to be forwarded to Docxpresso we only need to build an object in the following fashion:

var obj={};
obj["var1"] = [val1"];
obj["var2"] = ["val2"];

var data = JSON.stringify(obj);
window.parent.postMessage(data, "*");

A comment now is due on how the data is loaded into Docxpresso

If a variable is defined as global within Docxpresso and it is one of the variables defined in the previous object it will be replaced as many times as it appears in the document with the corresponding value.

If a variable is not defined as global within Docxpresso it will be replaced only if it belongs to the same cloneable block that the variable that have associated the external service.

This is done to allow for applying the same service, for example, to different rows of a cloneable table.

How to load multiple cloneable values in one shot.

Whenever we are populating the rows of a table or a set of list items with the help of an external service it may sometime show convenient to do it in just one shot. In order to do so one only has to slightly modify the JSON by wrapping the variables associated with each cloneable element within a “multipleDXO” property:

var obj={};
//first block
var subobj_1 = {};
subobj_1 ["var1"] = [val1"];
subobj_1 ["var2"] = ["val2"];
//second block
var subobj_2 = {};
subobj_2 ["var1"] = ["val3"];
subobj_2 ["var2"] = ["val4"];

obj["multipleDXO"] = [subobj_1, subobj_2];

var data = JSON.stringify(obj);
window.parent.postMessage(data, "*");