メニュー

リファレンス:form.fields の一覧

一般的なフィールドの属性

すべてのフィールドは、使用可能な属性のリストを受け入れます。それぞれのフィールドは、一般的な属性を共有できますが、特定のフィールドでは無視されることがあります。フィールドで、どの属性が許可されているかチェックする最良の方法は、このページのフィールドの説明を確認して、どの属性が言及されているかを確認することです。

以下のリストは、共通する事項なので、各フィールドの説明では繰り返しません。

属性説明
autocompleteon もしくは off を受け付けます
autofocus有効化すると、フィールドでオートフォーカスします
classes文字列を受けて、CSS クラスを追加します
defaultデフォルト値を設定します
disabledフィールドを disabled 状態にします
helptooltip をフィールドに追加します
idフィールドに id を設定します。また、label に for 属性を設定します
labelフィールドに label を設定します
display_labeltrue もしくは false を受け付けます
labelclasses文字列を受け取り、CSS クラスを追加します
sublabelフィールドに sublabel を設定します
sublabelclasses文字列を受け取り、CSS クラスを追加します
nameフィールドの name を設定します
novalidateフィールドを novalidate 状態にします
outerclasseslabel とそのフィールドを囲む div にクラスを追加します
wrapper_classes説明とフィールドを含む wrapper にクラスを追加します
placeholderplaceholder の値を設定します
readonlyreadonly 状態に設定します
sizeフィールドに size を設定します。この size は、コンテナにクラスとして追加されます。 largex-smallmediumlongsmall が適切な値ですが、もちろんフロントエンドで利用する場合に使える別の値を追加することも可能です
styleフィールドに style を設定します
titleフィールドに title の値を設定します
typeフィールドに type を設定します
validate.requiredtrue などのポジティブな値を設定すると、必須項目になります
validate.patternvalidation の pattern を設定します
validate.messagevalidation が失敗したときのメッセージを設定します

カスタム属性を追加することもできます:

attributes:
  key: value

カスタムの data-* 値を追加することもできます:

datasets:
  key: value

上記の attributes や、 datasets 定義は、次のようなフィールドになります:

<input name="data[name]" value="" type="text" class="form-input " key="value" data-key="value">

[!Tip]
注意: ポジティブな値は、複数の設定方法があります('on' や、 true1 など)。その他の値は、ネガティブな値として解釈されます。


利用可能なフィールド

Basic-Captcha Field

Forms プラグイン 7.0.0 で、Google ReCaptcha フィールドのローカルでの代替として追加されました。このフィールドは、Google の提供する GDPR 制限に惑わされたくない場合で、コンタクトフォームでのスパムを取り扱うときに、特に便利です。攻撃を阻止するため、OCR-耐性 のあるフォントを利用し、コピーするコードや、かんたんな算数の問題を設定できます。

Basic-Captcha

basic-captcha フィールドタイプは、forms 設定で、完全に制御できますが、適切なデフォルト値が設定されています。Basic-Captcha の全体的な設定は、グローバルなフォーム設定ファイル(通常は、 user/config/plugins/form.yaml )で行います。デフォルトのオプションは:

basic_captcha:
  type: characters            # options: [characters | math]
  chars:
    length: 6                 # number of chars to output
    font: zxx-noise.ttf       # options: [zxx-noise.ttf | zxx-camo.ttf | zxx-xed.ttf | zxx-sans.ttf]
    bg: '#cccccc'             # 6-char hex color
    text: '#333333'           # 6-char hex color
    size: 24                  # font size in px
    start_x: 5                # start position in x direction in px
    start_y: 30               # start position in y direction in px
    box_width: 135            # box width in px
    box_height: 40            # box height in px
  math:
    min: 1                    # smallest digit
    max: 12                   # largest digit
    operators: ['+','-','*']  # operators that can be used in math

具体例:

basic-captcha:
    type: basic-captcha
    placeholder: copy the 6 characters
    label: Are you human?

これは、フォームのバリデーションが適切に行われるために、process: とも適合している必要があります。

[!Note]
もし captcha が失敗していたときに、フォームのプロセスがきちんと止まるようにするため、フォームの process: の中で、これが最初のエントリーでなければいけません。

具体例:

process:
    basic-captcha:
        message: Humanity verification failed, please try again...

Turnstile Captcha Field (Cloudflare)

Form プラグイン v7.1.0 から、新しく Cloudflare 社の Turnstile フィールドをサポートしました。このフィールドは、フォームの SPAM 除けの新しい方法です。Google ReCaptcha フィールドと、 Google からの GDPR 規制の代替となる素晴らしいものです。このフィールドは、コンタクトフォームで SPAM を取り扱うときに特に便利です。Turnstile については、こちらを参照してください

Google ReCaptcha よりも優れている点
  1. GDPR に準拠し、ユーザーのプライバシーを重視している
  2. 検証が極めて速い
  3. Cloudflare と Grav の両方で、実装がとても簡単で、複雑な UI やパラメータを設定する必要がない
  4. No fancy workarounds for asynchronous form submissions (ajax), it just works!
  5. ReCaptcha と比べて、ユーザー体験が良い。車や信号機を数えたり、その他のナンセンスなことをしなくて済む
  6. 機械学習の上に構築されているので、時間の経過とともに改良され、新しい攻撃にも適応する
  7. チャレンジの効果を徹底的に分析できる。 スクリーンショットを見てください
統合

Grav のフォームを Turnstile と統合する前に、まずは Turnstile サイトを新しく作らなければいけません 。そして、公式の “get started” チュートリアル も進めてください。 ここで、 widget のタイプを選べます。managed か、non-interactive か、 invisible のいずれかです。重要な注意点として、 widget のタイプは Cloudflare からのみ変更できます。Grav からは設定できません。しかし、ある選択が良くなかったとき、必要に応じて、後で変更は可能です。widget タイプの違いについて、より詳しくはCloudflareで学んでください

[!Note]
Turnstile フィールドを使うかもしれないドメインはすべて、忘れずに追加してください。これには、あなたのローカル環境も含まれます。

一度サイトを作成すると、site_keysite_secret が与えられます。これらはフォームの設定ファイル(通常は、user/config/plugins/form.yaml )から設定するのに必要なものです。 You can ignore the script tag suggested, as Grav takes care of it for you.

デフォルトのオプションは、以下のとおりです:

turnstile:
  theme: light
  site_key: <Your Turnstile Site Key>
  secret_key: <Your Turnstile Secret Key>

最後に、ここでもまた、バリデーションが適切に行われたことを確認するため、process: 要素との整合が必要になります。

[!Note]
キャプチャのバリデーションが失敗したとき、フォームの処理が実行されないように、キャプチャの整合確認は、process: セクションの最初になければいけません。

具体例

コンタクトフォームの典型的な例は、以下のようになります。

form:
  name: contact
  fields:
    name:
      label: Name
      type: text
      validate:
        required: true
    email:
      label: Email
      type: email
      validate:
        required: true
    message:
      label: Message
      type: textarea
      validate:
        required: true
    captcha:
        type: turnstile
        theme: light
  buttons:
    submit:
      type: submit
      value: Submit
  process:
    turnstile: true
    email:
      subject: "[Acme] {{ form.value.name|e }}"
      reply_to: "{{ form.value.name|e }} <{{ form.value.email }}>"
    message: Thanks for contacting us!
    reset: true
    display: '/'

Google Captcha Field (ReCaptcha)

captcha フィールドタイプは、Google reCAPTCHA 要素をフォームに追加するために使われます。他の要素と違い、1つのフォームに1回だけ使えます。

[!Note]
You should configure your Google reCAPTCHA configurations in the reCAPTCHA Admin Console

As of version 3.0, the field supports 3 variations of reCAPTCHA. The overall configuration of reCAPTCHA is best set in your global form configuration file (typically user/config/plugins/form.yaml). The default options are:

recaptcha:
  version: 2-checkbox
  theme: light
  site_key:
  secret_key:

These options should be set based on the following:

KeyValues
versionDefaults to 2-checkbox, but can also be 2-invisible or 3
themeDefaults to light, but can also be dark (currently only works for version 2-x versions)
site_keyYour Google Site Key
secret_keyYour Google Secret Key

[!Info]
Please ensure the domain of the site is listed in Google’s reCAPTCHA configuration

In the form definition, the name attribute of the captcha field must be g-recaptcha-response. The reason is that Google reCAPTCHA stores the Captcha confirmation code in a field named g-recaptcha-response.

具体例:

g-recaptcha-response:
  type: captcha
  label: Captcha

You can also provide a custom failure recaptcha_not_validated message, but if you don’t the default one is provided by the Form plugin. If you want to set a form-specific recaptcha_site_key rather than setting it globally in the form configuration, you can set that also.

g-recaptcha-response:
  type: captcha
  label: Captcha
  recaptcha_site_key: ENTER_YOUR_CAPTCHA_PUBLIC_KEY
  recaptcha_not_validated: 'Captcha not valid!'
属性説明
recaptcha_site_keyThe Google reCAPTCHA Site Key (optional)
recaptcha_not_validatedThe message to show if the captcha is not valid
利用可能な一般属性
help
label
name
outerclasses
validate.required

This also requires a matching process: element to ensure the form is validated properly.

[!Note]
This must be the first entry in the process: section of the form to ensure the form is not processed if ReCaptcha validation fails.

具体例:

process:
    captcha: true
サーバーサイドのキャプチャのバリデーション

The above code will validate the Captcha in the frontend and prevent form submission if not correct. To also validate the captcha server-side, add the captcha process action to your forms:

  process:
    captcha: true

You can also provide an optional success message, but if you don’t no specific message will be displayed on success. If you want to set a form-specific recaptcha_secret rather than setting it globally in the form configuration, you can set that also.

  process:
    captcha:
      recaptcha_secret: ENTER_YOUR_CAPTCHA_SECRET_KEY
      message: 'Successfully passed reCAPTCHA!'

See the Contact Form example to see it in action.


Checkbox Field

Checkbox Field

checkbox フィールドタイプは、ひとつのチェックボックスをフォームに追加します。

具体例:

agree_to_terms:
  type: checkbox
  label: "Agree to the terms and conditions"
  validate:
      required: true
利用可能な一般属性
autofocus
classes
default
disabled
id
label
name
novalidate
outerclasses
size
style
validate.required
validate.pattern
validate.message

Checkboxes Field

Checkboxes Field

checkboxes フィールドタイプは、チェックボックスのグループをフォームに追加します。

具体例:

pages.process:
    type: checkboxes
    label: PLUGIN_ADMIN.PROCESS
    help: PLUGIN_ADMIN.PROCESS_HELP
    default:
        markdown: true
        twig: true
    options:
        markdown: Markdown
        twig: Twig
    use: keys
my_field:
    type: checkboxes
    label: A couple of checkboxes with help for each option and option1 disabled
    default:
        - option1
        - option2
    options:
        option1: Option 1
        option2: Option 2
    help_options:
        option1: Help for Option 1
        option2: Help for Option 2
    disabled_options:
        - option1
属性説明
usekeys を設定すると、チェックボックスは、フォームの送信時に要素の key の値を保存します。そうでない場合は、要素の値を使います
optionskey-value 形式の利用可能な選択肢の配列
help_optionsoptions で定義したそれぞれの選択肢のヘルプの key-value 形式の配列
disabled_optionsdisabled 状態で表示する選択肢のリスト
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
outerclasses
size
style
validate.required
validate.pattern
validate.message

[!Info]
注意: checkboxes フィールドは、remember プロセスアクションはサポートしません。


Conditional Field

conditional フィールドタイプは、条件によっては表示されるフィールドです。

具体例:

すでに true もしくは false で条件が決まった場合、以下のようなシンプルなフォーマットが使えます:

my_conditional:
  type: conditional
  condition: config.plugins.yourplugin.enabled
  fields: # The field(s) below will be displayed only if the plugin named yourplugin is enabled
    header.mytextfield:
      type: text
      label: A text field

しかし、より複雑な条件を要するなら、true もしくは false を文字列で返すロジックを実行できます。そしてこのフィールドはそのことも理解します。

my_conditional:
  type: conditional
  condition: "config.site.something == 'custom'"
  fields: # The field(s) below will be displayed only if the `site` configuration option `something` equals `custom`
    header.mytextfield:
        type: text
        label: A text field
属性説明
conditionTwig で評価される条件。Twig から利用可能な変数であれば、評価できます
利用可能な一般属性
disabled
id
label
name

Date Field

Date Field

data フィールドタイプは、HTML5 の data の input フィールドです。

具体例:

-
  type: date
  label: Enter a date
  validate.min: "2014-01-01"
  validate.max: "2018-12-31"
属性説明
validate.minmin 属性を設定します(次を見てください: http://html5doctor.com/the-woes-of-date-input/#feature-min-max-attributes
validate.maxmax 属性を設定します(次を見てください: http://html5doctor.com/the-woes-of-date-input/#feature-min-max-attributes
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Display Field

Display Field

display フィールドタイプは、フォーム内でテキストや説明書きを表示するために使われます。マークダウンコンテンツを受け付けます

具体例:

test:
    type: display
    size: large
    label: Instructions
    markdown: true
    content: "This is a test of **bold** and _italic_ in a text/display field\n\nanother paragraph...."
属性説明
markdownboolean value that enables markdown processing on the content field
contentthe textual content to show
利用可能な一般属性
help
id
label
name
id
outerclasses
size
style

Email Field

Email Field

email フィールドタイプは、 HTML5のemail input を使い、Eメールを受け付ける入力欄を表示します。

[!Info]
Eメールは、大文字と小文字を区別しないように設計されています。アプリケーションロジックを書くときは、大文字、小文字、それらの混在を適切に扱ってください。

具体例:

header.email:
  type: email
  autofocus: true
  label: Email
属性説明
minlength最小文字数
maxlength最大文字数
validate.minminlength と同じ
validate.maxmaxlength と同じ
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

File Field

file フィールドタイプにより、ユーザーはフォームからファイルをアップロードできるようになります。デフォルトでは、画像 タイプの 1つのファイル のみを許容し、フォームが表示されている 現在の ページにアップロードされます。

# Default settings
my_files:
  type: file
  multiple: false
  destination: 'self@'
  accept:
    - image/*
属性説明
multipletrue もしくは falsetrue を設定すると、一度に複数ファイルが選択できます
destination@self もしくは @page:/routelocal/rel/path/ もしくは PHPストリームを受け付けます。
@self を設定すると、フォームが宣言された(現在の .md )フォルダにアップロードされます。
@page:/route を使うと、そのルーティングページが存在すれば、そこににアップロードされます。(例: @page:/blog/a-blog-post
‘local/rel/path’ を設定すると、Grav のルートディレクトリからの相対パスでどこでも保存できます。たとえば、user/images/uploads などです。path が存在しなければ、作成されます。このため、書き込み権限があることを確認してください。
これ以外にも、Grav が認識できる適切な PHPストリームに設定可能です。たとえば: user-data://my-form や、 theme://media/uploads などです。
accept受け取れる MIME タイプの配列を渡します。たとえば、gif 画像と mp4 ファイルのみを受け付ける場合: accept: ['image/gif', 'video/mp4']

[!Tip]
管理プラグインでの File fields は少し違いがあり、フォームからアップロードされたファイルの削除もできます。なぜなら、管理パネルでのユースケースは、アップロードした後、ファイルをデータ項目に紐付けることだからです。

利用可能な一般属性
help
label
name
outerclasses

デフォルトでは、管理パネルでは、フィールド定義で、avoid_overwritingtrue にしておかない限り、 file フィールドは同じフォルダに同じ名前のファイルがアップロードされると、上書きします。


Hidden Field

hidden フィールドタイプは、フォームに hidden 要素を追加します。

具体例:

header.some_field:
  type: hidden
  default: my-value
属性説明
nameフィールド名です。もし書き忘れた場合、要素の定義フィールドの名前になります(上の例では: header.some_field
利用可能な一般属性
default

Honeypot Field

honeypot フィールドタイプは、入力されるとエラーを返す hidden フィールドを作ります。入力を埋めて送信するだけのボットへの対策として便利です。

具体例:

fields:
    honeypot:
      type: honeypot

上記は、単純なテキストフィールドで、フロントエンドには表示されません。ボットは、コードを探索し、自動で入力欄を埋めるので、このフィールドも埋めてしまいます。エラーにより、フォームは正しく送信されません。エラーは、メッセージブロックの上部ではなく、フォーム要素の次に表示されます。

honeypot は、captcha フィールドの代替として人気です。


Ignore Field

ignore フィールドタイプは、他のブループリントから拡張されたときに、不使用のフィールドを削除します。

具体例:

header.process:
  type: ignore
content:
  type: ignore

Number Field

number フィールドタイプは、 HTML5 の number input を使い、数字のみを受け付ける入力欄を表示します。

具体例:

header.count:
  type: number
  label: 'How Much?'
  validate:
    min: 10
    max: 360
    step: 10
属性説明
validate.min最小値
validate.max最大値
validate.step増減の step
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Password Field

password フィールドタイプは、パスワード入力欄を表示します。

具体例:

password:
  type: password
  label: Password
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Radio Field

Radio Field

ラジオボタンのセットを表示します

具体例:

my_choice:
  type: radio
  label: Choice
  default: markdown
  options:
      markdown: Markdown
      twig: Twig
属性説明
optionskey-value の選択肢の配列
利用可能な一般属性
default
disabled
help
id
label
name
outerclasses
validate.required
validate.pattern
validate.message

Range Field

Range Field

input type=“range” を表示します。

具体例:

header.choose_a_number_in_range:
  type: range
  label: Choose a number
  validate:
    min: 1
    max: 10
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Section Field

ページをセクションに分けます。

具体例:

content:
    type: section
    title: PLUGIN_ADMIN.DEFAULTS
    underline: true

    fields:

        #..... subfields
属性説明
titleA heading title
textA text to show beneath
securityAn array of credentials a user needs to visualize this section
title_levelSet a custom headline tag. Default: h3

Select Field

Select Field

select 入力欄を表示します。

具体例 1:

pages.order.by:
    type: select
    size: long
    classes: fancy
    label: 'Default Ordering'
    help: 'Pages in a list will render using this order unless it is overridden'
    options:
        default: 'Default - based on folder name'
        folder: 'Folder - based on prefix-less folder name'
        title: 'Title - based on title field in header'
        date: 'Date - based on date field in header'

具体例 2 - 選択肢を disable にする:

my_element:
    type: select
    size: long
    classes: fancy
    label: 'My Select Element'
    help: 'Use the disabled key:value to display but disable a particular option'
    options:
        option1:
          value: 'Option 1'
        option2:
          value: 'Option 2'
        option3:
          disabled: true
          value: 'Option 3'
属性説明
optionskey-value 形式の選択肢の配列。key はフォームで送信されます。
multiple複数の値を許容するか

multiple を true にするとき、以下を追記してください

pages.order.by:
  validate:
    type: array

そうでなければ、選ばれた値の配列が正しく保存されません。

利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
size
style
validate.required
validate.pattern
validate.message

Select Optgroup Field

Select Optgroup Field

グループに分かれた select 入力欄を表示します。

具体例:

header.newField:
    type: select_optgroup
    label: Test Optgroup Select Field
    options:
      - OptGroup1:
        - Option1
        - Option2
      - OptGroup2:
        - Option3
        - Option4
属性説明
optionskey-value 形式の選択肢の配列
multiple複数の値を許容するか
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
size
style
validate.required
validate.pattern
validate.message

Spacer Field

テキストか、headline、hr タグを追加します

具体例:

test:
    type: spacer
    title: A title
    title_type: h2
    text: Some text
    underline: true
属性説明
titleタイトルを追加します
title_typeタイトルの HTML タグ(例: h1, h2, h3, など)を決定します。指定しなければ、デフォルトでは h3 です
textテキストを追記します。タイトルが設定されていれば、タイトルの後に追加されます
underline真偽値で、ポジティブな値の場合、<hr> タグを追加します。

Tabs / Tab Fields

Tabs

フォームの入力欄をタブに分けます。

具体例:

tabs:
  type: tabs
  active: 1

  fields:
    content:
      type: tab
      title: PLUGIN_ADMIN.CONTENT

      fields:

        # .... other subfields

    options:
      type: tab
      title: PLUGIN_ADMIN.OPTIONS

      fields:

        # .... other subfields
属性説明
activeactive にするタブ番号

Tel Field

HTML5 の input tel を使って、電話番号入力欄を表示します。

具体例:

header.phone:
  type: tel
  label: 'Your Phone Number'
属性説明
minlength最小文字数
maxlength最大文字数
validate.minminlength と同じ
validate.maxmaxlength と同じ
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Text Field

Text Field

テキストの入力欄を表示します。

具体例:

header.title:
  type: text
  autofocus: true
  label: PLUGIN_ADMIN.TITLE
  minlength: 10
  maxlength: 255
属性説明
prependフィールドの前にテキストや HTML を追加する
appendフィールドの後にテキストや HTML を追加する
minlength文字数の最小値
maxlength文字数の最大値
validate.minminlength と同じ
validate.maxmaxlength と同じ
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Textarea Field

Textarea Field

textarea を表示します。

具体例:

header.content:
  type: textarea
  autofocus: true
  label: PLUGIN_ADMIN.CONTENT
  minlength: 10
  maxlength: 255
属性説明
rowsrows 属性を追加します
colscols 属性を追加します
minlength文字数の最小値
maxlength文字数の最大値
validate.minminlength と同じ
validate.maxmaxlength と同じ
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Toggle Field

Toggle Field

オン/オフ 切り替え入力欄を、label と一緒に表示します。

具体例:

summary.enabled:
    type: toggle
    label: PLUGIN_ADMIN.ENABLED
    highlight: 1
    help: PLUGIN_ADMIN.ENABLED_HELP
    options:
        1: PLUGIN_ADMIN.YES
        0: PLUGIN_ADMIN.NO
    validate:
        type: bool
属性説明
highlightオプションのキーを強調(選択されたときに緑色に着色)
optionskey-value 形式の選択肢のリスト
利用可能な一般属性
default
help
label
name
style
toggleable
validate.required
validate.type
disabled

Url Field

HTML5 input url を使って、URLを受け付ける入力欄を表示します。

具体例:

header.url:
  type: url
  label: 'Your Website Url'
属性説明
minlength文字数の最小値
maxlength文字数の最大値
validate.minminlength と同じ
validate.maxmaxlength と同じ
利用可能な一般属性
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

未ドキュメント化のfields

Field説明
Array
Avatar
Color
Columns
Column
Datetime
Fieldset
Formname
Key
Month
Signature
Switch
Time
Unique Id
Value
Week