Column Expand Changes in Tag Processor 2
Tag Processor 2 introduces some new functionality that differs from Tag Processor 1 (Legacy) to provide simpler and clearer functionality that will allow easier construction of more complex use cases within Fluent Templates. Amongst these changes are updates to column expanding ForEach tags. This article will explain those differences and why we made those changes.
Change 1: Removal of Block Column Foreach Tags
The first change we made was the ability to set the Foreach Tag property “block” to “true”. If you attempt to set “block=true” on a column expanding Foreach tag you will receive an error. We removed this functionality as this functionality is encapsulated within the placement of the start and end Foreach Tags.
The expansion of the column foreach will be in between the row and column of the start Foreach Tag and the row and column of the End Foreach Tag.
Example 1: Single Column Expansion
In this example we see the start Foreach is in row 1 and column 2 and the end foreach is in row 2 and column 2. This means the only columns being expanded is the second column and all cells before and after that column will not be affected.
If you set the End Foreach Tag to “deleteRow=true” then the table will appear like:
Example 2: Multiple Column Expansion
In this example we see that the start Foreach begins on row 1, column 2 and the End Foreach is on row 2, column 3, that means that both column 2 and column 3 will be included in the expansion.
If you set the End Foreach Tag to “deleteRow=true” then the table will appear like:
Example 3: Rows In-between Column Expansion
If there are multiple rows included in the column expanding Foreach, those will be included in the expanded table.
As we can see from these examples, we are able to achieve block column expansions the same way we could in Tag Processor 1, however with considering the start and end Foreach tag placement this allows a much cleaner looking template while providing much more powerful and precise functionality when creating complex tables than was available in Tag Processor 1.
Change 2: Jagged Tables
While Jagged Tables are a very rare use case we now account for them within Tag Processor 2 column expansion functionality. To start a Jagged Table is a table that contains rows with less columns than are in the table. Here is an example of a jagged table:
As we can see the first row has only 2 columns while the table itself has 3 columns in total. You may be thinking “do horizontally merged cells make a table jagged?”. The answer is “It depends”. For instance this table with a horizontally merged cell is not jagged as it contains the same amount of columns as the total table:
However, this table with horizontally merged cells would be considered “jagged”:
Example 1: Foreach not a part of the “jaggedness” of the table
In this example we have a jagged table, however the scope of the column expanding foreach does not contain the jagged part of the table.
Example 2: Foreach is within the “jaggedness” of the table
In this example we have a jagged table and the foreach tag is within the row that is jagged. In this case we will automatically add padding to the jaggedness since the end Foreach Tag is in a column where a column does not exist in the jagged row.
Example 3: Foreach is in jagged row, but not in scope of the jagged column
In this example we have a jagged table and the Foreach is within the row that is jagged. However, the scope of the column Foreach does not contain the jagged column so in this case we do not add any padded cells and the jaggedness is maintained.
Change 3: Restrictions
Case 1: Block=true for column foreach
As mentioned above you can no longer set the Foreach Tag property “block” to “true” as this block functionality is replaced by the placement of the Foreach and End Foreach Tags. If you specify “block=true” on a column expanding Foreach Tag you will receive an exception stating this.
Case 2: Placing End Foreach in column prior to Column Expanding Foreach Tag
The other restriction we added in is placing an End Foreach Tag in a column prior to a column expanding Foreach Tag. The table below shows this:
Since the row and column placement of the Foreach and End Foreach tags defines the block for the column expansion to occur, placing the End Foreach Tag in an earlier column creates a bounds indicates a negative number of column which is invalid. If the template table is setup like this an exception will be thrown explaining that the End Foreach Tag placement is invalid.