Looping and Conditionals within pdfMachine merge

Liquid allows you to apply formatting, perform loops, conditionals etc based on the values from your datasource. The standard filters and tags are supported as mentioned in Liquid For Designers and DotLiquid For Designers.

Note: To use Liquid Templating Tags in the email body the email body editor must always be in "Source" mode. The "wysiwig" mode will not preserve the Liquid Tags.

Examples of merge field formatting can be found here.

Liquid Tags - conditionals

Conditional output allows you to control the display of content based on the value of the merge field. This can be done using the standard Liquid tags such as the 'if/else', 'unless' tag in a HTML teamplate/body or a Word template.

Tags are the programming logic that tell templates what to do. Tags are wrapped in: {% %} characters.

eg. The following will only output if there is data in the "name" cell in the data source:

            Input:
                    {% if name != "" %}
                        Hello {{ name }}
                    {% endif %}
            Output:
                    Hello John

eg. The following will only output if the "age" cell in the data source has a value greater than or equal to 18:

            Input:
                    {% unless age >= 18 %}
                         Parent / Guardian signature is required.
                    {% endif %}
            Output when the value of age is greater than 18:
                    Parent / Guardian signature is required.

Looping

Looping through rows to make line items appear can be done using any of the following methods in a HTML template

The repeat_row, repeat_par filters
The Liquid for loop
Javascript

When referencing merge fields for looping use lower case for the merge field. For example {{row.name | repeat_row}} should be used not {{row.Name | repeat_row}}. Anything after the . must be in lower case.

Review the example profile showing how to loop through rows and create line items in a Word template here.

The repeat_row, repeat_par filters

repeat_row

Repeats the current table row. Works with HTML and Word templates. See an example.

repeat_par

For HTML documents, repeats the current P, LI or DIV blocks.
For Word documents, repeats the current paragraph.

This can be used when the "Rows to emails method" is set to "one or more rows generates an email", which has the effect of grouping the rows based on a merge field, usually the email address.

NOTE: you place the filter on one and only one data item in the row or paragraph you are repeating.

Note in the example the merge field names must be prefixed with "row."

repeat_row example

            Input:
                             
                                
                                    Name
                                    Amount
                                
                                
                                    {{row.name | repeat_row}}
                                    {{row.amount}}
                                

                            
            Output:
                             
                                
                                    Name
                                       
                                    Amount
                                
                                
                                    Dave
                                       
                                    1230
                                
                                
                                    Dave
                                       
                                    1000

Name	Amount
{{row.name \| repeat_row}}	{{row.amount}}

Name		Amount
Dave		1230
Dave		1000

repeat_par example

                    "=""> Input:
                    
                        Name: {{ row.name | repeat_par }} 

                        Amount: {{ row.amount }}
                    
                    Output:
                    
                        Name: Dave 

                        Amount: 1230

                    
                    
                        Name: Dave 

                        Amount: 1000

These filters are a shortcut for the Liquid 'for' loop. Specifically, the Liquid tag "{% for row in _rows %}" is placed around the paragraph or row. The Liquid for loop does not work well for visual html editors when used around table rows, so this is the preferred option.

Liquid Tags - looping using the 'for' loop

Tags are the programming logic that tell templates what to do. Tags are wrapped in: {% %} characters.

            Input:
                {% for row in _rows %}
                    
                        Name: {{ row.name  }} 

                        Amount: {{ row.amount }}
                    
                {% endfor %}

            Output:
                
                    Name: Dave 

                    Amount: 1230

                
                
                    Name: Dave 

                    Amount: 1000

If you need help or more information on this feature please contact craig@broadgun.com

word_table tag

Defines a table in Word to be used for repating rows. Very similar to the repeat_row filter, but takes a parameter which is the collection to iterate. One row will be created for each element in the collection. After the table you must close with a "endword_table" tag.

e.g.

Input

Output

When referencing merge fields for word_table tags use lower case for the merge field. For example {{row.invoice_id}} should be used not {{row.Invoice_Id}}. Anything after the . must be in lower case.