# Templates

SupportPal makes use of the [Twig template system](https://twig.symfony.com/). Twig is a fast, secure and flexible template engine for PHP. Twig template files use the `.twig` file extension and are stored in the `/resources/templates` directory.

## Twig

Twig is fully documented with a dedicated online book and full API documentation. For more information see: <https://twig.symfony.com/docs>

## Customising Templates

SupportPal ships with a default set of templates:

- `resources/templates/frontend/default`
- `resources/templates/operator/default`

  **Unsupported - Periods within directory names**  
 Please ensure your template directory name ("my-new-template" in the example below) does not contain any periods. 

### Method 1: Using Plugins

 For small template changes we highly recommend to investigate whether it's possible to use our plugin eco system. This appropriate is more beneficial than the following 2 methods because it means you no longer have to maintain the changes between SupportPal versions.

For example, below we're going to change the default selected Priority on the Submit Ticket page that's visible to users:

1. Create a plugin, see [Getting Started](Plugin+Development+Getting+Started) for more information.
2. Define a [view hook](Plugin+Development+Extending+Templates#ViewHooks) for "frontend.footer" with the following JavaScript: ```
    
    <script type="text/javascript">
        var element = document.getElementById('priority');
        if (element !== null) {
            element.value = 1;
        }
    </script>
    
    ```
3. Above change `1` to the ID of the priority that you want to select.

There are several other use cases that our possible so we encourage you to read through the [Extending Templates](Plugin+Development+Extending+Templates) plugin documentation.

### Method 2: Using Version Control

If you're familiar with Git, we've made our templates available on Github ([frontend-template](https://github.com/supportpal/frontend-template) and [operator-template](https://github.com/supportpal/operator-template)), allowing you to have your own fork and build your templates in a way that can be tracked and automatically updated when new versions of SupportPal are released.

1. Visit the relevant repository at Github (linked above), login and click the 'Fork' button near the top right. This will set up a fork of the repository in your account.
2. Next clone the repository to your computer, you can find the clone link by clicking the 'Clone or download' button. For example for the frontend-template: ```
    
                $ git clone https://github.com/username/frontend-template.git
            
    ```
3. You can now begin to make your changes, and can also commit them to your fork.
4. When ready to deploy, login to your server via FTP or control panel.
5. Browse to your SupportPal installation directory, and create a new template directory in `resources/templates/frontend` for example: `resources/templates/frontend/custom_template` where `custom_template` is the name of the new directory.
6. Upload all files from the repository to `resources/templates/frontend/custom_template` on your server.

#### Maintaining Changes

When a new version of SupportPal is released, our resources repository is updated and those changes should be merged in to your own repository and any conflicts dealt with. Check Github's [syncing a fork](https://help.github.com/articles/syncing-a-fork/) guide for more information on how to do this.

### Method 3: Manually Copying and Editing

Alternatively if you aren't familiar with Git, you can simply copy and edit the template manually. Copy the default template to a new folder with the name of your choice.

#### Maintaining Changes

When a new version of SupportPal is released, we add a list of resource changes ([example](2.1.2#ResourceChanges)) to the release notes showing a diff of what has changed between releases. These changes should be copied in to your template to ensure it remains fully functional.

### Keep Default Assets

When working on your template, we recommend to keep the asset files (files under the `resources/assets/` folder) the same, and instead create your own CSS or JS files that are loaded separately, making it easier to work with changes to assets files between releases.

### Preview and Activate New Template

1. To preview the new template, use the 'template' parameter in URLs, such as https://www.yourdomain.com/support/admin/?template=my-new-template
2. To activate the new template: 
    1. Go to **Settings -> Core -> Brands** and select the brand you wish to set it for.
    2. Click the "Website" tab.
    3. Change the Frontend or Operator Template to your new template.
    4. Click Save.
3. If you're updating the operator template, you may need to also update your [Manage Operators](Managing+Operators) section.

## Helpers

We've made some of our helper functions available for use in templates, below are a few that you might find useful in your template changes.

#### Purifying HTML

If you need to display any user submitted content, it is best to purify the HTML to remove the risk of XSS. This can be done with the `Purifier.clean` method.

```
{{ Purifier.clean(html_content) }}
```

#### Displaying raw HTML

Twig will automatically escape any HTML within a Twig tag. To stop this and display the code as it is, use the `raw` filter. Be careful to only do this on safe HTML that doesn't contain user submitted content.

```
{{ html_content|raw }}
```

#### asset\_rev

Creates a versioned URL for assets, so users download fresh assets on software updates.

```

    <link href="{{ asset_rev('resources/assets/operator/css/main.css') }}" rel="stylesheet" type="text/css" />

```

#### auth\_check

Checks if the user is logged in, works for both frontend and operator panel.

```

    {% if auth_check() %}

```

#### auth\_user

Fetches the authenticated user (or operator). Returns `null` if the user is not logged in.

```

    {{ auth_user().formatted_name }}

```

#### formatDate

Returns a formatted date for a timestamp based on the settings in the help desk.

```

    {{ formatDate(item.created_at) }}

```

#### timeago

Returns a relative date for a timestamp, such as '2 days ago'.

```

    {{ timeago(ticket.created_at) }}

```

## Adding PHP Functions

 By default, our system restricts the use of PHP functions in templates to a predefined set for security. However, you can extend this functionality by explicitly enabling additional functions. In the following example, we illustrate the process of adding the `count` and `substr` functions to the list of permissible functions:

1. Create the `config/production/twigbridge.php` file in your installation directory. If you're using Docker, refer to [updating config files](Deploy+on+Docker#updating-supportpal-config-files) for guidance.
2. Add the following contents to the file: ```
    
    <?php
    
    return [
        'extensions' => [
            'functions' => \App\Modules\Core\Controllers\Templates\Config\Twigbridge::functions()
                ->add('count')
                ->add('substr')
                ->toArray(),
        ],
    ];
    
    ```