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

About Guide templating versions

Jennifer Rowe
  • Edited
Zendesk Documentation Team

What's my plan?

Suite Growth, Professional, Enterprise, and Enterprise Plusprofessional 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

11 Comments

  • Andy Diehl

    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.

    0
  • Kyle Jones
    Zendesk Customer Care

    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

    0
  • Rona Yang

    @... 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

    0
  • Roman Hladkyy

    @... hi!

    Any updates on this? We are facing the same issue with drop-downs.

    Thanks!

    0
  • Toni Wowtscherk

    Kyle Jones any new leads on that? We faced the same problems and it seems like it's an Java Script issue. But couldn't figure out what exactly it might be. 

    0
  • Dion
    Zendesk Customer Care
    Hello Toni,

    I suggest that you contact our support team and provide more details about your issue. Please be advised that we do not provide support for custom codes or custom templates as this should be directed to your developers but we will try to see if we can provide some information on your issue. 

    Regards,

    Dion
    0
  • Rosa Lopez

    Hi, I was wondering if any of you have managed to solve this problem, as I have the same one and I can't get the dropdowns to work.

    Thanks.

    1
  • Dainne Lucena
    Zendesk Customer Care

    Hi Rosa Lopez,

    I went ahead & created a ticket on your behalf so we can work on the theme to see why the drop-down doesn't work. Please keep an eye out for our email!

    0
  • Michaela Vlckova
    • Edited

    Hi there, for all that have "dropdown" issues:
    it can be fixed by adding whole dropdown section in script.js from original Copenhagen theme + adding a css rules to style dropdown and hide/show them based on aria-expanded attributes: 

    [aria-expanded=true] {
      display: block;
    }
    [aria-expanded=false] {
      display: none;
    }

    JS snippet:

      // Dropdowns
      
      function Dropdown(toggle, menu) {
        this.toggle = toggle;
        this.menu = menu;

        this.menuPlacement = {
          top: menu.classList.contains("dropdown-menu-top"),
          end: menu.classList.contains("dropdown-menu-end")
        };

        this.toggle.addEventListener("click", this.clickHandler.bind(this));
        this.toggle.addEventListener("keydown", this.toggleKeyHandler.bind(this));
        this.menu.addEventListener("keydown", this.menuKeyHandler.bind(this));
      }

      Dropdown.prototype = {

        get isExpanded() {
          return this.menu.getAttribute("aria-expanded") === "true";
        },

        get menuItems() {
          return Array.prototype.slice.call(this.menu.querySelectorAll("[role='menuitem']"));
        },

        dismiss: function() {
          if (!this.isExpanded) return;

          this.menu.setAttribute("aria-expanded", false);
          this.menu.classList.remove("dropdown-menu-end", "dropdown-menu-top");
        },

        open: function() {
          if (this.isExpanded) return;

          this.menu.setAttribute("aria-expanded", true);
          this.handleOverflow();
        },

        handleOverflow: function() {
          var rect = this.menu.getBoundingClientRect();

          var overflow = {
            right: rect.left < 0 || rect.left + rect.width > window.innerWidth,
            bottom: rect.top < 0 || rect.top + rect.height > window.innerHeight
          };

          if (overflow.right || this.menuPlacement.end) {
            this.menu.classList.add("dropdown-menu-end");
          }

          if (overflow.bottom || this.menuPlacement.top) {
            this.menu.classList.add("dropdown-menu-top");
          }

          if (this.menu.getBoundingClientRect().top < 0) {
            this.menu.classList.remove("dropdown-menu-top")
          }
        },

        focusNextMenuItem: function(currentItem) {
          if (!this.menuItems.length) return;

          var currentIndex = this.menuItems.indexOf(currentItem);
          var nextIndex = currentIndex === this.menuItems.length - 1 || currentIndex < 0 ? 0 : currentIndex + 1;

          this.menuItems[nextIndex].focus();
        },

        focusPreviousMenuItem: function(currentItem) {
          if (!this.menuItems.length) return;

          var currentIndex = this.menuItems.indexOf(currentItem);
          var previousIndex = currentIndex <= 0 ? this.menuItems.length - 1 : currentIndex - 1;

          this.menuItems[previousIndex].focus();
        },

        clickHandler: function() {
          if (this.isExpanded) {
            this.dismiss();
          } else {
            this.open();
          }
        },

        toggleKeyHandler: function(e) {
          switch (e.keyCode) {
            case ENTER:
            case SPACE:
            case DOWN:
              e.preventDefault();
              this.open();
              this.focusNextMenuItem();
              break;
            case UP:
              e.preventDefault();
              this.open();
              this.focusPreviousMenuItem();
              break;
            case ESCAPE:
              this.dismiss();
              this.toggle.focus();
              break;
          }
        },

        menuKeyHandler: function(e) {
          var firstItem = this.menuItems[0];
          var lastItem = this.menuItems[this.menuItems.length - 1];
          var currentElement = e.target;

          switch (e.keyCode) {
            case ESCAPE:
              this.dismiss();
              this.toggle.focus();
              break;
            case DOWN:
              e.preventDefault();
              this.focusNextMenuItem(currentElement);
              break;
            case UP:
              e.preventDefault();
              this.focusPreviousMenuItem(currentElement);
              break;
            case TAB:
              if (e.shiftKey) {
                if (currentElement === firstItem) {
                  this.dismiss();
                } else {
                  e.preventDefault();
                  this.focusPreviousMenuItem(currentElement);
                }
              } else if (currentElement === lastItem) {
                this.dismiss();
              } else {
                e.preventDefault();
                this.focusNextMenuItem(currentElement);
              }
              break;
            case ENTER:
            case SPACE:
              e.preventDefault();
              currentElement.click();
              break;
          }
        }
      }

      var dropdowns = [];
      var dropdownToggles = Array.prototype.slice.call(document.querySelectorAll(".dropdown-toggle"));

      dropdownToggles.forEach(function(toggle) {
        var menu = toggle.nextElementSibling;
        if (menu && menu.classList.contains("dropdown-menu")) {
          dropdowns.push(new Dropdown(toggle, menu));
        }
      });

      document.addEventListener("click", function(evt) {
        dropdowns.forEach(function(dropdown) {
          if (!dropdown.toggle.contains(evt.target)) {
            dropdown.dismiss();
          }
        });
      });

    (source from https://github.com/zendesk/copenhagen_theme/blob/master/script.js lines 316-482)

    0
  • Toni Wowtscherk

    Thank you Michaela Vlckova! Just copy pasted the JS snippet and replaced it with the dropdown snippet from the template and it works perfectly fine! Awesome! 

    0
  • Mathijs Bok

    I have the latest Copemhagen theme and the Dropdown snippet is already placed there. But even with replacing the snippet I still get no dropdown language menu. Also added the CSS rule, but still no result. Anyone has an idea ?

    0

Please sign in to leave a comment.

Related articles

Powered by Zendesk