Basic Template Syntax - Expression Tags and Fields Leave feedback

GroupDocs.Assembly for Python via .NET uses a simple, LINQ-based template syntax that allows you to embed expressions directly in your documents. Expression tags are the foundation of template syntax, enabling you to output data values and perform calculations.

The main syntax elements are:

• Expression tags <<[expression]>> - output expression results
• Data bands <<foreach>> - iterate over collections
• Conditional blocks <<if>> - display content conditionally

Here are the steps to use basic template syntax:

• Create a template document in Word, Excel, PowerPoint, or HTML format
• Insert expression tags using <<[expression]>> syntax
• Reference the keys of your Python dicts (and the methods of their values) in expressions
• Assemble the document with your data source

Note

Template syntax is case-sensitive, and the expressions inside tags follow C# language rules whichever language calls the assembler: a Python program’s templates still write &&, == and "text". A dict key is a member name: person.Name reads the "Name" key of the dict passed as person. Expression tags are evaluated at runtime and replaced with their computed values.

Expression tags are the simplest way to output data in templates. They use the syntax <<[expression]>>:

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

# Sample data: the keys are the member names the template reads
person = {"Name": "Amara Osei", "Age": 41, "Email": "amara.osei@harborlane.example"}

# Assemble document
assembler = DocumentAssembler()
assembler.assemble_document("person-details.docx", "person-details-report.docx",
                            DataSourceInfo(person, "person"))

print("Document assembled with expression tags.")

Binary file (DOCX, 7 KB)

In your template document (person-details.docx), use expression tags like this:

Name: <<[person.Name]>>
Age: <<[person.Age]>>
Email: <<[person.Email]>>

After assembly, the output will be:

Name: Amara Osei
Age: 41
Email: amara.osei@harborlane.example

When using a single data source, you can omit the data source name and use contextual access:

from decimal import Decimal

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

product = {"Name": "Harbor Blend whole bean coffee", "Price": Decimal("18.40"), "Stock": 240}

assembler = DocumentAssembler()
assembler.assemble_document("product-summary.docx", "product-summary-report.docx",
                            DataSourceInfo(product))

print("Document assembled with contextual access.")

Binary file (DOCX, 7 KB)

Template with contextual access:

Product: <<[Name]>>
Price: <<[Price]>>
Stock: <<[Stock]>>

The price is a Decimal, so it reaches the template as a .NET decimal and keeps its two decimal places: 18.40.

You can perform calculations directly in expression tags:

from decimal import Decimal

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

order = {"Quantity": 5, "UnitPrice": Decimal("18.40")}

assembler = DocumentAssembler()
assembler.assemble_document("order-calculation.docx", "order-calculation-report.docx",
                            DataSourceInfo(order, "order"))

print("Document assembled with calculations.")

Binary file (DOCX, 7 KB)

Template with calculations:

Quantity: <<[order.Quantity]>>
Unit Price: <<[order.UnitPrice]>>
Total: <<[order.Quantity * order.UnitPrice]>>

The total is 92.00: an int times a Decimal is a decimal in the template, as in Python.

You can use .NET string methods in expressions: a Python str reaches the template as a .NET string.

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

company = {"Name": "Harbor Lane Provisions", "Website": "HTTPS://HarborLane.example/"}

assembler = DocumentAssembler()
assembler.assemble_document("company-header.docx", "company-header-report.docx",
                            DataSourceInfo(company, "company"))

print("Document assembled with string methods.")

Binary file (DOCX, 7 KB)

Template with string methods:

Company: <<[company.Name.ToUpper()]>>
Website: <<[company.Website.ToLower()]>>

You can format expression results using format strings:

from datetime import datetime
from decimal import Decimal

from groupdocs.assembly import DataSourceInfo, DocumentAssembler

invoice = {
    "Amount": Decimal("1500.50"),
    "Date": datetime(2015, 1, 15),
    "Percentage": 0.15,
}

assembler = DocumentAssembler()
assembler.assemble_document("invoice-format-strings.docx", "invoice-format-strings-report.docx",
                            DataSourceInfo(invoice, "invoice"))

print("Document assembled with formatting.")

Binary file (DOCX, 7 KB)

Template with formatting:

Amount: <<[invoice.Amount]:"C">>
Date: <<[invoice.Date]:"yyyy-MM-dd">>
Percentage: <<[invoice.Percentage]:"P">>

A date format needs a datetime (or a date) in the data. A string is written as it is: <<[invoice.Date]:"MMMM dd, yyyy">> gives January 15, 2015 for datetime(2015, 1, 15) but 2015-01-15 for the text "2015-01-15".

Warning

Format strings follow .NET formatting conventions, not Python’s: use “C” for currency, “P” for percentage, and .NET date/time format strings such as “yyyy-MM-dd” for dates (not %Y-%m-%d). “C” and “P” follow the culture of the process: under en-US the amount above is written $1,500.50.

To learn more about data bands, conditional blocks, LINQ expressions, and advanced template syntax features, please refer to the advanced usage section.

You may easily run the code above and see the feature in action in our GitHub examples:

• GroupDocs.Assembly for .NET examples, plugins, and showcase
• GroupDocs.Assembly for Java examples, plugins, and showcase
• GroupDocs.Assembly for Python via .NET examples, plugins, and showcase

Along with the full-featured library, we provide simple but powerful free online apps.

To assemble documents from templates and data sources, you can use the online apps from the GroupDocs.Assembly App Product Family.