Usage
You first have to initialize the form in your form page controller like this:
$form = uniform('contact-form',[
'required' => [
'_from' => 'email'
],
'actions' => [
[
'_action' => 'email',
'to' => (string) $page->email(),
'sender' => 'info@my-domain.tld',
'subject' => $site->title()->html() . ' - message from the contact form'
]
]
]);
The first argument is a unique ID of the form on your entire website. The second argument is the array of options.
In this case the _from
form field is required and validated as an email address. If the form data is correct, the email
action is performed, sending the data to an email address specified in $page->email()
.
You then create a form element with the own url of the page as action
target like this:
<form action="<?php echo $page->url() ?>" method="post"></form>
Uniform by default requires the presence of a website
field acting as a honey pot and a _submit
button. Note the _
at the beginning of the field name
attribute, marking it as special field that shouldn't be altered.
Here is an example with an additional _from
field required by the email
action:
<label for="email" class="required">Email</label>
<input<?php e($form->hasError('_from'), ' class="erroneous"')?> type="email" name="_from" id="email" value="<?php $form->echoValue('_from') ?>" required/>
<label class="uniform__potty" for="website">Please leave this field blank</label>
<input type="text" name="website" id="website" class="uniform__potty" />
<button type="submit" name="_submit" value="<?php echo $form->token() ?>"<?php e($form->successful(), " disabled")?>>Submit</button>
There are some important things happening here.
First, the echoValue()
method is used to set the value
of the email field. If the submission of the form has failed, this restores already set fields. So in this case you don't have to enter the email address again when the page is reloaded after submitting the form. Also, the hasError()
method is used to mark the email field with a special class if the server-side validation failed. For more on the available methods, see the methods section.
Second, the honey pot field uses the uniform__potty
class. If you check the uniform.css
you'll see that it makes the field disappear visually but not in the souce code of the page, the spam-bots are accessing.
Last, the submit button uses the token()
method to set its value. The token is submitted along with all the other data of the form and ensures that the form can only be submitted directly from the website and not e.g. with an automated script that doesn't know the token. If the honeypot check fails, a new token is generated to make it harder to guess.
The presence of the last two elements with the exact name
attributes and the token as a value of the submit button is critical for the plugin to work correctly! Actions may require their own fields like _from
, too.
Now you can add as many additional form fields as you like but you shouldn't use the _
prefix for your own field names.
Note: Disable the kirby cache for pages where you use Uniform to make sure the form is generated dynamically.