これは Craft CMS Advent Calendar 2017 25日目の記事です。
前回 に引き続き、 a&m forms プラグインでのフォーム作成の流れについて解説してみます。
フォーム作成の流れ
a&m forms プラグインでフォームを作成するには、大きく3つの工程が必要です。
- フォーム専用フィールドの作成
- フォームの作成と初期設定
- テンプレートの調整
順番に見ていきましょう。
フォーム専用フィールドを作成する
管理メニューの a&m forms > フィールド に移動し、フォーム専用フィールドを作成・編集します。
各フォームに必要なものだけフィールドレイアウト画面で配置できるため、似たような入力項目を一元管理できるのが便利ですね。
では 新規フィールド ボタンをクリックし、フィールドを作成してみましょう。
それぞれの設定内容は、以下の通りです。
「お名前」フィールド
| ラベル | 値 |
|---|---|
| 名前 | お名前 |
| ハンドル | customerName |
| フィールドタイプ | プレーンテキスト |
「メールアドレス」フィールド
| ラベル | 値 |
|---|---|
| 名前 | メールアドレス |
| ハンドル | customerEmail |
| フィールドタイプ |
「メッセージ」フィールド
| ラベル | 値 |
|---|---|
| 名前 | メッセージ |
| ハンドル | message |
| フィールドタイプ | プレーンテキスト |
| 改行を許可する | ON |
| 最初の行 | 4 |
なお、Craft CMS 標準のフィールドタイプに加えて
- E-mail
メールアドレス用のフィールドです。自動返信メールの送信先に指定できます。 - Hidden
不可視項目用のフィールドです。 - Form
a&m formsプラグインで作成したフォームの選択用フィールドです。 - Form Submission
フォームの受信データの選択用フィールドです。
が追加されていますので、必要に応じて利用しましょう。
フォームを作成する
管理メニューの a&m forms > Forms に移動し、 New form ボタンをクリックします。
フォームの編集画面には5つのタブがありますので、それぞれの項目の概要を列挙します。
一般
フォームに関する基本設定です。
| ラベル | 値 |
|---|---|
| 名前 | フォームの名称です。 |
| ハンドル | 半角英数でハンドル名を指定します。 |
| Display tab titles | フィールドレイアウトで複数のタブを作成している場合、ここが ON であればタブのタイトルが出力されます。 |
| Custom submit button text | テンプレートの送信ボタンのテキストが {{ submitValue }} である場合、ここで入力した文字列に置き換えます。 |
| After submission | 送信後の処理を指定します。（詳しくは、後述） |
| Text after submit | After submission の選択状況に応じて、変化する付帯項目です。（詳しくは、後述） |
| Save submissions | ON であれば、受信データをデータベースに保存します。 |
| Title format | 受信データのタイトルを指定します。 |
After submission について
フォーム送信時の処理は、以下の4つから選択できます。
| プルダウンの項目名 | 付帯項目 | 概要 |
|---|---|---|
| Redirect to same page and show text | Text after submit | 同一ページにリダイレクトし、テキストを表示します。 URL パラメータ submitted の有無で分岐できます。 |
| Redirect to a page | Redirect page | 選択したエントリの URL にリダイレクトします。 |
| Redirect to a URL | Redirect URL | リダイレクト先の URL を直接指定します。 |
| Submit form to a different URL | Submit action URL | フォームの action の URL を直接指定できます。 |
フィールド
フォームの入力項目に関する設定です。
従来のセクションのフィールドレイアウトと同様の操作で、必要なフィールドをドラッグ＆ドロップで配置します。
上段のタブに配置したフィールドは、Edit アイコンで必須項目にしたり、削除したりできます。
Notifications
フォーム送信時の通知メールに関する設定です。
| ラベル | 値 |
|---|---|
| Send notifications | ここが ON であれば、管理者向け通知メールが送信されます。 |
| Send confirmation | ここが ON であれば、自動返信メールが送信されます。 |
| Send confirmation to | フィールド タブでセットされた E-mail タイプのフィールドを選択します。 |
| Add attachments with notifications | ここが ON であれば、通知メールに添付ファイルが含まれるようになります。 |
| Email recipients | 管理者向け通知メールの受信先を指定します。 |
| Notification subject | 管理者向け通知メールの件名を指定します。 |
| Sender name notification email | 管理者向け通知メールの送信者名を指定します。 |
| Sender email address notification email | 管理者向け通知メールの送信者メールアドレスを指定します。 |
| Reply to email address | 管理者向け通知メールの返信先メールアドレスを指定します。 |
| Confirmation subject | 自動返信メールの件名を指定します。 |
| Sender name confirmation email | 自動返信メールの送信者名を指定します。 |
| Sender email address confirmation email | 自動返信メールの送信者メールアドレスを指定します。 |
Templates
フォーム表示用のテンプレートを craft/templates 下層にある任意のテンプレートで上書きします。
| ラベル | 値 |
|---|---|
| Form template | displayForm() で出力されるフォーム全体のテンプレートを指定します。 |
| Tab template | フォームの設定で Display tab titles が ON の場合に displayForm() で出力されるタブタイトル部分のテンプレートを指定します。 |
| Field template | displayField() で出力されるフィールド部分のテンプレートを指定します。 |
| Notification template | 管理者向け通知メールのテンプレートを指定します。 |
| Confirmation template | 自動返信メールのテンプレートを指定します。 |
このタブや a&m forms > 設定 > Templates でテンプレートのパスが指定されていない場合は、プラグインデフォルトのテンプレートで出力されます。
Used at
フォームを埋め込んでいるエントリの一覧が表示されます。
a&m forms プラグインをインストールした時点で追加されるForm フィールドタイプを選択し、標準機能のフィールドを作成します。
これを任意のセクションのフィールドレイアウトで配置します。
あとはエントリの編集画面で埋め込むフォームを選択すれば、対象フォームの Used at タブから参照できるようになります。
テンプレートを調整する
プラグインが持っている表示用テンプレートの構成を知っておきましょう。
craft/plugins/amforms/templates/_display/templates
├── _includes
│ └── forms # フィールド別マークアップの格納ディレクトリ
│ ├── checkbox.html # 「チェックボックス」フィールドのマークアップ
│ ├── （中略）
│ └── time.html # 「日/時（時間のみ）」フィールドのマークアップ
├── confirmation.twig # 「Confirmation template」で置き換わる自動返信メール本文のテンプレート
├── email.twig # デフォルトの通知メール本文用テンプレート
├── field.twig # 「Field template」で置き換わるフィールド部分のテンプレート
├── form.twig # 「Form template」で置き換わるフォーム全体のテンプレート
├── forms.twig # フォーム全般に関わる macro の定義ファイル
├── notification.twig # 「Notification template」で置き換わる管理者向け通知メール本文のテンプレート
└── tab.twig # 「Tab template」で置き換わるタブタイトル部分のテンプレートTemplates の設定画面でパスを指定する場合、あらかじめ amforms/templates/_display/templates から対応するデフォルトテンプレートをコピーしてカスタマイズすると効率的です。
あとは、任意のテンプレートにタグを記述してフォームを表示してみましょう。
{{ craft.amForms.displayForm('フォームのハンドル名') }}なお、フィールドごとのマークアップを変更する場合は、同ディレクトリに含まれる _includes/forms 下層の HTML ファイルで調整できます。ただし、プラグインのアップデート時に上書きされてしまう可能性があるため、_includes/forms を任意の名称で複製しつつ forms.twig 内に記述されたインクルード用のパスを書き換える方がよいかもしれません。
この件については最近 Issue も上がっているため、将来的にプラグインの基本機能として代替テンプレートを用意できる仕組みが追加されることを（勝手に）期待しています。
Change default field templates · Issue #167 · am-impact/amforms
https://github.com/am-impact/amforms/issues/167
まとめ
今回は a&m forms プラグインでフォームを作成するポイントについてまとめてみました。
取っ掛かりは難しいと感じられるかもしれませんが、柔軟にフォームを用意できるようになりますので、興味のある方はぜひお試しください。