Templates

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

SupportPro 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 SupportPro 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 SupportPro 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 SupportPro 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 SupportPro 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 SupportPro 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 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 personal settings if you currently have it set to a specific template (not '-- System Default --'). The same can be done for other operators through the Manage 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, 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'
        ],
    ],
];

Article Number: 251
Author: Jul 22, 2024
Last Updated: Jul 22, 2024

Online URL: https://docs.supportpro.vn/article/templates-251.html