Please wait...

How to create templates for WordPress Report Builder

Create Report Builder templateNavigation through Report Builder template creation

In this section we go through the main rules of template creation.

Whether you create an Excel XLSX report, or MS Word DOCX report, the templates follow almost same rules.

1. All variables (parts that should be dynamically inserted by WordPress Report Builder) start with a dollar sign and are wrapped in curly brackets, like this:

${variable}

Using this layout Report Builder distinguishes static content from the parts that should be replaced dynamically.

Please note: when you work with DOCX files you can place variables wherever you need, however in XLSX templates the variable MUST BE ALONE in the table cell, i.e. cell should contain nothing except the variable, or variable will not be recognized. For example if a cell contains “here is ${myvariable}” the variable won’t be recognized by Report Builder. 

2. When you are referencing a column name from a source wpDataTable, use the following layout:

${mycolumn.name}

Where “mycolumn” is column’s origin header – you can see it in wpDataTables configuration page when you open column settings panel by clicking on “Column settings” button column-config or by clicking “Column list”  button above the table from where you can open column configuration for each column.

Origin header

In this case, if we would like to use this column’s name we would put: ${product.name}

3. For any wpDataTable, there are 2 main ways to create a report: 1) a single report file for all rows, 2) separate report file for each row. First scenario is suitable when you’re e.g. printing an invoice for purchases done during the month, second scenario is suitable if you are e.g. generating welcome letters to all new hotel visitors that came today.

4. If you are creating a single report for all rows, you can reference the column cell values of each row like:

${mycolumn.all}

Where “mycolumn” is the original column name (see above). At the moment of generation, the ${mycolumn.all} is going to be duplicated for each table’s row, and filled with the cell value.

Please note some limitations of the current version:

  • Images, URL links, e-mail links are currently unsupported (“Raw” cell values will be inserted, but the links/images won’t)
  • Only a single wpDataTable can be referenced in the report
  • All source columns should be existing within the same template table, i.e. it’s not possible for the moment to have separate tables in the template for column1, column2, etc.

5. If you are generating a single report for all rows, you can calculate totals for numeric (float and integer) columns, to do this insert the variables like:

${mycolumn.total}

E.g. this can be done to insert invoice’s total, or similar.

6. If you are preparing a single MS Word DOCX report for all table’s rows, you can use repeating blocks for each row instead of a table. To do this use layout like:

${wpDataTable.row}
Column1: ${column1.all}
Column2: ${column2.all}

                …
${/wpDataTable.row}

Basically, block that you want to repeat for each row must be wrapped in ${wpDataTable.row}…{/wpDataTable.row}, and the cell reference is same as for the tables – ${column.all}.

Please note that those loops have to be in new rows.(You can not use it like this in one row)

${wpDataTable.row} ${column1.all} ${/wpDataTable.row}

7. If you are generating a multi-file report with a separate file for each row, reference the column values just like:

${column}

Where “column” is the target column’s original header (see above).

8. Any kind of report can use additional variables. You can define any number of additional variables at the moment of report creation, and reference them in the template. Please note if a variable will not be found in the incoming data, it is going to stay as is in the generated template: e.g. if you use ${myvar} variable in the template, but do not define it on WordPress site, it is going to stay ${myvar} in the generated reports.

9. All reports can use default pre-defined variables (username, today’s date, etc.). See the full list here.

From version 1.3 it is added ${wdtrowindex.all} variable for templates with which you can create index column in Word or Excel templates.