Documentation

Replace/Merge content

The main goal of the DXCloud REST API is to facilitate the creation of sophisticated documents in any format without the need of writing long and complex code or installing any library or program in your servers.

The easiest way to achive that goal is to start with a template that encapsulates from the very start much of the formatting and structure of the document we are aiming for.

But if we need to "inject dynamical" content in our resulting document we need to tag our template in a way that will allow us to enrich its contents with the required data.

In order to do that we have to insert "placeholder variables" that will be "waiting" for content of two types:

  • inline: or in other words (formatted) text.
  • block: complex and structured content like paragraphs, tables, images, headigns, charts, etc. See the HTML merging sample section for a detailed account.

In the following we will just pile up a series of code samples that will hopefully illustrate the standard perviously defined.

Although you are free to combine the replace option with the remove and clone ones in the way it best fit your purposes, the replace option will be able to take care by its own of the required cloning to accomodate the provided variable values in practically all but the most complex scenarios.

Replacing/Merging (formatted) text

Before starting with a some examples a few comments are due:

  • A placeholder variable may appear one or several times in a template.
  • A repeated placeholder variable may be replaced by just one or multiple variables.
  • The replacement algorithm follows a cyclic rule, i.e. if the number of provided values gets "exhausted" Docxpresso will go back to the first value again and continue replacement. This, in particular, implies that if we only provide a single value all instances of the placeholder variable will be replaced by that value.
  • If the number of provided values is higher that the number of ocurrences of the placeholder variable the "extra" values will be simply ignored.
  • If a placeholder value is not found for replacement it will be simply ignored (no error will be thrown).

In the following example we will replace a few variables by plain and HTML formatted text:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "replace": [
        {
            "vars": [
                {
                 "var": "name",
                 "value": ["Eduardo Ramos"]
                },
                {
                 "var": "company",
                 "value": ["Docxpresso", "No-Nonsense Labs"] 
                }
            ]
        }
    ]
}

DOWNLOAD: Template JSON Doc

replace variable by text

You can check that the formatting of the original variable is preserved although it can be complemented with HTML + CSS.

We leave to the reader as an exercise to check the effect of all other available options for text merging: match, html and parse-line-breaks.

Replacing/Merging paragraph content

Although we could combine the clone method for paragraphs with the plain text merging to create as many paragraphs as needed with the required content, we may do it in just in one shot with the paragraph option of the replace method.

The JSON in this case looks like:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "replace": [
        {
            "vars": [
                {
                 "var": "name",
                 "value": ["Eduardo Ramos", "John Smith", "Greta Johns"]
                },
                {
                 "var": "company",
                 "value": ["Docxpresso", "<span style='color: green'>No-Nonsense Labs</span>", "DXCloud"] 
                }
            ],
            "options": {
                "element": "paragraph"
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

replace variables in paragraphs

Replacing/Merging list items

The case of lists is equally simple, we just need the following JSON:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "replace": [
        {
            "vars": [
                {
                 "var": "item",
                 "value": ["First", "Second", "<strong>Third</strong>", "<span style='color: red'>Fourth</span>"]
                }
            ],
            "options": {
                "element": "list"
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

replace variables in lists

Replacing/Merging table content

Let us first run a simple example involving the replication and merging of a single row. The required JSON reads:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "replace": [
        {
            "vars": [
                {
                 "var": "product",
                 "value": ["Product 1", "Product 2", "Product 3"]
                },
                {
                 "var": "price",
                 "value": ["$30.00", "$25.50 <span style='color: red'>(Out of stock)</span>", "$10.00"] 
                }
            ],
            "options": {
                "element": "table"
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

replace variables in tables

But we can also do more complex table structures with verically merged cells (the JSON structure does not change though):

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "replace": [
        {
            "vars": [
                {
                 "var": "product",
                 "value": ["Product 1", "Product 2", "Product 3"]
                },
                {
                 "var": "price",
                 "value": ["$30.00", "$25.50 <span style='color: red'>(Out of stock)</span>", "$10.00"] 
                },
                {
                 "var": "availability",
                 "value": ["24 hours", "<span style='color: red'>(Out of stock)</span>", "4 days"] 
                }
            ],
            "options": {
                "element": "table"
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

replace variables in tables with merged cells

Replacing/Merging images

Replacing an image is equally simple. A tipycal usage case may be to replace a logo in a header. The required JSON for that particular case reads:

{   
    "template": "insert here the given template base64 encoded",
    "output": "odt",
    "replace": [
        {
            "vars": [
                {
                 "var": "logo",
                 "value": ["data:image/png;base64,..."],
                 "height": "46px",
                 "width": "205px"
                }
            ],
            "options": {
                "element": "image",
                "target": "header"
            }
        }
    ]
}

DOWNLOAD: Template JSON Doc

Notice that although the width and height parameters are optional if we do not explicitly give them the width and height of the original placeholder image would have been used (default behaviour) causing a distorted result in this case.

replace image in header