Configuration guide
Ce contenu n’est pas encore disponible dans votre langue.
The widget is Yii2\Extensions\DynamicForm\DynamicFormWidget, rendered with begin() and end() around the rows of an
ActiveForm. The first element matching widgetItem becomes the client template of a row. With integer min=0, the
configured model controls all rows: if its isNewRecord is truthy or absent, the server removes every rendered
widgetItem, including markup for persisted siblings. Otherwise all rendered rows remain, including new ones.
Individual row models are not inspected for this decision.
Widget properties
Section titled “Widget properties”| Property | Meaning |
|---|---|
widgetContainer | Class of the container rendered around the rows; alphanumeric characters and _ only. Required. |
widgetBody | CSS selector of the element that holds the rows. Required. |
widgetItem | CSS selector of one row. Required. |
limit | Maximum number of rows; inserting beyond it triggers limitReached instead. Default 999. |
min | Minimum row count for client deletion. Initial removal follows the model state above. Default 1. |
insertPosition | Where new rows are inserted, bottom or top. Default bottom. |
insertButton | Non-empty CSS selector of the buttons that insert a row. |
deleteButton | Non-empty CSS selector of the buttons that delete a row. |
model | Model of one row, used to build the client template; pass the first element of the rows. Required. |
formId | id of the ActiveForm; it must match the form the rows belong to. Required. |
formFields | Attributes of the row model whose client validation is registered for inserted rows. Required. |
Every option is documented in the PHPDoc of its property in src/DynamicFormWidget.php. The widget does not validate
the types or bounds of min and limit; the application should supply integers satisfying 0 <= min <= limit.
Set both button selectors explicitly. They default to null and are not validated; null or empty selectors bind the
click handler directly to the form and can prevent unrelated click defaults, including submission. To omit an action,
use a non-empty selector that matches no element. Use type="button" on insert and delete controls.
When redisplaying a failed POST with min=0, a configured model that still counts as new removes all rendered rows
and their errors, even if their models hold submitted values. If the application can require at least one row, use
min=1 consistently in the view and server-side count checks. This retains failed-POST rows but does not support
deleting all rows. The current API has no independent option to preserve new rows while allowing deletion to zero;
account for that limitation before adopting optional lists. Do not mark an unsaved ActiveRecord as persisted to bypass
it.
Several widgets on a page
Section titled “Several widgets on a page”A page registers each widget once per formId and widgetContainer. A widget rendered again with the same form and
container, such as an inner widget rendered once per outer row, reuses that registration, so it must be configured with
the same options; only its rendered rows may differ. Rendering the same container in the same form with other options
throws InvalidConfigException naming the options that differ. Forms are independent: two forms may use the same
container name with different options.
The min=0 rule applies to each nested widget too: a new configured model removes all its child rows, including any
persisted child markup. A missing child group caused by rendering is not an authorized request to delete those records.
When an outer template contains inner rows, cloning the outer row retains the first inner row even if its widget has
min=0; the minimum does not force a cloned inner list to start empty.
Insert and delete buttons act on the widget whose container holds them most closely, so nested widgets may share button
selectors. Place the buttons of a widget inside its container and outside the containers nested in it. With min=0,
keep an insert button outside every widgetItem of that widget so it survives initial row removal and deletion of the
last row. A delete button belongs inside the row it deletes.
Render one field per attribute with the tabular syntax [{$i}]attribute. Keep the hidden primary key of stored rows so
the update action can match them:
<?php if (!$modelAddress->isNewRecord): ?> <?= Html::activeHiddenInput($modelAddress, "[{$i}]id") ?><?php endif; ?><?= $form->field($modelAddress, "[{$i}]full_name")->textInput(['maxlength' => true]) ?>When rows are inserted, deleted or renumbered through updateContainer, the plugin rewrites the row indexes in the id
and name of every element of a row. For each id it changes, it also updates the label[for] and the field-<id>
container class that match the old id among the elements inside the row. Both are compared with the old id as literal
text, so an id holding characters such as ., : or a quote is updated like any other, and an element whose classes
only resemble a selector built from that id is left unchanged. The row element itself is not among those elements, so
its class is left unchanged when it is also the field container. The row indexes are located as follows:
- Row model inputs. The widget sends one id and name pattern per
formFieldsattribute, built from the form name ofmodel, such asaddress-{}-full_nameandAddress[{}][full_name]. The part before{}(address-,Address[) is shared by every input of that model, so an input that starts with it followed by its row indexes is located through it even when its attribute is not listed informFields, such as the hidden primary key. The row indexes follow that prefix, one per widget the input is nested in; what follows them, numeric keys included, is kept. A literal key in the form name of the model, such asModel[2024], belongs to the prefix (model-2024-,Model[2024][). - Other inputs. An id or name that starts with another model name, such as
Meta[0][5][ts], and not with a declared prefix has no declared pattern and is renumbered by position: in the first run of numeric segments after the model name (-0-5-inmeta-0-5-ts,[0][5]inMeta[0][5][ts]), the first segments, up to one per widget the input is nested in from the outermost, are the row indexes; the remaining segments are literal keys and are kept.Meta[0][5][ts]in the second row of a widget that is not nested becomesMeta[1][5][ts]. - Numeric keys before the row index. Position cannot tell a numeric key in front of the row indexes from an index:
Other[2024][0][x]would have2024replaced. Such a key is supported only in the form name ofmodel, whose declared patterns locate the index after it; there is no option to declare patterns for other models. Conversely, an input of another model whose id or name starts with a declared prefix is read as a row model input: when the form name ofmodelisModel[0], the5ofModel[0][5][ts]is taken for the row index and replaced, even in the first row. - Other shapes. When no declared prefix matches, an id without a numeric segment between two other segments gets the
row index appended once after a dash (
extrabecomesextra-0). A name is kept unless its numeric bracket segments are followed by a final bracket segment, as inMeta[0][ts]. Ids and names renumbered by position must not hold line breaks (line feed, carriage return, U+2028 or U+2029): such a value is handled as one of these other shapes.
Inserted and renumbered rows are validated with the rules ActiveForm registered for their field, under the new id. The
input and container selectors of that registration, including those set through ActiveField::$selectors, follow
the id when they name it as is or escaped with backslashes, such as #address-0-zip\.code or [id="address-0-zip"]; a
rewritten selector is kept only when it selects exactly the field or one container containing that field inside its
form. Otherwise, including when another constraint still names the old row, it falls back to #<id> or .field-<id>
with the id escaped. The initial Yii registration still needs escaped selectors for ids holding a period.
Server-side models
Section titled “Server-side models”Yii2\Extensions\DynamicForm\Models\Model::createMultiple() returns one model per posted row: it reuses the existing
models whose primary key was posted and creates new ones for the rest. Do not confuse it with yii\base\Model. The
following flat-list example assumes the payload checks described below have already passed.
use Yii;use Yii2\Extensions\DynamicForm\Models\Model;
$modelsAddress = Model::createMultiple(Address::class, $modelCustomer->addresses, 'id');
Model::loadMultiple($modelsAddress, Yii::$app->request->post());
$valid = Model::validateMultiple($modelsAddress);The third argument names the primary key; it defaults to id. This example expects a flat list with contiguous
zero-based indexes. createMultiple() reindexes its result, while loadMultiple() reads the original payload by those
indexes. Reject malformed row shapes and sparse or non-list indexes, or rebuild and load each model explicitly from the
same validated row entry. A successful loadMultiple() return does not prove every row was populated.
Enforce minimum and maximum posted row counts on the server before constructing models; widget min and limit are not
server-side submission validation. Model::validateMultiple([]) returns true, so it does not enforce a required row.
Define the endpoint’s policy for an intentionally empty list versus an invalid or missing group.
Authorize the parent and load existing children from its permitted relation. Before calling the helper or loading
attributes, reject non-empty posted keys outside that collection and repeated keys after schema-appropriate
normalization. Unknown keys create new models; repeated keys can reuse one instance. Use an explicit empty-key
convention for new rows rather than treating a valid key such as 0 as empty. Keep primary and parent foreign keys out
of mass assignment and assign the authorized parent on the server. Validate the parent, every row and the counts before
deleting intentionally omitted children or saving, and keep those writes in one transaction with a guarded rollback.
For nested payloads, apply counts and key ownership per parent, then rebuild, load and validate child lists explicitly;
createMultiple() neither traverses nested rows nor accepts a separate payload argument. Preserve parent/child index
mapping, authorize posted primary keys against their owning parent, and save the complete hierarchy in the same
transaction.
Enhanced controls
Section titled “Enhanced controls”Rows are cloned from the server markup, so a control enhanced on the client needs a marker that survives cloning. Add
data-tomselect to the selects that TomSelect should initialize in inserted rows; Kartik
widgets are detected through their own data-krajee-* attributes. The library versions and widget layouts the tests
cover are listed in the testing guide.
TomSelect notes:
- The selects of inserted rows are initialized with fixed settings: the
remove_buttonanddropdown_inputplugins andallowEmptyOption. Load a TomSelect build that includes those plugins, such astom-select.complete.js. The settings the application gave to the selects of the rendered rows are not copied to inserted rows. - Rendered selects that the application initialized keep their instance and settings when rows are inserted, deleted or renumbered; a renumbered instance takes the ids of its new row.
- The
.itemelements TomSelect renders for selected values are not rows, even whenwidgetItemis.item. - Deleting a row destroys its TomSelect instances.
- A native form reset restores the selects themselves; TomSelect does not update its own display on reset.
JavaScript events
Section titled “JavaScript events”The container that owns the clicked button triggers jQuery events when rows are inserted or deleted; containers of other
widgets, including other renderings of a nested widget, are not notified. beforeInsert receives the clicked button and
cannot cancel the insertion. Returning false from beforeDelete cancels the deletion.
$(".dynamicform_wrapper").on("beforeInsert", function (e, item) { console.log("beforeInsert");});
$(".dynamicform_wrapper").on("afterInsert", function (e, item) { console.log("afterInsert");});
$(".dynamicform_wrapper").on("beforeDelete", function (e, item) { if (!confirm("Are you sure you want to delete this item?")) { return false; }
return true;});
$(".dynamicform_wrapper").on("afterDelete", function (e) { console.log("Deleted item!");});
$(".dynamicform_wrapper").on("limitReached", function (e, item) { alert("Limit reached");});