Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document new form:fields changes #1606

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

Document new form:fields changes #1606

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dad4c8e
Make code snippet indentation more consistent.
jesseleite Feb 6, 2025
052df05
Conditional fields are not new anymore.
jesseleite Feb 6, 2025
dfc1943
Fix link.
jesseleite Feb 7, 2025
b03d98a
Document `form:fields` tag (still need dedicated doc page though).
jesseleite Feb 7, 2025
6dd6e73
You don’t need `{!! !!}` anymore because `field` is `Htmlable` 🤌
jesseleite Feb 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 88 additions & 103 deletions content/collections/tags/form-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ parameters:
-
name: csrf
type: boolean
description: When `false`, the hidden `name="_token"` attribute won't be added to the form so you can use other ways of providing the token. Defaults to `true`.
description: When `false`, the hidden `name="_token"` attribute won't be added to the form so you can use other ways of providing the token. Defaults to `true`.
-
name: files
type: boolean
Expand All @@ -45,7 +45,7 @@ variables:
name: fields
type: array
description: >
An array of available fields for [dynamic rendering](#dynamic-rendering).
An array of available fields for [dynamic rendering](#dynamically-rendering-fields).
-
name: errors
type: array
Expand Down Expand Up @@ -106,30 +106,30 @@ Here we'll be creating a form to submit an entry in a `contact` form.
```
::tab blade
```blade
<s:form:create
in="contact"
>
@if (count($errors) > 0)
<div class="bg-red-300 text-white p-2">
@foreach ($errors as $error)
{{ $error }}<br>
@endforeach
</div>
@endif
<s:form:create in="contact">

@if ($success)
<div class="bg-green-300 text-white p-2">
{{ $success }}
</div>
@endif
@if (count($errors) > 0)
<div class="bg-red-300 text-white p-2">
@foreach ($errors as $error)
{{ $error }}<br>
@endforeach
</div>
@endif

<label>Email</label>
<input type="text" name="email" value="{{ old('email') }}" />
@if ($success)
<div class="bg-green-300 text-white p-2">
{{ $success }}
</div>
@endif

<label>Message</label>
<textarea name="message" rows="5">{{ old('message') }}</textarea>
<label>Email</label>
<input type="text" name="email" value="{{ old('email') }}" />

<label>Message</label>
<textarea name="message" rows="5">{{ old('message') }}</textarea>

<button>Submit</button>

<button>Submit</button>
</s:form:create>
```
::
Expand All @@ -147,7 +147,7 @@ You can also use the shorthand syntax for `form:create in="contact"`.
::tab blade
```blade
<s:form:contact>
...
...
</s:form:contact>
```
::
Expand All @@ -173,16 +173,14 @@ When you need to render a form that's selected via the [Form Fieldtype](/fieldty

::tab antlers
```antlers
{{ form:create in="{ form_fieldtype:handle }" }}
{{ form:create :in="form_fieldtype:handle" }}
...
{{ /form:create }}
```
::tab blade
```blade
<s:form:create
:in="$form_fieldtype->handle"
>
...
<s:form:create :in="$form_fieldtype->handle">
...
</s:form:create>
```
::
Expand All @@ -191,15 +189,15 @@ This way you can let Control Panel users select which form should be used on an

### Dynamically Rendering Fields

Instead of hardcoding individual fields, you may loop through the `fields` array to render your blueprint's fields in a dynamic fashion.
Instead of hardcoding individual fields, you may loop through the `fields` array using the [form:fields](/tags/form-fields) tag to render your blueprint's fields in a dynamic fashion.

::tabs

::tab antlers
```antlers
{{ form:contact }}

{{ fields }}
{{ form:fields }}
<div class="p-2">
<label>
{{ display }}
Expand All @@ -212,7 +210,7 @@ Instead of hardcoding individual fields, you may loop through the `fields` array
<p class="text-gray-500">{{ error }}</p>
{{ /if }}
</div>
{{ /fields }}
{{ /form:fields }}

<button>Submit</button>

Expand All @@ -222,22 +220,22 @@ Instead of hardcoding individual fields, you may loop through the `fields` array
```blade
<s:form:contact>

@foreach ($fields as $field)
<div class="p-2">
<label>
{{ $field['display'] }}
@if (in_array('required', $field['validate'] ?? []))
<sup class="text-red">*</sup>
@endif
</label>
<div class="p-1">{!! $field['field'] !!}</div>
@if ($field['error'])
<p class="text-gray-500">{{ $field['error'] }}</p>
@endif
</div>
@endforeach
<s:form:fields>
<div class="p-2">
<label>
{{ $field['display'] }}
@if (in_array('required', $field['validate'] ?? []))
<sup class="text-red">*</sup>
@endif
</label>
<div class="p-1">{{ $field['field'] }}</div>
@if ($field['error'])
<p class="text-gray-500">{{ $field['error'] }}</p>
@endif
</div>
</s:form:fields>

<button>Submit</button>
<button>Submit</button>

</s:form:contact>
```
Expand All @@ -250,7 +248,7 @@ Each item in the `fields` array contains the following data configurable in the
| `handle` | string | System name for the field |
| `display` | string | User-friendly field label |
| `type` | string | Name of the [fieldtype](/fieldtypes) |
| ` field` | string | [Pre-rendered field HTML](#prerendered-field-html) based on the fieldtype |
| `field` | string | [Pre-rendered field HTML](#prerendered-field-html) based on the fieldtype |
| `error` | string | Error message from an unsuccessful submission |
| `old` | array | Contains user input from an unsuccessful submission |
| `instructions` | string | User-friendly instructions label |
Expand All @@ -276,21 +274,21 @@ This approach, combined with the [blueprint editor](/blueprints), will give you

::tab antlers
```antlers
{{ fields }}
{{ form:fields }}
<div class="mb-2">
<label class="block">{{ display }}</label>
{{ field }}
</div>
{{ /fields }}
{{ /form:fields }}
```
::tab blade
```blade
@foreach ($fields as $field)
<div class="mb-2">
<label class="block">{{ $field['display'] }}</label>
{!! $field['field'] !!}
</div>
@endforeach
<s:form:fields>
<div class="mb-2">
<label class="block">{{ $field['display'] }}</label>
{{ $field['field'] }}
</div>
</s:form:fields>
```
::

Expand Down Expand Up @@ -322,31 +320,30 @@ If you have defined multiple sections in your form's blueprint, you can loop ove
{{ sections }}
<fieldset>
<legend>{{ display }}</legend>
{{ fields }}
{{ form:fields }}
...
{{ /fields }}
{{ /form:fields }}
</fieldset>
{{ /sections }}

<button>Submit</button>

{{ /form:contact }}
```
::tab blade
```blade
<s:form:contact>

@foreach($sections as $section)
<fieldset>
<legend>{{ $section['display'] }}</legend>

@foreach ($section['fields'] as $field)
...
@endforeach
</fieldset>
@endforeach
@foreach($sections as $section)
<fieldset>
<legend>{{ $section['display'] }}</legend>
<s:form:fields :section="$section">
...
</s:form:fields>
</fieldset>
@endforeach

<button>Submit</button>
<button>Submit</button>

</s:form:contact>
```
Expand All @@ -361,7 +358,7 @@ Each item in the `sections` array contains the following data configurable in th
| `fields` | array | An array of [fields](#dynamically-rendering-fields) defined within that section |


## Conditional Fields 🆕
## Conditional Fields

You may conditionally show and hide fields by utilizing the [conditional fields](/conditional-fields#overview) settings in your form's blueprint editor. Once configured, by including the necessary front-end scripts and enabling JavaScript on the `form:create` tag, all of the conditional logic will Just Work™.

Expand Down Expand Up @@ -392,10 +389,8 @@ The next step is to enable the Alpine JS driver via the `js="alpine"` parameter.
```
::tab blade
```blade
<s:form:contact
js="alpine"
>
...
<s:form:contact js="alpine">
...
</s:form:contact>
```
::
Expand All @@ -420,10 +415,10 @@ Finally, you will need to wire up the fields. With Alpine, this is done using `x
::tab blade
```blade
<template x-if="{{ $show_field['name'] }}">
<div class="p-2">
<label>Name</label>
<input type="text" name="name" value="{{ old('name') }}" x-model="name" />
</div>
<div class="p-2">
<label>Name</label>
<input type="text" name="name" value="{{ old('name') }}" x-model="name" />
</div>
</template>
```
::
Expand All @@ -438,31 +433,25 @@ If you are [dynamically rendering your fields](#dynamic-rendering) using the `fi

::tab antlers
```antlers
{{ fields }}
{{ form:fields }}
<template x-if="{{ show_field }}">
<div class="p-2">
<label>{{ display }}</label>
<div class="p-1">{{ field }}</div>
</div>
</template>
{{ /fields }}
{{ /form:fields }}
```
::tab blade
```blade
<s:form:contact
js="alpine"
>

@foreach ($fields as $field)
<s:form:fields>
<template x-if="{{ $field['show_field'] }}">
<div class="p-2">
<label>{{ $field['display'] }}</label>
<div class="p-1">{!! $field['field'] !!}</div>
</div>
<div class="p-2">
<label>{{ $field['display'] }}</label>
<div class="p-1">{{ $field['field'] }}</div>
</div>
</template>
@endforeach

</s:form:contact>
</s:form:fields>
```
::

Expand All @@ -482,10 +471,8 @@ If you are using other Alpine components in your form or on your page, the inclu
```
::tab blade
```blade
<s:form:contact
js="alpine:contact_form"
>
...
<s:form:contact js="alpine:contact_form">
...
</s:form:contact>
```
::
Expand All @@ -508,10 +495,10 @@ If you are hardcoding your inputs, you will need adjust your `x-model` to follow
::tab blade
```blade
<template x-if="{{ $show_field['name'] }}">
<div class="p-2">
<label>Name</label>
<input type="text" name="name" value="{{ old('name') }}" x-model="contact_form.name" />
</div>
<div class="p-2">
<label>Name</label>
<input type="text" name="name" value="{{ old('name') }}" x-model="contact_form.name" />
</div>
</template>
```
::
Expand Down Expand Up @@ -618,10 +605,8 @@ You can also pass comma-delimited options into the `js` parameter like so:
```
::tab blade
```blade
<s:form:contact
js="radjs:foo:bar"
>
...
<s:form:contact js="radjs:foo:bar">
...
</s:form:contact>
```
::
Expand Down