While POD allows to repeat almost any part of an ODT or ODS document, there is nothing simple about repeating a complete table column. Indeed, a column is not an atomic document part: a column is a kind of conceptual part, made of cells, being themselves parts of rows. While, in most cases, you may lead a comfortable life without ever repeating any table column in ODT templates, you will almost inevitably encounter a case where column repetition is desired in an ODS template.
Consider the following example. It comes from a software for managing human resources.
Suppose variable self represents a company. Its employees may have several contracts. This ODS export includes one row per user and contract, containing data about a given period of time. The specificity here is that we want to dump one column for every day in the period.
The obvious part of the solution is, within each row, to repeat the "template" cell representing a given day (=column D) with a "do cell" statement. In this example, variable grid is a list of DateTime instances, each one representing a day of the current period = a complete month. Consequently, cells D1, D2, D3 and D4 all contain the same comment:
do cell for day in grid
This is a first step, but it will not be enough. Remember, from your knowledge of ODT templates, that cell repetition does not create any additional column: the loop simply walks through the existing cells, respecting the number of columns as defined in the table and creating additional rows of data when needed. In the example, although the sheet seems infinite, LibreOffice, when storing this ODS template, will produce a table of 9 columns (from A to I). Cell repetition will still produce a table of the same number of columns, with additional rows. Schematically, the process can be understood via this simpler ODS template.
Suppose variable grid contains a list of 30 dates (one for each day of some month). The ODS result would look like this.
POD simply repeats the content of cell D1 on subsequent cells, 30 times, creating an additional row of data everytime it reaches the end of the current row. At the end of this process, empty cells are added in order to produce a table whose rows all contain the same number of cells.
Obviously, it does not correspond to what we wanted to achieve: we wanted a true duplication of column D, with additional columns having the same width as D.
This is where variable columnsRepeated comes into play. Defining a variable with this predefined name, within the scope of a table, explains to Appy how many times every column will be repeated.
Because our table has 9 columns, variable columnsRepeated must be a tuple of 9 integers; every integer determining how many times the corresponding column will be repeated. In the initial example, by specifying
do table with columnsRepeated=(1,1,1,len(grid),1,1,1,1,1)
we tell Appy: "well, every column will only be repeated once, as usual, excepted the 4th one, that will be repeated as many times as there are elements in variable grid."
Thanks to this precision, Appy will produce the desired result, as shown below.
Every column has kept his initial characteristics (most notably, its original size); column D has been successfully repeated as desired.
You may argue that our desires are weird, because the generated cells are empty. It allows me to introduce the next section, where we will take this example one step further to fill these cells with styled info liked a colored background.
Alert
LibreOffice, when saving an ODS file, performs some optimizations that can break the way POD works.
Consider for example the following ODS template.
LibreOffice will detect that content of cells A1 to C1 are the same and will, behind the scenes, store a single ODF cell with a special attribute: table:number-columns-repeated="3". Idem for cells E1 to I1. This kind of optimizations breaks the Appy expectations w.r.t. the table structure. Try to execute this template and you will get a fanciful result whose sole interest would be to compete with ASCII art. Currently, Appy does not manage these cases.
