Transformations
Filtres Liquid
Ce que nous appelons des transformations sont en fait des fitres dans le jargon de Liquid. Nous listons ici les plus fréquents mais la documentation de Liquid en contient bien d’autres.
Changements de casse
Si vous souhaitez changer la casse d’une donnée dynamique, les filtres suivants pourraient vous être utiles :
{{client.nom | upcase}} -> JEANNE MACHIN
{{client.nom | downcase}} -> jeanne machin
{{client.nom | capitalize}} -> Jeanne machin
Valeurs par défaut
Pour donner une valeur par défaut à une donnée dynamique, préférez le filtre default à l’usage de if … else … :
{{client.nom | default: "Jeanne Machin"}}
À noter qu’il est possible de chaîner les filtres pour appliquer une transformation même si une valeur par défaut est présente :
{{client.nom | default: "Jeanne Machin" | upcase}}
Sauts de lignes
Lorsque du contenu saisi par un utilisateur est inséré dans un document, il est généralement préférable de conserver les sauts de ligne originaux.
Mettons que nous définissions les données d’exemple suivantes :
{
"userBio": "Je suis Bob.\nJ’ai 42 ans.\nJe me sens heureux et c’est un bon début."
}
Affiché directement en HTML, ce texte ne contiendrait pas de sauts le ligne, ces derniers sont ignorés.
Le filtre newline_to_br permet de remplacer chaque saut de ligne par une balise <br> :
{{userBio | newline_to_br}}
Le contenu est maintenant conforme à l’original saisi !
Calculs et arrondis
Il est parfois nécessaire d’effectuer quelques opérations mathématiques. On peut par exemple penser à multiplier un prix unitaire par une quantité dans le cas d’une facture. Il est parfois également intéressant d’arrondir une valeur.
Partons de données d’exemple :
{
"menu": {
"prix": 17.50,
"quantite": 4
},
"payeurs": 3
}
{{menu.prix | times: menu.quantite}} -> 68
{{menu.prix | times: menu.quantite | divided_by: payeurs}} -> 23.333333333333332
{{menu.prix | times: menu.quantite | divided_by: payeurs | round}} -> 23
{{menu.prix | times: menu.quantite | divided_by: payeurs | round: 2}} -> 23.33
Pour aller plus loin, vous avez à disposition abs, ceil, floor, minus, modulo et plus.
Filtres PDFMonkey
Nous proposons également quelques filtres qui pourraient vous être utiles :
JSON
Si vous devez insérer une donnée dynamique sous sa forme JSON originale (comme nous le faisons pour les graphiques par exemple), le filtre json vous sera utile. À noter qu’il retourne une chaine de caractère et non l’objet lui-même.
{{'banane, pomme' | split: ', ' | json}} -> '["banane", "pomme"]'
Forcer un protocole
Si vous manipulez des URL d’images sans protocole, le moteur de rendu de PDFMonkey ne saura pas les interpréter. Pour cela nous proposons le filtre ensure_protocol qui prefix au besoin vos URL :
{{"//exemple.fr/une-photo.jpg" | ensure_protocol}} -> https://example.fr/une-photo.jpg
{{"//exemple.fr/une-photo.jpg" | ensure_protocol: "http"}} -> http://example.fr/une-photo.jpg
{{"http://exemple.fr/une-photo.jpg" | ensure_protocol}} -> http://exemple.fr/une-photo.jpg
Format des nombres
Il est souvent nécessaire de formatter des nombres. Pour cela nous mettons à disposition un filtre with_delimiter :
{{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 | with_delimiter, delimiter: ',', precision: 2}} -> 12,345,678.00
{{12345678.05 | with_delimiter, separator: ' '}} -> 12,345,678 05
{{12345678.05 | with_delimiter, delimiter: ' ', separator: ','}} -> 12 345 678,05
{{'123a' | with_delimiter}} -> 123a
Format des nombres avancé
Formatter un nombre de façon très spécifique est possible grâce au filtre format :
{{5 | format: "%05d"}} -> 00005
{{5 | format: "%08.3f"}} -> 0005.000
{{5 | format: "%.2f"}} -> 5.00
{{5.1234 | format: "%.2f"}} -> 5.12
Vous pouvez en apprendre plus sur les formats possibles dans la documentation de format en Ruby (EN).
PDFMonkey