The 4D Write Pro document tables have greatly improved over the last few versions. In fact, we, the 4D team, are so invested in making 4D Write Pro a potent template-based documents generator —that we have already released advances such as headers, datasources, carry-over rows…a few powerful features off the top of my head.
Now, with 4D v20, it’s the turn of break rows to make their entry!
Ladies and gentlemen, drum roll, please!
The goal to reach
Whatever your activity is, you certainly need to create lists.
These lists are sorted according to your own criteria, and it is usually necessary to create groups for each of these groups to obtain totals or statistics. This is what this new feature of 4D Write Pro offers to you!
When and how? Here is A concrete example
When a table is fed by a sorted data source, the goal is to insert a break row when the value corresponding to the sorting criteria changes.
Imagine you know people from several continents, countries, and cities.
And you want to create a list of these people grouped by continent, country, and city.
Or you want to create a report based on the company relation and create a list of employees grouped by the company on each continent.
In both cases, you must first ensure this selection is sorted according to these three criteria.
Case 1:
ds.people.all().orderBy("continent asc, country asc, city asc")Case 2:
ds.People.all().orderBy("worksFor.name asc, continent asc)For each sorting criterion, a break Row
Once the datasource is associated with the table, the people will be displayed in the “repeated row” and in the desired order. Let’s see how to group them by sorting criteria.
Using the interface
New items are now available in the row menu. They are contextual and will appear only if the cursor is inside a table (and below the header, if any).
For example, the formula can be based on an attribute name (This.item.country) or a related attribute path (ex: This.item.worksFor.name) or any other formula (Substring(This.item.name;1;1)).
Once the break attribute has been set… you can see its formula when hovering over the break symbol “S” (as in Sort).
Above or below BreakS?
Break rows can be above or below the repeated row (filled by the table datasource).
Breaks will be rendered each time the value returned by the break formula changes, so make sure the position of the breaks matches the sort criterias of the datasource.
A new row attribute
The attribute wk break formula contains the formula whose result will determine the display of the break row. The mere presence of this attribute will cause a row to be considered a break row. You can define as many break rows as you need, for example, Formula(This.item.city) for the lowest break level and Formula(This.item.continent) for the highest level.
WP SET ATTRIBUTES($row; wk break formula; Formula(This.item.country))
WP RESET ATTRIBUTES($row; wk break formula)Keep in mind:
- A break row must be located just above or below a repeated row or another break row if there are several levels. Otherwise, they won’t be taken into account.
- The number of levels is limited to five. If you add a sixth level, no error will be triggered, but it won’t be rendered.
- Inserting break rows in the table does not sort the datasource. The data source must be sorted independently.
That’s it!
Break rows content
In addition to text, break rows can contain two types of formulas.
-
- The first possibility is to use the elements present – or could be present – in the repeated rows (Ex: This.item.continent).
The value returned will be the last value used before the break (or the first value used if the break row precedes the repeated rows). - The second possibility is new: The breakItems property can only be used in the context of breaks (Ex: This.breakItems).
The breakItems is a subset of the table’s source data which corresponds precisely to the repeated rows of the concerned break row. - To use the example of multiple breaks by continent-country-city, when the content changes, the subset corresponds to the people from the continent (before the change), and this is whether the break row is placed before or after the repeated row. This subset can be used to perform calculations like sum(“salary”), average(“salary”), etc.
- The first possibility is to use the elements present – or could be present – in the repeated rows (Ex: This.item.continent).
Finally, let’s specify that these subsets will be the same type as the table’s source data, i.e., an entity selection or a collection.
More info
More info about this feature can be found in the documentation.
Conclusion
This new feature again shows the power of 4D Write Pro regarding automatic document creation.
With the breaks, a further step is taken. Let us know what you think about the 4D Forum.