Upgrading from Templating API v3

Upgrading from Templating API v3

Version 4 of the Templating API is focused on providing a better foundation for customization and more accessible Guide help centers.

Read about the Templating API versions and how to upgrade in About Guide templating in Zendesk help.

This page summarizes what's changed from Templating API v3 to Templating API v4.

If you're upgrading from Templating API v1 or v2, consider also the changes listed in Upgrading from Templating API v1 and in Upgrading from Templating API v2.

The main changes are the removal of the {{request_form}} and {{follow_up}} helpers from the New Request page template. These helpers were outputting a fixed HTML template with a limited customization scope. In Templating API v4, you have access to the {{new_request_form}} object that contains the data needed to create a customized form in your theme.

The default implementation in the Copenhagen theme is built using React and Garden components and is fully accessible. You can use this implementation in your theme if you want the default experience and the accessibility improvements, or you can build your own form if you want to customize the experience further or use different libraries.

New object properties/helpers

{{json}}

The json helper makes it easier to use objects in JavaScript.

{{new_request_form}}

The new request form object has been added to the New Request page. Use this object to create a customized form in your template.

{{answer_bot}}

The answer_bot object has been added to the New Request page. Use this object to display articles suggested by the AI Agent autoreplies with articles in your template.

Updated object properties/helpers

{{categories}}

The articles, articles_count, and more_articles properties have been removed from the sections in the categories object in the Home page template. We've also introduced a limit of 5 sections (if there is more than one category) and 5 child-sections to optimize performance.

{{sections}}

We've introduced a limit of 5 child-sections and 5 articles in each child-section in the sections object in the Category page template.

article object

When the article object is used outside the Article page, the body and vote properties are removed and a new snippet property containing an excerpt of the article content is added.

Removed object properties/helpers

{{request_form}}

The {{request_form}} helper has been removed from the New Request page. Use the new request form object for creating a customized form in your template.

{{follow_up}}

The {{follow_up}} helper has been removed from the New Request page. Use the parent object for creating a link to the parent request.

Upgrading a theme to Templating API v4

With the upgrade to Templating API v4, several modifications were made to the request form page and other template pages. These changes mean that custom themes created in earlier versions are now incompatible with API v4. To address this, you can use the Copenhagen theme, which is v4-compatible, to adapt and update your custom themes, ensuring they work with the new version.

This section details the steps required to upgrade your custom theme to Templating API v4 and incorporate the Request Form implementation from the latest Copenhagen theme. The following instructions assume an upgrade from Templating API v3 to v4. If you are using a version prior to v3, additional steps may be needed. For more information see Upgrading from Templating API v1, Upgrading from Templating API v2 and Updating the standard request form implementation.

1. Download and unzip your custom theme ZIP file. See Importing and downloading your theme and manifest file.

2. Edit your custom theme manifest.json file and update api_version to 4.

3. Download and unzip the Copenhagen theme ZIP file.

4. Copy the contents of the Copenhagen assets folder into your custom theme assets folder.

5. In your custom theme folder, edit the templates/new_request_page.hbs file.

   a. Remove the following lines:

   <span class="follow-up-hint"> {{follow_up}} </span>

   b. Replace {{request_form}} with <div id="new-request-form"></div>

   c. Open the templates/new_request_page.hbs file in the extracted Copenhagen theme folder and copy the <script type="module"> block. Then paste this block to the end of your custom theme’s new_request_page.hbs file.

6. Open the templates/document_head.hbs file in the Copenhagen theme folder and copy the polyfill block (starting with <script type="text/javascript">), the <script type="importmap"> block, and the <script type="module"> block. Then paste them to the end of your custom theme templates/document_head.hbs file:

   <script type="text/javascript">
     // Load ES module polyfill only for browsers that don't support ES modules
     if (!(HTMLScriptElement.supports && HTMLScriptElement.supports('importmap'))) {
        document.write('<script async src="{{asset 'es-module-shims.js'}}"><\/script>');
     }
   </script>
   <script type="importmap">
   {
     "imports": {
         ...
     }
   }
   </script>
   <script type="module">
     import { renderFlashNotifications } from "flash-notifications";
        ...
   </script>

7. Remove any references to articles, articles_count or more_articles in your custom template home_page.hbs file. If these references do not exist, no change is needed.

8. Create a ZIP file containing your updated theme files and import it into help center as a new theme. See Importing and downloading your theme and manifest file.

If the New Request Form code was not customized, updating the form involves replacing old JavaScript assets and modifying certain .hbs files, which are included in the latest version of the Copenhagen theme. For this process, follow steps 4, 5c, and 6 above.

Updating your request form implementation

If you created a custom theme using the Standard Request Form implementation from an older version of the Copenhagen theme, you'll need to re-apply these customizations to the new version by doing one of the following:

• If the Theme Editor was used to create the customizations, install the latest version of the Copenhagen theme and integrate the previous customizations into this new version.

• If an external code editor was used, rebase the custom code on top of the latest version of the Copenhagen theme.