CakePHP では Widgetクラスを作成する事で独自のフォームテンプレートを定義する事が出来ます。

CakePHP3で独自フォームテンプレートをWidgetクラスで作成する（独自ウィジェット）

今回は、CakePHP3 の HTML フォームパーツのテンプレートを、Widget クラスを用いて独自に作成していきます。
<h2 id="contents">Contents</h2>
<ol>
<li><a href="#%E9%96%8B%E7%99%BA%E7%92%B0%E5%A2%83">開発環境</a></li>
<li><a href="#widget-%E3%82%AF%E3%83%A9%E3%82%B9">Widget クラス</a></li>
<li><a href="#widget-%E3%82%AF%E3%83%A9%E3%82%B9%E4%BD%9C%E6%88%90">Widget クラス作成</a></li>
<li><a href="#%E7%8B%AC%E8%87%AA%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E4%BD%9C%E6%88%90">独自フォームテンプレート作成</a></li>
<li><a href="#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%81%A8%E3%82%A6%E3%82%A3%E3%82%B8%E3%82%A7%E3%83%83%E3%83%88%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF">フォームテンプレートとウィジェット読み込み</a></li>
<li><a href="#formhelper-%E3%81%A7%E6%8F%8F%E7%94%BB">FormHelper で描画</a></li>
<li><a href="#%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">動作確認</a></li>
</ol>
<h2 id="開発環境">開発環境</h2>
今回の開発環境は以下の通りです。
<ul>
<li>Linux CentOS 7</li>
<li>Apache 2.4</li>
<li>PHP 7.2</li>
<li>CakePHP 3.5</li>
</ul>
CakePHP のルートディレクトリを「cakephp/」とします。
<h2 id="widget-クラス">Widget クラス</h2>
CakePHP3 のフォームテンプレートと言えば、FormHelper から利用する HTML フォームパーツのテンプレートの事を指しますが、それらは各タイプ（input/select/radio etc...）ごとに作成されているので融通が利かない場合があります。
例えば、同じ input だけど別のテンプレートを当てたい。みたいな時です。
そんな時は、Widget クラスを作成する事で、独自のフォームテンプレートを定義する事が出来ます。
ちなみに通常のテキスト入力といえば input タイプ「text」になりますが、今回は同じタイプでも別のフォームテンプレートを参照できるようにします。
そこで、今回もう一方の input には bootstrap の<a href="https://bootstrap-datepicker.readthedocs.io" rel="noopener noreferrer" target="_blank">DatePicker</a> をあてたいと思います。 DatePicker は日時を扱うものですが、入力自体は input で行われるので、通常の input のテンプレートだと基本的にはレイアウトが崩れてしまいます。
こいつを別テンプレートで表示させていきます。
<h2 id="widget-クラス作成">Widget クラス作成</h2>
Widget クラスを作成し定義していきます。
cakephp/src/View 配下に Widget ディレクトリを作成し、その配下に DatePickerWidget.php を作成します。
<pre><code class="hljs language-shell">cakephp
├─ src
│   ├─ View
│   │   ├─ Widget
│   │   │ └─ DatePickerWidget.php
</code></pre>
作成した DatePickerWidget.php を Widget クラスとして、以下のように記述します。
<dl class="description_setting">
<dt>cakephp/src/View/Widget/DatePickerWidget.php</dt>
<dd>
<pre><code class="hljs language-php">&#x3C;?php
namespace App\View\Widget;

use Cake\View\Form\ContextInterface;
use Cake\View\Widget\WidgetInterface;

class DatePickerWidget implements WidgetInterface
{
 protected $_templates;

 public function __construct($templates)
 {
 $this->_templates = $templates;
 }

 public function render(array $data, ContextInterface $context)
 {
 $data += [
 'name' => '',
 'val' => '',
 ];
 return $this->_templates->format('datepicker', [
 'name' => $data['name'],
 'val' => $data['val'],
 'templateVars' => $data['templateVars'],
 'attrs' => $this->_templates->formatAttributes($data, ['name'], ['val'])
 ]);
 }

 public function secureFields(array $data)
 {
 return [ $data['name']];
 }
}
</code></pre>
</dd>
</dl>
上から説明していきます。
Widget class の作成時は、WidgetInterface の実装が義務付けられている為、implements して必要な render() メソッドと secureFields() メソッドの実装を行います。
render() メソッドに関しては、入ってきた入力情報などをどう扱い、テンプレートへ渡すかを定義しています。ここで操作したフォームパーツ情報や入力データは、ウィジェットの HTML へ文字列として渡す事ができます。
ちなみに return する時に、format() の第二引数に各値をセットしていますが、第一引数には独自ウィジェット、要するに HTML テンプレートの識別子を指定します。
secureFields() メソッドに関しては、保護するフィールドのリストを渡しています。
今回は DatePicker のデモなのでこんな感じになっていますが、ひとまず試してみたいという場合は、上記ソースのクラス名の変更と、render() メソッドで return する時の、format() の第一引数の名前（例では「datepicker 」としている部分）を任意のものに変えてもらえれば、そのまま使えます。
<h2 id="独自フォームテンプレート作成">独自フォームテンプレート作成</h2>
次は、独自の HTML フォームパーツのテンプレート作成です。
cakephp/config 配下に Template ディレクトリを作成し、その配下に form-templates.php（ファイル名は任意で OK） を作成します。
<pre><code class="hljs language-shell">cakephp
├─ config
│   ├─ Templates
│   │   └─ form-templates.php
</code></pre>
作成したファイルに、DatePicker ウィジェットのフォームテンプレートを定義していきます。
<dl class="description_setting">
<dt>cakephp/config/Template/form-templates.php</dt>
<dd>
<pre><code class="hljs language-php">&#x3C;?php

return [
 /**
 * 通常のフォームテンプレート
 */
 'formStart' => '&#x3C;form class="form-horizontal" {{attrs}}>',
 'hiddenBlock' => '&#x3C;div style="display:none;">{{content}}&#x3C;/div>',

 'inputContainerError' => '&#x3C;div class="form-group has-error">&#x3C;label class="col-sm-2 control-label" {{attrs}}>{{label}}&#x3C;/label>&#x3C;div class="col-sm-10">{{content}}{{error}}&#x3C;/div>&#x3C;/div>&#x3C;div class="hr-line-dashed">&#x3C;/div>',

 'inputContainer' => '&#x3C;div class="form-group">&#x3C;label class="col-sm-2 control-label" {{attrs}}>{{label}}&#x3C;/label>&#x3C;div class="col-sm-10">{{content}}&#x3C;/div>&#x3C;/div>&#x3C;div class="hr-line-dashed">&#x3C;/div>',
 'label' => '&#x3C;label class="col-sm-2 control-label" {{attrs}}>{{text}}&#x3C;/label>',

 'input' => '&#x3C;input class="form-control" type="{{type}}" name="{{name}}" {{attrs}}>',

 'textarea' => '&#x3C;textarea name="{{name}}" class="form-control" {{attrs}}>{{value}}&#x3C;/textarea>',

 'select' => '&#x3C;select name="{{name}}" class="chosen-select" tabindex="2">{{content}}&#x3C;/select>',
 'option' => '&#x3C;option value="{{value}}"{{attrs}}>{{text}}&#x3C;/option>',

 'button' => '&#x3C;div class="form-group">&#x3C;div class="col-sm-4 col-sm-offset-2">&#x3C;button type="{{type}}" class="btn btn-primary" {{attrs}}>{{text}}&#x3C;/button>&#x3C;/div>&#x3C;/div>',


 /**
 * Widgetクラス DatePickerWidget 独自テンプレート
 */
 'datepicker' => '&#x3C;div class="input-group date">&#x3C;span class="input-group-addon">&#x3C;i class="fa fa-calendar">&#x3C;/i>&#x3C;/span>&#x3C;input type="text" value="{{value}}" class="form-control" name="{{name}}" data-date-format="yyyy-mm-dd" {{attrs}}>&#x3C;/div>'

];
</code></pre>
</dd>
</dl>
最下部に先ほど作成した DatePicker ウィジェットのフォームテンプレートを定義しています。
例では通常のフォームテンプレートも記述していますが、こうして混合で記述も出来るよと言いたいだけなので、不要ならば実装は不要です。
通常のフォームテンプレートには無い「datepicker 」という定義を見ると、なんだかわくわくしてきます。
<h2 id="フォームテンプレートとウィジェット読み込み">フォームテンプレートとウィジェット読み込み</h2>
作成したものをコントローラで読み込み、使えるようにします。適当なコントローラに、以下の記述を行い、テンプレートとウィジェットを読み込ませます。
<pre><code class="hljs language-php">class SampleController extends AppController
{
 public $helpers = [
 'Form' => [
 'templates' => 'Templates/form-templates',
 'widgets' => [
 'datepicker' => ['DatePicker']
 ]
 ],
 ];
</code></pre>
メンバ変数 $helpers に、フォームプロパティに対してそれぞれテンプレートとウィジェットを指定している事がわかると思います。これで先ほど作成したテンプレートとウィジェットが読み込まれます。
<h2 id="formhelper-で描画">FormHelper で描画</h2>
最後に、ビューテンプレート内で FormHelper を使ってフォームを描画します。以下のようにして、type に datepicker を指定してあげるだけです。その他は通常の使い方と変わりません。
<pre><code class="hljs language-php">echo $this->Form->control('sample_date_at', ['type' => 'datepicker', 'label' => false, 'templateVars' => ['label' => 'サンプル']]);
</code></pre>
<h2 id="動作確認">動作確認</h2>
実装が完了したのでブラウザから確認してみます。
<div class="img_wrap"><amp-img layout="responsive" src="/images/posts/84/Ns3QIBzbXTT2Y1sxRnU8.png" width="500" height="292" alt="Widget クラスによる DatePicker フォーム"></div>
フォームテンプレートから DatePicker を呼び出せました。
<h2 id="まとめ">まとめ</h2>
以上で作業は完了です。
通常のフォームのみを使っていればそんなに気にならない部分ですが、例えば JavaScript を使ってインタラクティブなフォームを作成する場合などは、どうしてもフォームの使い方がエクセントリックになったり複雑な id/class/data 属性になりがちなので、そんな時はウィジェットで独自にフォームパーツを作成すると作業もはかどると思いますので、是非試してみてください。

今回は、CakePHP3 の HTML フォームパーツのテンプレートを、Widget クラスを用いて独自に作成していきます。
<h2 id="contents">Contents</h2>
<ol>
<li><a href="#%E9%96%8B%E7%99%BA%E7%92%B0%E5%A2%83">開発環境</a></li>
<li><a href="#widget-%E3%82%AF%E3%83%A9%E3%82%B9">Widget クラス</a></li>
<li><a href="#widget-%E3%82%AF%E3%83%A9%E3%82%B9%E4%BD%9C%E6%88%90">Widget クラス作成</a></li>
<li><a href="#%E7%8B%AC%E8%87%AA%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E4%BD%9C%E6%88%90">独自フォームテンプレート作成</a></li>
<li><a href="#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%81%A8%E3%82%A6%E3%82%A3%E3%82%B8%E3%82%A7%E3%83%83%E3%83%88%E8%AA%AD%E3%81%BF%E8%BE%BC%E3%81%BF">フォームテンプレートとウィジェット読み込み</a></li>
<li><a href="#formhelper-%E3%81%A7%E6%8F%8F%E7%94%BB">FormHelper で描画</a></li>
<li><a href="#%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">動作確認</a></li>
</ol>
<h2 id="開発環境">開発環境</h2>
今回の開発環境は以下の通りです。
<ul>
<li>Linux CentOS 7</li>
<li>Apache 2.4</li>
<li>PHP 7.2</li>
<li>CakePHP 3.5</li>
</ul>
CakePHP のルートディレクトリを「cakephp/」とします。
<h2 id="widget-クラス">Widget クラス</h2>
CakePHP3 のフォームテンプレートと言えば、FormHelper から利用する HTML フォームパーツのテンプレートの事を指しますが、それらは各タイプ（input/select/radio etc...）ごとに作成されているので融通が利かない場合があります。
例えば、同じ input だけど別のテンプレートを当てたい。みたいな時です。
そんな時は、Widget クラスを作成する事で、独自のフォームテンプレートを定義する事が出来ます。
ちなみに通常のテキスト入力といえば input タイプ「text」になりますが、今回は同じタイプでも別のフォームテンプレートを参照できるようにします。
そこで、今回もう一方の input には bootstrap の<a href="https://bootstrap-datepicker.readthedocs.io" rel="noopener noreferrer" target="_blank">DatePicker</a> をあてたいと思います。 DatePicker は日時を扱うものですが、入力自体は input で行われるので、通常の input のテンプレートだと基本的にはレイアウトが崩れてしまいます。
こいつを別テンプレートで表示させていきます。
<h2 id="widget-クラス作成">Widget クラス作成</h2>
Widget クラスを作成し定義していきます。
cakephp/src/View 配下に Widget ディレクトリを作成し、その配下に DatePickerWidget.php を作成します。
<pre><code class="hljs language-shell">cakephp
├─ src
│   ├─ View
│   │   ├─ Widget
│   │   │ └─ DatePickerWidget.php
</code></pre>
作成した DatePickerWidget.php を Widget クラスとして、以下のように記述します。
<dl class="description_setting">
<dt>cakephp/src/View/Widget/DatePickerWidget.php</dt>
<dd>
<pre><code class="hljs language-php">&#x3C;?php
namespace App\View\Widget;

use Cake\View\Form\ContextInterface;
use Cake\View\Widget\WidgetInterface;

class DatePickerWidget implements WidgetInterface
{
 protected $_templates;

 public function __construct($templates)
 {
 $this->_templates = $templates;
 }

 public function render(array $data, ContextInterface $context)
 {
 $data += [
 'name' => '',
 'val' => '',
 ];
 return $this->_templates->format('datepicker', [
 'name' => $data['name'],
 'val' => $data['val'],
 'templateVars' => $data['templateVars'],
 'attrs' => $this->_templates->formatAttributes($data, ['name'], ['val'])
 ]);
 }

 public function secureFields(array $data)
 {
 return [ $data['name']];
 }
}
</code></pre>
</dd>
</dl>
上から説明していきます。
Widget class の作成時は、WidgetInterface の実装が義務付けられている為、implements して必要な render() メソッドと secureFields() メソッドの実装を行います。
render() メソッドに関しては、入ってきた入力情報などをどう扱い、テンプレートへ渡すかを定義しています。ここで操作したフォームパーツ情報や入力データは、ウィジェットの HTML へ文字列として渡す事ができます。
ちなみに return する時に、format() の第二引数に各値をセットしていますが、第一引数には独自ウィジェット、要するに HTML テンプレートの識別子を指定します。
secureFields() メソッドに関しては、保護するフィールドのリストを渡しています。
今回は DatePicker のデモなのでこんな感じになっていますが、ひとまず試してみたいという場合は、上記ソースのクラス名の変更と、render() メソッドで return する時の、format() の第一引数の名前（例では「datepicker 」としている部分）を任意のものに変えてもらえれば、そのまま使えます。
<h2 id="独自フォームテンプレート作成">独自フォームテンプレート作成</h2>
次は、独自の HTML フォームパーツのテンプレート作成です。
cakephp/config 配下に Template ディレクトリを作成し、その配下に form-templates.php（ファイル名は任意で OK） を作成します。
<pre><code class="hljs language-shell">cakephp
├─ config
│   ├─ Templates
│   │   └─ form-templates.php
</code></pre>
作成したファイルに、DatePicker ウィジェットのフォームテンプレートを定義していきます。
<dl class="description_setting">
<dt>cakephp/config/Template/form-templates.php</dt>
<dd>
<pre><code class="hljs language-php">&#x3C;?php

return [
 /**
 * 通常のフォームテンプレート
 */
 'formStart' => '&#x3C;form class="form-horizontal" {{attrs}}>',
 'hiddenBlock' => '&#x3C;div style="display:none;">{{content}}&#x3C;/div>',

 'inputContainerError' => '&#x3C;div class="form-group has-error">&#x3C;label class="col-sm-2 control-label" {{attrs}}>{{label}}&#x3C;/label>&#x3C;div class="col-sm-10">{{content}}{{error}}&#x3C;/div>&#x3C;/div>&#x3C;div class="hr-line-dashed">&#x3C;/div>',

 'inputContainer' => '&#x3C;div class="form-group">&#x3C;label class="col-sm-2 control-label" {{attrs}}>{{label}}&#x3C;/label>&#x3C;div class="col-sm-10">{{content}}&#x3C;/div>&#x3C;/div>&#x3C;div class="hr-line-dashed">&#x3C;/div>',
 'label' => '&#x3C;label class="col-sm-2 control-label" {{attrs}}>{{text}}&#x3C;/label>',

 'input' => '&#x3C;input class="form-control" type="{{type}}" name="{{name}}" {{attrs}}>',

 'textarea' => '&#x3C;textarea name="{{name}}" class="form-control" {{attrs}}>{{value}}&#x3C;/textarea>',

 'select' => '&#x3C;select name="{{name}}" class="chosen-select" tabindex="2">{{content}}&#x3C;/select>',
 'option' => '&#x3C;option value="{{value}}"{{attrs}}>{{text}}&#x3C;/option>',

 'button' => '&#x3C;div class="form-group">&#x3C;div class="col-sm-4 col-sm-offset-2">&#x3C;button type="{{type}}" class="btn btn-primary" {{attrs}}>{{text}}&#x3C;/button>&#x3C;/div>&#x3C;/div>',


 /**
 * Widgetクラス DatePickerWidget 独自テンプレート
 */
 'datepicker' => '&#x3C;div class="input-group date">&#x3C;span class="input-group-addon">&#x3C;i class="fa fa-calendar">&#x3C;/i>&#x3C;/span>&#x3C;input type="text" value="{{value}}" class="form-control" name="{{name}}" data-date-format="yyyy-mm-dd" {{attrs}}>&#x3C;/div>'

];
</code></pre>
</dd>
</dl>
最下部に先ほど作成した DatePicker ウィジェットのフォームテンプレートを定義しています。
例では通常のフォームテンプレートも記述していますが、こうして混合で記述も出来るよと言いたいだけなので、不要ならば実装は不要です。
通常のフォームテンプレートには無い「datepicker 」という定義を見ると、なんだかわくわくしてきます。
<h2 id="フォームテンプレートとウィジェット読み込み">フォームテンプレートとウィジェット読み込み</h2>
作成したものをコントローラで読み込み、使えるようにします。適当なコントローラに、以下の記述を行い、テンプレートとウィジェットを読み込ませます。
<pre><code class="hljs language-php">class SampleController extends AppController
{
 public $helpers = [
 'Form' => [
 'templates' => 'Templates/form-templates',
 'widgets' => [
 'datepicker' => ['DatePicker']
 ]
 ],
 ];
</code></pre>
メンバ変数 $helpers に、フォームプロパティに対してそれぞれテンプレートとウィジェットを指定している事がわかると思います。これで先ほど作成したテンプレートとウィジェットが読み込まれます。
<h2 id="formhelper-で描画">FormHelper で描画</h2>
最後に、ビューテンプレート内で FormHelper を使ってフォームを描画します。以下のようにして、type に datepicker を指定してあげるだけです。その他は通常の使い方と変わりません。
<pre><code class="hljs language-php">echo $this->Form->control('sample_date_at', ['type' => 'datepicker', 'label' => false, 'templateVars' => ['label' => 'サンプル']]);
</code></pre>
<h2 id="動作確認">動作確認</h2>
実装が完了したのでブラウザから確認してみます。
<div class="img_wrap"><img src="/images/posts/84/Ns3QIBzbXTT2Y1sxRnU8.png" width="500" height="292" alt="Widget クラスによる DatePicker フォーム"></div>
フォームテンプレートから DatePicker を呼び出せました。
<h2 id="まとめ">まとめ</h2>
以上で作業は完了です。
通常のフォームのみを使っていればそんなに気にならない部分ですが、例えば JavaScript を使ってインタラクティブなフォームを作成する場合などは、どうしてもフォームの使い方がエクセントリックになったり複雑な id/class/data 属性になりがちなので、そんな時はウィジェットで独自にフォームパーツを作成すると作業もはかどると思いますので、是非試してみてください。

Author