field-configuration.md

Field configuration

Because all fields are extended from Yiisoft\Widget\Widget from Yii Widget package, all widget configuration ways are suitable for form fields as well. They are described in Configuring the widget guide section.

Besides that, there are some additional configuration options that are specific to fields.

Theme

This package defines Yiisoft\Form\Theme\Theme as a following set of configuration:

• containerTag - HTML tag for outer container that wraps the field.
• containerAttributes - HTML attributes for outer container that wraps the field.
• containerClass - HTML class for outer container that wraps the field.
• useContainer - whether to use outer container that wraps the field.
• template - a template for a field where tokens (placeholders) are field parts. This template is used when field is rendered.
• templateBegin - starting template for the case when field is created using begin() and end() methods.
• templateEnd - ending template for the case when field is created using begin() and end() methods.
• shouldSetInputId - whether HTML ID for input should be set.
• inputAttributes - HTML attributes for input.
• inputClass - HTML class for input.
• inputContainerTag - HTML tag for outer container that wraps the input.
• inputContainerAttributes - HTML attributes for outer container that wraps the input.
• inputContainerClass - HTML class for outer container that wraps the input.
• labelClass - HTML class for label.
• labelConfig - Config with definitions for Label widget.
• hintClass - HTML class for hint.
• hintConfig - config with definitions for Hint widget.
• errorClass - HTML class for error.
• errorConfig - config with definitions for Error widget.
• usePlaceholder - whether to use placeholder - the example value intended to help user fill the actual value.
• validClass - HTML class for the field container when the field has been validated and has no validation errors.
• invalidClass - HTML class for the field container when the field has been validated and has validation errors.
• inputValidClass - HTML class for the input when the field has been validated and
• has no validation errors.
• inputInvalidClass - HTML class for the input when the field has been validated and has validation errors.
• enrichFromValidationRules - whether to enrich this field from validation rules.
• validationRulesEnricher - validation rules enricher instance.
• fieldConfigs - configuration sets by field type declared using definitions syntax.

All settings are optional.

Theme container

Theme container is used to register themes. Call initialize() method before using any field with $configs argument, where:

• key is a theme name;
• value is a mapping (associative array) between settings' names and their corresponding values.

use Yiisoft\Form\Theme\ThemeContainer;

ThemeContainer::initialize(
    configs: [
        'main' => [ 
            'containerClass' => 'field-container-main',
            // ...            
            'fieldConfigs' => [
                Checkbox::class => [
                    'inputContainerTag()' => ['div'],
                    // ...
                ],
                // ...
            ],
        ],
        'alternative' => [
            'containerClass' => 'field-container-alt',
            // ...            
            'fieldConfigs' => [
                Checkbox::class => [
                    'inputContainerTag()' => ['span'],
                    // ...
                ],
                // ...
            ],
        ],      
    ],
    defaultConfig: 'main',
);

You can additionally set (optional) config used as a default one using defaultConfig option.

Built-in themes

These themes are available out of the box:

• Bootstrap 5 Horizontal;
• Bootstrap 5 Vertical.

Their settings are stored in separate configuration files. To simplify including it, you can use Yiisoft\Form\Theme\ThemePath - constants with for all built-in themes.

use Yiisoft\Form\Theme\ThemeContainer;
use Yiisoft\Form\Theme\ThemePath;

ThemeContainer::initialize(
    config: [
        'vertical' => require ThemePath::BOOTSTRAP5_VERTICAL,
        'horizontal' => require ThemePath::BOOTSTRAP5_HORIZONTAL,
    ],
    defaultConfig: 'vertical',
);

In built-in themes no validation rules enrichers are used.

Using with Yii Config

When using Yii Config, there is no need to manually interact with theme cotnainer, it's initialized automatically during application's bootstrap. Here is an example of relevant config/params.php file section for configuration:

use Yiisoft\Form\Theme\ThemePath;

return [
    // ...
    'yiisoft/form' => [
        'themes' => [
            'vertical' => require ThemePath::BOOTSTRAP5_VERTICAL,
            'horizontal' => require ThemePath::BOOTSTRAP5_HORIZONTAL,
        ],
        'defaultTheme' => 'vertical',
    ],
    // ...
];

No built-in themes are used by default.