Documentation

How to prepare an Office template for DXCloud

Docxpresso has the ability to add, replace, remove and clone content from an existing Office template thus greatly simplifying the task to create beautiful reports and documents with just a few lines of code.

These tasks require to pre-process the Office document to insert "palceholder variables" that help to greatly simplify the creation of the final document.

Basically we introduce "variables" to streamline the following:

  • Replace runs of text by plain text or "inline" HTML content, i.e. just plain text formatting.
  • Insert blocks of content like paragraphs, table, charts, etc, anywhere within the document.
  • Replace "placeholder" images by new ones.
  • Modify chart data.
  • Remove or clone any type of content.

Let us briefly go over the details.

Replacing (formatted) text

You may introduce anywhere in the text a variable by just inserting it between double curly brackets, i.e. {{var_name}}.

Although we leave the details for the samples section of this documentation we would like to stress that you may:

  • Replace all ocurrences of a given variable by a single value: plain text or HTML.
  • By using an array replace the different ocurrences of the variable by different values, once again by plain text or HTML.
  • Replace a particular single ocurrence (this can be useful when combined with the clone option).

When replacing text the original document formatting style is preserved/merged as required.

Replacing by blocks of content

You may also replace a single variable by a whole chunk of content by declaring the variable a of the "block" type within the replace option.

By doing so you may insert anywhere in the document:

  • New paragraphs,
  • tables,
  • images,
  • charts
  • or in fact any other document component.

Beware that the original paragraph containing the variable will be removed but all previous nesting will be preserved, i.e. variables within tables, bookmarked content, etcetera. will be replaced by content inside those elements.

Replacing and cloning content in tables and lists

A typical need is to replace content that should be "cloned" within a table or a list of items.

There is no need to add to the template the required number of rows or list items: Docxpresso do that job for you just by declaring the variable to be of the "list" or "table" type in the replace option.

Something of the type:

  • {{item}}

for lists or

Product Description Price
{{product}} {{description}} ${{price}}

for tables will offer the desired result just by providing the corresponding arrays of values (once again as plain text or HTML content).

Much more complex combination of rows is also possible because Docxpresso detects automatically the involved table rows and groups them before carrying out the cloning.

Replacing images

Docxpresso also allows you to replace tagged images.

You just have to introduce the variable as the "title" of the "alternative text" that you may associate to an image within the text editor of your favourite Office Suite.

When replacing your "placeholder image" by a new one you also may:

  • Preserve the original dimensions.
  • Modify the width and height attributes of the image.
  • Introduce an offset in the x and y coordinates (this may show useful when you want to move an image over a chart or other kind of graph).
  • Replace all ocurrence of the image (useful with, for example, a logo) or do it one by one.

Images may also be easily replaced simply by matching order.

Replacing chart data

Like in the case of images introduce the variable as the "title" of the "alternative text" that you may associate to a chart within the text editor of your favourite Office Suite.

We refer to the replaceChartData option samples for further clarifications of the subject.

Charts may also be easily replaced simply by matching order.