Transformations
Liquid filters
What we call transformations are actually called filters in Liquid. We list the most often used here but you can find a lot more in Liquid’s documentation.
Case changes
If you want to change the case of a dynamic data the following filters might be useful:
{{client.name | upcase}} -> JANE DOE
{{client.name | downcase}} -> jane doe
{{client.name | capitalize}} -> Jane doe
Default values
If you want to provide a default value for a dynamic data, don’t use an if … else … construct. Simply use the default filter:
{{client.name | default: "Jeanne Doe"}}
Notice that you can chain filters if you want to apply transformations to a value, even with a default:
{{client.name | default: "Jeanne Doe" | upcase}}
Line breaks
If you need to insert user generated content, you will probably need to preserve the line breaks that the user inserted.
Let’s say you’re defining the following sample data:
{
"userBio": "I’m Bob.\nI am 42 years old.\nI feel happy and that’s a good start."
}
If you were to render this directly in HTML, the line breaks (\n) would be ignored.
Using the newline_to_br filter you can replace every line break with a <br> tag:
{{userBio | newline_to_br}}
Now the content will be rendered the same way the user typed it!
Computations and rounding
Sometimes you need to do some math. For instance in an invoice when computing a price based on a unit price and a quantity. Sometimes you may also want to round the numbers.
Let’s define some sample data so that we can play with it:
{
"menu": {
"price": 17.50,
"quantity": 4
},
"payers": 3
}
{{menu.price | times: menu.quantity}} -> 68
{{menu.price | times: menu.quantity | divided_by: payers}} -> 23.333333333333332
{{menu.price | times: menu.quantity | divided_by: payers | round}} -> 23
{{menu.price | times: menu.quantity | divided_by: payers | round: 2}} -> 23.33
You can do even more with the help of abs, ceil, floor, minus, modulo and plus.
PDFMonkey filters
We provide a few additional filters that you might find useful:
JSON
If you need to insert a dynamic data in its original JSON format (like we do for charts for instance) the json filter is what you need. Notice it’s returning a string, not the object itself.
{{'banana, apple' | split: ', ' | json}} -> '["banana", "apple"]'
Ensure protocol
You might get asset URLs that don’t include any protocol. Sadly our rendering engine doesn’t support this type of URL. For this reason we provide the ensure_protocol that will add a protocol as needed:
{{"//example.com/some-picture.jpg" | ensure_protocol}} -> https://example.com/some-picture.jpg
{{"//example.com/some-picture.jpg" | ensure_protocol: "http"}} -> http://example.com/some-picture.jpg
{{"http://example.com/some-picture.jpg" | ensure_protocol}} -> http://example.com/some-picture.jpg
Basic number formatting
Oftentimes formatting numbers is necessary. For that purpose, we provide a with_delimiter filter:
{{12345678 | with_delimiter}} -> 12,345,678
{{'123456' | with_delimiter}} -> 123,456
{{12345678.05 | with_delimiter}} -> 12,345,678.05
{{12345678 | with_delimiter, delimiter: '.'}} -> 12.345.678
{{12345678 | with_delimiter, delimiter: ','}} -> 12,345,678
{{12345678.05 | with_delimiter, separator: ' '}} -> 12,345,678 05
{{12345678.05 | with_delimiter, delimiter: ' ', separator: ','}} -> 12 345 678,05
{{'123a' | with_delimiter}} -> 123a
Advanced number formatting
If you need to format a number in a very specific way, the format filter might come in handy:
{{5 | format: "%05d"}} -> 00005
{{5 | format: "%08.3f"}} -> 0005.000
{{5 | format: "%.2f"}} -> 5.00
{{5.1234 | format: "%.2f"}} -> 5.12
To learn more about the possible formats, refer to Ruby’s documentation on format
PDFMonkey