How to prepare an Office template for content replacements
DOWNLOAD TEMPLATE:
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.
Some of these tasks require to pre-process the Office document to insert “palceholder variables” that help to greatly
simplify the ceration 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. jsut plain text formatting.
- Insert blocks of content like paragraphs, table, charts, etcetera, anywhere within the document.
- Replace “placeholder” images by new ones.
- Remove or clone content.
Although, as commented before, all these tasks can be carried out without additional pre-processing of the original Office template the
introduction of variables greatly simplify the procedure and let the designers to have greater control over the final result.
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 you may
use any other symbol the double curly bracket is the default choice (otherwise you should instruct the replace method which symbol you have chossen).
Although we leave the details for the corresponding tutorial page, we would like to strees that one easily can:
- Replace all ocurrences of a given variable by a single value: palin 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 method).
When replacing text the original document formatting style is preserved/merged as required.
Replacing by blocks of content
You amy also replace a single variable by a whole chunk of content by declaring the variable a of teh “block” type within
the replace method.
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 method.
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) to the replace method.
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.
Replacing chart data
The replacement of chart data does not reuire of any specific tagging because one always should proceed by matching order.
We refer to the replaceChartData method for further clarifications of the subject.
Images may also be easily replaced simply by matching order.
