2012-12-13 16:33:58 +01:00
|
|
|
# How to Show Help Text on CMS Form Fields
|
|
|
|
|
|
|
|
Sometimes you need to express more context for a form field
|
|
|
|
than is suitable for its `<label>` element.
|
|
|
|
The CMS provides you with an easy way to transform
|
2015-04-22 04:42:24 +02:00
|
|
|
form field attributes into help text
|
|
|
|
shown alongside the field, a tooltip which shows on demand, or toggleable description text.
|
2012-12-13 16:33:58 +01:00
|
|
|
|
|
|
|
The `FormField->setDescription()` method will add a `<span class="description">`
|
|
|
|
at the last position within the field, and expects unescaped HTML content.
|
|
|
|
|
2017-08-03 02:51:32 +02:00
|
|
|
|
|
|
|
```php
|
2017-10-27 04:38:27 +02:00
|
|
|
use SilverStripe\Forms\TextField;
|
|
|
|
|
|
|
|
TextField::create('MyText', 'My Text Label')
|
|
|
|
->setDescription('More <strong>detailed</strong> help');
|
2017-08-03 02:51:32 +02:00
|
|
|
```
|
2012-12-13 16:33:58 +01:00
|
|
|
|
|
|
|
To show the help text as a tooltip instead of inline,
|
2014-11-07 20:43:57 +01:00
|
|
|
add a `.cms-description-tooltip` class.
|
2012-12-13 16:33:58 +01:00
|
|
|
|
2017-08-03 02:51:32 +02:00
|
|
|
|
|
|
|
```php
|
2017-10-27 04:38:27 +02:00
|
|
|
TextField::create('MyText', 'My Text Label')
|
|
|
|
->setDescription('More <strong>detailed</strong> help')
|
|
|
|
->addExtraClass('cms-description-tooltip');
|
2017-08-03 02:51:32 +02:00
|
|
|
```
|
2012-12-13 16:33:58 +01:00
|
|
|
|
|
|
|
Tooltips are only supported
|
|
|
|
for native, focusable input elements, which excludes
|
2017-02-28 04:01:13 +01:00
|
|
|
more complex fields like `GridField`
|
2012-12-13 16:33:58 +01:00
|
|
|
or `DropdownField` with the chosen.js behaviour applied.
|
|
|
|
|
2015-04-22 04:42:24 +02:00
|
|
|
Sometimes a field requires a longer description to provied the user with context.
|
|
|
|
Tooltips can be unwieldy when dealing with large blocks of text, especially if
|
|
|
|
you're including interactive elements like links.
|
|
|
|
|
|
|
|
Another option you have available is making the field's description togglable. This keeps
|
|
|
|
the UI tidy by hiding the description until the user requests more information
|
|
|
|
by clicking the 'info' icon displayed alongside the field.
|
|
|
|
|
2017-08-03 02:51:32 +02:00
|
|
|
|
|
|
|
```php
|
2017-10-27 04:38:27 +02:00
|
|
|
TextField::create('MyText', 'My Text Label')
|
|
|
|
->setDescription('More <strong>detailed</strong> help')
|
|
|
|
->addExtraClass('cms-description-toggle');
|
2017-08-03 02:51:32 +02:00
|
|
|
```
|
2015-04-22 04:42:24 +02:00
|
|
|
|
|
|
|
If you want to provide a custom icon for toggling the description, you can do that
|
|
|
|
by setting an additional `RightTitle`.
|
|
|
|
|
2017-08-03 02:51:32 +02:00
|
|
|
|
|
|
|
```php
|
2017-10-27 04:38:27 +02:00
|
|
|
TextField::create('MyText', 'My Text Label')
|
|
|
|
->setDescription('More <strong>detailed</strong> help')
|
|
|
|
->addExtraClass('cms-description-toggle')
|
|
|
|
->setRightTitle('<a class="cms-description-trigger">My custom icon</a>');
|
2017-08-03 02:51:32 +02:00
|
|
|
```
|
2015-04-22 04:42:24 +02:00
|
|
|
|
2012-12-13 16:33:58 +01:00
|
|
|
Note: For more advanced help text we recommend using
|
2016-01-14 11:59:53 +01:00
|
|
|
[Custom form field templates](/developer_guides/forms/form_templates);
|