SupportPal Docs

Templates

SupportPal makes use of the Twig template system. 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.

Contents

Twig

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

Customising Templates

SupportPal ships with a default set of templates:

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 for more information.
  2. Define a view hook 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 documentation.

Method 2: Using Version Control

If you're familiar with Git, we've made our templates available on Github (frontend-template and 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 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) 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 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.


    <?php

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