2019-11-18 05:58:33 +01:00
---
2014-10-19 10:32:34 +02:00
title: Form Templates
summary: Customize the generated HTML for a FormField or an entire Form.
2019-11-18 05:58:33 +01:00
icon: file-code
---
2014-10-19 10:32:34 +02:00
# Form Templates
2017-07-03 03:22:12 +02:00
Most markup generated in SilverStripe can be replaced by custom templates. Both [Form ](api:SilverStripe\Forms\Form ) and [FormField ](api:SilverStripe\Forms\FormField ) instances
2017-08-03 02:51:32 +02:00
can be rendered out using custom templates using `setTemplate` .
```php
2017-10-27 04:38:27 +02:00
$form = new Form(..);
$form->setTemplate('MyCustomFormTemplate');
2014-10-19 10:32:34 +02:00
2017-10-27 04:38:27 +02:00
// or, just a field
$field = new TextField(..);
$field->setTemplate('MyCustomTextField');
2017-08-03 02:51:32 +02:00
```
2014-10-19 10:32:34 +02:00
2019-01-24 13:55:52 +01:00
To override the template for CMS forms, the custom templates should be located in ** /app/templates**. Front-end form templates can be located in ** /app/templates** or in the active theme's ** /templates** directory.
2014-10-19 10:32:34 +02:00
2019-11-18 05:58:33 +01:00
[notice]
2014-10-19 10:32:34 +02:00
It's recommended to copy the contents of the template you're going to replace and use that as a start. For instance, if
you want to create a `MyCustomFormTemplate` copy the contents of `Form.ss` to a `MyCustomFormTemplate.ss` file and
modify as you need.
2019-01-24 11:27:38 +01:00
*The default Form.ss can be found in `/vendor/silverstripe/framework/templates/SilverStripe/Forms/Includes/` *
2019-11-18 05:58:33 +01:00
[/notice]
2014-10-19 10:32:34 +02:00
By default, Form and Fields follow the SilverStripe Template convention and are rendered into templates of the same
class name (i.e EmailField will attempt to render into `EmailField.ss` and if that isn't found, `TextField.ss` or
finally `FormField.ss` ).
2019-11-18 05:58:33 +01:00
[alert]
2014-10-19 10:32:34 +02:00
While you can override all templates using normal view inheritance (i.e defining a `Form.ss` ) other modules may rely on
the core template structure. It is recommended to use `setTemplate` and unique templates for specific forms.
2019-11-18 05:58:33 +01:00
[/alert]
2014-10-19 10:32:34 +02:00
2017-07-03 03:22:12 +02:00
For [FormField ](api:SilverStripe\Forms\FormField ) instances, there are several other templates that are used on top of the main `setTemplate` .
2014-10-19 10:32:34 +02:00
2017-08-03 02:51:32 +02:00
```php
2017-10-27 04:38:27 +02:00
$field = new TextField();
$field->setTemplate('CustomTextField');
// Sets the template for the < input > tag. i.e '< input $ AttributesHTML / > '
$field->setFieldHolderTemplate('CustomTextField_Holder');
// Sets the template for the wrapper around the text field. i.e
// '< div class = "text" > '
//
// The actual FormField is rendered into the holder via the `$Field`
// variable.
//
// setFieldHolder() is used in most `Form` instances and needs to output
// labels, error messages and the like.
$field->setSmallFieldHolderTemplate('CustomTextField_Holder_Small');
// Sets the template for the wrapper around the text field.
//
// The difference here is the small field holder template is used when the
// field is embedded within another field. For example, if the field is
// part of a `FieldGroup` or `CompositeField` alongside other fields.
2017-08-03 02:51:32 +02:00
```
2014-10-19 10:32:34 +02:00
2017-07-03 03:22:12 +02:00
All templates are rendered within the scope of the [FormField ](api:SilverStripe\Forms\FormField ). To understand more about Scope within Templates as
2014-10-19 10:32:34 +02:00
well as the available syntax, see the [Templates ](../templates ) documentation.
## Related Documentation
* [How to: Create a lightweight Form ](how_tos/lightweight_form )
## API Documentation
2017-07-03 03:22:12 +02:00
* [Form ](api:SilverStripe\Forms\Form )
* [FormField ](api:SilverStripe\Forms\FormField )