You're browsing the documentation for an old version of SupportPal. Consider upgrading to the [latest version](https://docs.supportpal.com/current/Templates). 

# 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`

### 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.

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

### 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 http://www.yourdomain.com/support/admin/?template=my-new-template
2. To activate the new template: 
    1. For frontend templates 
        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 Template to your new template.
        4. Click Save.
    2. For operator panel templates: 
        1. Go to **Settings -> Core -> General Settings**.
        2. Click the "Operator Panel" tab.
        3. Change the Operator Template to your new template.
        4. Click Save.

## 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.

#### 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, we only allow certain PHP functions to be used in the templates. You can add additional functions to the configuration if you'd like to use them in the Twig code, below is an example of adding the count() and substr() functions.

  **Important**  
 When upgrading to a new version of SupportPal please ensure that any new configuration changes are updated in your production copy. If you do not migrate changes, array elements may be overwritten and the policy will be incorrect. 

  Create a new file `twigbridge.php` in the `/config/production` folder instead of updating the `twigbridge.php` found in the main `/config` folder, this will mean your configuration is not lost when you update your system. 

```

    <?php

    return [
        'extensions' => [
            'functions' => [
                'count',
                'substr'
            ],
        ],
    ];

```