Modern vs. Classic DOCX engine

The Modern Word DOCX templating engine is the default engine in Plumsail Documents. It builds upon and extends the capabilities of the Classic templating engine.

This article explains the key differences between the two engines and how they compare.

When to use each engine

The Modern engine is enabled by default for all new processes, and all premade templates use Modern syntax. If you start a new project, try using the Modern engine since it offers extended functionality.

If you are currently using the Classic engine, you may gradually update your templates to Modern syntax when making changes or introducing new features.

The Classic engine remains fully supported and may be suitable if you are maintaining templates created with Classic syntax.

Key differences

The Modern engine retains the data-driven approach of the Classic engine while allowing for easy data structure mapping and calculations directly within your templates. This eliminates the need to pre-process your data and simplifies integrations with third-party systems. It also features advanced conditional hiding logic, allowing you to conceal entire document blocks rather than collapsing individual pieces of data.

With calculated properties and an advanced expression evaluator, the Modern engine provides more flexibility directly within the template.

It extends the functionality of the Classic engine and simplifies many complex scenarios.

Note

Modern DOCX engine is available in Processes, Power Automate, Zapier and Make.

Data transformation

The primary difference is how each engine handles data preparation. In the Classic engine, data transformation was limited. You could create temporary names (aliases) for data already in your data source, but you couldn’t modify the source data itself.

The Modern engine lets you modify your original data before it’s used to generate the document. This is achieved through calculated properties. You can reorganize, recalculate, or reformat your data within the template.

Conditional content

In the Classic engine, conditional hiding often requires workarounds, such as using the map formatter, especially in complex scenarios.

The Modern engine offers direct control with logical operations like #hide-if and #if / #else blocks:

#hide-if is local, affecting only the closest repeatable object;
#if allows to conditionally include/exclude entire blocks of data.

Value manipulation

Beyond simply presenting data, you often need to format it or perform calculations. The Classic engine offers basic value formatters for this purpose.

The Modern engine uses value functions. These functions offer the same capabilities as the Classic engine’s formatters, along with the ability to perform calculations, manipulate text, and work with lists.

Operations

The Modern engine introduces object operations and logical operations. Object operations let you add Word-specific objects, while logical operations control how template markup is created based on your data.

Some value formatters such as picture, barcode, qrcode, and html migrated from the Classic engine to object operations in the Modern engine.

Syntax

Let’s look at some examples to understand the syntax differences between the Classic and Modern engines.

Operations	Classic	Modern
Sum	{{items}:sum()}	{{items\|sum()}}
Calculated Sum	{{sales}:sum(value.quantity * value.price)}	{{sales\|sum(@value.quantity * @value.price)}}
Barcode	{{value}:barcode(CODE128, 200, 100)}	{{#barcode value CODE128 200 100}}
Hide blocks	{{count}:hide-block-if(value == 1)}	{{#hide-if count == 1}}
Offset formatter	{{date}:offset(10.1:5:10)}	{{date\|offset(10.1:5:10)}}
Map formatter	{{deliveryType}:map(“1” = “Physical”, “2” = “Digital”)}	{{deliveryType\|map(“1” => “Physical”, “2” => “Digital”)}}
Conditionally hide sections	{{report.department}:hide-block-if(development)}	{{#hide-if report.department == “Development”}}
Hide table rows	{{nonDev = employees\|filter(value.department != “development”)}}	{{nonDev = employees\|filter(@value.department != “development”)}}
Hide arbitrary block	{{contacts}:hide-block-if(value == null)}	{{#if isActive}}Active{{#else}}Disabled{{/if}}
Picture	{{imageData}:picture}	{{#picture imageData}}
QR code	{{officeAddress}:qrcode(5)}	{{#qrcode officeAddress 150}}

While testing your template, you may see a mismatch alert in the toolbox within the editor.

This alert triggers when the template syntax does not match the selected process engine. For example, if you reuse an older template in a new process, the system will default to the Modern Engine, causing a mismatch with the previous syntax.

To solve this, simply check your engine settings and refer to the syntax table above to ensure the template format is correct.

Summary

The Modern engine provides extended tools for building complex and self-contained templates. It offers more flexibility for data transformation, object handling, and conditional content.

We recommend using it in all your new projects.

Learn more

Check out the documentation for each templating engine at the following links:

Templates syntax

Word DOCX templates (Modern)