Template Syntax - Part 2 of 2 Leave feedback

Note

This article is the second part of the Template Syntax series of articles. For first part, please visit Template Syntax - Part 1 of 2.

You can output expression results to your reports using expression tags. An expression tag denotes a placeholder for an expression result within a template. While building a report, the corresponding expression is evaluated, and this placeholder is replaced with the formatted result of the expression.

An expression tag has no name and consists of the following elements:

• An expression enclosed by brackets
• An optional format string enclosed by double quotes and preceded by the “:” character
• An optional html switch

<<[expression]:"format" -html>>

If html switch is not present, the result of the corresponding expression is written to a document as a plain text at runtime. Font attributes are derived from the first character of the corresponding tag in this case.

If html switch is present, the expression result is considered to be a HTML block and is written as such. This feature is useful, when you need to format text parts of an expression result in different ways. For example, the following tag is replaced with a content like “Bold and italic text” at runtime.

<<["<b>Bold</b> and <i>italic</i> text"] -html>>

To format a numeric or date-time expression result, you can specify a format string as an element of the corresponding expression tag. Such format strings are the same as the ones that you pass to IFormattable.ToString method implementors. That is, for example, given that d is a DateTime value, you can use the following template to format the value using the “yyyy.MM.dd” pattern.

<<[d]:"yyyy.MM.dd">>

You can output a sequence of elements of the same type to your report using a data band. A data band has a body that represents a template for a single element of such a sequence. While building a report, sequence elements are enumerated, and the following procedure takes place for each of the elements:

1. The data band body is duplicated and appended to the report.
2. The appended data band body is populated with the element’s data.

Note – A data band body can contain nested data bands.

A data band body is defined between the corresponding opening and closing foreach tags within a template as follows.

<<foreach ...>>
data_band_body
<</foreach>>

You can reference an element of the corresponding sequence in template expressions within a data band body using an iteration variable. At runtime, an iteration variable represents a sequence element for which an iteration is currently being performed. You can declare an iteration variable within the corresponding opening foreach tag.

An opening foreach tag defines a foreach statement enclosed by brackets. The following table describes elements of this statement.

The complete syntax of a foreach tag (including optional elements) is as follows.

<<foreach [variable_type variable_name in sequence_expression]>>
data_band_body
<</foreach>>

A common data band is a data band which body starts and ends within paragraphs that belong to a single story or table cell.

In particular, a common data band can be entirely located within a single paragraph. In this case, while building a report, the band is replaced with contents that are entirely located within the same paragraph as well. The following example illustrates such a scenario. Given that items is an enumeration of the strings “item1”, “item2”, and “item3”, you can use the following template to enumerate them with commas in a single paragraph.

The items are: <<foreach [item in items]>><<[item]>>, <</foreach>>and others.

In this case, the engine produces a report as follows.

The items are: item1, item2, item3, and others.

When the body of a common data band starts and ends within different paragraphs, the engine duplicates on iteration only those paragraph breaks which are located within the body. The following table illustrates the relevant cases.

Note – Examples in the table are given with paragraph marks shown as per Microsoft Word® editor.

While building a report, duplicated paragraph breaks derive common attributes from their template prototypes. In particular, this fact enables you to build numbered or bulleted lists in reports dynamically. For example, given the above declaration of items, you can get a report with their numbered list using the following template.

You can merge table cells with equal textual contents within your reports dynamically using cellMerge tags. Syntax of a cellMerge tag is defined as follows.

<<cellMerge>>

By default, a cellMerge tag causes a cell merging operation only in a vertical direction during runtime. However, you can alter this behavior in the following ways:

• To merge cells only in a horizontal direction, use the horz switch as follows. <<cellMerge -horz>>

• To merge cells in both – vertical and horizontal – directions, use the both switch as follows. <<cellMerge -both>>

For two or more successive table cells to be merged dynamically in either direction by the engine, the following requirements must be met:

• Each of the cells must contain a cellMerge tag denoting a cell merging operation in the same direction (or directions).
• Each of the cells must not be already merged in another direction. This requirement does not apply when a both switch is used.
• The cells must have equal textual contents ignoring leading and trailing whitespaces.

Consider the following template.

If value1 and value2 have the same value, say “Hello”, table cells containing cellMerge tags are successfully merged during runtime and a result report looks as follows then.

If value1 and value2 have different values, say “Hello” and “World”, table cells containing cellMerge tags are not merged during runtime and a result report looks as follows then.

Note – A cellMerge tag can be normally used within a table data band.

You can define an additional restriction on dynamic merging of table cells by providing an expression for acellMerge tag using the following syntax.

<<cellMerge [expression]>>

During runtime, expressions defined for cellMerge tags are evaluated and dynamic cell merging is discarded for those tags, which expressions return unequal values, even if all other conditions for merging such as equal cell textual contents are met. In particular, this feature is useful when cells corresponding to different data band sequence elements should not be merged as shown in the following example.

Assume that you have the Invoice and InvoiceItem classes defined in your application as follows.

public class Invoice
{
	public int Number { get { ... } }
	public IEnumerable<InvoiceItem> Items { get { ... } }
	...
}
public class InvoiceItem
{
	public String Ware { get { ... } }
	public String Pack { get { ... } }
	public int Quantity { get { ... } }
	...
}

Given that invoices is an enumeration of Invoice instances, you could use the following template to output information on several invoices in one table.

A result document would look as follows then.

That is, cells corresponding to the same wares at different invoices would be merged, which is unwanted. To prevent this from happening, you can use the following template instead.

Then, a result document looks as follows.

 “1. " in the above template stands for a numbered list label.

1. <<foreach [item in items]>><<[item]>>
<</foreach>>

In this case, the engine produces a report as follows.

1. item1
2. item2
3. item3

This feature is useful when working with a nested numbered list within a data band as shown in the following example.

Assume that you have the Order and Service classes defined in your application as follows.

public class Order
{
    public String ClientName { get { ... } }
    public String ClientAddress { get { ... } }
    public IEnumerable<Service> Services { get { ... } }
    ...
}
 
public class Service
{
    public String Name { get { ... } }
    ...
}

Given that orders is an enumeration of Order instances, you could try to use the following template to output information on several orders in one document.

<<foreach [order in orders]>><<[order.ClientName]>> (<<[order.ClientAddress]>>)
1. <<foreach [service in order.Services]>><<[service.Name]>>
<</foreach>><</foreach>>

But then, a result document would look as follows.

Jane Doe (445 Mount Eden Road Mount Eden Auckland 1024)

   1. Regular Cleaning
   2. Oven Cleaning

John Smith (43 Vogel Street Roslyn Palmerston North 4414)

   3. Regular Cleaning
   4. Oven Cleaning
   5. Carpet Cleaning

That is, there would be a single numbered list across all orders, which is not applicable for this scenario. However, you can make list numbering to restart for every order by putting a restartNum tag into your template before a corresponding foreach tag as follows.

<<foreach [order in orders]>><<[order.ClientName]>> (<<[order.ClientAddress]>>)
1. <<restartNum>><<foreach [service in order.Services]>><<[service.Name]>>
<</foreach>><</foreach>>

Warning

When using with a data band, it is required to put a restartNum tag before a corresponding foreach tag in the same numbered paragraph.

Then, a result document looks as follows.

Jane Doe (445 Mount Eden Road Mount Eden Auckland 1024)

   1. Regular Cleaning
   2. Oven Cleaning

John Smith (43 Vogel Street Roslyn Palmerston North 4414)

   1. Regular Cleaning
   2. Oven Cleaning
   3. Carpet Cleaning

Warning

You can use a restartNum tag without a data band to dynamically restart list numbering for a containing paragraph, for example, the tag can be used to restart list numbering for a document inserted dynamically.

A table-row data band is a data band which body occupies single or multiple rows of a single document table. The body of such a band starts at the beginning of the first occupied row and ends at the end of the last occupied row as follows.

The most common use case of a table-row data band is the building of a document table that represents a list of items. You can use a template like the following one to achieve this.

In this case, the engine produces a report as follows.

To populate a document table with a master-detail data, you can use nested table-row data bands like in the following template.

In this case, the engine produces a report as follows.

You can normally use common data bands nested to table-row data bands as well like in the following template.

In this case, the engine produces a report as follows.

GroupDocs.Assembly Engine provides special extension methods for iteration variables of any type. You can normally use these extension methods in template expressions. The following list describes the extension methods.

• IndexOf()

Returns the zero-based index of a sequence item that is represented by the corresponding iteration variable. You can use this extension method to distinguish sequence items with different indexes and then handle them in different ways. For example, given that items is an enumeration of the strings “item1”, “item2”, and “item3”, you can use the following template to enumerate them prefixing all of them but the first one with commas.

The items are: <<foreach [
    item in items]>><<[item.IndexOf() != 0
        ? ", "
        : ""]>><<[item]>><</foreach>>.

In this case, the engine produces a report as follows.

The items are: item1, item2, item3.

• NumberOf()

Returns the one-based index of a sequence item that is represented by the corresponding iteration variable. You can use this extension method to number sequence items without involving Microsoft Word® lists. For example, given the previous declaration of items, you can enumerate and number them in a document table using the following template.

In this case, the engine produces a report as follows.

GroupDocs.Assembly Engine enables you to use charts to represent your sequential data. To declare a chart that is going to be populated with data dynamically within your template, do the following steps:

1. Add a chart to your template at the place where you want it to appear in a result document.

2. Configure the appearance of the chart.

3. Add required chart series and configure their appearance as well.

4. Add a title to the chart, if missing.

5. Add an opening foreach tag to the chart title.

6. Depending on the type of the chart, add x tags to the chart title or chart series’ names as follows.

   <<x [x_value_expression]>>
   

   • For a scatter or bubble chart, you can go one of the following ways:
     • To use the same x-value expression for all chart series, add a single x tag to the chart title after the corresponding foreachtag.
     • To use different x-value expressions for every chart series, add multiple x tags to chart series’ names – one for each chart series. An x-value expression for a scatter or bubble chart must return a numeric value.
   • For a chart of another type, add a single x tag to the chart title after the corresponding foreach tag. In this case, an x-value expression must return a numeric, date, or string value.

7. For a chart of any type, add y tags to chart series’ names as follows.

   <<y [y_value_expression]>>
   

   An y-value expression must return a numeric value.

8. For a bubble chart, add size tags to chart series’ names as follows.

   <<size [bubble_size_expression]>>
   

   A bubble-size expression must return a numeric value.

9. For a chart with dynamic data, you can select which series to include into it dynamically based upon conditions. In particular, this feature is useful when you need to restrict access to sensitive data in chart series for some users of your application. To use the feature, do the following steps:

   • Declare a chart with dynamic data in the usual way
   • For series to be removed from the chart based upon conditions dynamically, define the conditions in names of these series using removeif tags having the following syntax

   <<removeif [conditional_expression]>>
   

   A conditional expression must return a Boolean value.

Note: A closing foreach tag is not used for a chart.
While composing expressions for x, y, and size tags, you can normally reference an iteration variable declared at the corresponding foreach tag in a chart title in the same way as if you intended to output results of expressions within a data band.

Note: You can normally use charts with dynamic data within data bands.
During runtime, a chart with a foreach tag in its title is processed by the engine as follows:

1. A sequence expression declared at the foreach tag is evaluated and iterated.

2. For every sequence item, expressions declared at x, y, and size tags are evaluated.

3. Results of these expressions are used to populate corresponding chart series.

4. All foreach, x, y, and size tags are removed from the chart title and chart series’ names.
   Consider the following example. Assume that you have the Manager and Contract classes defined in your application as follows.

   public class Manager
   {
       public String Name { get { ... } }
       public IEnumerable<Contract> Contracts { get { ... } }
       ...
   }
   
   public class Contract
   {
       public float Price { get { ... } }
       ...
   }
   

   Given that managers is an enumeration of Manager instances, you can use the following template to represent total contract prices achieved by managers in a column chart.

   In this case, the engine produces a report as follows.

GroupDocs.Assembly Engine enables you to perform common manipulations on a sequential data through the engine’s built-in extension methods for IEnumerable. These extension methods mimic some extension methods of IEnumerable providing the same signatures and behavior features. Thus, you can group, sort, and perform other sequential data manipulations in template expressions in a familiar way.

Below table describes the built-in extension methods. The following notation conventions are used within the table:

• Selector stands for a lambda function returning a value and taking an enumeration item as its single argument. See Using Lambda Functions for more information.
• ComparableSelector stands for Selector returning IComparable.
• Predicate stands for Selector returning a Boolean value.

Examples in this table are given using persons and otherPersons, enumerations of instances of the Person class that is defined as follows.

public class Person
{
    public String Name { get { ... } }
    public int Age { get { ... } }
    public IEnumerable<Person> Children { get { ... } }
    ...
}