Document Solutions for Word
Report Templates / Template Configuration / Formatters
In This Topic
    Formatters
    In This Topic

    DsWord 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:

    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:

    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:

    For example:

    Sample Data Template Tag Output
    { Name= "Richard Clark"}  {{Name}:substring(5)}  Clark


    String Formatters

    String formatters can be used to format string values:

    For example:

    Sample Data Template Tag Output
    { cities = new[] {name = "China"}};  {{cities.name}:toupper()}  CHINA

    Date and time formatters

    The below mentioned formatters are applicable to DateTime and DateTimeOffset:

    The below mentioned formatters are applicable to DateTime:

    For example:

    Sample Data Template Tag Output
    { Timestamp= "2020-04-21T16:15:45-08:00"} {{TimeStamp}:year()} 2020

    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:

    Formatters:

    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 update
      sudo apt-get install libc6-dev libgdiplus -y
    • macOS
      brew 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:

    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,

    For example:

    Sample Data Template Tag Output
    { "-2", "32", "16", "5,45", "12,39" } {{ds.value}:todouble():hbi-less(7)}

    32

    16

    12,39

    { d = "samplestring" } {{ds.d}:tobool(false)} False

    Miscellaneous Formatters:

    Report Templates also support following formatters:

    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.

    Note:

    • DsWord uses "not" instead of "!" for negative checks. The use of "!" will throw an exception when processing the template.
      For example: {{if not isLast(ds.companyKeywordList)}}
    • Formatters cannot be applied to tags inside a conditional template’s calc and if blocks.
      For example: ds.tag:toupper() cannot be used as {{if ds.tag:toupper() = “XXX“}} and {{calc ds.tag:toupper()…}}.
    • Functions cannot be used outside conditional template definitions.
      For example: {{#ds}}{{ToUpper(ds.tag}}}}{{/ds}}.
    • The short notation will create all necessary range tags automatically. If the user wants to inspect such auto-generated tags, user should use DataTemplate.DebugExpandTemplate API. It is useful when the user wants to know why and how the template structure was auto-generated in an unexpected way.