Template design best practices

Well-designed templates are easier to maintain, adapt to multiple languages and companies, and produce correct output across every culture. This article covers the key practices for building reliable templates in Docentric Template Designer and avoiding common traps, organized by design workflow, page layout, and calculations.

Prerequisites

Workflow best practices

Follow these practices while you design and iterate on a template.

Start from a finished layout, not a blank page

First, draft the report as a plain Word document with real sample data. Apply the final formatting, fonts, theme, and content exactly as you want the printed output to look. Once you're happy with the mock-up, start replacing static content with Docentric tagging elements. If marketing or another team has theme, font, or layout requirements, incorporate those before you begin tagging.

Watch for copy/paste and undo traps

WARNING

When you copy template parts that already contain tagging elements, select the Word element, such as table or paragraph completely. Copying part a multi-row List or Group produces inconsistent Word elements that can cause errors, crashes, or a damaged template.

One Docentric action may bundle several Word steps that appear in Undo list. Because undo works at the Word-step level, reverting one Docentric action may take multiple undo actions.

Save versions as you go

Save versions regularly as you design, especially for complex templates.

  • SharePoint provides automatic versioning and easy rollback.
  • On a file system, save manually under new version names so you can revert if necessary.

Design for multilingual, multi-brand, multi-company and multi-currency reuse

Build one template that serves every language, brand, and company (Business Unit). Maintain separate copies only if the requirements differ significantly.

  • Replace static text with Labels, whose translations are stored in the DDSP file. For more information, see Label tagging element. A single template can then serve multiple languages. Test by switching the Preview language in the Preview group on the Docentric ribbon tab. For more information, see Preview document templates.
  • Replace static text with tagging elements where ever data exists in Data model. Test your templates by loading DDSP files prepared in different contexts, such as different business units or companies. For more information, see Reload a Data Source.
  • For money, use the currency code or symbol field when the Data Source provides one. Do not hardcode the currency.

Always control formatting explicitly

For date and number fields, always set a formatting string. Explicit formatting keeps output correct across all languages, so you never have to manage formatting by hand. For more information, see Format numeric data and Format date-time data.

Layout best practices

Give Docentric Template Designer predictable structure to work with so your output renders reliably.

Use Word tables to control layout

Tables enclose text predictably in cells and give reliable control over widths, heights, rows, and columns. Learn the standard Word table property options and experiment with them.

WARNING

Avoid floating objects (objects positioned with text wrapping around them). They do not work well with Docentric templates, especially with repeating content, and may render incorrectly or not at all.

Give List and Group elements a spare row

Once a List or Group tagging element is defined on a single table row, you cannot add more rows without removing and rebinding the whole element. Give yourself room up front.

  • Always define a List or Group across at least two rows.
  • If you only need one row, wrap the second in an If element with a false condition to hide it. You can drop the condition later if you need the row. For more information, see If tagging element.
  • With two or more rows in the list, you can freely add further rows and they remain part of the list.

Calculations and logic best practices

Keep calculations correct and templates easy for the next person to maintain.

Prefer prepared values; calculate manually only when needed

  • Where the Data Model already provides calculated values (net, tax, discounts, totals), bind those directly for performance and correctness reasons.
  • When you must compute a value in the template, use either a Summary Field over a record collection or a Field with the Sum() function. For more information, see Summary Field tagging element.
  • Use conditional (If) content to show or hide sections based on the data. For more information, see If tagging element.

Keep template maintainable

You can build complex templates through Power Fx calculations, functions, variables, and conditional content. The more complex the template, the harder it is for the next person to maintain.

Consider moving some calculations into Data Model preparation so the template only displays data that is already prepared and shaped. Restructure data in Dataverse or modify the relevant Document Setup's Data Model.

Related content