baserCMS 4系テーマの5系化（step 4） - 「Omotenashi2」コンテンツテンプレートと周辺をマイグレートする。

「4系テーマの5系化」ステップ4は、「Omotenashi2」ブログコンテンツテンプレートやメールコンテンツテンプレート、周辺の関連ファイルをマイグレートします。

さて、まずは、あらためてフォルダ構成の学習。ブログやメールなどのコンテンツテンプレートの配置については、「5系テーマガイド - テンプレートのカスタマイズ」を参照。

ひとまず、ブログコンテンツテンプレートとブログ周りのエレメントテンプレートに絞ってマイグレートしていきます。
初期状態では、これらのコンテンツテンプレートはbaserCMSのパッケージが提供する初期テンプレート（具体的には、/vendor/baserproject/bc-front/templates/plugin/BcBlog/Blog/default/内のテンプレートファイル）が読み込まれる設定となっていますが、テーマ独自にエレメントテンプレートに変更する場合は、下記の場所に同名ファイルを配置することになります。

以下、「5系テーマガイド - テンプレートのカスタマイズ」から引用。

/plugins/{YourTheme}/templates/plugin/BcBlog/Blog/{コンテンツテンプレート名}/index.php
/plugins/{YourTheme}/templates/plugin/BcBlog/Blog/{コンテンツテンプレート名}/archives.php
/plugins/{YourTheme}/templates/plugin/BcBlog/Blog/{コンテンツテンプレート名}/single.php
/plugins/{YourTheme}/templates/plugin/BcBlog/Blog/{コンテンツテンプレート名}/posts.php

# 次のパスでも動作します
/plugins/{YourTheme}/templates/Blog/{コンテンツテンプレート名}/index.php
/plugins/{YourTheme}/templates/Blog/{コンテンツテンプレート名}/archives.php
/plugins/{YourTheme}/templates/Blog/{コンテンツテンプレート名}/single.php
/plugins/{YourTheme}/templates/Blog/{コンテンツテンプレート名}/posts.php

4系をずっと使ってきた人には、/plugins/Omotenashi2/templates/Blog/default/ の方がなんとなく馴染みがあると思います。
なので、今回は /plugins/Omotenashi2/templates/Blog/default/ に配置することにします。
ちなみに、メールについても同様で /plugins/Omotenashi2/templates/Mail/default/ に配置していいということの様です。

詳細

さて、本題のマイグレート作業です。
まずは、ブログコンテンツテンプレートのマイグレートから始めます。ひとまず、4系「Omotenashi2」テーマの/Blog/default/フォルダをコピーし、/plugins/Omotenashi2/templates/Blog/default/にそのまま配置してみます。
4系のままのsinglephp、index.php、archive.php、post.phpをファイル毎、エラー確認していくのですが、この時点ですでにトップページがエラーで開かなくなります。トップページのスライダーの下部辺りにレイアウトされているブログポスト表示が、post.phpを配置したことによってエラーになったためです。

メッセージをみると、Undefined constant "FULL_BASE_URL" Error in: ROOT/plugins/Omotenashi2/templates/Blog/default/post.php, line 14とエラー表示されています。
実は、CakePHP2系で、http:(もしくはhttps:)からのURLを出力するためによく使われていたこの FULL_BASE_URL 定数は、CakePHP4以降では撤廃されたためエラーになったのですが、なんとタイムリーなことに、baserCMS5系になってから（たぶん？）BlogHelper の getPostLinkUrl 関数に$full : bool = trueのパラメーターがデフォルトで追加されたことで、<?php echo $this->Blog->getPostLinkUrl($post) ?>と記述するだけで記事へのURLをhttp:(もしくはhttps:)からのURLで出力されるようになっています。
おかげで、ブログ記事のSNSのツイートボタンやいいね！ボタン用のコードで多く利用されていた

data-url="<?php echo FULL_BASE_URL . $this->Blog->getPostLinkUrl($post, $post['BlogPost']['name']) ?>"

というコードは、

data-url="<?php echo $this->Blog->getPostLinkUrl($post) ?>"

とシンプルに書けるようになりました。

この修正で、無事、トップ画面もエラー無く表示されるようになり、ブログポストも正しいレイアウトで表示されます。

このコードは、post.php以外のsinglephp、index.php、archive.phpでも同様に使われていて、それらを書き換えることで、今回のブログコンテンツテンプレートのマイグレートは、事実上完了です。

ただ、この時点で、ブログページのentryAreaエリア（記事が表示されているエリア）は正しく表示されていますが、sideNavエリア（ウィジェットが表示されているエリア）は「エレメントテンプレート「sidebox」が見つかりませんでした。」と表示されていてウィジェット等は表示されていません。
ブログ周りで必要なエレメントファイル（sidebox.php、widgetsフォルダなど）が読み込まれていないためで、先のステップ3 「baserCMS 4系テーマの5系化（step 3） - 「Omotenashi2」エレメントテンプレートをマイグレートする。 」で整理した（下図）ブログ絡みで必要なエレメントファイルを順次読み込ませていきます。

まずは、「エレメントテンプレート「sidebox」が見つかりませんでした。」のメッセージどおり、4系のsidebox.phpを/plugins/Omotenashi2/templates/element/sidebox.phpに配置するだけで、特に何も修正せずともウィジェットが表示されるのですが、デザインはまったく「Omotenashi2」テーマのものには当然なっていません。

そもそも、4系「Omotenashi2」テーマの「widgets」フォルダは、ウィジェット欄を「Omotenashi2」テーマ独自のデザインにするためにコアファイル内からコピーして加工していたものなので、そのままマイグレートしようとすると結構手を入れることになりそうです。なので、ここは一旦、/vendor/baserproject/bc-front/templates/plugin/BcBlog/element/内の「widget」フォルダをコピーして、/plugins/Omotenashi2/templates/element/widget/に配置し、4系「Omotenashi2」テーマで独自デザインとするために変更していたHTMLタグに該当する箇所を同様に変更、追記していくといった手順が無理がないと思います。
/vendor/baserproject/bc-front/templates/plugin/BcBlog/element/内のblog_comment.php、blog_comments.phpや /vendor/baserproject/bc-front/templates/plugin/BcWidgetArea/element/内のwidget_area.phpも同様の手順です。

次に、メールコンテンツテンプレートと周辺ファイルのマイグレートです。
初期状態では、ブログコンテンツテンプレートと同様、baserCMSのパッケージが提供する初期テンプレート（具体的には、/vendor/baserproject/bc-front/templates/plugin/BcMail/Mail/default/内のテンプレートファイル）が読み込まれる設定となっていますが、テーマ独自に変更する場合は、/plugins/Omotenashi2/templates/Mail/default/に同名ファイルを配置します。（「5系テーマガイド - テンプレートのカスタマイズ」）
なので、メールコンテンツテンプレートも、一旦、4系「Omotenashi2」テーマの/Mail/default/フォルダをコピーし、/plugins/Omotenashi2/templates/Mail/default/にそのまま配置してみます。

この時点で、ブラウザで/contact/にアクセスしてみると、特にエラー表示なくお問合せ画面全体のレイアウトも正しく表示されるものの、メールフォーム内のレイアウトが正しく適用されていません。（対策は、後述。）
ここで、実際にテスト送信を行うとわかるのですが、メールコンテンツテンプレートのsubmit.phpでエラーが出ます。
submit.phpのマイグレートに関しては、/vendor/baserproject/bc-front/templates/plugin/BcMail/Mail/default/submit.phpをコピーして、/plugins/Omotenashi2/templates/element/Mail/default/submit.phpに配置し、「Omotenashi2」テーマで独自デザインとするために変更していたHTMLタグに該当する箇所を同様に変更、追記していきます。

メールフォーム内のレイアウトは、マイグレートした4系「Omotenashi2」テーマ「Elements」フォルダ内のmail_form.php、mail_input.phpファイルを/plugins/Omotenashi2/templates/element/に配置すれば、正しく適用されます。
ただ、4系「Omotenashi2」テーマ「Elements」フォルダ内のmail_form.php、mail_input.phpもコアファイル内からコピーして加工していたもので、そのままマイグレートしようとすると結構手を入れることになりそうなので、これも一旦、/vendor/baserproject/bc-front/templates/plugin/BcMail/element/内のmail_form.php、mail_input.phpをコピーし、/plugins/Omotenashi2/templates/element/に配置し、HTMLタグに該当する箇所を変更、追記します。

最後はちょっと駆け足になってしまいましたが、以上で、「Omotenashi2」コンテンツテンプレートとその周辺ファイルのマイグレートは完了です。

さて、「4系テーマの5系化」と題して、番外編を入れて5回にわたって連載した記事ですが、今回をもって最終回です。
最後に体系的なマイグレートのステップから外れたり、漏れてしまった内容を簡単にまとめて締め括りたいと思います。ちょっとした総括も。

体系的なマイグレートから外れてしまった内容

上図、赤色でハイライトしたのが、「体系的なマイグレートから外れてしまった内容」です。

• 「移行しない。」としたものは、しなくても良いという意味。ですが、テーマ自体を全く手を入れないで使う人は、ほとんどいない気がするので、改修目的でこれらのファイルが必要になった場合は、わざわざ不具合を起こすかもしれない4系のテンプレートを利用せず、初期テンプレート（/vendor/baserproject/bc-front/以下）からコピー、テーマ内に配置して利用（改修、変更）することを薦めます。
• 「移行不要。」としたものは、そもそも5系では必要ない、あるいは、4系テーマ作者が開発時に利用していたツールなどがエクスポートしたファイルなどです。
• 「sass」フォルダは、/plugins/Omotenashi2/webroot/以下にそのまま配置で良いのではないかと思います。
• 「emails」フォルダは、/vendor/baserproject/bc-front/templates/plugin/BcBlog/email/内の初期テンプレートが優先して読み込まれるので、特に移行しなくて良いかと思います。なお、もし、移行するのなら/plugins/Omotenashi2/templates/直下の配置で、フォルダ名称を「Emails」から「email」に変更します。

総括

今回の「4系テーマの5系化」と題したマイグレート作業。体系的にステップを踏んでやってみましたが、面倒かと思いきや、意外？！と面白かったというのが印象です。
マイグレート作業に限らずなんでもそうですが、マニュアルやリファレンスは、決して全網羅しているわけではないし、当然間違いだってあるわけで、やはりトライアル＆エラーでやっていくしかないのでして、そこに新たな発見や理解、面白みも達成感もあるのだと思います。 是非、臆せず他のテーマなどでも、皆さんトライしてみてはいかがでしょうか。