9月23日に書いた記事「CMSの管理画面でクラス名を変更できるようにしたことを後悔している」の続きです。

この記事を読んだプログラマの友人に
「モジュールに設定したクラス名一覧を資料化すればいいのではないですか？」
と聞かれました。

当初はこれについても書くつもりでしたが、結論から言うと諸々の問題で難しいのと、ますます記事が長くなるので追記しなかったのでした。

この件について改めて書いてみたいと思います。

モジュールID一覧を作ったことはある

一時期、管理画面で表示されている「モジュールID一覧」のHTMLをPDFに書き出し、資料として納品時にお渡ししていたことがありました。

a-blog cmsは、CMS内の設定（IDがnewsのカテゴリーのエントリーを5件呼び出す）に名前をつけて「モジュールID」として使い回すことができます。DrupalのViewsも同様だったと思います。
これもクラス名と同様、管理画面でしか参照できないものです。なので友人の指摘の通り、資料化しようと考えたのです。

ですが、これには以下のような問題がありました。

予算がつかない

これはウェブ制作全体の問題ですが、「サイトマップ」「マニュアル」以外の資料には、あまり価値を見いだされません。企画を重視していない案件では「カスタマージャーニーマップ」さえ予算がつくのが難しいでしょう。それ以前に私は受注制作がメインなので、予算に関われる案件はまずありません。

もしこちらから「モジュールID一覧もお送りしますね」と言っても、たぶん「いやー、いらないですよ！」と返事が来ます。
なので、できるだけシステム化して、こちらの見積内に組み込むことになります。よほど効率化しないとタダ働きになります。

やっぱり使われない

そうやって頑張って作成しても、サイトの改修自体がないことが多いです。私自身も完全納品だと、その後は声がかからないので使うことはありません。前回の記事のように、常時改修をお手伝いさせてもらっている案件もまれにありますが、全体の一割くらいです。
もしかすると、多くの納品先が、このような資料を必要としていたのかもしれません。しかし何も言われないのでわからないのです。あー、SNSでつながっている方、その後必要だったかこっそり教えて下さい…

サーバーと同期されない

オフラインの資料にしてしまうと、管理画面の内容を更新したときに資料も更新しなければなりません。資料と最新の状態が食い違うのはまずいです。 これは友人も指摘していました。むしろ資料作成を重視するプログラマさんやSIerさんは、こっちを気にすると思います。

管理画面の情報を常に閲覧できればいいのでは

そこで「管理画面に、モジュール関連の必要な情報だけを一覧できるテンプレートを作ればいいのでは？」と考えました。
テーマ内に含むようにできれば、毎回資料を作成する手数もなくなります。

a-blog cmsなら簡単にできるかもしれないと、管理画面にざっと書いてみたテンプレートがこれです。

<!-- BEGIN_MODULE Admin_Module_Index -->
<!-- BEGIN module:loop -->
mid: {mid}<br>
モジュールID: {identifier}<br>
<!-- BEGIN status#open -->
<span class="acms-admin-label acms-admin-label-info admin-status-label acms-admin-text-nowrap"><!--T-->有効<!--/T--></span><!-- END status#open --><!-- BEGIN status#close -->
<span class="acms-admin-label acms-admin-label-danger admin-status-label acms-admin-text-nowrap"><!--T-->無効<!--/T--></span><!-- END status#close -->
<br>
	<!-- BEGIN_MODULE\ Admin_Module_Edit ctx="bid/%{BID}/mid/\{mid\}" -->
	説明: \{description\}<br>
	追加クラス: \{module_exclass\}<br>
	追加属性: \{module_exattr\}<br>
	<!-- END_MODULE\ Admin_Module_Edit -->
<hr>
<!-- END module:loop -->
<!-- END_MODULE Admin_Module_Index -->

Admin_Module_Indexモジュールは、モジュールIDの最低限の情報を一覧表示するモジュールです。
ループ内でエスケープされているAdmin_Module_Editモジュールは、指定したモジュールIDの詳細情報を出力し、GET送信すれば編集可能にするモジュールです。
いずれも管理画面専用です。

• mid
• 識別名
• 有効／無効
• 説明文
• 追加クラス（モジュールのカスタムフィールド）
• 追加属性（モジュールのカスタムフィールド）

ここまで一画面で表示できればかなり便利になると思ったのですが…
残念ながらAdmin_Module_Editに属性値でIDを渡すことができないようで、説明文やクラスは表示できませんでした。何か間違えているのかもしれませんが。

となると、PHPを書いて、データベースへの直接のアクセスが必要になります。さすがにそこまでする必要があるかは微妙です。

リッチCMSに備えないといけない

かつては汎用CMSとは、本格的なエンタープライズCMSではなく、ごくごくシンプルなものでした。
ですが利用者が多いWordPressであっても、納品後にもコーディングに関与できる「リッチCMS」の採用が当たり前になっています。

制作側もこれまでのように作るだけで終わらせず、納品から半年後、一年後の改修で無駄な工数を食わないよう、対策を講じなければならなりません。
消化不良ですがこの話題はまたいつか。

コーディングとCMSのテーマ設計の話です。かなりCMS構築に慣れていないと理解しづらい内容になるので、順を追って説明します。

モジュール型のサイト設計

CMSで運用されるサイトは、トップページや下層ページのサイドバーで、投稿の新着やナビゲーションなどの「モジュール」を埋め込む前提で構築やコーディングをします。
ここでは「モジュール」としていますが、CMSによって名称は異なります。よく知られているのはWordPressの「ウィジェット」です。

コーディングにについては、以前書いた記事「CMSの構築を考慮したコーディングとかクラスの命名規則の話」で詳しく書いていますが、つまりはこの場合、それぞれのモジュール（＝ウィジェット）はクラス名が付与されたdivで包括される前提となります。

例えば、WordPressの人気テーマ「Lightning」のトップページで、新着記事を表示している箇所は以下のようにマークアップされています。

<div class="widget widget_vkexunit_post_list" id="vkexunit_post_list-13">
（新着記事リスト）
</div>

自由モジュールであることを示す「widget」、テーマ専用パーツであることを示す「widget_vkexunit_post_list」のクラスに加え、一意のIDが付与されています。
これによって似たようなモジュールをページに複数配置しても、クラスかIDで区別してCSSスタイルを調整できます。

モジュールのクラス名を自由に決められるようにしてみる

DrupalのBlockやViewsでは、先述した包括divに付与するクラス名を変更できる機能があります。コーダー側のコーディングルールを活かせるので、とても魅力的な機能です。

ヘッダ、フッタのボタン、包括divの属性を変更できるようにした例

このクラス名変更機能を、a-blog cmsのモジュール設定に組み込んだのが、二年ほど前に公開したテーマ「echo_zero」でした。

モジュールの外観のカスタマイズ | はじめての方へ | 解説資料 | echo_zeroデモサイト

このテーマは当時はかなり満足していて、安定したウェブサイトをサクサク構築できるので、いくつかの案件にそのまま採用していました。
…が、二年が経って、一部の案件でこの機能が足を引っ張るようになってしまいました。

クラス名を見つけられない

完全納品ではなく、納品後も改修をお手伝いする案件だと、半年ほど経ってコンテンツが増えてきてから、二段階目の改修を依頼されることがあります。
モジュールの追加やデザイン変更などが発生しますから、コーディングも変わってきます。以前はイベント新着関係のモジュールが一個しかなかったのに、似たようなモジュール（関連イベント・現在位置から近い順）が増えたりします。

半年も経つと、自分の作ったテーマでも細かい構造は忘れています。このクラスは、どのモジュールで使用していたろうかと、テーマをクラス名の一部、例えば「module-event」などで検索してみても…見つかりません。
クラス名はCMS側で管理しているので、ローカル環境のエディタの全文検索ではヒットしないのです。
こうなると、a-blog cmsの管理画面に入って「モジュールID」の一覧から該当のモジュールを探すことになります。かなりの手間です。

CMSで何もかも管理すればいいわけでもない

一般に配布するテーマであれば、クラス名を変更できる機能は非常に便利です。
利用する人の大半は、モジュールごとに細かくCSSを調整したり、コーディングルールにこだわったりすることがないので、メリットの方が大きいでしょう。

ですが、自分がいちからテーマを作成していて、改修も多い場合は、修正すべき箇所をローカル検索できないというのは、毎回の時間のロスは大したことがないものの、けっこうストレスが貯まります。

そんなこんなで最近は、多くの人がやっているように、記事リストを呼び出す箇所を共通のインクルードファイルにして、クラス名や繰り返すコンポーネント名を変数で渡す構築になっています。
以下はa-blog cmsの場合です。a-blog cmsはJSON形式で変数を渡せます。これなら検索にもヒットします。

@include("/include/module/summary.html", {"class": "c-module-event-top", "mid": "summary_event_top", "loop": "event"})

ここまで書いて、どのくらいの人にこの文章が伝わっているのだろうか…と思いはじめていますが…

よく考えたら、モジュールの包括divを、制作者以外が変更できるようにする必要は基本的にないわけです。配布テーマでは便利でも、制作者が不便になるような機能は制作段階で外しておかなければと、改めて反省しています。

テーマの継承＝親子テーマの概念があるa-blog cmsでは、複数のブログで構成されたウェブサイトを製作する場合、子ブログのテーマはルートブログの子テーマとします。

フォルダ構造をざっと書くと以下のとおりです。子ブログ「ニュース」の親ブログには「sample」というテーマが指定されています。
a-blog cmsは「テーマ名@親テーマ名」でテーマの親子関係ができますから、ニュース用のテーマは「news@sample」とすればよいわけです。

            sample ┬ テンプレート
                         ├ テンプレート
                         ├ テンプレート
             　            ・・・

news@sample ┬ テンプレート
                         ├ テンプレート
                         ├ テンプレート
                         　・・・

ですが最近、他の人が製作した親子テーマを使わない「シングルテーマ構築」を見る機会があり、試してみたところ、開発者によっては、親子テーマよりもメリットが大きいかもしれないと感じました。

シングルテーマ構築とは

手法としては、特に凝ったものではなく、かなり昔からあったものです。私自身、Movable Typeで試したことがあります。

テンプレート内にインクルードを書き、ファイル名の一部に「ブログ名」もしくは「ブログID」を引数として渡します。
a-blog cmsで、詳細ページ用テンプレートの場合こうなります。

@include("/_entry/entry_blog_%{BID}.html")

コードネームを取得する変数「%{BCD}」を使って、より直感的なファイル名にしても良いと思いますが、a-blog cmsはルートブログではコードネームがない（NULL）ので「entry_blog_.html」というファイル名になってもよいのかは考える必要があります。

フォルダ構造は以下のようになります。画面ごとに「_top」「_index」「_entry」のフォルダがあり、現在訪問しているブログのIDをキーとして、表示するテンプレートを切り替えます。

シングルテーマ構築のメリット

やったことがない人から見ると複雑そうに感じますが、大規模なウェブサイトほどメリットがあります。

修正漏れが出にくい

親子テーマで構築したときに問題となるのが、子テーマの修正漏れです。親テーマと子テーマはテキストエディタや統合開発環境でファイル一覧を見た場合、かなり離れた場所に表示されます。このため、複数人で開発したり、数ヶ月語に改修をしたときに見落としが出やすくなります。

ファイルを探しやすい

テンプレートが画面ごとにひとつのフォルダに入っており、かつ一意のファイル名になっているので、ファイル名を検索して修正する作業がスムーズです。 親子テーマの場合、「index.html」を探そうとすると、テーマの総数分だけファイルがヒットすることになります。 カテゴリー単位でディレクトリを作っていると、ますます大変なことになります。

他の条件分岐を併用できる

親子テーマの場合、振り分けるのはあくまでブログ単位であって「ルートカテゴリーがitemsのエントリー」などのカテゴリー単位の振り分けは併用できません。
a-blog cmsの場合、「コンフィグセット」機能が追加されたので、カテゴリーごとにテーマを変えることもできるようにはなったのですが、テーマだけではなく同様にコンフィグに含まれている編集設定なども変わってしまうので、あまり現実的ではありません。

シングルテーマ構築のデメリット

説明が必要

CMS構築にそれほど詳しくない人には、事前説明が必要になります。最低でも、ブログIDとコンテンツの対照表がないと、ブログIDの調べ方がわからない人にはどうしてよいかわからないでしょう。

ルールはやはり子テーマ（a-blog cmsの場合）

スマートフォンではテンプレートを差し替える、などの「ルール」機能を利用する場合は、子テーマでなければなりません。

ELSE分岐が面倒（a-blog cmsの場合）

インクルード時にファイル名が一致していなければならないため、「ではない」を条件とした分岐が難しいです。

えっ？IFブロックを使って、こうすればよいのでは…と思うかもしれませんが、

<!-- BEGIN_IF [%{BID}/eq/2] -->
@include("/_entry/entry_blog_%{BID}.html")
<!-- ELSE -->
@include("/_entry/entry_blog_not2.html")
<!-- END_IF -->

a-blog cmsはIFブロックを使用した場合、条件に合致していないコードも処理されます。なので、このような書き方をすると、実質２ページ分の読み込みが発生して処理が遅くなります。

ELSE分岐はこのように、条件に合致しないテンプレートに、さらにインクルードを書くことになります。

_entry.html

@include("/_entry/entry_blog_%{BID}.html")

entry_blog_2.html 以外のブログIDのテンプレート

@include("/_entry/entry_not_blog_2.html")

なお、自作のグローバル変数を作成する知識があれば、 %{IS_NEWS} のような特殊な条件でtrueを返すグローバル変数を作ったり、特定のカスタムフィールドの値をテンプレートファイル名に使ったりできるので、大幅に有用性が上がります。
その場合はa-blog cmsのアップデートやサーバー移転の際に、オリジナルのグローバル変数を定義している /extension/acms/Hook.php を上書きしないよう、資料を書いて共有しておく必要があります。

まとめ：これでいいのか…？

メリットのところで書いたとおり、シングルテーマ構築は、私的には便利でした。途中、ディレクターさんが急ぎの文言変更でテーマを編集しましたが、フォルダ階層を登ったり降りたりしなくて良いので、作業しやすかったようです。

この構築手法は、a-blog cmsの公式テーマの管理画面のカスタムフィールドでは昔から使われています。ですが、公開側のテンプレートについては、ドキュメントでもこのような手法は解説していないので、オレオレカオステーマになってしまわないか、このまま採用し続けて良いものかという迷いがかなりあります。うぇびんたんいつも迷ってますね。

このへん、他の製作者さんの見解を知りたいので、SNSのコメントなどいただけると、とてもうれしいです。

すでに解決していただきましたが、旧バージョンの管理画面テーマを使用している人が検索するかもしれませんので、ログとして残しておきます。

私が制作したbaserCMSのテーマ「ratio_3_2」に、バージョン4.2から選択できるようになった新しい管理画面テーマを適用すると、SNSアイコンが出なくなってしまいました。

先月リリースされたbaserCMS4.2について、不具合のお知らせです。
ベータ版として同梱されている管理画面テーマ「admin-third」を有効にすると、ratio_3_2のFontAwesomeのアイコンがリンク切れになる不具合を確認しています。（続く） #baserCMS pic.twitter.com/oL9Y1ItiQp

— うぇびんさん (@webbingstudio) 2019年7月15日

調べたところ、以下の原因が判明しました。

• baseCMSはログイン中、ヘッダに常時ツールバーが表示される
• ツールバーでは、FontAwesomeの5系が使用されている
• FontAwesomeは、4系と5系を同時に使用すると、4系のアイコンが正常に表示できなくなる（クラス名が重複しているため）。

ratio_3_2だけでなく、FontAwesomeの4系が使用されているテーマはすべてこの不具合が発生する可能性がある、ということで、FontAwesomeをツールバーに使用しないように修正していただきました。ありがとうございます。

2019年7月20日時点では、まだ公式サイトのダウンロードファイルは更新されていません。気になる方は、baserCMSの公式リポジトリから、最新バージョンをダウンロードしてください。

https://github.com/baserproject/basercms

テーマだけ差し替えたいという場合は、 /app/webroot/theme/admin-third/ 以下を差し替えればOKです。

まだベータ版ですが、baserCMSの新しい管理画面用テーマは、デザインやカラーリングのバランスが取れていて、旧テーマよりもかなり使いやすいと思います。日常的にbaserを使用している方は試してみてください。

これは、a-blog cms Advent Calendar 2018の12日目の記事です。
a-blog cms Advent Calendar 2018 - Adventar

今回は、かなり制作者向けの記事です。a-blog cmsを利用していても、運用やディレクションが中心の方には、少し難しい内容であることを前置きしておきます。ですが、テーマの制作をしている方は、ぜひ読んでいただけるとうれしいです。

• はじめに
• includeの変数渡し
  • 概要
  • 構造図
  • includeの特徴
• extendによるコードの継承
  • 概要
  • 構造図
  • extendの特徴
• いえズームでの活用
  • includeの変数渡し
  • extendによるコードの継承
• まとめ、使ってみての雑感

はじめに

北海道住宅新聞社さんの情報サイト「いえズーム」の管理をはじめてから、一年半くらい経ちます。

【iezoom】（いえズーム）北海道の住宅会社選び | いえズーム（iezoom）

いえズームの制作をはじめた頃は、「includeの変数渡し」「extendによるコードの継承」はリリースされていませんでした（バージョン2.8.0から）。 旧来のインクルードを使用したまま改修を重ねていたら、テーマがカオス化してきたこともあり、新しい機能を使用してコード整理をしています。

新しい機能のそれぞれの特徴と、いえズームでの実際の利用場面を紹介します。

includeの変数渡し

概要

旧来のインクルードは、SSI風の書式で、読み込むファイル名を指示するのみのシンプルなものでした。

<!--#include file="/path/to/filename"-->

しかし、2.8以降では、JSON風の書式で、読み込み先で使用できる独自変数を渡せるようになっています。

@include("/path/to/filename", {"key": "value", "key2": "value2"})

詳細な仕様解説は公式ドキュメントを参照ください。
インクルード | テンプレート | ドキュメント | a-blog cms developer

構造図

図で解説すると以下の通りです。 「sample_01.html」と「sample_02.html」は同じパーツ、module.htmlを読み込んでいますが、変数「button」の値が異なるため、実際に表示されるコードが一部変わります。 「sample_01.html」では、新着記事一覧の下に「詳しくはこちら」ボタンが表示されるはずです。

includeの特徴

includeの変数はグローバル変数ではないので、読み込み先以外に干渉することはありません。いくつでも渡すことができ、変数の初期値も定義できますが、長いコードを渡すことはできません（できたとしても可読性が著しく落ちます）。

extendによるコードの継承

概要

いっぽうextendですが、WordPressやa-blog cmsに実装されている「親・子テーマ」の「コードの使い回し」を、テンプレート間で実行することができます。

テンプレート冒頭で「@extend」を書くと、指定したファイルを丸ごと読み込むことができます。ここまではincludeと変わりませんが…

@extend(/path/to/filename)

指定した読み込み元のファイルに「@section(任意の英数字名) 」〜「@endsection 」で囲んだ領域があると、読み込み先のファイルでコードを上書きすることができます。

@section(sample)
  <h2>内容を書き換えちゃうよ！</h2>
@endsection

つまり、読み込み先では、差分コードだけ記述すれば良いのです。

詳細な仕様解説は公式ドキュメントを参照ください。
テンプレートの継承 | テンプレート | ドキュメント | a-blog cms developer

構造図

図で解説すると以下の通りです。
レイアウト用に作成した非公開テンプレート「_layout.html」のコードを３つの公開テンプレートで使い回していますが、それぞれ実際の表示結果が変わります。特にsample_03.htmlの「継承しつつ追記」はいろいろ便利です。

extendの特徴

extendは、前もってレイアウト用のテンプレートを作り、どの箇所を継承可能にするか定義することになります。

長いコードをテンプレート間で渡すことができるので、似ているけれど微妙に違うレイアウトが多いサイトでは、書くべきテンプレートの行数を大幅に節約できます。反面、includeとは異なり、条件分岐などに使える変数を渡すことはできません。

いえズームでの活用

includeの変数渡し

いえズームは一見シンプルなサイトですが、訪問者の導線を意識しているため、コンテンツごとに記事の表示件数や体裁、ページ内での表示位置などが細かく違っています。改修を重ねているうちに、モジュール部分のテンプレート数が肥大してしまっていました。

例えば「summary_sub_story_future」モジュールと「summary_sub_story_recent」モジュールは、IDが違うだけでコードがまったく同じなのに別ファイルになっています。

<!-- BEGIN_MODULE Entry_Summary id="summary_sub_story_future" -->
・・・
<!-- END_MODULE Entry_Summary -->

<!-- BEGIN_MODULE Entry_Summary id="summary_sub_story_recent" -->
・・・
<!-- END_MODULE Entry_Summary -->

これを、includeの変数渡しに書き換えることで、ひとつのファイルでidだけ違うコードを出力することができました。

さらに、なんと、読み込み先のincludeのファイル名に変数を引き継ぐことができることに気付いてしまいました。エントリーの繰り返し部分の体裁だけが違うテンプレートも共通化できそうです。

@include("/include/module/summary_sub.html", {"mid": "summary_sub_story_recent", "loop": "story_media.html"})

<!-- BEGIN_MODULE Entry_Summary id="{{mid}}" -->
・・・
@include("/include/module_loop/{{loop}}")
・・・
<!-- END_MODULE Entry_Summary -->

extendによるコードの継承

いえズームは、すべてのページのフッタ上部に、「いえズームとは？」というサイトの概要が記載されています。

ですが、一箇所だけ例外があります。地域別企業一覧のページでは、ヘッダの地域紹介の直下にあるのです。

札幌圏の住宅会社（ハウスメーカー・工務店）一覧 | いえズーム（iezoom）

地域ページは、冒頭に地域情報のパーツがあったり、地域名を変数に入れていたりと、かなりレイアウトが異なっています。以前は地域ページだけまったく違うテンプレートを用意していたのですが、extendを使うことで、他のテンプレートが利用している「/_layout_col2.html」との共通化ができるようになりました。

@extends("/_layout_col2.html")

@section(head_before)
（地域名を変数に取得）
@endsection

@section(pagehead)
（地域情報とサイト紹介パーツ）
@endsection

以下略

まとめ、使ってみての雑感

このように、わかりやすいところから少しずつコードの整理をしています。

使ってみての感想は、やはりテーマ職人としては、extendが手応えがある分面白いなあと感じています。大幅にテンプレートの数を減らせそうです。ただし、テーマ全体の構成を把握していないと実装できませんから、コーダーとテーマ制作者が違う案件では苦戦するかもしれません。

includeの変数渡しは便利な反面、インクルード先のテンプレートで、その変数がどこから定義されたものなのかわかりにくいという欠点があります（変数名でテンプレートを検索すればいいのですが）。 同じような変数名を使いすぎてカオス化しないよう、ルール決めが必要です。

いえズームは現在も、数週間に一度のペースでコンテンツの改修や追加が続いています。 このため、私も手早く対応できるようにしなければなりません。テンプレートを整理することで余裕が出て、より良い制作や提案ができればと期待しています。