フロントエンドのフォーム
Form プラグインによって、フロントエンドに表示するどんなフォームでも作れます。これは、ページで利用できる、フォーム制作キットです。先へ進む前に、もしまだなら、 Form プラグイン を忘れずにインストールしておいてください。bin/gpm install form
により実行可能です。
どのように Form プラグインが機能するかを理解するため、シンプルなフォームの制作から始めましょう。
[!Warning]
From 2.0 のリリース以降、hidenフィールドとして フォームの名前 をパスする必要があります。form プラグインが提供するforms.html.twig
を使っている場合は、自動的に適用されていますが、テーマや別プラグインでデフォルトのforms.html.twig
を上書きしている場合は、レンダリングする Twig ファイルに、手作業で{% include "forms/fields/formname/formname.html.twig" %}
を追記する必要があります。
シンプルな1つのフォームを作る
ページにフォームを追加するには、ページを作り、ページファイルに “フォーム” を設定します。これは管理パネルからできますし、form.md
という名前のページで、ファイルシステムから直接することもできます。
では、具体例として、 user/pages/03.your-form/form.md
を考えてみましょう。
このページのコンテンツは、次のようになります:
---
title: "フォーム例付きのページ"
form:
name: contact-form
fields:
name:
label: Name
placeholder: Enter your name
autofocus: on
autocomplete: on
type: text
validate:
required: true
email:
label: Email
placeholder: Enter your email address
type: email
validate:
required: true
buttons:
submit:
type: submit
value: Submit
reset:
type: reset
value: Reset
process:
email:
from: "{{ config.plugins.email.from }}"
to:
- "{{ config.plugins.email.to }}"
- "{{ form.value.email }}"
subject: "[Feedback] {{ form.value.name|e }}"
body: "{% include 'forms/data.html.twig' %}"
save:
fileprefix: feedback-
dateformat: Ymd-His-u
extension: txt
body: "{% include 'forms/data.txt.twig' %}"
message: Thank you for your feedback!
display: thankyou
---
# 私のフォーム
通常の **マークダウン** コンテンツは、ここに書いてください...
[!Tip]
この例は、ファイルシステムから見たときのform.md
ファイルのコンテンツです。管理パネルからする場合は、 Expert Mode でページを開き、3つのダッシュ---
の間の部分をコピーし、フロントマターに貼り付けてください。
これで、ページコンテンツの後に、フォームが表示されます。名前と、Eメールフィールドと、2つのボタン(1つは送信用、もう1つはリセット用)を持つシンプルなフォームです。利用可能なフィールドに関するより詳しい情報は、この後のセクションを見てください。
送信
ボタンを押すと、何が起こるでしょう? process
に書いたアクションを、順番に実行します。この他のアクションについては、アクションのリファレンス を見ていただくか、自身で作ることもできます 。
-
[Feedback] {{ フォームに入力された名前 }}
という題名のメールを送信します。メール本文は、利用中のテーマのforms/data.html.twig
ファイルで定義されます。 -
user/data
フォルダに、インプットされたデータを保存するファイルが作成されます。テンプレートは、利用中のテーマのforms/data.txt.twg
ファイルで定義されます。 -
メッセージがパスすると、
thankyou
サブページが表示されます。このtyankyou
ページは、フォームページのサブページでなければいけません。
[!Tip]
Email プラグインを、メールが正しく送信されるように、設定しておいてください。
複数のフォーム
Form プラグイン v2.0 がリリースされ、ひとつのページに複数のフォームを設置できるようになりました。構文は似ていますが、それぞれのフォームは、フォーム名を別にしなければいけません。以下の例では、 contact-form
と、 newsletter-form
となっています:
forms:
contact-form:
fields:
...
buttons:
...
process:
...
newsletter-form:
fields:
...
buttons:
...
process:
...
このフォーマットは、ひとつのフォームでも使えます。ただ、forms:
に続けて、1つのフォームを定義するだけです:
forms:
contact-form:
fields:
...
buttons:
...
process:
...
Twigからフォームを表示する
フォームを含める最もかんたんな方法は、フォームが定義されているページをレンダリングするテンプレートに、Twig ファイルを含めることです。たとえば:
{% include "forms/form.html.twig" %}
上記は、Form プラグインそれ自体から提供される Twig テンプレートを使っています。そして、ページのフロントマターで定義したとおりにフォームをレンダリングし、フォームが送信されたときに、成功メッセージやエラーを表示します。
一方で、複数のフォームに対応した、より強力なフォーム表示方法があります。以下の方法で、 form:
パラメータをフォームを表示したい Twig テンプレートに渡します:
{% include "forms/form.html.twig" with { form: forms('contact-form') } %}
上記の方法を使えば、表示したいフォーム名を選択できます。別ページで定義したフォーム名さえ使うことができます。サイト全体で、そのフォーム名が単一である限り、Grav はそのフォームを見つけ出し、レンダリングします!
ひとつのページに、複数のフォームを表示することもできます:
# Contact Form
{% include "forms/form.html.twig" with { form: forms('contact-form') } %}
# Newsletter Signup
{% include "forms/form.html.twig" with { form: forms('newsletter-form') } %}
また別の方法では、フォーム名ではなくページのルーティングを参照して、フォームを表示できます。たとえば:
# Contact Form
{% include "forms/form.html.twig" with { form: forms( {route:'/forms/contact'} ) } %}
上記の例では、/forms/contact
のルーティングでたどり着くページの最初のフォームが見つかります。
ページコンテンツ中にフォームを表示する
ページコンテンツ(たとえば: default.md
)の中から、そのページで定義されていないフォームを表示することもできます。単に、フォーム名やルーティングをフォームに渡すだけです。
[!Info]
フォーム制御が発火するときに、フォームが動的に処理され、静的にキャッシュされないために、 Twig プロセス が有効化されており、ページキャッシュ が無効化されている必要があります。
---
title: Page with Forms
process:
twig: true
cache_enable: false
---
# Contact Form
{% include "forms/form.html.twig" with {form: forms('contact-form')} %}
# Newsletter Signup
{% include "forms/form.html.twig" with {form: forms( {route: '/newsletter-signup'} ) } %}
モジュラーフォーム
以前のバージョンの Form プラグインでは、 モジュラー ページのサブページでフォームを表示するには、トップレベルのモジュラーページ でフォームを定義しなければいけませんでした。この方法により、フォームが処理され、モジュラーのサブページで表示されました。
From プラグイン v2.0 からは、他のフォームページと同様、直接、モジュラーのサブページにフォームを定義できます。しかし、そこにフォームが見つからなければ、form プラグインは、‘現在のページ’ つまりトップレベルのモジュラーページに、フォームが無いか探します。つまり、1.0 と完全な後方互換性があります。
ここまでに書かれた具体例のように、モジュラーのサブページでの Twig テンプレートでも、フォームの設定ができます。
[!Note]
モジュラーのサブページに定義したフォームを使う時、 action: に親モジュラーページを設定し、 redirect: や、 display: アクションは、そのモジュラーのサブページが ルーティング外 であり、ブラウザからは到達できないので、送信時に読み込まれるべきでないものとして設定されていないといけません。
以下が、form/modular/_form/form.md
での例です。
---
title: Modular Form
form:
action: '/form/modular'
inline_errors: true
fields:
person.name:
type: text
label: Name
validate:
required: true
buttons:
submit:
type: submit
value: Submit
process:
message: "Thank you from your submission <b>{{ form.value('person.name') }}</b>!"
reset: true
display: '/form/modular'
---
## Modular Form