English (US)
  1. Zendesk help
  2. Guide
  3. Using Guide
  4. Using themes and customizing your Help Center

About Guide templating versions

Sophie McMonagle
  • Edited

professional enterprise plan

Guide templating renders the Help Center theme packages. This contains the Curlybars templating language that is used in the template files, CSS and JS files, and the manifest file.

Guide templating is also known as the Templating API.

To learn more about Guide themes, see Customizing your Help Center theme and the Help Center Templates developer documentation.

This article covers the following topics:

About Guide templating versions

Templating API V2 was released on February 24, 2020, and this version applies to the Copenhagen theme and any new theme releases.

If you have customized your theme, you can continue to use Templating API V1 and do not need to upgrade to V2 unless you want to take advantage of new features and improved performance. You can check which version of the framework you're using in Guide (see Checking your templating version).

With V2, you can no longer use jQuery statements anywhere in a theme where you could use vanilla JavaScript (such as script.js or document_head.hbs). If you want to use jQuery with V2 you'll need to import the jQuery library.

We've also deprecated some helpers and changed some helpers to output data objects instead of HTML. You can find a full list here.

Checking your templating version

You can see the templating version from the Edit code view in your theme or in the manifest file.

To check the templating version

  1. In Guide, click the Customize design icon () in the sidebar.
  2. Click Customize on the theme you want to see.
  3. Click Edit code.
  4. Under the theme name, you'll see the templating version number, for example, Templating API v2.

    This version number corresponds to the api_version field in the manifest file.

Upgrading from Guide templating version 1 to version 2

If you have customized your Guide theme, you can upgrade to version 2 to take advantage of new features and improved performance.

To upgrade the templating version

  1. Download your Help Center theme (see Downloading a Help Center theme).
  2. Open the theme package locally and edit the manifest.json file.
  3. In the manifest.json file, find the api_version field and change the value to 2.
  4. Preview your theme changes locally. When you preview the theme, you'll get warnings if you are using helpers that have been deprecated in version 2.
  5. If you are using a deprecated helper, use this information to replace the helper with a supported equivalent.

    Preview your theme again to verify that there are no further warnings.

  6. Upload the updated theme to Guide (see importing your Help Center theme).

    You can check that the new version has been applied by checking your templating version.

Return to top
Have more questions? Submit a request

15 Comments

  • Rona Yang

    I'm trying to upgrade my template to V2- I've replaced all of the deprecated helpers, but have the following 3 errors left...  how do I go about fixing this? 

     

     

    0
  • Augusto Silva
    Zendesk team member

    Hi Rona,

    Happy to hear you're upgrading to V2.

    In V2, we have improved validation for helpers resulting in these errors.

    To solve this errors, you need to check if you are using these helpers together with a conditional.

    You shouldn't need to use conditionals with these helpers as they render HTML only when available.

    Hope this helps

    0
  • Rona Yang

    Hi Augusto Silva - do you mean I should just be able to delete this line of code? It was a developer who created a new template for us, so I don't have any background on what they did. How can I check if these helpers are being used with a conditional? 

    0
  • Augusto Silva
    Zendesk team member

    Hi Rona,

    You'll need to remove the {{#if in those lines. You can check the Copenhagen theme template as an example.

    I would also suggest reaching out to the developer to see if there's a new version of the theme using V2 or if they can help you out with the upgrade.

     

    0
  • Chen Arbel

    Hi Augusto Silva, in continue to Rona's question.

    I removed the "if"/"isn't" to resolve the errors, but isn't if affect the theme's logic somehow?

    Additionally, Some CSS is breaking on the new version, are you aware of CSS bugs? I.e 'follow' button on the new version has the SAME CSS as in the old one, but it looks like it doesn't apply.

     

    Thanks! Chen

    0
  • Chen Arbel

    Hi Augusto Silva, have you had a chance to check my question?

    thanks!

    0
  • Luis Almeida

    Hi Rona,

    The helpers already encapsulate that logic so there is no need for the "if", "is" or "isn't" blocks. 

    Regarding the theme CSS, we could not possibly push updates to the stylesheet safely so it is up to the theme customizer to implement the necessary changes.

    0
  • Chen Arbel

    Luis Almeida

    How do I access the HTML of a follow button?

    Can't see it under templates 

    0
  • Luis Almeida

    The follow button (subscribe helper) really is just a button so that's all there is to style. It can be targeted by rendering it inside a div with a class of your choosing:

    <div class="article-subscribe">{{subscribe}}</div>

    And then with CSS:

    .article-subscribe button { /* button styling */ }

     

    The dropdown it renders when there are multiple subscription options is something that should not be targeted with styling as it's an internal piece of UI that might change in the future.

    0
  • Chen Arbel

    Luis Almeida Thanks for the answer but I'm searching for a solution without touching the css. 

    How do I edit the HTML markup of the follow button?

    I have all the hbs files, where I can see markup but not foe the clas you mentioned...

     

    thanks again

    0
  • Chen Arbel

    Luis Almeida

    ill accurate my question - I would like to add an attribute rolr="button" to the following button.

    Since it inherits all css automatically. 

    i can't see under ''subscription_page.gbs" any HTML related to the follow button. how do I find it?

     

    thanks

     

    1
  • Luis Almeida

    The HTML output of the subscribe helper cannot be modified. So the button can no longer be targeted by the role attribute and the easiest way is how I described in my previous comment.

    The subscribe (follow) behaviour is now optimized for accessibility and that's why it is a bit more restrictive in terms of customization.

    0
  • Chen Arbel

    hi Luis Almeida

     

    can you please see Rona's errors again?

    for some of the deprecated helpers, you didn't mention the new ones here: https://developer.zendesk.com/apps/docs/help-center-templates/v1

     

    How can I know with what new helpers they should be replaced?

    I really can't build all the CSS from scratch... 

    0
  • Luis Almeida

    It's a bit hard for me to give more directions at this point without looking into the specific errors.

    Only the deprecated helpers need to be removed from the theme when upgrading. If there are styling issue with the helpers that have changed with improvements for accessibility, those need to be addressed with CSS.

    We recommend looking into the Copenhagen theme source code as guidance when applying these changes.

    0
  • Jeanette Hawkinson

    Is it necessary to upgrade to V2 if using a Custom Theme in order to use JavaScript in articles?  I have been working all day to get a simple JavaScript statement to work, and just found the information regarding V2, but everything keeps referring to the Copenhagen theme V2.

    0

Please sign in to leave a comment.

Related articles

Powered by Zendesk