Block Behavior Formatters

Block behavior formatters allow you to modify the default behavior when rendering a data range (a collection of data items). GcWord provides two block behavior formatters:

• paragraph-block-behavior(), pbb(): When applied to a start range tag inside a table cell, it causes the range blocks to repeat as separate paragraphs inside that single cell rather than repeating each block as a table row. This formatter 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, it causes the range blocks to repeat as runs within the same paragraph rather than separate paragraphs.

Paragraph block behavior (paragraph-block-behavior, pbb) formatter

Paragraph block behavior formatter is helpful in rendering a range of data or list of items, as a block inside a single table cell. It renders the range of data or items as a vertical list in the single cell of a table. This formatter is applicable only in the case of table cells. The following table demonstrates the difference in generated output without the pbb and with it:

// Add a list for oceans, and a nested table for seas:
doc.Body.Paragraphs.Add("{{#ds}}{{ds.name}}", doc.Styles[BuiltInStyleId.ListParagraph]);

var table = doc.Body.Tables.Add(1, 1);
table.Style = doc.Styles[BuiltInStyleId.GridTable1LightAccent1];
var cell_11 = table[0, 0];

//reuse first paragraph of the cell and define seas range with pbb() formatter.
//This formatter force range to be expanded in single cell, instead of generating row per each item.
cell_11.GetRange().Paragraphs.First.GetRange().Runs.Add("{{#ds.seas}:pbb()}{{ds.seas.name}}{{/ds.seas}}");

//close parent range #ds.
doc.Body.Paragraphs.Add("{{/ds}}");

Limitations

• A range defined with a paragraph block behavior formatter must start and end in the same table cell.

• If pbb range contains inner ranges, those are converted to pbb ranges too, unless they are already defined as run-block-behavior(rbb) ranges. This rule is not applicable to ranges in inner table. That is, if inner table is defined inside a pbb range, its ranges do not automatically inherit pbb behavior.

• In case of sibling, that is, a template range defined at same level in their parent range, following rules are applied:

  • Siblings of any type are valid if it does not include cell where pbb template is defined. If previous sibling is formatted as rbb or pbb in same cell, then pbb range is allowed to be the next sibling. Otherwise, template is considered malformed and exception InvalidTemplateStructureException is thrown.

  • If previous sibling is defined inside inner table of a cell, any type of siblings are allowed.

  • Any type of next siblings are allowed.

  • If next sibling in cell is rbb or default, we check the location where it is defined and template is considered malformed if this sibling is defined as end of pbb sibling in the same paragraph.

Run block behavior (run-block-behavior, rbb) formatter

Run block behavior formatter causes the range blocks (data items in a range) to repeat as runs inside the same paragraph rather than separate paragraphs. The following table demonstrates the difference in generated output without the rbb and with it:

// Add a list for oceans, and a nested table for seas:
doc.Body.Paragraphs.Add("{{#ds}}{{ds.name}}", doc.Styles[BuiltInStyleId.ListParagraph]);

//Add new paragraph to define seas range with rbb() formatter.
//This formatter force range to be expanded in single paragraph, instead of generating new paragraph
//per each item.
doc.Body.Paragraphs.Add("{{#ds.seas}:rbb()}{{ds.seas.name}} ; {{/ds.seas}}");

//close parent range #ds.
doc.Body.Paragraphs.Add("{{/ds}}");

Limitations

• Range, defined with rbb formatter, can be defined only in single paragraph.

• If rbb range contain inner ranges, they are converted to rbb ranges too, unless they already are rbb ranges.

• pbb range can not be defined inside an rbb range.