GrapeCity.Documents.Word.Templates.DataTemplate

Class DataTemplate

Namespace

GrapeCity.Documents.Word.Templates

Assembly

GcDocs.Word.dll

Provides properties and methods that are used to associate a GcWordDocument with template data sources, and to process data templates. See remarks for details.

public class DataTemplate

Inheritance

object

DataTemplate

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Remarks

Data templates have the form of "{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}", where

• dsA user-defined name of the data source.
• value_pathThe full dot-delimited path from data source to the property name.
• formatterXOptional: one or more formatters that process the value, see below for details.

## Range tags:

Open and close tags resolve start and end of a repeating section of data. If omitted, the template engine will automatically calculate start and end of a repeating block. If 'ds' is the name of a data set:

• {{#ds}} or {{#ds.enumerable_path}}Start of a range block.
• {{/ds}} or {{/ds.enumerable_path}}End of a range block.

E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:

{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}

Arrays of elementary types can be used as data sources. To address array elements, use the "value" tag. E.g. if the "ds" data source is such an array, "ds.value" will expand to the array elements' values. The following elementary types are supported: Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Double, Single and String.

Many formatters allow hiding a block of data if a certain condition is met. All such formatters have two equivalent forms - 'hide-block-if-<condition>' and the short form 'hbi-<condition>'. Conditions are self-explanatory.

## Range behavior modifying formatters:

• paragraph-block-behavior(), pbb()When applied to a start range tag inside a table cell, causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. Cannot be used anywhere else. The end range tag must appear inside the same cell.
• run-block-behavior(), rbb()When applied to a start range tag, causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

## Block hiding formatters:

These formatters hide a block of data if the value in the block meets a condition.

• hide-block-if-equals(), hbi-equals()
• hide-block-if-greater(), hbi-greater()
• hide-block-if-less(), hbi-less()
• hide-block-if-contains(), hbi-contains()
• hide-block-if-starts(), hbi-starts()
• hide-block-if-ends(), hbi-ends()
• hide-block-if-empty(), hbi-empty()
• hide-block-if-not-equals(), hbi-not-equals()
• hide-block-if-not-contains(), hbi-not-contains()
• hide-block-if-not-starts(), hbi-not-starts()
• hide-block-if-not-ends(), hbi-not-ends()

## Value formatters:

• format()Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".
• format(format)Formats a value using the specified format string, e.g. "format(N2)".
• substring(index)Returns the specified substring of a value.
• substring(index,length)Returns the specified substring of a value.
• join(separator)Joins array values using the specified separator.
• bool(yes,no,maybe)Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).
• empty(default)If a value is null, empty or empty array, returns 'default'.
• todouble([default_str])Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.
• tobool([default_str])Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.

## String formatters:

• lengthThe number of characters in the current string.
• tolowerA copy of this string converted to lowercase.
• toupperA copy of this string converted to uppercase.
• trimA copy of this string without leading and trailing whitespace characters.
• gethashcodeThe hash code of this string.

## Date and time formatters (applicable to DateTime and DateTimeOffset):

• dateThe date component with zeroed time.
• dayThe day of the month.
• dayofweekThe day of the week.
• dayofyearThe day of the year.
• hourThe hour component of the DateTime .
• millisecondThe millisecond component of this DateTime.
• minuteThe minute component of this DateTime.
• monthThe month component of this DateTime.
• secondThe second component of this DateTime.
• ticksThe number of ticks representing this DateTime.
• timeofdayThe time of day.
• yearThe year component of this DateTime.
• addAdds TimeSpan to this DateTime.
• subtractSubtracts TimeSpane from this DateTime.
• tofiletimeConverts this DateTime to a Windows file time.

## Date and time formatters (applicable to DateTime):

• gethashcodeThe hash code of this DateTime.
• tolongdatestringLong string date representation of this DateTime.
• tolongtimestringLong string time representation of this DateTime.
• tooadateOLE Automation date representation of this DateTime.
• toshortdatestringShort string date representation of this DateTime.
• toshorttimestringShort string time representation of this DateTime.
• tofiletimeutcConverts the value of this DateTime to a Windows file time.

## Image formatters:

Image formatters convert a value to an image and insert it into the document. The value must be of one of the following types:

• A byte array containing image data.
• A System.IO.Stream object that can be used to read image data.
• A System.Drawing.Image object.
• A string that can be converted to an absolute file URI, or containing Base64-encoded image data.

Formatters:

• image(width, height)Inserts the image with the specified width and height.
• image()If the image is inside a shape, it is stretched to fill the shape. Otherwise it is inserted with its original width and height.
• image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)Fits the image into the host shape using a specified fitting strategy.

## Miscellaneous formatters:

• lengthGets the total number of elements in all dimensions of this array.
• countGets the number of elements in this collection.
• restart()Can only be applied to a range. Restarts all nested numbered lists except the topmost one.
• restart(all)Same as restart() but restarts all lists including the topmost one.
• sequence(id), seq(id)Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.
• follow(id)Can only be applied to a range. Makes this range follow the named sequence 'id'.
• countGets the number of elements in this collection.

Properties

DataSources

Gets the collection of data sources associated with the current document's data templates.

public DataSourceDictionary DataSources { get; }

Property Value

DataSourceDictionary

Remarks

Data templates have the form of "{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}", where

• dsA user-defined name of the data source.
• value_pathThe full dot-delimited path from data source to the property name.
• formatterXOptional: one or more formatters that process the value, see below for details.

## Range tags:

Open and close tags resolve start and end of a repeating section of data. If omitted, the template engine will automatically calculate start and end of a repeating block. If 'ds' is the name of a data set:

• {{#ds}} or {{#ds.enumerable_path}}Start of a range block.
• {{/ds}} or {{/ds.enumerable_path}}End of a range block.

E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:

{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}

Arrays of elementary types can be used as data sources. To address array elements, use the "value" tag. E.g. if the "ds" data source is such an array, "ds.value" will expand to the array elements' values. The following elementary types are supported: Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Double, Single and String.

Many formatters allow hiding a block of data if a certain condition is met. All such formatters have two equivalent forms - 'hide-block-if-<condition>' and the short form 'hbi-<condition>'. Conditions are self-explanatory.

## Range behavior modifying formatters:

• paragraph-block-behavior(), pbb()When applied to a start range tag inside a table cell, causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. Cannot be used anywhere else. The end range tag must appear inside the same cell.
• run-block-behavior(), rbb()When applied to a start range tag, causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

## Block hiding formatters:

These formatters hide a block of data if the value in the block meets a condition.

• hide-block-if-equals(), hbi-equals()
• hide-block-if-greater(), hbi-greater()
• hide-block-if-less(), hbi-less()
• hide-block-if-contains(), hbi-contains()
• hide-block-if-starts(), hbi-starts()
• hide-block-if-ends(), hbi-ends()
• hide-block-if-empty(), hbi-empty()
• hide-block-if-not-equals(), hbi-not-equals()
• hide-block-if-not-contains(), hbi-not-contains()
• hide-block-if-not-starts(), hbi-not-starts()
• hide-block-if-not-ends(), hbi-not-ends()

## Value formatters:

• format()Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".
• format(format)Formats a value using the specified format string, e.g. "format(N2)".
• substring(index)Returns the specified substring of a value.
• substring(index,length)Returns the specified substring of a value.
• join(separator)Joins array values using the specified separator.
• bool(yes,no,maybe)Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).
• empty(default)If a value is null, empty or empty array, returns 'default'.
• todouble([default_str])Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.
• tobool([default_str])Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.

## String formatters:

• lengthThe number of characters in the current string.
• tolowerA copy of this string converted to lowercase.
• toupperA copy of this string converted to uppercase.
• trimA copy of this string without leading and trailing whitespace characters.
• gethashcodeThe hash code of this string.

## Date and time formatters (applicable to DateTime and DateTimeOffset):

• dateThe date component with zeroed time.
• dayThe day of the month.
• dayofweekThe day of the week.
• dayofyearThe day of the year.
• hourThe hour component of the DateTime .
• millisecondThe millisecond component of this DateTime.
• minuteThe minute component of this DateTime.
• monthThe month component of this DateTime.
• secondThe second component of this DateTime.
• ticksThe number of ticks representing this DateTime.
• timeofdayThe time of day.
• yearThe year component of this DateTime.
• addAdds TimeSpan to this DateTime.
• subtractSubtracts TimeSpane from this DateTime.
• tofiletimeConverts this DateTime to a Windows file time.

## Date and time formatters (applicable to DateTime):

• gethashcodeThe hash code of this DateTime.
• tolongdatestringLong string date representation of this DateTime.
• tolongtimestringLong string time representation of this DateTime.
• tooadateOLE Automation date representation of this DateTime.
• toshortdatestringShort string date representation of this DateTime.
• toshorttimestringShort string time representation of this DateTime.
• tofiletimeutcConverts the value of this DateTime to a Windows file time.

## Image formatters:

Image formatters convert a value to an image and insert it into the document. The value must be of one of the following types:

• A byte array containing image data.
• A System.IO.Stream object that can be used to read image data.
• A System.Drawing.Image object.
• A string that can be converted to an absolute file URI, or containing Base64-encoded image data.

Formatters:

• image(width, height)Inserts the image with the specified width and height.
• image()If the image is inside a shape, it is stretched to fill the shape. Otherwise it is inserted with its original width and height.
• image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)Fits the image into the host shape using a specified fitting strategy.

## Miscellaneous formatters:

• lengthGets the total number of elements in all dimensions of this array.
• countGets the number of elements in this collection.
• restart()Can only be applied to a range. Restarts all nested numbered lists except the topmost one.
• restart(all)Same as restart() but restarts all lists including the topmost one.
• sequence(id), seq(id)Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.
• follow(id)Can only be applied to a range. Makes this range follow the named sequence 'id'.
• countGets the number of elements in this collection.

Options

Gets options controlling the behavior of the template processing engine.

public DataTemplateOptions Options { get; }

Property Value

DataTemplateOptions

Remarks

Data templates have the form of "{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}", where

• dsA user-defined name of the data source.
• value_pathThe full dot-delimited path from data source to the property name.
• formatterXOptional: one or more formatters that process the value, see below for details.

## Range tags:

Open and close tags resolve start and end of a repeating section of data. If omitted, the template engine will automatically calculate start and end of a repeating block. If 'ds' is the name of a data set:

• {{#ds}} or {{#ds.enumerable_path}}Start of a range block.
• {{/ds}} or {{/ds.enumerable_path}}End of a range block.

E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:

{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}

Arrays of elementary types can be used as data sources. To address array elements, use the "value" tag. E.g. if the "ds" data source is such an array, "ds.value" will expand to the array elements' values. The following elementary types are supported: Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Double, Single and String.

Many formatters allow hiding a block of data if a certain condition is met. All such formatters have two equivalent forms - 'hide-block-if-<condition>' and the short form 'hbi-<condition>'. Conditions are self-explanatory.

## Range behavior modifying formatters:

• paragraph-block-behavior(), pbb()When applied to a start range tag inside a table cell, causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. Cannot be used anywhere else. The end range tag must appear inside the same cell.
• run-block-behavior(), rbb()When applied to a start range tag, causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

## Block hiding formatters:

These formatters hide a block of data if the value in the block meets a condition.

• hide-block-if-equals(), hbi-equals()
• hide-block-if-greater(), hbi-greater()
• hide-block-if-less(), hbi-less()
• hide-block-if-contains(), hbi-contains()
• hide-block-if-starts(), hbi-starts()
• hide-block-if-ends(), hbi-ends()
• hide-block-if-empty(), hbi-empty()
• hide-block-if-not-equals(), hbi-not-equals()
• hide-block-if-not-contains(), hbi-not-contains()
• hide-block-if-not-starts(), hbi-not-starts()
• hide-block-if-not-ends(), hbi-not-ends()

## Value formatters:

• format()Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".
• format(format)Formats a value using the specified format string, e.g. "format(N2)".
• substring(index)Returns the specified substring of a value.
• substring(index,length)Returns the specified substring of a value.
• join(separator)Joins array values using the specified separator.
• bool(yes,no,maybe)Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).
• empty(default)If a value is null, empty or empty array, returns 'default'.
• todouble([default_str])Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.
• tobool([default_str])Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.

## String formatters:

• lengthThe number of characters in the current string.
• tolowerA copy of this string converted to lowercase.
• toupperA copy of this string converted to uppercase.
• trimA copy of this string without leading and trailing whitespace characters.
• gethashcodeThe hash code of this string.

## Date and time formatters (applicable to DateTime and DateTimeOffset):

• dateThe date component with zeroed time.
• dayThe day of the month.
• dayofweekThe day of the week.
• dayofyearThe day of the year.
• hourThe hour component of the DateTime .
• millisecondThe millisecond component of this DateTime.
• minuteThe minute component of this DateTime.
• monthThe month component of this DateTime.
• secondThe second component of this DateTime.
• ticksThe number of ticks representing this DateTime.
• timeofdayThe time of day.
• yearThe year component of this DateTime.
• addAdds TimeSpan to this DateTime.
• subtractSubtracts TimeSpane from this DateTime.
• tofiletimeConverts this DateTime to a Windows file time.

## Date and time formatters (applicable to DateTime):

• gethashcodeThe hash code of this DateTime.
• tolongdatestringLong string date representation of this DateTime.
• tolongtimestringLong string time representation of this DateTime.
• tooadateOLE Automation date representation of this DateTime.
• toshortdatestringShort string date representation of this DateTime.
• toshorttimestringShort string time representation of this DateTime.
• tofiletimeutcConverts the value of this DateTime to a Windows file time.

## Image formatters:

Image formatters convert a value to an image and insert it into the document. The value must be of one of the following types:

• A byte array containing image data.
• A System.IO.Stream object that can be used to read image data.
• A System.Drawing.Image object.
• A string that can be converted to an absolute file URI, or containing Base64-encoded image data.

Formatters:

• image(width, height)Inserts the image with the specified width and height.
• image()If the image is inside a shape, it is stretched to fill the shape. Otherwise it is inserted with its original width and height.
• image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)Fits the image into the host shape using a specified fitting strategy.

## Miscellaneous formatters:

• lengthGets the total number of elements in all dimensions of this array.
• countGets the number of elements in this collection.
• restart()Can only be applied to a range. Restarts all nested numbered lists except the topmost one.
• restart(all)Same as restart() but restarts all lists including the topmost one.
• sequence(id), seq(id)Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.
• follow(id)Can only be applied to a range. Makes this range follow the named sequence 'id'.
• countGets the number of elements in this collection.

Methods

BatchProcess(Action, CultureInfo)

Iterates over root items in DataSources, starting with a fresh copy of the document and processing templates separately for each root data item.

The itemProcessed action is called as each data item is processed. This action can be used to save the current version of the document (containing data only from the current root data item).

When this method completes, the document is restored to the original state (i.e. it will contain the original template tags rather than data values).

public void BatchProcess(Action itemProcessed, CultureInfo cultureInfo = null)

Parameters

itemProcessed System.Action

The action to be invoked after each root data item is processed.

cultureInfo System.Globalization.CultureInfo

Culture used to format data values. If null, the current culture is used.

Remarks

Data templates have the form of "{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}", where

• dsA user-defined name of the data source.
• value_pathThe full dot-delimited path from data source to the property name.
• formatterXOptional: one or more formatters that process the value, see below for details.

## Range tags:

Open and close tags resolve start and end of a repeating section of data. If omitted, the template engine will automatically calculate start and end of a repeating block. If 'ds' is the name of a data set:

• {{#ds}} or {{#ds.enumerable_path}}Start of a range block.
• {{/ds}} or {{/ds.enumerable_path}}End of a range block.

E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:

{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}

Arrays of elementary types can be used as data sources. To address array elements, use the "value" tag. E.g. if the "ds" data source is such an array, "ds.value" will expand to the array elements' values. The following elementary types are supported: Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Double, Single and String.

Many formatters allow hiding a block of data if a certain condition is met. All such formatters have two equivalent forms - 'hide-block-if-<condition>' and the short form 'hbi-<condition>'. Conditions are self-explanatory.

## Range behavior modifying formatters:

• paragraph-block-behavior(), pbb()When applied to a start range tag inside a table cell, causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. Cannot be used anywhere else. The end range tag must appear inside the same cell.
• run-block-behavior(), rbb()When applied to a start range tag, causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

## Block hiding formatters:

These formatters hide a block of data if the value in the block meets a condition.

• hide-block-if-equals(), hbi-equals()
• hide-block-if-greater(), hbi-greater()
• hide-block-if-less(), hbi-less()
• hide-block-if-contains(), hbi-contains()
• hide-block-if-starts(), hbi-starts()
• hide-block-if-ends(), hbi-ends()
• hide-block-if-empty(), hbi-empty()
• hide-block-if-not-equals(), hbi-not-equals()
• hide-block-if-not-contains(), hbi-not-contains()
• hide-block-if-not-starts(), hbi-not-starts()
• hide-block-if-not-ends(), hbi-not-ends()

## Value formatters:

• format()Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".
• format(format)Formats a value using the specified format string, e.g. "format(N2)".
• substring(index)Returns the specified substring of a value.
• substring(index,length)Returns the specified substring of a value.
• join(separator)Joins array values using the specified separator.
• bool(yes,no,maybe)Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).
• empty(default)If a value is null, empty or empty array, returns 'default'.
• todouble([default_str])Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.
• tobool([default_str])Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.

## String formatters:

• lengthThe number of characters in the current string.
• tolowerA copy of this string converted to lowercase.
• toupperA copy of this string converted to uppercase.
• trimA copy of this string without leading and trailing whitespace characters.
• gethashcodeThe hash code of this string.

## Date and time formatters (applicable to DateTime and DateTimeOffset):

• dateThe date component with zeroed time.
• dayThe day of the month.
• dayofweekThe day of the week.
• dayofyearThe day of the year.
• hourThe hour component of the DateTime .
• millisecondThe millisecond component of this DateTime.
• minuteThe minute component of this DateTime.
• monthThe month component of this DateTime.
• secondThe second component of this DateTime.
• ticksThe number of ticks representing this DateTime.
• timeofdayThe time of day.
• yearThe year component of this DateTime.
• addAdds TimeSpan to this DateTime.
• subtractSubtracts TimeSpane from this DateTime.
• tofiletimeConverts this DateTime to a Windows file time.

## Date and time formatters (applicable to DateTime):

• gethashcodeThe hash code of this DateTime.
• tolongdatestringLong string date representation of this DateTime.
• tolongtimestringLong string time representation of this DateTime.
• tooadateOLE Automation date representation of this DateTime.
• toshortdatestringShort string date representation of this DateTime.
• toshorttimestringShort string time representation of this DateTime.
• tofiletimeutcConverts the value of this DateTime to a Windows file time.

## Image formatters:

Image formatters convert a value to an image and insert it into the document. The value must be of one of the following types:

• A byte array containing image data.
• A System.IO.Stream object that can be used to read image data.
• A System.Drawing.Image object.
• A string that can be converted to an absolute file URI, or containing Base64-encoded image data.

Formatters:

• image(width, height)Inserts the image with the specified width and height.
• image()If the image is inside a shape, it is stretched to fill the shape. Otherwise it is inserted with its original width and height.
• image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)Fits the image into the host shape using a specified fitting strategy.

## Miscellaneous formatters:

• lengthGets the total number of elements in all dimensions of this array.
• countGets the number of elements in this collection.
• restart()Can only be applied to a range. Restarts all nested numbered lists except the topmost one.
• restart(all)Same as restart() but restarts all lists including the topmost one.
• sequence(id), seq(id)Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.
• follow(id)Can only be applied to a range. Makes this range follow the named sequence 'id'.
• countGets the number of elements in this collection.

See Also

Process(CultureInfo)

DebugExpandTemplate(bool, CultureInfo)

Expands the template. The template will be processed and all missed tags added.

public void DebugExpandTemplate(bool simpleModeEnabled = true, CultureInfo culture = null)

Parameters

simpleModeEnabled bool

Allows parsing templates without a data source tag.

culture System.Globalization.CultureInfo

Culture used to format data values.

Remarks

Data templates have the form of "{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}", where

• dsA user-defined name of the data source.
• value_pathThe full dot-delimited path from data source to the property name.
• formatterXOptional: one or more formatters that process the value, see below for details.

## Range tags:

Open and close tags resolve start and end of a repeating section of data. If omitted, the template engine will automatically calculate start and end of a repeating block. If 'ds' is the name of a data set:

• {{#ds}} or {{#ds.enumerable_path}}Start of a range block.
• {{/ds}} or {{/ds.enumerable_path}}End of a range block.

E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:

{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}

Arrays of elementary types can be used as data sources. To address array elements, use the "value" tag. E.g. if the "ds" data source is such an array, "ds.value" will expand to the array elements' values. The following elementary types are supported: Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Double, Single and String.

Many formatters allow hiding a block of data if a certain condition is met. All such formatters have two equivalent forms - 'hide-block-if-<condition>' and the short form 'hbi-<condition>'. Conditions are self-explanatory.

## Range behavior modifying formatters:

• paragraph-block-behavior(), pbb()When applied to a start range tag inside a table cell, causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. Cannot be used anywhere else. The end range tag must appear inside the same cell.
• run-block-behavior(), rbb()When applied to a start range tag, causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

## Block hiding formatters:

These formatters hide a block of data if the value in the block meets a condition.

• hide-block-if-equals(), hbi-equals()
• hide-block-if-greater(), hbi-greater()
• hide-block-if-less(), hbi-less()
• hide-block-if-contains(), hbi-contains()
• hide-block-if-starts(), hbi-starts()
• hide-block-if-ends(), hbi-ends()
• hide-block-if-empty(), hbi-empty()
• hide-block-if-not-equals(), hbi-not-equals()
• hide-block-if-not-contains(), hbi-not-contains()
• hide-block-if-not-starts(), hbi-not-starts()
• hide-block-if-not-ends(), hbi-not-ends()

## Value formatters:

• format()Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".
• format(format)Formats a value using the specified format string, e.g. "format(N2)".
• substring(index)Returns the specified substring of a value.
• substring(index,length)Returns the specified substring of a value.
• join(separator)Joins array values using the specified separator.
• bool(yes,no,maybe)Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).
• empty(default)If a value is null, empty or empty array, returns 'default'.
• todouble([default_str])Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.
• tobool([default_str])Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.

## String formatters:

• lengthThe number of characters in the current string.
• tolowerA copy of this string converted to lowercase.
• toupperA copy of this string converted to uppercase.
• trimA copy of this string without leading and trailing whitespace characters.
• gethashcodeThe hash code of this string.

## Date and time formatters (applicable to DateTime and DateTimeOffset):

• dateThe date component with zeroed time.
• dayThe day of the month.
• dayofweekThe day of the week.
• dayofyearThe day of the year.
• hourThe hour component of the DateTime .
• millisecondThe millisecond component of this DateTime.
• minuteThe minute component of this DateTime.
• monthThe month component of this DateTime.
• secondThe second component of this DateTime.
• ticksThe number of ticks representing this DateTime.
• timeofdayThe time of day.
• yearThe year component of this DateTime.
• addAdds TimeSpan to this DateTime.
• subtractSubtracts TimeSpane from this DateTime.
• tofiletimeConverts this DateTime to a Windows file time.

## Date and time formatters (applicable to DateTime):

• gethashcodeThe hash code of this DateTime.
• tolongdatestringLong string date representation of this DateTime.
• tolongtimestringLong string time representation of this DateTime.
• tooadateOLE Automation date representation of this DateTime.
• toshortdatestringShort string date representation of this DateTime.
• toshorttimestringShort string time representation of this DateTime.
• tofiletimeutcConverts the value of this DateTime to a Windows file time.

## Image formatters:

Image formatters convert a value to an image and insert it into the document. The value must be of one of the following types:

• A byte array containing image data.
• A System.IO.Stream object that can be used to read image data.
• A System.Drawing.Image object.
• A string that can be converted to an absolute file URI, or containing Base64-encoded image data.

Formatters:

• image(width, height)Inserts the image with the specified width and height.
• image()If the image is inside a shape, it is stretched to fill the shape. Otherwise it is inserted with its original width and height.
• image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)Fits the image into the host shape using a specified fitting strategy.

## Miscellaneous formatters:

• lengthGets the total number of elements in all dimensions of this array.
• countGets the number of elements in this collection.
• restart()Can only be applied to a range. Restarts all nested numbered lists except the topmost one.
• restart(all)Same as restart() but restarts all lists including the topmost one.
• sequence(id), seq(id)Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.
• follow(id)Can only be applied to a range. Makes this range follow the named sequence 'id'.
• countGets the number of elements in this collection.

Process(CultureInfo)

Processes templates in the document, iterating over root items in DataSources, and replacing template tags in the document with data.

public void Process(CultureInfo cultureInfo = null)

Parameters

cultureInfo System.Globalization.CultureInfo

Culture used to format data values. If null, the current culture is used.

Remarks

Data templates have the form of "{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}", where

• dsA user-defined name of the data source.
• value_pathThe full dot-delimited path from data source to the property name.
• formatterXOptional: one or more formatters that process the value, see below for details.

## Range tags:

Open and close tags resolve start and end of a repeating section of data. If omitted, the template engine will automatically calculate start and end of a repeating block. If 'ds' is the name of a data set:

• {{#ds}} or {{#ds.enumerable_path}}Start of a range block.
• {{/ds}} or {{/ds.enumerable_path}}End of a range block.

E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:

{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}

Arrays of elementary types can be used as data sources. To address array elements, use the "value" tag. E.g. if the "ds" data source is such an array, "ds.value" will expand to the array elements' values. The following elementary types are supported: Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Double, Single and String.

Many formatters allow hiding a block of data if a certain condition is met. All such formatters have two equivalent forms - 'hide-block-if-<condition>' and the short form 'hbi-<condition>'. Conditions are self-explanatory.

## Range behavior modifying formatters:

• paragraph-block-behavior(), pbb()When applied to a start range tag inside a table cell, causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. Cannot be used anywhere else. The end range tag must appear inside the same cell.
• run-block-behavior(), rbb()When applied to a start range tag, causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

## Block hiding formatters:

These formatters hide a block of data if the value in the block meets a condition.

• hide-block-if-equals(), hbi-equals()
• hide-block-if-greater(), hbi-greater()
• hide-block-if-less(), hbi-less()
• hide-block-if-contains(), hbi-contains()
• hide-block-if-starts(), hbi-starts()
• hide-block-if-ends(), hbi-ends()
• hide-block-if-empty(), hbi-empty()
• hide-block-if-not-equals(), hbi-not-equals()
• hide-block-if-not-contains(), hbi-not-contains()
• hide-block-if-not-starts(), hbi-not-starts()
• hide-block-if-not-ends(), hbi-not-ends()

## Value formatters:

• format()Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".
• format(format)Formats a value using the specified format string, e.g. "format(N2)".
• substring(index)Returns the specified substring of a value.
• substring(index,length)Returns the specified substring of a value.
• join(separator)Joins array values using the specified separator.
• bool(yes,no,maybe)Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).
• empty(default)If a value is null, empty or empty array, returns 'default'.
• todouble([default_str])Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.
• tobool([default_str])Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.

## String formatters:

• lengthThe number of characters in the current string.
• tolowerA copy of this string converted to lowercase.
• toupperA copy of this string converted to uppercase.
• trimA copy of this string without leading and trailing whitespace characters.
• gethashcodeThe hash code of this string.

## Date and time formatters (applicable to DateTime and DateTimeOffset):

• dateThe date component with zeroed time.
• dayThe day of the month.
• dayofweekThe day of the week.
• dayofyearThe day of the year.
• hourThe hour component of the DateTime .
• millisecondThe millisecond component of this DateTime.
• minuteThe minute component of this DateTime.
• monthThe month component of this DateTime.
• secondThe second component of this DateTime.
• ticksThe number of ticks representing this DateTime.
• timeofdayThe time of day.
• yearThe year component of this DateTime.
• addAdds TimeSpan to this DateTime.
• subtractSubtracts TimeSpane from this DateTime.
• tofiletimeConverts this DateTime to a Windows file time.

## Date and time formatters (applicable to DateTime):

• gethashcodeThe hash code of this DateTime.
• tolongdatestringLong string date representation of this DateTime.
• tolongtimestringLong string time representation of this DateTime.
• tooadateOLE Automation date representation of this DateTime.
• toshortdatestringShort string date representation of this DateTime.
• toshorttimestringShort string time representation of this DateTime.
• tofiletimeutcConverts the value of this DateTime to a Windows file time.

## Image formatters:

Image formatters convert a value to an image and insert it into the document. The value must be of one of the following types:

• A byte array containing image data.
• A System.IO.Stream object that can be used to read image data.
• A System.Drawing.Image object.
• A string that can be converted to an absolute file URI, or containing Base64-encoded image data.

Formatters:

• image(width, height)Inserts the image with the specified width and height.
• image()If the image is inside a shape, it is stretched to fill the shape. Otherwise it is inserted with its original width and height.
• image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)Fits the image into the host shape using a specified fitting strategy.

## Miscellaneous formatters:

• lengthGets the total number of elements in all dimensions of this array.
• countGets the number of elements in this collection.
• restart()Can only be applied to a range. Restarts all nested numbered lists except the topmost one.
• restart(all)Same as restart() but restarts all lists including the topmost one.
• sequence(id), seq(id)Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.
• follow(id)Can only be applied to a range. Makes this range follow the named sequence 'id'.
• countGets the number of elements in this collection.

See Also

BatchProcess(Action, CultureInfo)

Validate(bool)

Validates all templates in the current document, finds any template tags that are malformed or used incorrectly.

public IEnumerable<TemplateError> Validate(bool markErrors = false)

Parameters

markErrors bool

If true, erroneous tags will be marked in the document, and a Comment with the error description will be added to each such occurrence. If false, the templates will be left as is, just the list of errors will be returned.

Returns

System.Collections.Generic.IEnumerable<T><TemplateError>

The list of all found template errors.

Remarks

Data templates have the form of "{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}", where

• dsA user-defined name of the data source.
• value_pathThe full dot-delimited path from data source to the property name.
• formatterXOptional: one or more formatters that process the value, see below for details.

## Range tags:

Open and close tags resolve start and end of a repeating section of data. If omitted, the template engine will automatically calculate start and end of a repeating block. If 'ds' is the name of a data set:

• {{#ds}} or {{#ds.enumerable_path}}Start of a range block.
• {{/ds}} or {{/ds.enumerable_path}}End of a range block.

E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:

{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}

Arrays of elementary types can be used as data sources. To address array elements, use the "value" tag. E.g. if the "ds" data source is such an array, "ds.value" will expand to the array elements' values. The following elementary types are supported: Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Char, Double, Single and String.

Many formatters allow hiding a block of data if a certain condition is met. All such formatters have two equivalent forms - 'hide-block-if-<condition>' and the short form 'hbi-<condition>'. Conditions are self-explanatory.

## Range behavior modifying formatters:

• paragraph-block-behavior(), pbb()When applied to a start range tag inside a table cell, causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. Cannot be used anywhere else. The end range tag must appear inside the same cell.
• run-block-behavior(), rbb()When applied to a start range tag, causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

## Block hiding formatters:

These formatters hide a block of data if the value in the block meets a condition.

• hide-block-if-equals(), hbi-equals()
• hide-block-if-greater(), hbi-greater()
• hide-block-if-less(), hbi-less()
• hide-block-if-contains(), hbi-contains()
• hide-block-if-starts(), hbi-starts()
• hide-block-if-ends(), hbi-ends()
• hide-block-if-empty(), hbi-empty()
• hide-block-if-not-equals(), hbi-not-equals()
• hide-block-if-not-contains(), hbi-not-contains()
• hide-block-if-not-starts(), hbi-not-starts()
• hide-block-if-not-ends(), hbi-not-ends()

## Value formatters:

• format()Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".
• format(format)Formats a value using the specified format string, e.g. "format(N2)".
• substring(index)Returns the specified substring of a value.
• substring(index,length)Returns the specified substring of a value.
• join(separator)Joins array values using the specified separator.
• bool(yes,no,maybe)Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).
• empty(default)If a value is null, empty or empty array, returns 'default'.
• todouble([default_str])Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.
• tobool([default_str])Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.

## String formatters:

• lengthThe number of characters in the current string.
• tolowerA copy of this string converted to lowercase.
• toupperA copy of this string converted to uppercase.
• trimA copy of this string without leading and trailing whitespace characters.
• gethashcodeThe hash code of this string.

## Date and time formatters (applicable to DateTime and DateTimeOffset):

• dateThe date component with zeroed time.
• dayThe day of the month.
• dayofweekThe day of the week.
• dayofyearThe day of the year.
• hourThe hour component of the DateTime .
• millisecondThe millisecond component of this DateTime.
• minuteThe minute component of this DateTime.
• monthThe month component of this DateTime.
• secondThe second component of this DateTime.
• ticksThe number of ticks representing this DateTime.
• timeofdayThe time of day.
• yearThe year component of this DateTime.
• addAdds TimeSpan to this DateTime.
• subtractSubtracts TimeSpane from this DateTime.
• tofiletimeConverts this DateTime to a Windows file time.

## Date and time formatters (applicable to DateTime):

• gethashcodeThe hash code of this DateTime.
• tolongdatestringLong string date representation of this DateTime.
• tolongtimestringLong string time representation of this DateTime.
• tooadateOLE Automation date representation of this DateTime.
• toshortdatestringShort string date representation of this DateTime.
• toshorttimestringShort string time representation of this DateTime.
• tofiletimeutcConverts the value of this DateTime to a Windows file time.

## Image formatters:

Image formatters convert a value to an image and insert it into the document. The value must be of one of the following types:

• A byte array containing image data.
• A System.IO.Stream object that can be used to read image data.
• A System.Drawing.Image object.
• A string that can be converted to an absolute file URI, or containing Base64-encoded image data.

Formatters:

• image(width, height)Inserts the image with the specified width and height.
• image()If the image is inside a shape, it is stretched to fill the shape. Otherwise it is inserted with its original width and height.
• image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)Fits the image into the host shape using a specified fitting strategy.

## Miscellaneous formatters:

• lengthGets the total number of elements in all dimensions of this array.
• countGets the number of elements in this collection.
• restart()Can only be applied to a range. Restarts all nested numbered lists except the topmost one.
• restart(all)Same as restart() but restarts all lists including the topmost one.
• sequence(id), seq(id)Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.
• follow(id)Can only be applied to a range. Makes this range follow the named sequence 'id'.
• countGets the number of elements in this collection.