Formatters

GcWord supports various kinds of formatters in Report Templates which allow you to format the Word document in a structured manner. You can apply any input formatting to generate the desired output. For example, hiding some piece of information based on a condition, displaying strings in upper or lower case, inserting an image, displaying date time in the specified format etc.

Range Formatters

Range formatters can be used to hide a block of data if an enumerable collection meets the formatter requirements. These are mentioned below along with their short versions:

• hide-block-if-equals() OR hbi-equals()

• hide-block-if-contains() OR hbi-contains()

• hide-block-if-empty() OR hbi-empty()

The collections of standard C# types can be only formatted by using hbi-contains/hbi-equals range formatters.

Example: {{ds.countries}:hbi-equals("England")}

Block Hiding Formatters

These formatters can be used to hide a block of data if the value in a block meets the condition. These formatters are mentioned below along with their short versions:

• hide-block-if-equals() OR hbi-equals()

• hide-block-if-greater() OR hbi-greater()

• hide-block-if-less() OR hbi-less()

• hide-block-if-contains() OR hbi-contains()

• hide-block-if-starts() OR hbi-starts()

• hide-block-if-ends() OR hbi-ends()

• hide-block-if-empty() OR hbi-empty()

• hide-block-if-not-equals() OR hbi-not-equals()

• hide-block-if-not-contains() OR hbi-not-contains()

• hide-block-if-not-starts() OR hbi-not-starts()

• hide-block-if-not-ends() OR hbi-not-ends()

Example: {{ds.year}:hide-block-if-equals("2020")}

Value Formatters

Value formatters can be used to format the value of template tags. You can use these with or without parameters:

• format() - Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g"

• format(format) - Formats the value using the specified format string, e.g. "format(N2)"

• substring(index) - Returns the specified substring of the value

• substring(index,length) - Returns the specified substring of the value

• join(separator) - Joins array values using the specified separator

• bool(yes,no,maybe) - Converts a boolean to a 'yes'/'no'/'maybe' values ('maybe' is optional and is used if the value is null)

• empty(default) - If the value is null, empty or empty array, returns 'default'

For example:

String Formatters

String formatters can be used to format string values:

• length - Gets the number of characters in the current string.

• tolower - Returns a copy of this string converted to lowercase.

• toupper - Returns a copy of this string converted to uppercase.

• trim - Removes all leading and trailing white-space characters from this string.

• gethashcode - Gets the hash code of this string.

For example:

Date and time formatters

The below mentioned formatters are applicable to DateTime and DateTimeOffset:

• date - Date component with zeroed time

• day - Day of the month

• dayofweek - Day of the week

• dayofyear - Day of the year

• hour - Hour component of the DateTime

• millisecond - Millisecond component of this DateTime

• minute - Minute component of this DateTime

• month - Month component of this DateTime

• second - Second component of this DateTime

• ticks - Number of ticks representing this DateTime

• timeofday - Time of day

• year - Year component of this DateTime

• add - Adds TimeSpan to this DateTime

• subtract - Subtracts TimeSpane from this DateTime

• tofiletime - Converts this DateTime to a Windows file time

The below mentioned formatters are applicable to DateTime:

• gethashcode - Hash code of this DateTime.

• tolongdatestring - Long string date representation of this DateTime.

• tolongtimestring - Long string time representation of this DateTime.

• tooadate - OLE Automation date representation of this DateTime.

• toshortdatestring - Short string date representation of this DateTime.

• toshorttimestring - Short string time representation of this DateTime.

• tofiletimeutc - Converts the value of this DateTime to a Windows file time.

For example:

Image Formatters

Image formatters convert a value to an image and inserts 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

• keepratio - Stretches the image to fit the host shape, preserving the image aspect ratio

• fitheight - The height of the host shape is adjusted so that the image fills the shape, preserving the image aspect ratio

• fitwidth - The width of the host shape is adjusted so that the image fills the shape, preserving the image aspect ratio

• fitsize - Fits the size of the host shape to the size of the image

• fitsizelim - Like fitsize but does not increase the size of the shape

Example: {{ds.value}:image(100,100)}

Note: Image formatters use System.Drawing.Image class. This works out of the box on Windows, but requires installation of additional shared libraries on Linux and macOS:

• Linux:sudo apt-get updatesudo apt-get install libc6-dev libgdiplus -y

• macOSbrew install mono-libgdiplus

Type Conversion Formatters

As the name suggests, the type conversion formatters let you convert the input types into numeric type data. These formatters are helpful in conversion of strings that hold numeric data in the JSON data source.

Formatters:

• todouble(optional_string) - Converts the input type to a double value.

• tobool(optional_string) - Converts the input type to a bool value.

  Note: If conversion fails, then the optional_string parameter is converted. In case the optional string also cannot be converted, then the optional string itself is returned as output.

Limitations:

Culture-specific bool conversion works only with user-defined types because conversions are implemented using Convert API. For instance, "true" or "True" strings are converted to true regardless of CultureInfo setting. That is,

• when numeric type is used as data source, 0 is converted to False and any other number except 0 is converted to True.

• when string type is used as data source, only "true", "True", "false", and "False" strings are converted to bool regardless of culture. Any other string, including "0" and "1" are not converted. This rule is applicable to optional_string parameter as well.

For example:

Miscellaneous Formatters:

Report Templates also support following formatters:

• length - Gets the total number of elements in all dimensions of this array. Example: {{ds.countries}:length()}

• count - Gets the number of elements in this collection. Example: {{ds.countries}:count()}

Example: {{ds.countries}:count()}

Note: Chars like '{','}',':' are allowed inside formatter parameters but only when paired with '\' so format({x:y}) should be written as format(\{x\:y\}). This is due to the regex nature of engine.