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.
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
- In Guide, click the Customize design icon (
) in the sidebar. - Click Customize on the theme you want to see.
- Click Edit code.
- Under the theme name, you'll see the templating version number, for example,
Templating API v2.
This version number corresponds to the
api_versionfield 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
- Download your help center theme, see Downloading a help center theme.
- Open the theme package locally and edit the manifest.json file.
- In the manifest.json file, find the
api_versionfield and change the value to 2. - 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.
- 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.
- 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.
18 Comments
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?
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
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?
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.
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
Hi Augusto Silva, have you had a chance to check my question?
thanks!
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.
Luis Almeida
How do I access the HTML of a follow button?
Can't see it under templates
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.
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
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
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.
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...
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.
I tried updating a test copy to v2 and replaced all the depreciated helpers. But now none of the dropdowns work. All items are displayed all the time. I've copied the dropdown code from the copenhagen example but nothing works.
Hey there Andy,
I've created a ticket we can work together in, since I'll need to investigate your account. Normally, we do not assist with custom code within Support, but I would like to see if I can point you in the right direction. I hope members of our community can also jump in with advice here!
Kyle Jones | Technical Support Engineer
Ask our Zendesk Community
Kyle Jones can you please post what you find. You can see above from my colleague Chen we also ran into something similar - copied the copenhagen code, removed the depreciated helpers, but still ran into some of the same formatting issues as Andy.
We ended up not upgrading to V2 and not purchasing the badging options because we couldn't figure it out.
Thanks
Kyle Jones hi!
Any updates on this? We are facing the same issue with drop-downs.
Thanks!
Please sign in to leave a comment.