358 lines
11 KiB
Markdown
358 lines
11 KiB
Markdown
title: Introduction to Forms
|
|
summary: An introduction to creating a Form instance and handling submissions.
|
|
|
|
# Forms
|
|
|
|
The HTML `Form` is the most used way to interact with a user. SilverStripe provides classes to generate forms through
|
|
the [Form](api:SilverStripe\Forms\Form) class, [FormField](api:SilverStripe\Forms\FormField) instances to capture data and submissions through [FormAction](api:SilverStripe\Forms\FormAction).
|
|
|
|
<div class="notice" markdown="1">
|
|
See the [Forms Tutorial](../../tutorials/forms/) for a step by step process of creating a `Form`
|
|
</div>
|
|
|
|
## Creating a Form
|
|
|
|
Creating a [Form](api:SilverStripe\Forms\Form) has the following signature.
|
|
|
|
|
|
```php
|
|
use SilverStripe\Forms\Form;
|
|
use SilverStripe\Forms\FieldList;
|
|
|
|
$form = new Form(
|
|
$controller, // the Controller to render this form on
|
|
$name, // name of the method that returns this form on the controller
|
|
FieldList $fields, // list of FormField instances
|
|
FieldList $actions, // list of FormAction instances
|
|
$required // optional use of RequiredFields object
|
|
);
|
|
```
|
|
|
|
In practice, this looks like:
|
|
|
|
**mysite/code/Page.php**
|
|
|
|
```php
|
|
use SilverStripe\CMS\Controllers\ContentController;
|
|
use SilverStripe\Forms\FieldList;
|
|
use SilverStripe\Forms\Form;
|
|
use SilverStripe\Forms\FormAction;
|
|
use SilverStripe\Forms\RequiredFields;
|
|
use SilverStripe\Forms\TextField;
|
|
|
|
class PageController extends ContentController
|
|
{
|
|
private static $allowed_actions = [
|
|
'HelloForm'
|
|
];
|
|
|
|
public function HelloForm()
|
|
{
|
|
$fields = new FieldList(
|
|
TextField::create('Name', 'Your Name')
|
|
);
|
|
|
|
$actions = new FieldList(
|
|
FormAction::create('doSayHello')->setTitle('Say hello')
|
|
);
|
|
|
|
$required = new RequiredFields('Name');
|
|
|
|
$form = new Form($this, 'HelloForm', $fields, $actions, $required);
|
|
|
|
return $form;
|
|
}
|
|
|
|
public function doSayHello($data, Form $form)
|
|
{
|
|
$form->sessionMessage('Hello ' . $data['Name'], 'success');
|
|
|
|
return $this->redirectBack();
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
**mysite/templates/Page.ss**
|
|
|
|
```ss
|
|
$HelloForm
|
|
```
|
|
|
|
<div class="info" markdown="1">
|
|
The examples above use `FormField::create()` instead of the `new` operator (`new FormField()`). These are functionally
|
|
equivalent, but allows PHP to chain operations like `setTitle()` without assigning the field instance to a temporary
|
|
variable.
|
|
</div>
|
|
|
|
When constructing the `Form` instance (`new Form($controller, $name)`) both controller and name are required. The
|
|
`$controller` and `$name` are used to allow SilverStripe to calculate the origin of the `Form object`. When a user
|
|
submits the `HelloForm` from your `contact-us` page the form submission will go to `contact-us/HelloForm` before any of
|
|
the [FormAction](api:SilverStripe\Forms\FormAction). The URL is known as the `$controller` instance will know the 'contact-us' link and we provide
|
|
`HelloForm` as the `$name` of the form. `$name` **needs** to match the method name.
|
|
|
|
Because the `HelloForm()` method will be the location the user is taken to, it needs to be handled like any other
|
|
controller action. To grant it access through URLs, we add it to the `$allowed_actions` array.
|
|
|
|
```php
|
|
private static $allowed_actions = [
|
|
'HelloForm'
|
|
];
|
|
|
|
```
|
|
|
|
<div class="notice" markdown="1">
|
|
Form actions (`doSayHello`), on the other hand, should _not_ be included in `$allowed_actions`; these are handled
|
|
separately through [Form::httpSubmission()](api:SilverStripe\Forms\Form::httpSubmission()).
|
|
</div>
|
|
|
|
|
|
## Adding FormFields
|
|
|
|
Fields in a [Form](api:SilverStripe\Forms\Form) are represented as a single [FieldList](api:SilverStripe\Forms\FieldList) instance containing subclasses of [FormField](api:SilverStripe\Forms\FormField).
|
|
Some common examples are [TextField](api:SilverStripe\Forms\TextField) or [DropdownField](api:SilverStripe\Forms\DropdownField).
|
|
|
|
```php
|
|
SilverStripe\Forms\TextField::create($name, $title, $value);
|
|
```
|
|
|
|
<div class="info" markdown='1'>
|
|
A list of the common FormField subclasses is available on the [Common Subclasses](field_types/common_subclasses/) page.
|
|
</div>
|
|
|
|
The fields are added to the [FieldList](api:SilverStripe\Forms\FieldList) `fields` property on the `Form` and can be modified at up to the point the
|
|
`Form` is rendered.
|
|
|
|
```php
|
|
$fields = new FieldList(
|
|
TextField::create('Name'),
|
|
EmailField::create('Email')
|
|
);
|
|
|
|
$form = new Form($controller, 'MethodName', $fields, ...);
|
|
|
|
// or use `setFields`
|
|
$form->setFields($fields);
|
|
|
|
// to fetch the current fields..
|
|
$fields = $form->getFields();
|
|
```
|
|
|
|
A field can be appended to the [FieldList](api:SilverStripe\Forms\FieldList).
|
|
|
|
```php
|
|
$fields = $form->Fields();
|
|
|
|
// add a field
|
|
$fields->push(TextField::create(/* ... */));
|
|
|
|
// insert a field before another one
|
|
$fields->insertBefore(TextField::create(/* ... */), 'Email');
|
|
|
|
// insert a field after another one
|
|
$fields->insertAfter(TextField::create(/* ... */), 'Name');
|
|
|
|
// insert a tab before the main content tab (used to position tabs in the CMS)
|
|
$fields->insertBefore(Tab::create(/* ... */), 'Main');
|
|
// Note: you need to create and position the new tab prior to adding fields via addFieldToTab()
|
|
```
|
|
|
|
Fields can be fetched after they have been added in.
|
|
|
|
```php
|
|
$email = $form->Fields()->dataFieldByName('Email');
|
|
$email->setTitle('Your Email Address');
|
|
```
|
|
|
|
Fields can be removed from the form.
|
|
|
|
```php
|
|
$form->getFields()->removeByName('Email');
|
|
```
|
|
|
|
<div class="alert" markdown="1">
|
|
Forms can be tabbed (such as the CMS interface). In these cases, there are additional functions such as `addFieldToTab`
|
|
and `removeFieldByTab` to ensure the fields are on the correct interface. See [Tabbed Forms](tabbed_forms) for more
|
|
information on the CMS interface.
|
|
</div>
|
|
|
|
## Modifying FormFields
|
|
|
|
Each [FormField](api:SilverStripe\Forms\FormField) subclass has a number of methods you can call on it to customise its' behavior or HTML markup. The
|
|
default `FormField` object has several methods for doing common operations.
|
|
|
|
<div class="notice" markdown="1">
|
|
Most of the `set` operations will return the object back so methods can be chained.
|
|
</div>
|
|
|
|
```php
|
|
$field = new TextField(..);
|
|
|
|
$field
|
|
->setMaxLength(100)
|
|
->setAttribute('placeholder', 'Enter a value..')
|
|
->setTitle('');
|
|
```
|
|
|
|
### Custom Templates
|
|
|
|
The [Form](api:SilverStripe\Forms\Form) HTML markup and each of the [FormField](api:SilverStripe\Forms\FormField) instances are rendered into templates. You can provide custom
|
|
templates by using the `setTemplate` method on either the `Form` or `FormField`. For more details on providing custom
|
|
templates see [Form Templates](form_templates)
|
|
|
|
```php
|
|
$form = new Form(..);
|
|
|
|
$form->setTemplate('CustomForm');
|
|
|
|
// or, for a FormField
|
|
$field = new TextField(..);
|
|
|
|
$field->setTemplate('CustomTextField');
|
|
$field->setFieldHolderTemplate('CustomTextField_Holder');
|
|
```
|
|
|
|
## Adding FormActions
|
|
|
|
[FormAction](api:SilverStripe\Forms\FormAction) objects are displayed at the bottom of the `Form` in the form of a `button` or `input` tag. When a
|
|
user presses the button, the form is submitted to the corresponding method.
|
|
|
|
```php
|
|
FormAction::create($action, $title);
|
|
```
|
|
|
|
As with [FormField](api:SilverStripe\Forms\FormField), the actions for a `Form` are stored within a [FieldList](api:SilverStripe\Forms\FieldList) instance in the `actions` property
|
|
on the form.
|
|
|
|
```php
|
|
public function MyForm()
|
|
{
|
|
$fields = new FieldList(/* .. */);
|
|
|
|
$actions = new FieldList(
|
|
FormAction::create('doSubmitForm', 'Submit')
|
|
);
|
|
|
|
$form = new Form($controller, 'MyForm', $fields, $actions);
|
|
|
|
// Get the actions
|
|
$actions = $form->Actions();
|
|
|
|
// As actions is a FieldList, push, insertBefore, removeByName and other
|
|
// methods described for `Fields` also work for actions.
|
|
|
|
$actions->push(
|
|
FormAction::create('doSecondaryFormAction', 'Another Button')
|
|
);
|
|
|
|
$actions->removeByName('doSubmitForm');
|
|
$form->setActions($actions);
|
|
|
|
return $form
|
|
}
|
|
|
|
public function doSubmitForm($data, $form)
|
|
{
|
|
//
|
|
}
|
|
|
|
public function doSecondaryFormAction($data, $form)
|
|
{
|
|
//
|
|
}
|
|
```
|
|
|
|
The first `$action` argument for creating a `FormAction` is the name of the method to invoke when submitting the form
|
|
with the particular button. In the previous example, clicking the 'Another Button' would invoke the
|
|
`doSecondaryFormAction` method. This action can be defined (in order) on either:
|
|
|
|
* One of the `FormField` instances.
|
|
* The `Form` instance.
|
|
* The `Controller` instance.
|
|
|
|
<div class="notice" markdown="1">
|
|
If the `$action` method cannot be found on any of those or is marked as `private` or `protected`, an error will be
|
|
thrown.
|
|
</div>
|
|
|
|
The `$action` method takes two arguments:
|
|
|
|
* `$data` an array containing the values of the form mapped from `$name => $value`
|
|
* `$form` the submitted [Form](api:SilverStripe\Forms\Form) instance.
|
|
|
|
```php
|
|
use SilverStripe\CMS\Controllers\ContentController;
|
|
use SilverStripe\Forms\EmailField;
|
|
use SilverStripe\Forms\FieldList;
|
|
use SilverStripe\Forms\Form;
|
|
use SilverStripe\Forms\FormAction;
|
|
use SilverStripe\Forms\TextField;
|
|
|
|
class PageController extends ContentController
|
|
{
|
|
private static $allowed_actions = [
|
|
'MyForm'
|
|
];
|
|
|
|
public function MyForm()
|
|
{
|
|
$fields = new FieldList(
|
|
TextField::create('Name'),
|
|
EmailField::create('Email')
|
|
);
|
|
|
|
$actions = new FieldList(
|
|
FormAction::create('doSubmitForm', 'Submit')
|
|
);
|
|
|
|
$form = new Form($controller, 'MyForm', $fields, $actions);
|
|
|
|
return $form
|
|
}
|
|
|
|
public function doSubmitForm($data, $form)
|
|
{
|
|
// Submitted data is available as a map.
|
|
echo $data['Name'];
|
|
echo $data['Email'];
|
|
|
|
// You can also fetch the value from the field.
|
|
echo $form->Fields()->dataFieldByName('Email')->Value();
|
|
|
|
// Using the Form instance you can get / set status such as error messages.
|
|
$form->sessionMessage('Successful!', 'good');
|
|
|
|
// After dealing with the data you can redirect the user back.
|
|
return $this->redirectBack();
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
## Validation
|
|
|
|
Form validation is handled by the [Validator](api:SilverStripe\Forms\Validator) class and the `validator` property on the `Form` object. The validator
|
|
is provided with a name of each of the [FormField](api:SilverStripe\Forms\FormField)s to validate and each `FormField` instance is responsible for
|
|
validating its' own data value.
|
|
|
|
For more information, see the [Form Validation](validation) documentation.
|
|
|
|
```php
|
|
$validator = new SilverStripe\Forms\RequiredFields([
|
|
'Name',
|
|
'Email'
|
|
]);
|
|
|
|
$form = new Form($this, 'MyForm', $fields, $actions, $validator);
|
|
```
|
|
|
|
## Related Lessons
|
|
* [Intoduction to frontend forms](https://www.silverstripe.org/learn/lessons/v4/introduction-to-frontend-forms-1)
|
|
|
|
## API Documentation
|
|
|
|
* [Form](api:SilverStripe\Forms\Form)
|
|
* [FormField](api:SilverStripe\Forms\FormField)
|
|
* [FieldList](api:SilverStripe\Forms\FieldList)
|
|
* [FormAction](api:SilverStripe\Forms\FormAction)
|