Sometimes you will need whole sections of the document to repeat. For example you might want a separate signature block for each participant. Each signature block will print the participant name and address under the signature lines. You can also create lists and tables from custom data sets defined as "multi-row".
In order to create a repeating block all you need to do is edit the template and surround the block(s) as follows:
<Block of text to repeat - which can contain merge fields>
The 'data_source' tells the repeat block what to count in order to determine the number of repetitions.
The 'data_source' can be the name of any data_source of custom data collections in the merge_field list. It can also be an Action Participant. If it is a participant type then it needs to be further qualified by the participant type.
If the Data Source is 'action_participant' then you need to further qualify this with the participant type. Example: [[*REPEAT|data_source=action_participant.Client|*]]
Examples of data sources
When pulling merge fields form a participant: Action_participant.ParticipantType
In this case ParticipantType is the name of the participant type that you are pulling information on. For example a "Client", "Lawyer" or "Customer".
When pulling merge fields form a multi-row data collection: Data_Collection_Name
The name of the data collection that the fields you are repeating will be found under.
When Pulling information from a Sales/Purchase document (such as an invoice): SP_LineItems
When the document generates it will look at the data_source (see merge field list) to determine how many times to repeat. It will then substitute the * character in the repeating clock for the number of the repeat block.
|NOTE: It is important to set the record number to an asterisk within the repeat block (rn=*)|
will translate to:
After all repeat blocks have been created then the merge fields will be substituted in the normal way.
Tip: If you want to get all the participants in an action, regardless of type, then use "All__Participants" (with a double underscore between All and Participants).
|NOTE: "action_participant" in the data_source specification needs to be in lower case.|
Full List of Data Sources
The availability of the data sources will depend on what type of document template is being generated, however below is a full list of possible data sources and how to type them.
- any multi-row data-collection name
Sorting Participant Data in Repeat Blocks
The only sort option we have for participants is "sort=name". Name must be in all lowercase.
Sorting Multi-Row Custom Data Elements in Repeat Blocks
By default the multi-row custom data elements will be sorted by the order they were added to the action (Record Number). If you want to sort by specific columns then add a 'sort' directive to the merge field. Valid values for sort are as follows (NOTE:Column numbering starts at Zero):
- Specific Columns: A comma-separated list of columns in the order you require e.g. "sort=0,4,2" will sort by the first column then by the fifth and then by the third column
- Range of columns: "sort=0-3" will sort by the first 4 columns in order
- All columns: "sort=all" will sort by the order of the columns in the list. This is the easiest way to do it.
- The name of the field can be used instead of the column number e.g. sort=my_custom_field_name
You can control the direction of the sort with the "direction=" option.
- "Direction=asc" will sort ascending order (A-Z)
- "Direction=desc" will sort descending order (Z-A)
Creating Tables using Repeat Blocks
You can create table rows for each repeat block by placing the repeat clock inside a regular DOCX table in MS Word. However problems sometimes occur because it is difficult to see where the (invisible) row markers start and end. The key to keeping all the columns together is to use the "tablerow" merge field option in the first REPEAT directive.
[[*REPEAT|...|tablerow|*]] … [[*REPEAT|END*]]
The effect this has on the merge process is that Actionstep will automatically include the start and end row tags from the template inside the REPEAT block to ensure that the whole row gets repeated rather than individual cells.