Zendesk Guideのテーマファイルをカスタマイズする際に必要になりそうなこと

2021.06.13

今回は、Zendesk Guideのテーマファイルをカスタマイズする際に必要になりそうなことを書いていきたいと思います。

Zendesk Guideの管理画面でも設定可能な項目がございますが、テーマファイル側で制御できるものは、そちらで行う方針で記載しております。

作業環境のセットアップ

編集したテーマファイルを毎回Zendeskにアップロードするのは面倒なので、ローカル環境でプレビューできるようにします。 手順は下記に記載しております。

Zendesk Guideテーマの編集結果をローカルで確認できるようにする

テーマファイルの取得

テーマファイルをイチから作るのではなく、Zendesk Guideの標準テーマであるCopenhagenに対してカスタマイズを行うことが推奨されております。 テーマファイルは下記から取得できます。

https://github.com/zendesk/copenhagen_theme

テーマファイルの構成について

  • templates 以下が各ページのテンプレートファイルになっており、カスタマイズ必要なファイルを編集します。
  • FAQサイトを作成するならば、下記を最低限カスタマイズする必要があります。
    • 記事ページ(article_page.hbs)
    • カテゴリページ(category_page.hbs)
    • エラーページ(error_page.hbs)
    • フッター(footer.hbs)
    • ヘッダー(header.hbs)
    • ホームページ(home_page.hbs)
    • セクションページ(section_page.hbs)
    • 検索結果(search_results.hbs)
  • ユーザーページ、リクエストページ、フォローページなどは、機能を使用するかで変わってきます。コミュニティ関連のページも同様です。

  • CSS(スタイルシート)のカスタマイズは、 styles 以下のファイルを編集するか新たなファイルを追加します。

(注意)ZAT(Zendesk App Tools)はLive SASSコンパイルをサポートしていないとのことです。

Note: Zendesk App Tools theme preview currently does not support live SASS compilation.

manifest.jsonの編集

下記の方法でテーマファイルをZendesk Guideにインポートするために編集しておきます。

GitHubインテグレーションを使用したGuideテーマの設定

冒頭のnameとversionを変えておきます。 versionはテーマファイルを更新してインポートする際に変更します。

{
  "name": "Copenhagen-Custom",
  "author": "Zendesk",
  "version": "1.0.0",

フッターのPowered by Zendeskを表示させない

これのことです。

設定 > Guide設定 > インテグレーションPowered by Zendeskロゴ のチェックを外します。

更新ボタンを押して反映させます。

ホームページのカテゴリを並び替えたい

例えば、このように並んでいるのを

一般 , プリズム , 注文の返品について の並び順にしたい場合は、Zendesk Guideの管理画面で変更いたします。

順番を入れ替えました。

一般 , プリズム , 注文の返品について の並び順に変わりました。

ホームページの検索ボックスにプレースホルダーを設定する

templates/home_page.hbs の下記でハイライトしている行に placeholder="検索ワードを入力してください" みたいにベタ書きしても実現できるのですが、Zendesk Guideは多言語対応しているため、それを意識した方法にします。動的コンテンツという機能を使います。

変更前

<section id="main-content" class="section hero">
  <div class="hero-inner">
    <h2 class="visibility-hidden">{{ t 'search' }}</h2>
    <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" focusable="false" viewBox="0 0 12 12" class="search-icon" aria-hidden="true">
      <circle cx="4.5" cy="4.5" r="4" fill="none" stroke="currentColor"/>
      <path stroke="currentColor" stroke-linecap="round" d="M11 11L7.5 7.5"/>
    </svg>
    {{search submit=false instant=settings.instant_search class='search search-full'}}
  </div>
</section>

変更後

<section id="main-content" class="section hero">
  <div class="hero-inner">
    <h2 class="visibility-hidden">{{ t 'search' }}</h2>
    <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" focusable="false" viewBox="0 0 12 12" class="search-icon" aria-hidden="true">
      <circle cx="4.5" cy="4.5" r="4" fill="none" stroke="currentColor"/>
      <path stroke="currentColor" stroke-linecap="round" d="M11 11L7.5 7.5"/>
    </svg>
    {{search submit=false instant=settings.instant_search class='search search-full' placeholder=(dc "cmys01_hc_search_placeholder")}}
  </div>
</section>

動的コンテンツの設定

Zendesk Supportの 管理 > 動的コンテンツ > 項目を追加 をクリックします。

下記を入力して作成ボタンを押します。

入力項目 説明
動的コンテンツ項目のタイトル 画面テンプレートから参照する値になります。任意の値を設定します。ここでは cmys01_hc_search_placeholder にしました。
デフォルト言語 日本語 にします。
コンテンツ 検索キーワードを入力してください にします。

下記のようになりましたら、登録完了です。

あとはテンプレート内で、 dc "cmys01_hc_search_placeholder" のようにして参照します。

このように表示されます。

ホームページの検索ボックスにタイトルを表示させたい

デフォルトだと、検索ボックスが表示されてます。例えば「ヘルプ記事の検索」といったタイトルをつけるとします。

templates/home_page.hbs の下記でハイライトしている部分を編集するのですが、上記の「ホームページの検索ボックスにプレースホルダーを設定する」と同様に動的コンテンツという機能を使います。 cmys01_hc_search_title というものを登録しました。

変更前

<section id="main-content" class="section hero">
  <div class="hero-inner">
    <h2 class="visibility-hidden">{{ t 'search' }}</h2>
    <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" focusable="false" viewBox="0 0 12 12" class="search-icon" aria-hidden="true">
      <circle cx="4.5" cy="4.5" r="4" fill="none" stroke="currentColor"/>
      <path stroke="currentColor" stroke-linecap="round" d="M11 11L7.5 7.5"/>
    </svg>
    {{search submit=false instant=settings.instant_search class='search search-full'}}
  </div>
</section>

変更後

<section id="main-content" class="section hero">
  <div class="hero-inner">
    <h2 class="">{{ dc "cmys01_hc_search_title" }}</h2>
    <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" focusable="false" viewBox="0 0 12 12" class="search-icon" aria-hidden="true">
      <circle cx="4.5" cy="4.5" r="4" fill="none" stroke="currentColor"/>
      <path stroke="currentColor" stroke-linecap="round" d="M11 11L7.5 7.5"/>
    </svg>
    {{search submit=false instant=settings.instant_search class='search search-full' placeholder=(dc "cmys01_hc_search_placeholder")}}
  </div>
</section>

タイトルを表示できました。

ホームページの最近のアクティビティを表示させない

manifest.json の下記でハイライトしている部分を false にします。

    {
      "label": "home_page_group_label",
      "variables": [
        {
          "identifier": "show_recent_activity",
          "type": "checkbox",
          "description": "recent_activity_description",
          "label": "recent_activity_label",
          "value": false
        }
      ]
    },

ヘッダーのサインインを非表示にしたい

一般公開するFAQの場合などサインインが不要で、これを非表示にしたいことがあります。

templates/header.hbs の下記を削除します。

    {{#if signed_in}}
      <div class="user-info dropdown">
        <button class="dropdown-toggle" aria-haspopup="true">
          {{user_avatar class="user-avatar"}}
          <span class="hide-on-mobile">
            {{user_name}}
            <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" focusable="false" viewBox="0 0 12 12" class="dropdown-chevron-icon" aria-hidden="true">
              <path fill="none" stroke="currentColor" stroke-linecap="round" d="M3 4.5l2.6 2.6c.2.2.5.2.7 0L9 4.5"/>
            </svg>
          </span>
        </button>
        <div class="dropdown-menu" role="menu">
          {{link "my_activities" role="menuitem"}}
          {{my_profile role="menuitem"}}
          {{change_password role="menuitem"}}
          {{link "sign_out" role="menuitem"}}
        </div>
      </div>
    {{else}}
      {{#link "sign_in" class="sign-in"}}
        {{t 'sign_in'}}
      {{/link}}
    {{/if}}

参考までですが、このようにサインインか否かのロジックだけ残す方法もありますが中途半端ですので必要になった時に追加すれば良いと思いました。

    {{#if signed_in}}

    {{else}}

    {{/if}}

ヘッダーのリクエストを送信を非表示にしたい、別のリンク先にしたい

問い合わせ受付をZendesk Supportで実現している場合は、このリンクを活用することになりますが、Zendesk以外で受付している場合はリンクを別のものにしたくなると思います。

非表示にする方法(CSSで非表示にする)

単純に非表示にする方法です。

「リクエストを送信」リンクを非表示にする

styles/_header.scss に下記CSSを追加します。

.submit-a-request {
  display:none;
}

追加したあとにSCSSファイルをコンパイルするのを忘れないでください。

コンパイル手順はこちらを参考にしてください。※ windows環境でbashコマンドをubuntuを入れて動かしている場合は、PowerShellなどを起動したあとに bash コマンドを実行してからブログに記載のコマンドを実行します。

非表示にする方法(タグを物理的に削除する)

templates/header.hbs の下記でハイライトしている部分を削除する。

    <nav class="user-nav" id="user-nav">
      {{link 'community'}}
      {{link 'new_request' class='submit-a-request'}}
    </nav>

リンク先を変更する

リンクを別のものにしたい場合は、templates/header.hbs の下記でハイライトしている部分を直接編集する。

変更前

    <nav class="user-nav" id="user-nav">
      {{link 'community'}}
      {{link 'new_request' class='submit-a-request'}}
    </nav>

変更後

    <nav class="user-nav" id="user-nav">
      {{link 'community'}}
      <a class="submit-a-request" href="https://somedomain/contact/">お問い合わせする</a>
    </nav>

記事にコメントをできないようにしたい

記事に対するコメントの有効・無効の設定

記事のコメントを無効にする方法

記事ごとに記事の設定で コメントを有効 にチェックをつけるとコメントできるようになります。

チェックを外すとコメントを受付しなくなります。

コメントに関する欄を非表示にしたい

コメントに関する表示そのものを出したくない場合です。

manifest.json の下記でハイライトしている部分を false にします。

        {
          "identifier": "show_article_comments",
          "type": "checkbox",
          "description": "article_comments_description",
          "label": "article_comments_label",
          "value": false
        },

記事にある「他にご質問がございましたら、リクエストを送信してください」の文言を変更する

この部分のことです。

この文言は、 templates/article_page.hbs で下記のように出力しております。

        <div class="article-more-questions">
          {{request_callout}}
        </div>

ここで使われているrequest_callout helperは下記を出力しますので、文言を変えるには方法を変える必要があります。

<!-- this is only displayed if user can submit a request -->
Have more questions? <a href="/path_to_new_request/">Submit a request</a>

link_helperを使う方法

templates/header.hbs で使われている リクエストを送信 を表示するlink_helperを使うと、 リクエストを送信 以外は自由に文言を設定できます。

{{link 'new_request' class='submit-a-request'}}

例えば、このようにしてみます。

        <div class="article-more-questions">
          ご不明な点がございましたら、{{link 'new_request' class='submit-a-request'}}してください。
        </div>

page_path helperを使う方法

リクエストを送信 自体を変更したい場合はpage_path helperで下記のようにします。

        <div class="article-more-questions">
          ご不明な点がございましたら、<a href="{{page_path 'new_request'}}">お問い合わせ</a>ください。
        </div>

page_path helperと動的コンテンツを使う方法

動的コンテンツという機能を使う場合は、コンテンツを下記のようにします。

ご不明な点がございましたら、<a href="{{page_path 'new_request'}}">お問い合わせ</a>ください。

テンプレートで呼び出します。

        <div class="article-more-questions">
          {{dc "cmys01_hc_make_request"}}
        </div>

記事の下の欄に追加文言を表示したい場合

このあたりに文言を追加したい場合です。

templates/article_page.hbs<footer> タグの中身を編集します。

例えば <div class="article-more-questions"> の中に追記すると下記イメージのようになります。

        <div class="article-more-questions">
          {{request_callout}}
          <p>コールセンター(050-xxxx-xxxx)でも受付しております。</p>
        </div>

記事の作成者情報を表示させない

デフォルトだと、このように作成者が表示されます。

manifest.json の下記でハイライトしている部分を false にします。

        {
          "identifier": "show_article_author",
          "type": "checkbox",
          "description": "article_author_description",
          "label": "article_author_label",
          "value": false
        },

このように非表示にできます。

フォローをする/フォローを止めるボタンを表示させない

manifest.json の下記でハイライトしている部分を false にします。

        {
          "identifier": "show_follow_article",
          "type": "checkbox",
          "description": "follow_article_description",
          "label": "follow_article_label",
          "value": false
        },

記事の共有ボタンを表示させない

manifest.json の下記でハイライトしている部分を false にします。

        {
          "identifier": "show_article_sharing",
          "type": "checkbox",
          "description": "article_sharing_description",
          "label": "article_sharing_label",
          "value": false
        }

ホームページに「よくある質問」として記事を表示する

templates/home_page.hbs に 記事の設定で 記事を推奨 をつけた記事を表示するタグがあるので、これを利用します。

    {{#if promoted_articles}}
      <section class="articles">
        <h2>{{t 'promoted_articles'}}</h2>
        <ul class="article-list promoted-articles">
          {{#each promoted_articles}}
            <li class="promoted-articles-item">
                <a href="{{url}}">
                  {{title}}

                  {{#if internal}}
                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" focusable="false" viewBox="0 0 16 16" class="icon-lock" title="{{t 'internal'}}">
                      <rect width="12" height="9" x="2" y="7" fill="currentColor" rx="1" ry="1"/>
                      <path fill="none" stroke="currentColor" d="M4.5 7.5V4a3.5 3.5 0 017 0v3.5"/>
                    </svg>
                  {{/if}}
                </a>
            </li>
          {{/each}}
        </ul>
      </section>
    {{/if}}

記事の設定で 記事を推奨 をつけたものが出てきます。

ホームページにカテゴリ、セクション、記事を表示したい

templates/home_page.hbscategories プロパティが参照可能なので、下記のようにカテゴリに紐づくセクションを参照して、セクションに紐づく記事を参照するといったことをしていくことができます。

<div class="knowledge-base">
  <ul>
  {{#each categories}}
    <li class="category-name">
      <h1><a href="{{url}}">{{name}}</a></h1>
      <ul>
      {{#each sections}}
        <li class="section-name">
          <h2><a href="{{url}}">{{name}}</a>({{article_count}}件の記事)</h2>      
          <ul>
            {{#each articles}}
              <li class="article-name">
                <h3><a href="{{url}}">{{title}}</a></h3>
              </li>
            {{/each}}          
          </ul>
          {{#if more_articles}}
          <a href="{{url}}">もっと見る</a>
          {{/if}}             
        </li>
      {{/each}}
      </ul>
    </li>
  {{/each}}
  </ul>
</div>

このように処理できます。

カテゴリページに記事本文の一部を表示させたい

excerptヘルパーを使うことで実現できます。 {{excerpt body characters=50}} のようにして使います。

      <div id="main-content" class="section-tree">
        {{#each sections}}
          <section class="section">
            <h2 class="section-tree-title">
              <a href="{{url}}">{{name}}</a>
            </h2>
            {{#if articles}}
              <ul class="article-list">
                {{#each articles}}
                  <li class="article-list-item{{#if promoted}} article-promoted{{/if}}">
                    {{#if promoted}}
                      <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" focusable="false" viewBox="0 0 12 12" class="icon-star" title="{{t 'promoted'}}">
                        <path fill="currentColor" d="M2.88 11.73c-.19 0-.39-.06-.55-.18a.938.938 0 01-.37-1.01l.8-3L.35 5.57a.938.938 0 01-.3-1.03c.12-.37.45-.63.85-.65L4 3.73 5.12.83c.14-.37.49-.61.88-.61s.74.24.88.6L8 3.73l3.11.17a.946.946 0 01.55 1.68L9.24 7.53l.8 3a.95.95 0 01-1.43 1.04L6 9.88l-2.61 1.69c-.16.1-.34.16-.51.16z"/>
                      </svg>
                    {{/if}}
                    <a href="{{url}}" class="article-list-link">{{title}}</a>
                    <p>{{excerpt body characters=50}}</p>
・・略・・

セクションページに記事本文の一部を表示させたい

excerptヘルパーを使うことで実現できます。 {{excerpt body characters=50}} のようにして使います。

      {{#if section.articles}}
        <ul class="article-list">
          {{#each section.articles}}
            <li class="article-list-item {{#if promoted}} article-promoted{{/if}}">
              {{#if promoted}}
                <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" focusable="false" viewBox="0 0 12 12" class="icon-star" title="{{t 'promoted'}}">
                  <path fill="currentColor" d="M2.88 11.73c-.19 0-.39-.06-.55-.18a.938.938 0 01-.37-1.01l.8-3L.35 5.57a.938.938 0 01-.3-1.03c.12-.37.45-.63.85-.65L4 3.73 5.12.83c.14-.37.49-.61.88-.61s.74.24.88.6L8 3.73l3.11.17a.946.946 0 01.55 1.68L9.24 7.53l.8 3a.95.95 0 01-1.43 1.04L6 9.88l-2.61 1.69c-.16.1-.34.16-.51.16z"/>
                </svg>
              {{/if}}
              <a href="{{url}}" class="article-list-link">{{title}}</a>
              <p>{{excerpt body characters=50}}</p>
・・略・・

ロゴ / ファビコン / 背景画像を変更する

ロゴを変更する

settings/logo.png を差し替えます。

ファビコンを変更する

settings/favicon.png を差し替えます。

ホームページの背景色を変更する

settings/homepage_background_image.png を差し替えます。

このように変更することができます。

ボタン / テキスト / リンクテキスト色などを変更する

manifest.json の下記で変更できます。

    {
      "label": "colors_group_label",
      "variables": [
        {
          "identifier": "brand_color",
          "type": "color",
          "description": "brand_color_description",
          "label": "brand_color_label",
          "value": "#c38ad6"
        },
        {
          "identifier": "brand_text_color",
          "type": "color",
          "description": "brand_text_color_description",
          "label": "brand_text_color_label",
          "value": "#FFFFFF"
        },
        {
          "identifier": "text_color",
          "type": "color",
          "description": "text_color_description",
          "label": "text_color_label",
          "value": "#53585f"
        },
        {
          "identifier": "link_color",
          "type": "color",
          "description": "link_color_description",
          "label": "link_color_label",
          "value": "#f97298"
        },
        {
          "identifier": "visited_link_color",
          "type": "color",
          "description": "visited_link_color_description",
          "label": "visited_link_color_label",
          "value": "#f97298"
        },
        {
          "identifier": "background_color",
          "type": "color",
          "description": "background_color_description",
          "label": "background_color_label",
          "value": "#FFFFFF"
        }
      ]
    },

このように変更することができます。

補足

section objectのsectionsプロパティのように、Zendeskのプランによっては使用できないものがあるため、注意が必要です。

参考情報