# GrapeCity.Documents.Word.Templates.DataTemplate

## Content

<div class="doc-site-dotnet-api-container">



  <h1 id="GrapeCity_Documents_Word_Templates_DataTemplate" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate" class="text-break">DataTemplate Class
</h1>
  <div class="markdown level0 summary"><p>Provides properties and methods that are used to associate a <a class="xref" href="GrapeCity.Documents.Word.GcWordDocument.html">GcWordDocument</a>
with template data sources, and to process data templates. See remarks for details.</p>
</div>
  <div class="markdown level0 conceptual"></div>
  <div class="inheritance">
    <h5>Inheritance</h5>
    <div class="level0"><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object">object</a></div>
    <div class="level1"><span class="xref">DataTemplate</span></div>
  </div>
  <h6><strong>Namespace</strong>: <a class="xref" href="GrapeCity.Documents.Word.Templates.html">GrapeCity.Documents.Word.Templates</a></h6>
  <h6><strong>Assembly</strong>: DS.Documents.Word.dll</h6>
  <h5 id="GrapeCity_Documents_Word_Templates_DataTemplate_syntax">Syntax</h5>
  <div class="codewrapper">
    <pre><code class="lang-csharp hljs">public class DataTemplate</code></pre>
  </div>
  <div class="codewrapper">
    <pre><code class="lang-vbnet hljs">Public Class DataTemplate</code></pre>
  </div>
  <h5 id="GrapeCity_Documents_Word_Templates_DataTemplate_remarks"><strong>Remarks</strong></h5>
  <div class="markdown level0 remarks"><p>Data templates have the form of &quot;{{ds.value_path}[:formatter1(args1):formatter2(args2):..formatterN(argsN)]}&quot;,
where</p>
<ul><li><span class="term">ds</span>A user-defined name of the data source.</li><li><span class="term">value_path</span>The full dot-delimited path from data source to the property name.</li><li><span class="term">formatterX</span>Optional: one or more formatters that process the value, see below for details.</li></ul>
<p>## Range tags:</p>
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:
<ul><li><span class="term">{{#ds}} or {{#ds.enumerable_path}}</span>Start of a range block.</li><li><span class="term">{{/ds}} or {{/ds.enumerable_path}}</span>End of a range block.</li></ul>
E.g. a fully qualified template tag to list all cities in uppercase from the data source can look like this:
<pre><code class="lang-csharp">{{#ds}}{{#ds.cities}}{{ds.cities.name}:toupper()}{{/ds.cities}}{{/ds}}</code></pre>
<p>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.
</p>
<p>Many formatters allow hiding a block of data if a certain condition is met.
All such formatters have two equivalent forms - 'hide-block-if-&lt;condition&gt;' and the short form 'hbi-&lt;condition&gt;'.
Conditions are self-explanatory.</p>
<p>## Range behavior modifying formatters:</p>
<ul><li><span class="term">paragraph-block-behavior(), pbb()</span>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.</li><li><span class="term">run-block-behavior(), rbb()</span>When applied to a start range tag, causes the range blocks
to repeat as runs within the same paragraph rather than separate paragraphs.</li></ul>
<p>## Block hiding formatters:</p>
These formatters hide a block of data if the value in the block meets a condition.
<ul><li>hide-block-if-equals(), hbi-equals()</li><li>hide-block-if-greater(), hbi-greater()</li><li>hide-block-if-less(), hbi-less()</li><li>hide-block-if-contains(), hbi-contains()</li><li>hide-block-if-starts(), hbi-starts()</li><li>hide-block-if-ends(), hbi-ends()</li><li>hide-block-if-empty(), hbi-empty()</li><li>hide-block-if-not-equals(), hbi-not-equals()</li><li>hide-block-if-not-contains(), hbi-not-contains()</li><li>hide-block-if-not-starts(), hbi-not-starts()</li><li>hide-block-if-not-ends(), hbi-not-ends()</li></ul>
<p>## Value formatters:</p>
<ul><li><span class="term">format()</span>Default. If applied on a date, will format as short date string "d", numeric types will be formatted as "g".</li><li><span class="term">format(format)</span>Formats a value using the specified format string, e.g. "format(N2)".</li><li><span class="term">substring(index)</span>Returns the specified substring of a value.</li><li><span class="term">substring(index,length)</span>Returns the specified substring of a value.</li><li><span class="term">join(separator)</span>Joins array values using the specified separator.</li><li><span class="term">bool(yes,no,maybe)</span>Converts a boolean to a 'yes'/'no'/'maybe' value ('maybe' is optional and is used if the value is null).</li><li><span class="term">empty(default)</span>If a value is null, empty or empty array, returns 'default'.</li><li><span class="term">todouble([default_str])</span>Converts a value to double. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.</li><li><span class="term">tobool([default_str])</span>Converts a value to boolean. If conversion fails, 'default_str' is converted. If that also fails, 'default_str' itself is used.</li></ul>
<p>## String formatters:</p>
<ul><li><span class="term">length</span>The number of characters in the current string.</li><li><span class="term">tolower</span>A copy of this string converted to lowercase.</li><li><span class="term">toupper</span>A copy of this string converted to uppercase.</li><li><span class="term">trim</span>A copy of this string without leading and trailing whitespace characters.</li><li><span class="term">gethashcode</span>The hash code of this string.</li></ul>
<p>## Date and time formatters (applicable to DateTime and DateTimeOffset):</p>
<ul><li><span class="term">date</span>The date component with zeroed time.</li><li><span class="term">day</span>The day of the month.</li><li><span class="term">dayofweek</span>The day of the week.</li><li><span class="term">dayofyear</span>The day of the year.</li><li><span class="term">hour</span>The hour component of the DateTime .</li><li><span class="term">millisecond</span>The millisecond component of this DateTime.</li><li><span class="term">minute</span>The minute component of this DateTime.</li><li><span class="term">month</span>The month component of this DateTime.</li><li><span class="term">second</span>The second component of this DateTime.</li><li><span class="term">ticks</span>The number of ticks representing this DateTime.</li><li><span class="term">timeofday</span>The time of day.</li><li><span class="term">year</span>The year component of this DateTime.</li><li><span class="term">add</span>Adds TimeSpan to this DateTime.</li><li><span class="term">subtract</span>Subtracts TimeSpane from this DateTime.</li><li><span class="term">tofiletime</span>Converts this DateTime to a Windows file time.</li></ul>
<p>## Date and time formatters (applicable to DateTime):</p>
<ul><li><span class="term">gethashcode</span>The hash code of this DateTime.</li><li><span class="term">tolongdatestring</span>Long string date representation of this DateTime.</li><li><span class="term">tolongtimestring</span>Long string time representation of this DateTime.</li><li><span class="term">tooadate</span>OLE Automation date representation of this DateTime.</li><li><span class="term">toshortdatestring</span>Short string date representation of this DateTime.</li><li><span class="term">toshorttimestring</span>Short string time representation of this DateTime.</li><li><span class="term">tofiletimeutc</span>Converts the value of this DateTime to a Windows file time.</li></ul>
<p>## Image formatters:</p>
Image formatters convert a value to an image and insert it into the document.
The value must be of one of the following types:
<ul><li>A byte array containing image data.</li><li>A System.IO.Stream object that can be used to read image data.</li><li>A System.Drawing.Image object.</li><li>A string that can be converted to an absolute file URI, or containing Base64-encoded image data.</li></ul>
Formatters:
<ul><li><span class="term">image(width, height)</span>Inserts the image with the specified width and height.</li><li><span class="term">image()</span>If the image is inside a shape, it is stretched to fill the shape.
Otherwise it is inserted with its original width and height.</li><li><span class="term">image(keepratio|fitheight|fitwidth|fitsize|fitsizelim)</span>Fits the image into the host shape using a specified fitting strategy.</li></ul>
<p>## Miscellaneous formatters:</p>
<ul><li><span class="term">length</span>Gets the total number of elements in all dimensions of this array.</li><li><span class="term">count</span>Gets the number of elements in this collection.</li><li><span class="term">restart()</span>Can only be applied to a range. Restarts all nested numbered lists except the topmost one.</li><li><span class="term">restart(all)</span>Same as restart() but restarts all lists including the topmost one.</li><li><span class="term">sequence(id), seq(id)</span>Can only be applied to a range. Gives this range a unique name 'id'. Allows following it using the 'follow' formatter.</li><li><span class="term">follow(id)</span>Can only be applied to a range. Makes this range follow the named sequence 'id'.</li><li><span class="term">count</span>Gets the number of elements in this collection.</li></ul>
</div>
  <h3 id="properties">Properties
</h3>
  <table class="table table-bordered table-condensed">
    <thead>
      <tr>
        <th>Name</th>
        <th>Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_DataSources" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.DataSources">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.DataSources.html#GrapeCity_Documents_Word_Templates_DataTemplate_DataSources">DataSources</a>
        </td>
        <td class="markdown level1 summary"><p>Gets the collection of data sources associated with the current document's
data templates.</p>
</td>
      </tr>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_Options" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.Options">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.Options.html#GrapeCity_Documents_Word_Templates_DataTemplate_Options">Options</a>
        </td>
        <td class="markdown level1 summary"><p>Gets options controlling the behavior of the template processing engine.</p>
</td>
      </tr>
    </tbody>
  </table>
  <h3 id="methods">Methods
</h3>
  <table class="table table-bordered table-condensed">
    <thead>
      <tr>
        <th>Name</th>
        <th>Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_BatchProcess_System_Action_System_Globalization_CultureInfo_" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.BatchProcess(System.Action,System.Globalization.CultureInfo)">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.BatchProcess.html#GrapeCity_Documents_Word_Templates_DataTemplate_BatchProcess_System_Action_System_Globalization_CultureInfo_">BatchProcess(Action, CultureInfo)</a>
        </td>
        <td class="markdown level1 summary"><p>Iterates over root items in <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.DataSources.html#GrapeCity_Documents_Word_Templates_DataTemplate_DataSources">DataSources</a>,
starting with a fresh copy of the document and processing templates separately
for each root data item.</p>
<p>
The <code class="paramref">itemProcessed</code> 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).
</p>
<p>
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).
</p>
</td>
      </tr>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_DebugExpandTemplate_System_Boolean_System_Globalization_CultureInfo_" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.DebugExpandTemplate(System.Boolean,System.Globalization.CultureInfo)">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.DebugExpandTemplate.html#GrapeCity_Documents_Word_Templates_DataTemplate_DebugExpandTemplate_System_Boolean_System_Globalization_CultureInfo_">DebugExpandTemplate(bool, CultureInfo)</a>
        </td>
        <td class="markdown level1 summary"><p>Expands the template. The template will be processed and all missed tags added.</p>
</td>
      </tr>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_GetTemplateTagInfos" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.GetTemplateTagInfos">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.GetTemplateTagInfos.html#GrapeCity_Documents_Word_Templates_DataTemplate_GetTemplateTagInfos">GetTemplateTagInfos()</a>
        </td>
        <td class="markdown level1 summary"><p>Gets the list of <a class="xref" href="GrapeCity.Documents.Word.Templates.TemplateTagInfo.html">TemplateTagInfo</a> objects in the document.</p>
</td>
      </tr>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_InitBatchStepProcessor_System_Globalization_CultureInfo_" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.InitBatchStepProcessor(System.Globalization.CultureInfo)">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.InitBatchStepProcessor.html#GrapeCity_Documents_Word_Templates_DataTemplate_InitBatchStepProcessor_System_Globalization_CultureInfo_">InitBatchStepProcessor(CultureInfo)</a>
        </td>
        <td class="markdown level1 summary"><p>Initializes the template engine for batch processing in single-step mode and returns a <a class="xref" href="GrapeCity.Documents.Word.Templates.BatchStepProcessor.html">BatchStepProcessor</a>
that can be used to control the processing of an individual record.</p>
</td>
      </tr>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_Process_System_Globalization_CultureInfo_" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.Process(System.Globalization.CultureInfo)">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.Process.html#GrapeCity_Documents_Word_Templates_DataTemplate_Process_System_Globalization_CultureInfo_">Process(CultureInfo)</a>
        </td>
        <td class="markdown level1 summary"><p>Processes templates in the document, iterating over root items in <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.DataSources.html#GrapeCity_Documents_Word_Templates_DataTemplate_DataSources">DataSources</a>,
and replacing template tags in the document with data.</p>
</td>
      </tr>
      <tr>
        <td id="GrapeCity_Documents_Word_Templates_DataTemplate_Validate_System_Boolean_" data-uid="GrapeCity.Documents.Word.Templates.DataTemplate.Validate(System.Boolean)">
          <a class="xref" href="GrapeCity.Documents.Word.Templates.DataTemplate.Validate.html#GrapeCity_Documents_Word_Templates_DataTemplate_Validate_System_Boolean_">Validate(bool)</a>
        </td>
        <td class="markdown level1 summary"><p>Validates all templates in the current document,
finds any template tags that are malformed or used incorrectly.</p>
</td>
      </tr>
    </tbody>
  </table>

</div>