Form¶

フォーム作成のためのオプション¶

$options 配列は、ほとんどのフォーム設定が行われる場所です。この特別な配列には、 form タグの生成方法に影響を与えるさまざまなキーと値のペアが含まれます。 有効な値:

• 'type' - 作成するフォームの種類を選択できます。type が未指定の場合、 フォームコンテキストに基づいて自動的に決まります。 有効な値:

  • 'get' - フォームの method に HTTP GET を設定します。

  • 'file' - フォームの method に POST を設定し、 enctype に "multipart/form-data" を設定します。

  • 'post' - method に POST を設定します。

  • 'put', 'delete', 'patch' - フォームの送信時に、HTTP メソッドを PUT、 DELETE もしくは PATCH に上書きします。

• 'method' - 有効な値は、上記と同じです。フォームの method を明示的に上書きできます。

• 'url' - フォームを送信する URL を指定します。文字列および URL 配列を指定できます。

• 'encoding' - フォームに accept-charset エンコーディングをセットします。 デフォルトは、 Configure::read('App.encoding') です。

• 'enctype' - 明示的にフォームのエンコーディングをセットできます。

• 'templates' - このフォームで使用したいテンプレート。指定したテンプレートは、 既に読み込まれたテンプレートの上にマージされます。 /config のファイル名 (拡張子を除く) か、 使用したいテンプレートの配列のいずれかを指定します。

• 'context' - フォームコンテキストクラスの追加オプション。(例えば、 EntityContext は、フォームのベースとなる特定の Table クラスを設定するための 'table' オプションを受け付けます。)

• 'idPrefix' - 生成された ID 属性のプレフィックス。

• 'templateVars' - formStart テンプレートのためのテンプレート変数を提供することができます。

• autoSetCustomValidity - コントロールの HTML5 検証メッセージでカスタム必須および notBlank 検証メッセージを使用するには、 true を設定します。デフォルトは false です。

クエリー文字列からフォームの値を取得¶

FormHelper の値ソースは、input タグなどの描画される要素がどこから値を受け取るかを定義します。

デフォルトでは、FormHelper は、「コンテキスト」をもとにその値を描画します。 EntityContext などのデフォルトのコンテキストは、現在のエンティティーや $request->getData() からデータを取得します。

しかし、クエリー文字列から読み込む必要があるフォームを構築している場合は、 FormHelper の valueSource() を使って、どこから入力データを読み込むかを変更できます。

// コンテキストでクエリー文字列の優先順位をつける
echo $this->Form->create($article, [
    'type' => 'get',
    'valueSources' => ['query', 'context']
]);

// 同じ効果:
echo $this->Form
    ->setValueSources(['query', 'context'])
    ->create($articles, ['type' => 'get']);

When input data has to be processed by the entity, i.e. marshal transformations, table query result or entity computations, and displayed after one or multiple form submissions where request data is retained, you need to put context first:

// Prioritize context over request data:
echo $this->Form->create($article,
    'valueSources' => ['context', 'data']
]);

サポートするソースは、 context, data そして query です。 単一または複数のソースを使用できます。 FormHelper によって生成されたウィジェットは 設定した順序でソースから値を集めます。

end() が呼ばれた時、値ソースはデフォルト (['context']) にリセットされます。

フォームの HTTP メソッドを変更¶

type オプションを使用することにより、フォームが使用する HTTP メソッドを変更することができます。

echo $this->Form->create($article, ['type' => 'get']);

出力結果:

<form method="get" action="/articles/edit/5">

type の値に 'file' を指定すると、フォームの送信方法は、'POST' に変更し、form タグに "multipart/form-data" の enctype が含まれます。 これは、フォーム内部に file 要素がある場合に使用されます。 適切な enctype 属性が存在しない場合は、ファイルのアップロードが機能しない原因となります。

例:

echo $this->Form->create($article, ['type' => 'file']);

出力結果:

<form enctype="multipart/form-data" method="post" action="/articles/add">

'type' の値として 'put' 、 'patch' または 'delete' を使用すると、 フォームは機能的に 'post' フォームに相当しますが、送信されると、HTTP リクエストメソッドは、 それぞれ 'PUT'、 'PATCH' または 'DELETE' で上書きされます。 これで、CakePHP は、ウェブブラウザーで適切な REST サポートをエミュレートすることができます。

フォームの URL を設定¶

url オプションを使うと、フォームを現在のコントローラーやアプリケーションの別のコントローラーの 特定のアクションに向けることができます。

例えば、フォームを現在のコントローラーの publish() アクションに向けるには、次のような $options 配列を与えます。

echo $this->Form->create($article, ['url' => ['action' => 'publish']]);

出力結果:

<form method="post" action="/articles/publish">

目的のフォームアクションが現在のコントローラーにない場合は、フォームアクションの完全な URL を指定できます。 出力される URL は CakePHP アプリケーションに対する相対になります。

echo $this->Form->create(null, [
    'url' => [
        'controller' => 'Articles',
        'action' => 'publish'
    ]
]);

出力結果:

<form method="post" action="/articles/publish">

または外部ドメインを指定することができます。

echo $this->Form->create(null, [
    'url' => 'https://www.google.com/search',
    'type' => 'get'
]);

出力結果:

<form method="get" action="https://www.google.com/search">

フォームアクションに URL を出力したくない場合、 'url' => false を使用してください。

カスタムバリデーターの利用¶

多くの場合、モデルには複数の検証セットがあり、コントローラーアクションが適用される 特定の検証ルールに基づいて必要なフィールドに FormHelper を設定する必要があります。 たとえば、Users テーブルには、アカウントの登録時にのみ適用される特定の検証ルールがあります。

echo $this->Form->create($user, [
    'context' => ['validator' => 'register']
]);

上記では UsersTable::validationRegister() で定義されている register バリデーターの中で定義されたルールを $user と関連するすべてのアソシエーションに使用します。 関連付けられたエンティティーのフォームを作成する場合は、配列を使用して各アソシエーションの検証ルールを 定義できます。

echo $this->Form->create($user, [
    'context' => [
        'validator' => [
            'Users' => 'register',
            'Comments' => 'default'
        ]
    ]
]);

上記は、ユーザーには register 、そしてユーザーのコメントには default を使用します。

コンテキストクラスの作成¶

組み込みのコンテキストクラスは基本的なケースをカバーすることを目的としていますが、 異なる ORM を使用している場合は新しいコンテキストクラスを作成する必要があります。 このような状況では、 Cake\View\Form\ContextInterface を実装する必要があります。 このインターフェイスを実装すると、新しいコンテキストを FormHelper に追加することができます。 View.beforeRender イベントリスナーやアプリケーションビュークラスで行うのが最善の方法です。

$this->Form->addContextProvider('myprovider', function ($request, $data) {
    if ($data['entity'] instanceof MyOrmClass) {
        return new MyProvider($request, $data);
    }
});

コンテキストのファクトリー関数では、正しいエンティティータイプのフォームオプションを確認するための ロジックを追加できます。一致する入力データが見つかった場合は、オブジェクトを返すことができます。 一致するものがない場合は null を返します。

フィールドの命名規則¶

コントロールウィジェットを作成するときは、フィールドの名前をフォームのエンティティーに一致する属性の後に 指定する必要があります。たとえば、 $article エンティティーのフォームを作成した場合、 そのプロパティーの名前を付けたフィールドを作成します。例えば title 、 body と published 。

association.fieldname を最初のパラメーターとして渡すことで、関連するモデルや任意のモデルの コントロールを作成できます。

echo $this->Form->control('association.fieldname');

フィールド名のドットは、ネストされたリクエストデータに変換されます。 たとえば、 0.comments.body という名前のフィールドを作成した場合、 0[comments][body] のような名前属性が得られます。 この規則により、ORM でデータを簡単に保存できます。 さまざまなアソシエーションタイプの詳細は、 関連データの入力を作成 セクションにあります。

datetime に関連するコントロールを作成する場合、FormHelper はフィールドのサフィックスを追加します。 year 、 month 、 day 、 hour 、 minute 、または meridian というフィールドが追加されていることがあります。エンティティーがマーシャリングされると、 これらのフィールドは自動的に DateTime オブジェクトに変換されます。

コントロールのオプション¶

FormHelper::control() は、その $options 引数を通して、多数のオプションをサポートしています。 control() 自身のオプションに加えて、生成されたコントロールタイプに対するオプションと HTML 属性を受け付けます。以下は FormHelper::control() で特有のオプションについて説明します。

• $options['type'] - 生成するためのウィジェットタイプを指定する文字列。 フォームコントロールの作成 にあるフィールド型に加えて、 'file' 、 'password' 、 および HTML5 でサポートされているすべてのタイプを作成することもできます。 'type' を指定することで、モデルの設定を上書きして、コントロールのタイプを強制することができます。 デフォルトは null 。

  例:

  echo $this->Form->control('field', ['type' => 'file']);
  echo $this->Form->control('email', ['type' => 'email']);
  

  出力結果:

  <div class="input file">
      <label for="field">Field</label>
      <input type="file" name="field" value="" id="field" />
  </div>
  <div class="input email">
      <label for="email">Email</label>
      <input type="email" name="email" value="" id="email" />
  </div>
  

• $options['label'] - 文字列の見出しや ラベルのオプション の配列。 このキーは、通常は input HTML 要素に付随するラベル内に表示したい文字列に設定することができます。 デフォルトは null です。

  例:

  echo $this->Form->control('name', [
      'label' => 'The User Alias'
  ]);
  

  出力結果:

  <div class="input">
      <label for="name">The User Alias</label>
      <input name="name" type="text" value="" id="name" />
  </div>
  

  あるいは、 label 要素の出力を無効にするには、このキーに false を設定します。

  例:

  echo $this->Form->control('name', ['label' => false]);
  

  出力結果:

  <div class="input">
      <input name="name" type="text" value="" id="name" />
  </div>
  

  これに配列を設定すると、 label 要素の追加オプションが提供されます。 これを行う場合、配列中の text キーを使ってラベルテキストをカスタマイズすることができます。

  例:

  echo $this->Form->control('name', [
      'label' => [
          'class' => 'thingy',
          'text' => 'The User Alias'
      ]
  ]);
  

  出力結果:

  <div class="input">
      <label for="name" class="thingy">The User Alias</label>
      <input name="name" type="text" value="" id="name" />
  </div>
  

• $options['options'] - ここには、アイテムの配列を引数として必要とする radio や select のようなウィジェットのために、生成される要素を含む配列を提供することができます (詳細は、 ラジオボタンの作成 と 選択ピッカーの作成 をご覧ください)。 デフォルトは、 null です。

• $options['error'] - このキーを使用すると、デフォルトのモデルエラーメッセージを 無効にすることができ、たとえば国際化メッセージを設定するために使用できます。 エラーメッセージの出力とフィールドクラスを無効にするには、 'error' キーを false に設定してください。デフォルトは null 。

  例:

  echo $this->Form->control('name', ['error' => false]);
  

  モデルのエラーメッセージを上書きするには、 元の検証エラーメッセージと一致するキーを持つ配列を使用します。

  例:

  $this->Form->control('name', [
      'error' => ['Not long enough' => __('This is not long enough')]
  ]);
  

  上記のように、モデルにある各検証ルールに対してエラーメッセージを設定することができます。 さらに、フォームに国際化メッセージを提供することもできます。

• $options['nestedInput'] - チェックボックスとラジオボタンで使用。 input 要素を label 要素の内側か外側に生成するかどうかを制御します。 control() がチェックボックスやラジオボタンを生成する時、これに false を設定して、 label 要素の外側に HTML の input 要素を強制的に生成することができます。

  一方、任意のコントロールタイプに対して、これを true に設定することで、 生成された input 要素をラベルの中に強制的に入れることができます。 これをラジオボタンで変更する場合は、デフォルトの radioWrapper テンプレートも変更する必要があります。生成されるコントロールタイプによっては、 デフォルトが true や false になります。

• $options['templates'] - この入力に使用するテンプレート。 指定したテンプレートは、既に読み込まれたテンプレートの上にマージされます。 このオプションは、ロードするテンプレートを含む /config のファイル名 (拡張子を除く) か、 使用するテンプレートの配列のいずれかです。

• $options['labelOptions'] - これを false に設定すると nestedWidgets の周りのラベルを無効にします。または、 label タグに提供される属性の配列を設定します。

• $options['readOnly'] - フォームにて、フィールドを readOnly に設定します。

  例:

  echo $this->Form->control('name', ['readonly' => true]);
  

特定のコントロールのための共通オプション¶

さまざまなコントロール要素メソッドは、共通のオプションをサポートしており、 使用されるフォームメソッドに応じて、 $options または $attributes 配列の引数の中に 指定する必要があります。これらのオプションはすべて、 control() でもサポートされています。 繰り返しを減らすために、すべてのコントロールメソッドで共有される共通オプションは次の通りです。

• 'id' - このキーを設定すると、コントロールの DOM id の値が強制的に設定されます。 これにより、設定可能な 'idPrefix' が上書きされます。

• 'default' コントロールフィールドのデフォルト値を設定します。 この値は、フォームに渡されるデータにそのフィールドに関する値が含まれていない場合 (または、一切データが渡されない場合) に使われます。 明示的なデフォルト値は、スキーマで定義されたデフォルト値を上書きします。

  使用例:

  echo $this->Form->text('ingredient', ['default' => 'Sugar']);
  

  select フィールドを持つ例（"Medium" サイズがデフォルトで選択されます）

  $sizes = ['s' => 'Small', 'm' => 'Medium', 'l' => 'Large'];
  echo $this->Form->select('size', $sizes, ['default' => 'm']);
  

  注釈

  checkbox をチェックする目的では default は使えません。その代わり、コントローラーで $this->request->getData() の中の値をセットするか、またはコントロールオプションの checked を true にします。

  デフォルト値への代入の際 false を使うのは注意が必要です。 false 値はコントロールフィールドのオプションを無効または除外するために使われます。 そのため 'default' => false では値を全く設定しません。 代わりに 'default' => 0 を使用してください。

• 'value' - コントロールフィールドに特定の値を設定するために使用します。 これは、Form、Entity、 request->getData() などのコンテキストから 注入される可能性のある値を上書きします。

  注釈

  コンテキストや valuesSource から値を取得しないようにフィールドを設定したい場合、 'value' を '' に設定する必要があります (もしくは null に設定) 。

上記のオプションに加えて、任意の HTML 属性を混在させることができます。 特に規定のないオプション名は HTML 属性として扱われ、生成された HTML のコントロール要素に反映されます。

テキスト入力の作成¶

Cake\View\Helper\FormHelper::text(string $name, array $options)¶

• $name - 'Modelname.fieldname' の形式のフィールド名。

• $options - 特定のコントロールのための共通オプション や有効な HTML 属性を含むオプション配列。

シンプルな text 型の input HTML 要素を作成します。

例:

echo $this->Form->text('username', ['class' => 'users']);

出力結果:

<input name="username" type="text" class="users">

パスワード入力の作成¶

Cake\View\Helper\FormHelper::password(string $fieldName, array $options)¶

• $fieldName - 'Modelname.fieldname' の形式のフィールド名。

• $options - 特定のコントロールのための共通オプション や有効な HTML 属性を含むオプション配列。

シンプルな password 型の input 要素を作成します。

例:

echo $this->Form->password('password');

出力結果:

<input name="password" value="" type="password">

非表示入力の作成¶

Cake\View\Helper\FormHelper::hidden(string $fieldName, array $options)¶

• $fieldName - 'Modelname.fieldname' の形式のフィールド名。

• $options - 特定のコントロールのための共通オプション や有効な HTML 属性を含むオプション配列。

非表示のフォーム入力を作成します。

例:

echo $this->Form->hidden('id');

出力結果:

<input name="id" type="hidden" />

テキストエリアの作成¶

Cake\View\Helper\FormHelper::textarea(string $fieldName, array $options)¶

• $fieldName - 'Modelname.fieldname' の形式のフィールド名。

• $options - 特定のコントロールのための共通オプション やテキストエリア特有のオプション (下記参照) と、有効な HTML 属性を含むオプション配列。

textarea コントロールフィールドを作成します。使用されるデフォルトのウィジェットテンプレートは、

'textarea' => '<textarea name="{{name}}"{{attrs}}>{{value}}</textarea>'

例:

echo $this->Form->textarea('notes');

出力結果:

<textarea name="notes"></textarea>

フォームが編集されると（すなわち、配列 $this->request->getData() に User モデルに渡すために保存された情報が含まれている場合）、生成される HTML には notes フィールドに対応する値が自動的に含まれます。

例:

<textarea name="notes" id="notes">
このテキストは編集されます。
</textarea>

テキストエリアのオプション

特定のコントロールのための共通オプション に加えて、 textarea() はいくつかの固有のオプションを サポートします。

• 'escape' - テキストエリアの内容をエスケープするかどうかを指定します。 デフォルトは true です。

  例:

  echo $this->Form->textarea('notes', ['escape' => false]);
  // もしくは....
  echo $this->Form->control('notes', ['type' => 'textarea', 'escape' => false]);
  

• 'rows', 'cols' - これらの2つのキーを使用して、 textarea フィールドの行数と列数を 指定する HTML 属性を設定することができます。

  例:

  echo $this->Form->textarea('comment', ['rows' => '5', 'cols' => '5']);
  

  出力結果:

  <textarea name="comment" cols="5" rows="5">
  </textarea>
  

セレクト、チェックボックス、ラジオコントロールの作成¶

これらのコントロールは、いくつかの共通点といくつかのオプションを共有し、 それらは簡単に参照するために、このサブセクションで全てグループ化します。

$options = $examples->combine('id', 'name');

$options = $examples->map(function ($value, $key) {
    return [
        'value' => $value->id,
        'text' => $value->name,
        'data-created' => $value->created
    ];
});

'checkbox' => '<input type="checkbox" name="{{name}}" value="{{value}}"{{attrs}}>'

echo $this->Form->checkbox('done');

<input type="hidden" name="done" value="0">
<input type="checkbox" name="done" value="1">

echo $this->Form->checkbox('done', ['value' => 555]);

<input type="hidden" name="done" value="0">
<input type="checkbox" name="done" value="555">

echo $this->Form->checkbox('done', ['hiddenField' => false]);

<input type="checkbox" name="done" value="1">

'radio' => '<input type="radio" name="{{name}}" value="{{value}}"{{attrs}}>'
'radioWrapper' => '{{label}}'

$this->Form->radio('gender', ['Masculine','Feminine','Neuter']);

<input name="gender" value="" type="hidden">
<label for="gender-0">
    <input name="gender" value="0" id="gender-0" type="radio">
    Masculine
</label>
<label for="gender-1">
    <input name="gender" value="1" id="gender-1" type="radio">
    Feminine
</label>
<label for="gender-2">
    <input name="gender" value="2" id="gender-2" type="radio">
    Neuter
</label>

echo $this->Form->radio(
    'favorite_color',
    [
        ['value' => 'r', 'text' => 'Red', 'style' => 'color:red;'],
        ['value' => 'u', 'text' => 'Blue', 'style' => 'color:blue;'],
        ['value' => 'g', 'text' => 'Green', 'style' => 'color:green;'],
    ]
);

<input type="hidden" name="favorite_color" value="">
<label for="favorite-color-r">
    <input type="radio" name="favorite_color" value="r" style="color:red;" id="favorite-color-r">
    Red
</label>
<label for="favorite-color-u">
    <input type="radio" name="favorite_color" value="u" style="color:blue;" id="favorite-color-u">
    Blue
</label>
<label for="favorite-color-g">
    <input type="radio" name="favorite_color" value="g" style="color:green;" id="favorite-color-g">
    Green
</label>

'select' => '<select name="{{name}}"{{attrs}}>{{content}}</select>'
'option' => '<option value="{{value}}"{{attrs}}>{{text}}</option>'

'optgroup' => '<optgroup label="{{label}}"{{attrs}}>{{content}}</optgroup>'
'selectMultiple' => '<select name="{{name}}[]" multiple="multiple"{{attrs}}>{{content}}</select>'

echo $this->Form->select('field', [1, 2, 3, 4, 5]);

<select name="field">
    <option value="0">1</option>
    <option value="1">2</option>
    <option value="2">3</option>
    <option value="3">4</option>
    <option value="4">5</option>
</select>

echo $this->Form->select('field', [
    'Value 1' => 'Label 1',
    'Value 2' => 'Label 2',
    'Value 3' => 'Label 3'
]);

<select name="field">
    <option value="Value 1">Label 1</option>
    <option value="Value 2">Label 2</option>
    <option value="Value 3">Label 3</option>
</select>

$options = [
    'Group 1' => [
        'Value 1' => 'Label 1',
        'Value 2' => 'Label 2'
    ],
    'Group 2' => [
        'Value 3' => 'Label 3'
    ]
];
echo $this->Form->select('field', $options);

<select name="field">
    <optgroup label="Group 1">
        <option value="Value 1">Label 1</option>
        <option value="Value 2">Label 2</option>
    </optgroup>
    <optgroup label="Group 2">
        <option value="Value 3">Label 3</option>
    </optgroup>
</select>

$options = [
    [ 'text' => 'Description 1', 'value' => 'value 1', 'attr_name' => 'attr_value 1' ],
    [ 'text' => 'Description 2', 'value' => 'value 2', 'attr_name' => 'attr_value 2' ],
    [ 'text' => 'Description 3', 'value' => 'value 3', 'other_attr_name' => 'other_attr_value' ],
];
echo $this->Form->select('field', $options);

<select name="field">
    <option value="value 1" attr_name="attr_value 1">Description 1</option>
    <option value="value 2" attr_name="attr_value 2">Description 2</option>
    <option value="value 3" other_attr_name="other_attr_value">Description 3</option>
</select>

ファイル入力の作成¶

Cake\View\Helper\FormHelper::file(string $fieldName, array $options)¶

• $fieldName - 'Modelname.fieldname' の形式のフィールド名。

• $options - 特定のコントロールのための共通オプション や有効な HTML 属性を含むオプション配列。

フォームの中にファイルアップロードフィールドを作成します。 デフォルトで使用されるウィジェットテンプレートは:

'file' => '<input type="file" name="{{name}}"{{attrs}}>'

フォームにファイルアップロードフィールドを追加するためには、まずフォームの enctype に 'multipart/form-data' がセットされていることを確認してください。

まずは、次のように create() メソッドを使用してください。

echo $this->Form->create($document, ['enctype' => 'multipart/form-data']);
// または
echo $this->Form->create($document, ['type' => 'file']);

次にフォームのビューファイルに以下のいずれかを追加します。

echo $this->Form->control('submittedfile', [
    'type' => 'file'
]);

// または
echo $this->Form->file('submittedfile');

フォームの送信に際して file フィールドは、フォームを受信しようとしているスクリプトに対して拡張された data 配列を提供します。

CakePHP が Windows サーバー上にインストールされている場合、上記の例について、 送信されるデータ配列内の値は次のように構成されます (Unix 環境では 'tmp_name' が異なったパスになります)。

$this->request->data['submittedfile']

// 次の配列を含みます:
[
    'name' => 'conference_schedule.pdf',
    'type' => 'application/pdf',
    'tmp_name' => 'C:/WINDOWS/TEMP/php1EE.tmp',
    'error' => 0, // Windows の場合、文字列になります。
    'size' => 41737,
];

この配列は PHP 自身によって生成されます。PHP が file フィールドを通してデータを どう処理しているのかについては、 PHP マニュアルのファイルアップロードのセクションをご覧ください 。

日付と時刻に関するコントロールの作成¶

日時関連の方法は、多くの共通の特性とオプションを共有しているため、 このサブセクションにまとめられています。

{{year}}{{month}}{{day}}{{hour}}{{minute}}{{second}}{{meridian}}

<?= $this->form->dateTime('registered') ?>

<select name="registered[year]">
    <option value="" selected="selected"></option>
    <option value="2022">2022</option>
    ...
    <option value="2012">2012</option>
</select>
<select name="registered[month]">
    <option value="" selected="selected"></option>
    <option value="01">January</option>
    ...
    <option value="12">December</option>
</select>
<select name="registered[day]">
    <option value="" selected="selected"></option>
    <option value="01">1</option>
    ...
    <option value="31">31</option>
</select>
<select name="registered[hour]">
    <option value="" selected="selected"></option>
    <option value="00">0</option>
    ...
    <option value="23">23</option>
</select>
<select name="registered[minute]">
    <option value="" selected="selected"></option>
    <option value="00">00</option>
    ...
    <option value="59">59</option>
</select>

<?= $this->form->dateTime('registered', ['value' => new DateTime()]) ?>

<input type="datetime-local" name="registered" value="2019-02-08T18:20:10" />

// 今年が 2017 年だと仮定すると、これは日ピッカーを無効にし、年ピッカーの空の
// オプションを削除し、最低年を制限し、年の HTML 属性を追加し、
// 月の文字列の 'empty' オプションを追加し、月を数値に変更します。
<?php
    echo $this->Form->date('registered', [
        'minYear' => 2018,
        'monthNames' => false, // 月は数字で表示されます。
        'empty' => [
            'year' => false, // 年選択コントロールは空の値のオプションを持ちません。
            'month' => 'Choose month...' // しかしながら、月選択コントロールは持ちます。
        ],
        'day' => false, // 日付選択コントールを表示しない。
        'year' => [
            'class' => 'cool-years',
            'title' => 'Registration Year'
        ]
    ]);
?>

<input type="date" name="registered" />

echo $this->Form->time('released', [
    'interval' => 15,
    'hour' => [
        'class' => 'foo-class',
    ],
    'minute' => [
        'class' => 'bar-class',
    ],
]);

echo $this->Form->time('released');

echo $this->Form->year('purchased', [
    'min' => 2000,
    'max' => date('Y')
]);

<input type="time" name="released" />

echo $this->Form->month('mob');

<input type="month" name="mob" />

echo $this->Form->hour('created', [
    'format' => 12
]);
echo $this->Form->hour('created', [
    'format' => 24
]);

// ビューテンプレートファイルの中で
echo $this->Form->minute('arrival', [
    'interval' => 10
]);

<select name="purchased">
    <option value=""></option>
    <option value="2009">2009</option>
    <option value="2008">2008</option>
    <option value="2007">2007</option>
    <option value="2006">2006</option>
    <option value="2005">2005</option>
    <option value="2004">2004</option>
    <option value="2003">2003</option>
    <option value="2002">2002</option>
    <option value="2001">2001</option>
    <option value="2000">2000</option>
</select>

エラーの表示¶

Cake\View\Helper\FormHelper::error(string $fieldName, mixed $text, array $options)¶

• $fieldName - 'Modelname.fieldname' の形式のフィールド名。

• $text - オプション。エラーメッセージを提供する文字列または配列。 配列の場合、 キー名 => メッセージのハッシュになります。デフォルトは null 。

• $options - 'escape' キーのブール値のみを含みます。これは、 エラーメッセージの内容を HTML エスケープするかどうかを定義します。デフォルトは true です。

検証エラーが発生した際に、与えられたフィールドの $text で指定された、 検証エラーメッセージを表示します。フィールドの $text がない場合、 そのフィールドのデフォルトの検証エラーメッセージが使用されます。

次のテンプレートウィジェットを使います。

'error' => '<div class="error-message">{{content}}</div>'
'errorList' => '<ul>{{content}}</ul>'
'errorItem' => '<li>{{text}}</li>'

'errorList' と 'errorItem' テンプレートは、１つのフィールドに複数の エラーメッセージを書式化するために使用されます。

例:

// TicketsTable に 'notEmptyString' 検証ルールがある場合:
public function validationDefault(Validator $validator)
{
    $validator
        ->requirePresence('ticket', 'create')
        ->notEmptyString('ticket');
}

// そして、 templates/Tickets/add.php の中が次のような場合:
echo $this->Form->text('ticket');

if ($this->Form->isFieldError('ticket')) {
    echo $this->Form->error('ticket', 'Completely custom error message!');
}

もし、 Ticket フィールドの値を指定せずにフォームの Submit ボタンをクリックした場合、 フォームは次のように出力されます。

<input name="ticket" class="form-error" required="required" value="" type="text">
<div class="error-message">Completely custom error message!</div>

エラーの確認¶

Cake\View\Helper\FormHelper::isFieldError(string $fieldName)¶

• $fieldName - 'Modelname.fieldname' の形式のフィールド名。

指定された $fieldName に有効な検証エラーがある場合は true を返します。 そうでなければ fales を返します。

例:

if ($this->Form->isFieldError('gender')) {
    echo $this->Form->error('gender');
}

Submit 要素の作成¶

Cake\View\Helper\FormHelper::submit(string $caption, array $options)¶

• $caption - ボタンのテキスト見出しまたは画像へのパスを提供するオプション文字列。 デフォルトは、 'Submit' です。

• $options - 特定のコントロールのための共通オプション 、または submit 特有のオプション (下記参照) 。

$caption を値としてもつ submit タイプの input 要素を作成します。 指定された $caption が画像の URL である場合 (つまり、 '://' を含む文字列または、拡張子 '.jpg, .jpe, .jpeg, .gif' を含む場合)、画像の送信ボタンが生成され、指定された画像が 存在する場合は、それを使用します。最初の文字が '/' の場合、画像は webroot からの 相対パスになり、最初の文字が '/' ではない場合、画像は webroot/img からの相対パスになります。

デフォルトで次のウィジェットテンプレートを使用します。

'inputSubmit' => '<input type="{{type}}"{{attrs}}/>'
'submitContainer' => '<div class="submit">{{content}}</div>'

Submit のオプション

• 'type' - リセットボタンを生成するためにこのオプションに 'reset' を設定します。 デフォルトは 'submit' です。

• 'templateVars' - input 要素や、そのコンテナーにテンプレート変数を追加するために、 この配列を設定します。

• その他の指定された属性は input 要素に割り当てられます。

例:

echo $this->Form->submit('Click me');

出力結果:

<div class="submit"><input value="Click me" type="submit"></div>

見出しテキストの代わりに見出しパラメーターとして画像への相対 URL または 絶対 URL を渡すことができます。

echo $this->Form->submit('ok.png');

出力結果:

<div class="submit"><input type="image" src="/img/ok.png"></div>

submit 入力は、基本的なテキストやイメージが必要な場合に便利です。 より複雑なボタンの内容が必要な場合は、 button() を使用してください。

ボタン要素の作成¶

Cake\View\Helper\FormHelper::button(string $title, array $options = [])¶

• $title - ボタンの見出しテキストを提供する必須の文字列。

• $options - 特定のコントロールのための共通オプション やボタン特有のオプション (下記参照)と 有効な HTML 属性を含むオプション配列。

指定されたタイトルと 'button' のデフォルトタイプの HTML ボタンを作成します。

ボタンのオプション

• 'type' - これを設定すると、次の3つの button タイプのどれかが出力されます。

  1. 'submit' - $this->Form->submit() と同様に送信ボタンを作成します。 しかしながら、 submit() のように div の囲い込みは生成しません。 これがデフォルトのタイプです。

  2. 'reset' - フォームのリセットボタンを作成します。

  3. 'button' - 標準の押しボタンを作成します。

• 'escapeTitle' - ブール値。 true をセットした場合、 $title で指定された値を HTML エンコードします。デフォルトは true です。

• 'escape' - ブール値。 true に設定すると、 ボタンに対して生成されたすべてのHTML属性をHTMLエンコードします。 デフォルトは true です。

• 'confirm' - クリック時に表示される確認メッセージ。デフォルトは null です。

例:

echo $this->Form->button('ボタン');
echo $this->Form->button('別のボタン', ['type' => 'button']);
echo $this->Form->button('フォームのリセット', ['type' => 'reset']);
echo $this->Form->button('フォームの送信', ['type' => 'submit']);

出力結果:

<button type="submit">ボタン</button>
<button type="button">別のボタン</button>
<button type="reset">フォームのリセット</button>
<button type="submit">フォームの送信</button>

'escapeTitle' オプションの使用例:

// エスケープされていないHTMLをレンダリングします。
echo $this->Form->button('<em>Submit Form</em>', [
    'type' => 'submit',
    'escapeTitle' => false,
]);

POST ボタンの作成¶

Cake\View\Helper\FormHelper::postButton(string $title, mixed $url, array $options = [])¶

• $title - ボタンの見出しテキストを提供する必須の文字列。 デフォルトでは HTML エンコードされません。

• $url - 文字列や配列として提供される URL。

• $options - 特定のコントロールのための共通オプション 、特定のオプション（下記参照）と 有効な HTML 属性を含むオプション配列。

デフォルトでは、POST で送信する <form> 要素で囲まれた <button> タグを作成します。 また、デフォルトでは、SecurityComponent のために非表示入力フィールドも生成します。

POST ボタンのオプション

• 'data' - hidden 入力に渡すキーと値の配列。

• 'method' - 使用するリクエスト方法。例えば、 'delete' をセットすると、 HTTP/1.1 DELETE リクエストをシミュレートします。デフォルトは 'post' です。

• 'form' - FormHelper::create() に渡す任意のオプションの配列。

• また、 postButton() メソッドは、 button() メソッドで有効なオプションも受け付けます。

例:

// templates/Tickets/index.php の中で
<?= $this->Form->postButton('Delete Record', ['controller' => 'Tickets', 'action' => 'delete', 5]) ?>

出力結果:

<form method="post" accept-charset="utf-8" action="/Rtools/tickets/delete/5">
    <div style="display:none;">
        <input name="_method" value="POST" type="hidden">
    </div>
    <button type="submit">Delete Record</button>
    <div style="display:none;">
        <input name="_Token[fields]" value="186cfbfc6f519622e19d1e688633c4028229081f%3A" type="hidden">
        <input name="_Token[unlocked]" value="" type="hidden">
        <input name="_Token[debug]" value="%5B%22%5C%2FRtools%5C%2Ftickets%5C%2Fdelete%5C%2F1%22%2C%5B%5D%2C%5B%5D%5D" type="hidden">
    </div>
</form>

このメソッドは form 要素を作成します。 なので、開かれたフォームの中でこのメソッドを使用しないでください。 代わりに Cake\View\Helper\FormHelper::submit() または Cake\View\Helper\FormHelper::button() を使用して、 開かれたフォームの中でボタンを作成してください。

POST リンクの作成¶

Cake\View\Helper\FormHelper::postLink(string $title, mixed $url = null, array $options = [])¶

• $title - <a> タグに囲まれたテキストを提供する必須の文字列。

• $url - オプション。フォームの URL (相対 URL 、または http:// で始まる外部 URL) を含む文字列または配列。

• $options - 特定のコントロールのための共通オプション 、特有のオプション（下記参照）と 有効な HTML 属性を含むオプション配列。

HTML リンクを作成しますが、指定した方法 (デフォルトは POST)で URL にアクセスします。 ブラウザーで有効にするには JavaScript が必要です。

POST リンクのオプション

• 'data' - hidden 入力に渡すキーと値の配列。

• 'method' - 使用するリクエスト方法。例えば、 'delete' をセットすると、 HTTP/1.1 DELETE リクエストをシミュレートします。デフォルトは 'post' です。

• 'confirm' - クリック時に表示される確認メッセージ。デフォルトは null です。

• 'block' - ビューブロック 'postLink' へフォームの追加するために このオプションに true をセットしたり、カスタムブロック名を指定します。 デフォルトは null です。

• また、 postLink メソッドは、 link() メソッドの有効なオプションを受け付けます。

このメソッドは <form> 要素を作成します。 このメソッドを既存のフォームの中で使いたい場合は、 block オプションを使用して、 新しいフォームがメインフォームの外部でレンダリング可能な ビューブロック に設定されるようにする必要があります。

あなたが探しているものがフォームを送信するボタンであれば、代わりに Cake\View\Helper\FormHelper::button() または Cake\View\Helper\FormHelper::submit() を使用してください。

テンプレート一覧¶

デフォルトのテンプレートのリスト、それらのデフォルトのフォーマット、そして期待される変数は FormHelper API ドキュメント で見つけることができます。

// 独自の HTML で囲まれた radio を追加
$this->Form->templates([
    'radioContainer' => '<div class="form-radio">{{content}}</div>'
]);

// 独自の div で囲まれた radio セットを作成
echo $this->Form->control('email_notifications', [
    'options' => ['y', 'n'],
    'type' => 'radio'
]);

// 独自の radio フォームグループを追加
$this->Form->setTemplates([
    'radioFormGroup' => '<div class="radio">{{label}}{{input}}</div>'
]);

テンプレートにテンプレート変数を追加¶

カスタムテンプレートにテンプレートプレースホルダを追加し、 コントロールを生成するときにプレースホルダを設定することができます。

例:

// help プレースホルダ付きでテンプレートを追加
$this->Form->setTemplates([
    'inputContainer' => '<div class="input {{type}}{{required}}">
        {{content}} <span class="help">{{help}}</span></div>'
]);

// help 変数を設定し入力を生成
echo $this->Form->control('password', [
    'templateVars' => ['help' => '少なくとも 8 文字の長さ。']
]);

出力結果:

<div class="input password">
    <label for="password">
        Password
    </label>
    <input name="password" id="password" type="password">
    <span class="help">少なくとも 8 文字の長さ。</span>
</div>

チェックボックスとラジオのラベル外への移動¶

デフォルトでは、CakePHP は、 control() で作成されたチェックボックスと control() と radio() の両方で作成されたラジオボタンをラベル要素内でネストします。 これにより、人気の CSS フレームワークとの統合に役立ちます。 ラベルの外に checkbox/radio 入力を配置する必要がある場合は、 テンプレートを変更することで行うことができます。

$this->Form->setTemplates([
    'nestingLabel' => '{{hidden}}{{input}}<label{{attrs}}>{{text}}</label>',
    'formGroup' => '{{input}}{{label}}',
]);

これにより、ラジオボタンとチェックボックスがラベルの外側に描画されます。

複数のコントロールの作成¶

Cake\View\Helper\FormHelper::controls(array $fields = [], $options = [])¶

• $fields - 生成するフィールドの配列。指定した各フィールドのカスタムタイプ、 ラベル、その他のオプションを設定できます。

• $options - オプション。オプションの配列。有効なキーは:

  1. 'fieldset' - filedset を無効にするために false を設定してください。 空の配列を渡すと、fieldset は有効になります。 HTML 属性として適用するパラメーターの配列を fieldset タグに渡すこともできます。

  2. legend - legend のテキストをカスタマイズするための文字列。 生成された入力セットの legend を無効にするために false を設定してください。

fieldset で囲まれた指定された一連のコントロールセットを生成します。 生成されたフィールドを含めることで指定できます。

echo $this->Form->controls([
    'name',
    'email'
]);

オプションを使用して legend のテキストをカスタマイズすることができます。

echo $this->Form->controls($fields, ['legend' => 'Update news post']);

$fields パラメーターで追加のオプションを定義することによって、 生成されたコントロールをカスタマイズすることができます。

echo $this->Form->controls([
    'name' => ['label' => 'カスタムラベル']
]);

$fields をカスタマイズする場合、生成された legend/fieldset を制御するために $options パラメーターを使用することができます。

例えば:

echo $this->Form->controls(
    [
        'name' => ['label' => 'カスタムラベル']
    ],
    ['legend' => 'Update your post']
);

fieldset を無効にすると、 legend は出力されません。

エンティティー全体のコントロールを作成¶

Cake\View\Helper\FormHelper::allControls(array $fields, $options = [])¶

• $fields - オプション。生成するフィールドのカスタマイズ配列。 カスタムタイプ、ラベル、その他のオプションを設定できます。

• $options - オプション。オプションの配列。有効なキーは:

  1. 'fieldset' - これに false を設定すると fieldset が無効になります。 空の場合、fieldset は有効になります。パラメーターの配列を渡すと、 fieldset の HTML 属性として適用されます。

  2. legend - legend テキストをカスタマイズするための文字列。 これに false を設定すると、生成されたコントロールセットの legend が無効になります。

このメソッドは controls() と密接に関係していますが、 $fields 引数は 現在のトップレベルエンティティーの 全ての フィールドにデフォルト設定されています。 生成されたコントロールから特定のフィールドを除外するには、 $fields パラメーターで false を設定します。

echo $this->Form->allControls(['password' => false]);
// 3.4.0 より前の場合:
echo $this->Form->allInputs(['password' => false]);