From 5736816b2bdf7369b190ba17a53c43ea8937765f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20B=C3=B6hmer?= <mail@jan-boehmer.de>
Date: Wed, 6 Mar 2024 21:22:47 +0100
Subject: [PATCH] Document on how to use the placeholder function and
 placeholder twig filter in label twig mode

Related with #546
---
 docs/usage/labels.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/usage/labels.md b/docs/usage/labels.md
index 65473ad6..701a3c54 100644
--- a/docs/usage/labels.md
+++ b/docs/usage/labels.md
@@ -102,6 +102,31 @@ or `{% raw %}{{ variable.property }}{% endraw %}`):
 | `{% raw %}{{ paper_width }}{% endraw %}`   | The width of the label paper in mm                                                   |
 | `{% raw %}{{ paper_height }}{% endraw %}`  | The height of the label paper in mm                                                  |
 
+### Use the placeholders in twig mode
+
+You can use the placeholders described above in the twig mode on `element` using the `{% raw %}{{ placeholder('PLACEHOLDER', element) }}{% endraw %}`
+function or the ``{{ "[[PLACEHOLDER]]"|placeholders(element) }}`` filter:
+
+```twig
+{% raw %}
+{# The function can be used to get the a single placeholder value of an element, if the placeholder does not exist, null is returned #}
+{{ placeholder('[[NAME]]', element) }}
+
+{# The filter can be used to replace all placeholders in a string with the values of the element #}
+{{ "[[NAME]]: [[DESCRIPTION]]"|placeholders(element) }}
+
+{# Using the apply environment every placeholder in the apply block will be replaced automatically #}
+{% apply placeholders(element) %}
+    [[NAME]]: [[DESCRIPTION]]
+{% endapply %}
+
+{# If the block contains HTML use placeholders(element)|raw to prevent escaping of the HTML #}
+{% apply placeholders(element)|raw %}
+    <b>[[NAME]]</b>: [[DESCRIPTION]]
+{% endapply %}
+
+{% endraw %}
+```
 
 ## Use custom fonts for PDF labels