# DynamicFormWidget

> Yii2 Dynamic form widget for cloning form elements in a nested manner while maintaining accessibility.

[API reference](/docs/api/index.md) › [DynamicForm](/docs/extensions/dynamicform/reference/index.md) › DynamicFormWidget

| class | `Yii2\Extensions\DynamicForm\DynamicFormWidget` |
| --- | --- |
| Extends | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) » [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\ViewContextInterface`](/docs/api/yii/base/viewcontextinterface/index.md), [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Source | [`src/DynamicFormWidget.php`](https://github.com/yii2-extensions/dynamicform/blob/main/src/DynamicFormWidget.php#L33) |

Yii2 Dynamic form widget for cloning form elements in a nested manner while maintaining accessibility.

A widget is registered once per page, form and container: its options, click handlers and initialization are
declared by the first rendering, and later renderings with the same `formId` and `widgetContainer` in the same page,
such as a nested widget rendered once per outer row, reuse that registration. They must serialize the same options
except the row template; a different configuration under the same container of the same form is rejected. The page
ends when the view is cleared, as [`View::endPage()`](/docs/api/yii/web/view/index.md#method-endPage) and [`View::renderAjax()`](/docs/api/yii/web/view/index.md#method-renderAjax) do.

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-autoIdPrefix"></span>[`$autoIdPrefix`](/docs/api/yii/base/widget/index.md#property-autoIdPrefix) static | `string` | The prefix to the automatically generated widget IDs. Default: `'w'`. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="property-deleteButton"></span>`$deleteButton` | `string` | Non-empty CSS selector of the buttons that delete a row. Default: `null`. | `DynamicFormWidget` |
| <span id="property-formFields"></span>`$formFields` | `list<string>\|null` | Fields to be validated. Default: `null`. | `DynamicFormWidget` |
| <span id="property-formId"></span>`$formId` | `string` | Form ID Default: `null`. | `DynamicFormWidget` |
| <span id="property-id"></span>[`$id`](/docs/api/yii/base/widget/index.md#property-id) | `string` | Id of the widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="property-insertButton"></span>`$insertButton` | `string` | Non-empty CSS selector of the buttons that insert a row. Default: `null`. | `DynamicFormWidget` |
| <span id="property-insertPosition"></span>`$insertPosition` | `string` | 'bottom' or 'top'; Default: `'bottom'`. | `DynamicFormWidget` |
| <span id="property-limit"></span>`$limit` | `int` | Maximum row count for client-side insertion. Default: `999`. | `DynamicFormWidget` |
| <span id="property-min"></span>`$min` | `int` | Minimum row count for client-side deletion. Default: `1`. | `DynamicFormWidget` |
| <span id="property-model"></span>`$model` | [`yii\base\Model`](/docs/api/yii/base/model/index.md)`\|null` | The model used for the form Default: `null`. | `DynamicFormWidget` |
| <span id="property-view"></span>[`$view`](/docs/api/yii/base/widget/index.md#property-view) | [`yii\web\View`](/docs/api/yii/web/view/index.md) | The view object that can be used to render views or view files. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="property-viewPath"></span>[`$viewPath`](/docs/api/yii/base/widget/index.md#property-viewPath) read-only | `string` | The directory containing the view files for this widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="property-widgetBody"></span>`$widgetBody` | `string` | CSS selector of the element that holds the rows. Default: `null`. | `DynamicFormWidget` |
| <span id="property-widgetContainer"></span>`$widgetContainer` | `string` | Class of the container rendered around the rows; letters, digits and underscores only. Default: `null`. | `DynamicFormWidget` |
| <span id="property-widgetItem"></span>`$widgetItem` | `string` | CSS selector of one row; the first matching element supplies the client template. Default: `null`. | `DynamicFormWidget` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/component/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__clone"></span>[`__clone()`](/docs/api/yii/base/component/index.md#method-__clone) | This method is called after the object is created by cloning an existing one. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/component/index.md#method-__get) | Returns the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/component/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/component/index.md#method-__set) | Sets the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/component/index.md#method-__unset) | Sets a component property to be null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-afterRun"></span>[`afterRun()`](/docs/api/yii/base/widget/index.md#method-afterRun) | This method is invoked right after a widget is executed. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-attachBehavior"></span>[`attachBehavior()`](/docs/api/yii/base/component/index.md#method-attachBehavior) | Attaches a behavior to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehaviors"></span>[`attachBehaviors()`](/docs/api/yii/base/component/index.md#method-attachBehaviors) | Attaches a list of behaviors to the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-beforeRun"></span>[`beforeRun()`](/docs/api/yii/base/widget/index.md#method-beforeRun) | This method is invoked right before the widget is executed. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-begin"></span>[`begin()`](/docs/api/yii/base/widget/index.md#method-begin) static | Begins a widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-behaviors"></span>[`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) | Returns a list of behaviors that this component should behave as. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/component/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/component/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-detachBehavior"></span>[`detachBehavior()`](/docs/api/yii/base/component/index.md#method-detachBehavior) | Detaches a behavior from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-detachBehaviors"></span>[`detachBehaviors()`](/docs/api/yii/base/component/index.md#method-detachBehaviors) | Detaches all behaviors from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-end"></span>[`end()`](/docs/api/yii/base/widget/index.md#method-end) static | Ends a widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-ensureBehaviors"></span>[`ensureBehaviors()`](/docs/api/yii/base/component/index.md#method-ensureBehaviors) | Makes sure that the behaviors declared in [`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) are attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehavior"></span>[`getBehavior()`](/docs/api/yii/base/component/index.md#method-getBehavior) | Returns the named behavior object. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehaviors"></span>[`getBehaviors()`](/docs/api/yii/base/component/index.md#method-getBehaviors) | Returns all behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getId"></span>[`getId()`](/docs/api/yii/base/widget/index.md#method-getId) | Returns the ID of the widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-getView"></span>[`getView()`](/docs/api/yii/base/widget/index.md#method-getView) | Returns the view object that can be used to render views or view files. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-getViewPath"></span>[`getViewPath()`](/docs/api/yii/base/widget/index.md#method-getViewPath) | Returns the directory containing the view files for this widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-hasEventHandlers"></span>[`hasEventHandlers()`](/docs/api/yii/base/component/index.md#method-hasEventHandlers) | Returns a value indicating whether there is any handler attached to the named event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/component/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/component/index.md#method-hasProperty) | Returns a value indicating whether a property is defined for this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`init()`](#method-init) | Initializes the widget. | `DynamicFormWidget` |
| <span id="method-off"></span>[`off()`](/docs/api/yii/base/component/index.md#method-off) | Detaches an existing event handler from this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-on"></span>[`on()`](/docs/api/yii/base/component/index.md#method-on) | Attaches an event handler to an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`registerAssets()`](#method-registerAssets) | Registers the needed assets. | `DynamicFormWidget` |
| [`registerHashVarWidget()`](#method-registerHashVarWidget) | Registers the widget for its form and container in the current page of the view. | `DynamicFormWidget` |
| <span id="method-render"></span>[`render()`](/docs/api/yii/base/widget/index.md#method-render) | Renders a view. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-renderFile"></span>[`renderFile()`](/docs/api/yii/base/widget/index.md#method-renderFile) | Renders a view file. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| [`run()`](#method-run) | Renders the buffered rows and registers their template and client behavior. | `DynamicFormWidget` |
| <span id="method-setId"></span>[`setId()`](/docs/api/yii/base/widget/index.md#method-setId) | Sets the ID of the widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-setView"></span>[`setView()`](/docs/api/yii/base/widget/index.md#method-setView) | Sets the view object to be used by this widget. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="method-trigger"></span>[`trigger()`](/docs/api/yii/base/component/index.md#method-trigger) | Triggers an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-widget"></span>[`widget()`](/docs/api/yii/base/widget/index.md#method-widget) static | Creates a widget instance and runs it. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| [`getHashVarName()`](#method-getHashVarName) protected | Returns the hashed variable: the one registered for the form and container in the current page, if any. | `DynamicFormWidget` |
| [`hashOptions()`](#method-hashOptions) protected | Generates a hashed variable to store the options. | `DynamicFormWidget` |
| [`initOptions()`](#method-initOptions) protected | Initializes the widget options. | `DynamicFormWidget` |
| [`registerOptions()`](#method-registerOptions) protected | Registers plugin options by storing it in a hashed javascript variable. | `DynamicFormWidget` |

## Events

| Event | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="event-EVENT_INIT"></span>[`EVENT_INIT`](/docs/api/yii/base/widget/index.md#event-EVENT_INIT) | [`yii\base\Event`](/docs/api/yii/base/event/index.md) | An event that is triggered when the widget is initialized via [`init()`](/docs/api/yii/base/widget/index.md#method-init). Event name: `'init'`. Available since 2.0.11. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="event-EVENT_BEFORE_RUN"></span>[`EVENT_BEFORE_RUN`](/docs/api/yii/base/widget/index.md#event-EVENT_BEFORE_RUN) | [`yii\base\WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | An event raised right before executing a widget. Event name: `'beforeRun'`. Available since 2.0.11. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |
| <span id="event-EVENT_AFTER_RUN"></span>[`EVENT_AFTER_RUN`](/docs/api/yii/base/widget/index.md#event-EVENT_AFTER_RUN) | [`yii\base\WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | An event raised right after executing a widget. Event name: `'afterRun'`. Available since 2.0.11. | [`yii\base\Widget`](/docs/api/yii/base/widget/index.md) |

## Constants

| Constant | Value | Description | Defined by |
| --- | --- | --- | --- |
| <span id="const-WIDGET_NAME"></span>`WIDGET_NAME` | `'dynamicform'` |  | `DynamicFormWidget` |

## Method details

### init() <span id="method-init"></span>

```php
public function init(): void
```

Initializes the widget.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md)

### registerAssets() <span id="method-registerAssets"></span>

```php
public function registerAssets(yii\web\View $view): void
```

Registers the needed assets.

The click handlers are delegated from the form and act only when the clicked button belongs directly to a
container of this registration, so widgets that share button selectors, such as nested widgets, never act on
each other's rows. `beforeInsert` is triggered on that container with the button; it is informational and cannot
cancel the insertion.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$view` | [`yii\web\View`](/docs/api/yii/web/view/index.md) | The View object |

### registerHashVarWidget() <span id="method-registerHashVarWidget"></span>

```php
public function registerHashVarWidget(): bool
```

Registers the widget for its form and container in the current page of the view.

Call it after [`hashOptions()`](/docs/extensions/dynamicform/reference/dynamicformwidget/index.md#method-hashOptions). The registration stays in effect while the page holds the options declared by
[`registerOptions()`](/docs/extensions/dynamicform/reference/dynamicformwidget/index.md#method-registerOptions).

**Returns**

`bool`: `true` when the widget was registered, `false` when the page already holds a compatible registration.

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): When the page already holds a registration for the same form and container whose options, other than the row template, differ.

### run() <span id="method-run"></span>

```php
public function run(): mixed
```

Renders the buffered rows and registers their template and client behavior.

**Returns**

`mixed`

### getHashVarName() <span id="method-getHashVarName"></span>

```php
protected function getHashVarName(): string
```

Returns the hashed variable: the one registered for the form and container in the current page, if any.

**Returns**

`string`

### hashOptions() <span id="method-hashOptions"></span>

```php
protected function hashOptions(): void
```

Generates a hashed variable to store the options.

### initOptions() <span id="method-initOptions"></span>

```php
protected function initOptions(): void
```

Initializes the widget options.

### registerOptions() <span id="method-registerOptions"></span>

```php
protected function registerOptions(yii\web\View $view): void
```

Registers plugin options by storing it in a hashed javascript variable.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$view` | [`yii\web\View`](/docs/api/yii/web/view/index.md) | The View object |