# Merge Fields Merge fields are a great way for you to personalise messages sent to the end-user. For example, you may wish to address each user by name when sending a group e-mail or simply save yourself the time when writing a canned response! ## How Does It Work? Merge fields make use of the template engine [Twig](https://twig.symfony.com/doc/templates.html), allowing you to define complex logic when constructing messages that may be sent to the end-user. It is currently possible to use merge fields in the following areas of the help desk: - Canned Responses - E-mail Templates - User Profile -> Send Email - Mass Emails Our e-mails templates are the perfect starting point to see how we've constructed content-rich e-mails. Below is a simple example of how you may define a merge field: ``` Dear {{ user.formatted_name }}, ``` When sent to Joe Bloggs would be replaced by: ``` Dear Joe Bloggs, ``` ## Available Merge Fields To view a list of available merge fields in a given section, click the curly brackets icon in the editor. Below is an example of loading the merge fields while editing an email template. This will open a popup with a full list of available fields, and clicking on the merge field will insert it directly in to the editor. There will usually be a preview or test button which can be used to verify the contents, however note that this usually makes use of test data. ## What's Allowed? For security reasons merge fields are ran inside a sandbox which only permits specific functionality. The allowed functionality has been detailed below: ### Tags Name Example [IF](https://twig.symfony.com/doc/tags/if.html) ``` {% if user.country == 'GB' %} We've sent you a welcome pack in the post. {% endif %} ``` This only shows the text if the user's country is United Kingdom. [ELSE](https://twig.symfony.com/doc/tags/if.html) ``` {% if user.confirmed %} Thank you for confirming you account with us. {% else %} You haven't confirmed your account yet. {% endif %} ``` This will show a different line if the user's account is confirmed. [FOR](https://twig.symfony.com/doc/tags/for.html) ```

Your Groups

{{ group.name }}

``` This will list all the user's groups. ### Filters Name Example [join](https://twig.symfony.com/doc/filters/join.html) ``` {{ [1, 2, 3]|join(', ') }} ``` This would return "1, 2, 3" ### Methods Object Method Example [Collection](https://laravel.com/docs/6.x/collections#available-methods) [reverse()](https://laravel.com/docs/6.x/collections#method-reverse) ``` {% for message in ticket.messages.reverse() %} ``` This will reverse all ticket messages so it shows the latest message first. [take()](https://laravel.com/docs/6.x/collections#method-take) ``` {% for message in ticket.messages.take(5) %} ``` This will only take the first 5 ticket messages from the whole collection. ### Properties The application page includes a list of available merge fields, these are the properties that can be accessed and used, all other properties are not allowed. ### Functions Definition Description `formatDate($time, $dateOnly = false)` Convert a unix timestamp to a human readable date/time string based on the system configuration. `route()` Convert a named route into a URL. `get_logo($dark_mode = false)` Get an absolute path or direct URL to the frontend logo image. Set parameter to true to fetch the dark mode logo if one is set. `floor()` Round fractions down to the next lowest integer. `is_gt($x, $y)` Check whether x is greater than y. **Use this instead of `$x > $y`** `is_lt($x, $y)` Check whether x is less than y. **Use this instead of `$x < $y`** ## Extending Functionality Merge fields within SupportPal are governed by a strict security policy; this restricts what is possible and helps to keep your help desk secure. ### New Functions If you would like to make use of a PHP function within merge fields you will first need to define it within the [mail security policy](Mail+Security+Policy). ### New Filters, Tags, Methods and Properties It's possible to add *other* twig functionality to the mail security policy, this includes: filters, tags, methods and properties. There is no need to define these within the twigbridge configuration, simply permit them in the [mail security policy](Mail+Security+Policy).