IORI-ST

IORI-ST

a-blog cmsの初心者ハンズオンをもっと噛み砕いて説明してみる②

a-blog cmsのデベロッパーサイトに記載の初心者向けのハンズオン記事「静的HTMLサイトからCMSのテーマを作ってみよう（Ver.2.8）」を噛み砕いて自分なりに説明してみるシリーズ第2段です。

前回までの記事

a-blog cmsの初心者ハンズオンをもっと噛み砕いて説明してみる①

目的

前回の第1弾では「sample」のテーマ設定まで行いました。続いて、第2弾の目的は3つです。

  1. インクルード機能でファイルをまとめる

    -インクルード機能とは

    -インクルード機能を実践する

  2. ナビゲーションをブラウザから変更できるようにする

    -1. ナビゲーションのスニペットをコピー＆ペーストする

    -2. ナビゲーションのスニペットにモジュールIDを設定する

    -3. 既存のコードをモジュール化する

  3. テンプレートファイルの名前を変更する

    -ファイル名とのナビゲーションモジュールのURLを書き換える

    -コンフィグのテーマ設定を変更する

1. インクルード機能でファイルをまとめる

インクルード機能とは

インクルード機能とは、それぞれのファイルに含まれている共通のパーツごとにファイルを分割してコードを簡潔にすることです。文章で説明しても伝わらないと思うので、ここはキャプチャ画像で見ていきます。

一度ログアウトした状態で、現在のinde.html・list.html・entry.htmlの表示画面を並べてみました。見比べてみると、主にヘッダーやフッター、ナビゲーションなど、共通のパーツがいくつか見つかります。

index.html

index.html

list.html

list.html

entry.html

entry.html

そしてそれぞれのHTML内には、それなりにボリュームのあるコード量でヘッダー・フッター・ナビゲーションなどの情報が書かれています。

index.html list.html entry.html

これらの共通しているコード部分をパーツとして管理し、配置したい時にいつでも引用できるようにするのがインクルードの機能です。例えるなら円周率3.14…をπに置き換えて計算するような感覚でしょうか。

index.html list.html entry.html header.html

この機能を使うことでheader部分の何行かに渡るコードがそれぞれのファイルで1行にまとまるだけでなく、headerを編集したい時も1つのファイルを編集するだけで全てのページに反映されるようになります。インクルードの作業は必須ではありませんが、作業が効率化されて非常に便利なので是非実践してみてくださいね。

インクルード機能を実践する

例としてheaderをインクルードしてみましょう。ここで踏む手順は2つです。

  1. 新しく「header.html」というファイルを作り、その中にheaderのコードをコピー＆ペーストして保存する
  2. headerを配置したい部分に、「ここでheader.htmlを読み込んで！」という命令を書く

それでは詳しく見ていきましょう。

1. 新しく「header.html」というファイルを作り、その中にheaderのコードをコピー＆ペーストして保存する

まず「sample」テーマ内に「include」というフォルダを新規作成します。さらにこの中に、新規作成した「header.html」ファイルを置いておきます。

sample/include/header.html

sample/include/header.html

次にindex.htmlを開き、ヘッダーに関するコードである<header>〜</header>間をコピーして、先ほど作った「header.html」内にペーストします。「header.html」を保存したら、index.html内のheaderのコードは削除してしまいましょう。

index.html内のheaderコード

index.html内のheaderコード

2. headerを配置したい部分に「ここでheader.htmlを読み込んで！」という命令を書く

この命令はa-blog cmsでは以下のように書かれます。

@include("/include/header.html")

元々<header>が書かれていたちょうど上にインクルード機能がすでに埋め込まれているので、慣れるまではこのコードをコピー＆ペーストして書き変えればOKです。

@include("/include/header.html")

これでインクルードの作業は完了です！該当サイトの要素の検証に「Start of include :」から始まるコードが追加されている事からも、しっかりとインクルードがされていることが確認できます。

サイトの検証画面

この作業をindex.htmlだけでなくlist.htmlやentry.htmlでも同様に行います。またヘッダーだけでなくフッターや<head>タグ部分など、共通化できそうなパーツは可能な限りインクルードをしておきましょう。特にこのハンズオンでは

  • ヘッダー
  • フッター
  • headタグ内の共通リンク類
  • サブカラムのエントリーリスト
  • サブカラムのサイト内検索フォーム
  • サブカラムのバナー
  • list.htmlとentry.htmlのカテゴリータイトル
  • list.htmlとentry.htmlのトピックパス
  • list.htmlとentry.htmlのサブカラム

をインクルードしておくと、のちの作業が楽になりますよ。

2. ナビゲーションをブラウザから変更できるようにする

インクルードの作業が完了したら、次はナビゲーションをブラウザから変更できるようにしていきましょう。この作業をすることで、「トップ」「一覧」「詳細」以外にもページを増やした際に、簡単にナビゲーションにその項目を追加することができるようになります。

事前準備として、ナビゲーションのコードが記載されているincludeフォルダ内「header.html」をテキストエディタで確認しておきましょう。

header-navコード

<div class="header-nav">から始まるこの部分を、3つの手順で変更していきます。

  1. ナビゲーションのスニペットをコピー＆ペーストする
  2. ナビゲーションのスニペットにモジュールIDを設定する
  3. 既存のコードをモジュール化する

1. ナビゲーションのスニペットをコピー＆ペーストする

スニペットとはa-blog cmsで使われているサンプルコードです。まずはcommand+Kでクイックサーチを開き、ナビゲーションのスニペットを検索します。

クイックサーチでナビゲーションを検索

これをクリックするとスニペットが表示されるので、そのままコピーします。

ナビゲーションのスニペット

コピーしたら先ほどのheader.htmlファイルに戻り、既存のナビゲーションコードの付近にペーストします。この場所については双方のコードが見比べられる位置ならどこでも構いません。

ペースト完了後のコード

スニペットを観察してみると、冒頭には「BEGIN_MODULE Navigation（＝ナビゲーションモジュールの始まり）」と記載されていることがわかります。このようにa-blog cmsではWebサイトのそれぞれのページについて、ブラウザ上で更新できる部分を「モジュール」と呼んでいます。

ここからはこのナビゲーションのスニペットを参考に、画面上の既存のコードをモジュール化していきます。その前にまずはサンプルコードであるスニペットをサイトに表示させてみましょう。

2. ナビゲーションのスニペットにモジュールIDを設定する

モジュールIDとは、「何件表示するか」「何を表示するか」などといった「表示に関わる設定」を管理するものです。それぞれのモジュールはこのモジュールIDが設定されることにより作動し、さらにIDに付随している「表示に関わる設定」を受け取ることができます。

設定は管理画面から行います。まずはメニューより「モジュールID」を開き、初期設定されたモジュールIDの一覧を確認しましょう。

今回はその中から「global_navi」を使っていきます。画面右の「設定」ボタンを開き、「表示設定」内で初期設定の項目を非表示に変更したのちに、sampleテーマのサイト3つのページ「トップ」「一覧」「詳細」についてラベルとURLを設定しましょう。

モジュールIDの表示設定画面

この際、属性の部分に「class="js-link_match_location"」と表記すると、表示されているページに赤い線がつくスタイルを設定できます。この部分はa-blog cms が標準で用意している JavaScript を使用しているので、詳しくは公式デベロッパーズサイトの現在位置によって異なるクラスを付与する ( link match location ) をご参照ください。

最後にこの表示設定をモジュールに受け渡します。「header.html」で先ほどコピー＆ペーストしたスニペットの冒頭に、以下のようにモジュールIDを追記しましょう。ちなみにモジュールIDの最後の「"」後にはスペースが要ります。（私はこのことが原因で何時間も先に進めなかったことが…。）

<!-- BEGIN_MODULE Navigation id="global_navi" -->

これでモジュールIDの設定は完了です。サイトに戻ると、既存のナビゲーションの下にナビゲーションモジュールのサンプルが表示されるのが確認できます。

ナビゲーションモジュールのサンプル

3. 既存のコードをモジュール化する

いよいよここから既存のコードをモジュール化していきます。作業として複雑な点も多々ありますが、ここで意識することは簡潔に「既存のコードの構造とスタイルのかかったクラス名を維持」しながら「スニペットの構造を組み込んでいく」ことのみです。

まずは「ここからここまで書き換える」というマークの意味もかねて、既存のコードの冒頭<div class="header-nav">の直前に<!-- BEGIN_MODULE Navigation id="global_navi" -->を、</div>直後に<!-- END_MODULE Navigation -->をスニペットからコピー＆ペーストします。

<!-- BEGIN_MODULE Navigation id="global_navi" -->
   <div class="header-nav">
      <div class="acms-grid">
        <nav class="navbar">
           <ul>
              <li class="stay"><a href="index.html">ホーム</a></li>
              <li><a href="list.html">一覧</a></li>
              <li><a href="entry.html">詳細</a></li>
            </ul>
        </nav>
     </div>
   </div>
<!-- END_MODULE Navigation -->

さらにスニペットには<div>タグの直後に@include("/admin/module/setting.html")と設定に関わるファイルがインクルードされていることがみて取れるので、こちらもコピー＆ペーストして<div class="header-nav">の直後に書き加えましょう。

<!-- BEGIN_MODULE Navigation id="global_navi" -->
   <div class="header-nav">
      @include("/admin/module/setting.html")
      <div class="acms-grid">
        <nav class="navbar">
           <ul>
              <li class="stay"><a href="index.html">ホーム</a></li>
              <li><a href="list.html">一覧</a></li>
              <li><a href="entry.html">詳細</a></li>
            </ul>
        </nav>
     </div>
   </div>
<!-- END_MODULE Navigation -->

次に、双方のコードの<li>タグ内に注目してみましょう。既存のコードではテキストで「ホーム」「一覧」「詳細」とテキストによって静的に定義されていますが、この部分はブラウザ上で管理・編集するにあたって変数に置き換える必要があります。さらに「ホーム」にかかっているclass="stay"も動的に処理させたい部分であり、残すべき「スタイルのかかったクラス名」には該当しません。したがってこの<li>タグを含む<ul>タグ内は、下のようにスニペットからそのまま置換できます。

<!-- BEGIN_MODULE Navigation id="global_navi" -->
  <div class="header-nav">
    @include("/admin/module/setting.html")
    <div class="acms-grid">
      <nav class="navbar">
        <!-- BEGIN ul#front --><ul><!-- END ul#front -->
            <!-- BEGIN li#front --><li {attr} class="c_{level}" ><!-- END li#front -->
                <!-- BEGIN link#front --><a href="{url}" target="{target}"><!-- END link#front -->
                <!-- BEGIN label:veil -->{label}[raw]<!-- END label:veil -->
                <!-- BEGIN link#rear --></a><!-- END link#rear -->
            <!-- BEGIN li#rear --></li><!-- END li#rear -->
         <!-- BEGIN ul#rear --></ul><!-- END ul#rear -->
      </nav>
    </div>
   </div>
<!-- END_MODULE Navigation -->

これで<ul>タグ内の処理が完了しました。しかしこのままだと表示される<li>の項目が1つのみになってしまいます。この部分はモジュールIDで設定する「表示件数」に基づき、必要な分だけ<li>タグを複製しなければいけません。ここで、最後に<ul>の直前に「繰り返す命令」である<!-- BEGIN navigation:loop -->を、直後には<!-- END navigation:loop -->を追記しましょう。

<!-- BEGIN_MODULE Navigation id="global_navi" -->
  <div class="header-nav">
    @include("/admin/module/setting.html")
    <div class="acms-grid">
      <nav class="navbar">
        <!-- BEGIN navigation:loop -->
        <!-- BEGIN ul#front --><ul><!-- END ul#front -->
            <!-- BEGIN li#front --><li {attr} class="c_{level}" ><!-- END li#front -->
                <!-- BEGIN link#front --><a href="{url}" target="{target}"><!-- END link#front -->
                <!-- BEGIN label:veil -->{label}[raw]<!-- END label:veil -->
                <!-- BEGIN link#rear --></a><!-- END link#rear -->
            <!-- BEGIN li#rear --></li><!-- END li#rear -->
         <!-- BEGIN ul#rear --></ul><!-- END ul#rear -->
         <!-- END navigation:loop -->
      </nav>
    </div>
   </div>
<!-- END_MODULE Navigation -->

以上でナビゲーションのモジュール化は完了です。サイトで該当部分を確認してみましょう。ナビゲーションをhoverすると、右上に「モジュール」というボタンが表示されました。こちらから書き換えたものがページに反映されたら成功です。

また参考にしていたスニペット部分は不要になるので、最後に削除しておきましょう。

3. テンプレートファイルの名前を変更する

現在のサイトではトップページにindex.html、一覧ページにlist.html、詳細ページにentry.htmlが表示されています。ここでは、これらのファイル名を下の表のように、a-blog cmsで一般的に使われる形へ変更していきます。

トップページ：_top.html
一覧ページ：index.html
詳細ページ：entry.html

ここで、何故「_top.html」だけ先頭に「 _ 」がつくの？と疑問に思った方もいらっしゃると思います。これは、同じ表示のページが複数存在してしまう問題を回避するための設定です。

例えばサイトトップのテンプレートを「top.html」と名付けると、2つのURL「https://example.com/」と「https://example.com/top.html」で同じテンプレートが表示されてしまいます。しかし通常トップページは「https://example.com/」のみで表示されるのが適切です。

a-blog cmsではファイル名に「 _ 」を付けることでファイル名が直接URLに反映しないように設定することができます。つまりサイトトップのテンプレートを「_top.html」と名付けることで、URLは「https://example.com/」のみになり、「https://example.com/top.html」や「https://example.com/_top.html」でアクセスしようとしてもアクセスできない仕組みにすること可能です。

そしてここからは、この変更に伴って、ナビゲーションモジュールのURLの書き換えやコンフィグの再設定をしていきます。

ファイル名とのナビゲーションモジュールのURLを書き換える

まずはそれぞれのファイル名を変更します。

  • 「top.html」→「_top.html」
  • 「list.html」→「index.html」
  • 「entry.html」→「 entry.html」

加えてナビゲーションモジュールから、「一覧」「詳細」ラベルのURLも変更しておきましょう。「トップ」のURLは「%{HOME_URL}#top」のままで大丈夫です。

コンフィグのテーマ設定を変更する

コンフィグのテーマ設定とは、前回記事「a-blog cmsの初心者ハンズオンをもっと噛み砕いて説明してみる①」内「4.「sample」テーマを設定する」で行った各テンプレートファイルの定義づけのことです。下の図の①でテーマの設定、②でテンプレート選択ファイルの設定、③でテンプレートファイルの設定ができました。

コンフィグのテーマ設定

以前はこの画面の③よりテンプレートファイルの名前を入力していきましたが、ここからは②のテンプレート選択ファイルを使った設定方法にシフトしていきましょう。

テンプレート選択ファイル（template.yaml）とは

テンプレート選択ファイル（template.yaml）とは、③で行っているテンプレートファイルの設定を定義づけしたテーマ内ファイルのことです。「beginner2018」や「site2018」など、a-blog cmsインストール時に用意されているテーマの多くには初めから組み込まれています。一度休憩がてら、FTPソフトで「beginner2018」を開いてみましょう。

テンプレート選択ファイル

テンプレート選択ファイル（template.yaml）がありましたね。さらにこのファイルをテキストエディタで開いてみると、以下のようなコードが確認できます。

tpl_top         : _top.html
tpl_index       : index.html
tpl_detail      : _entry.html
tpl_404         : 404.html
tpl_admin       : admin.html
tpl_entry_edit  : entry.html
tpl_entry_add   : entry.html
tpl_login       : login.html

「beginner2018」はこのコードによって、トップページには_top.htmlを、一覧ページにはindex.htmlを…というように定義づけされています。つまり今回作成中のテーマ「sample」でもテンプレート選択ファイル（template.yaml）を用意することによって、今後テーマを変更した際にコンフィグのテーマ設定を書き換えなくても自動でそのテーマに合ったテンプレートの設定が行われるようになります。

テンプレート選択ファイル（template.yaml）の設定方法

sampleフォルダ内でtemplate.yamlというファイルを新規作成し、その中に以下のコードをコピー＆ペーストして保存します。

tpl_top         : _top.html
tpl_index       : index.html
tpl_detail      : entry.html
tpl_404         : 404.html
tpl_admin       : admin.html
tpl_entry_edit  : _entry.html
tpl_entry_add   : _entry.html
tpl_login       : login.html
sample/template.yaml

sample内にtemplate.yamlを用意しました

最後はコンフィグのテーマ設定から「テンプレート選択ファイル（template.yaml）の値を優先する」にチェックをうち、このファイルの情報をa-blog cmsに伝えるようにします。

手入力で設定することによるミスが回避できるので、今後もテーマ作成の際はぜひテンプレート選択ファイル（template.yaml）を活用してみてください。以上でテンプレートファイルの名前を変更が完了しました。

まとめ

いかがでしたか？

私自身も初めてのモジュール化に苦戦した経験があるので、それを生かして記事を書けたら思ったのですが…文章で説明するのは本当に難しいですね。同じ思いをしている方がいらっしゃったらぜひ口頭で説明させてください。

そんな訳で、秋にはa-blog cms Training Camp 2018 TOKYOが開催されます。私も急ピッチで勉強して参りますので、またよろしくお願いします！

Related Posts

この記事に関連するエントリーは見つかりませんでした。

Tags