|
| 1 | +# Configuration |
| 2 | + |
| 3 | +Widget support the following options that are additionally recognized over and above the configuration options in the InputWidget. |
| 4 | + |
| 5 | +## Base options |
| 6 | + |
| 7 | +**theme** _string_: specify the theme of the widget. Available 2 themes: |
| 8 | + |
| 9 | +* `default` with only widget css classes |
| 10 | +* `bs` \(twitter bootstrap\) theme with additional BS ccs classes\). |
| 11 | + |
| 12 | +Default value is `bs` |
| 13 | + |
| 14 | +**max** _integer_: maximum number of rows. If not set will default to unlimited |
| 15 | + |
| 16 | +**min** _integer_: minimum number of rows. Set to `0` if you need the empty list in case you don't have any data |
| 17 | + |
| 18 | +**prepend** _boolean_: add a new row to the beginning of the list, not to the end |
| 19 | + |
| 20 | +**attributeOptions** _array_: client-side attribute options, e.g. enableAjaxValidation. You may use this property in case when you use widget without a model, since in this case widget is not able to detect client-side options automatically |
| 21 | + |
| 22 | +**addButtonPosition** _integer\|array_: the position\(s\) of `add` button. This can be `MultipleInput::POS_HEADER`, `MultipleInput::POS_ROW`, `MultipleInput::POS_ROW_BEGIN` or `MultipleInput::POS_FOOTER`. |
| 23 | + |
| 24 | +**addButtonOptions** _array_: the HTML options for `add` button. Can contains `class` and `label` keys |
| 25 | + |
| 26 | +**removeButtonOptions** _array_: the HTML options for `remove` button. Can contains `class` and `label` keys |
| 27 | + |
| 28 | +**data** _array_: array of values in case you use widget without model |
| 29 | + |
| 30 | +**models** _array_: the list of models. Required in case you use `TabularInput` widget |
| 31 | + |
| 32 | +**allowEmptyList** _boolean_: whether to allow the empty list |
| 33 | + |
| 34 | +**columnClass** _string_: the name of column class. You can specify your own class to extend base functionality. Defaults to `unclead\multipleinput\MultipleInputColumn` for `MultipleInput` and `unclead\multipleinput\TabularColumn` for `TabularInput`. |
| 35 | + |
| 36 | +**rendererClass** _string_: the name of renderer class. You can specify your own class to extend base functionality. Defaults to `unclead\multipleinput\renderers\TableRenderer`. |
| 37 | + |
| 38 | +**columns** _array_: the row columns configuration where you can set the properties which is described below |
| 39 | + |
| 40 | +**rowOptions** _array\|\Closure_: the HTML attributes for the table body rows. This can be either an array specifying the common HTML attributes for all body rows, or an anonymous function that returns an array of the HTML attributes. It should have the following signature: |
| 41 | + |
| 42 | +```php |
| 43 | +function ($model, $index, $context) |
| 44 | +``` |
| 45 | + |
| 46 | +* `$model`: the current data model being rendered |
| 47 | +* `$index`: the zero-based index of the data model in the model array |
| 48 | +* `$context`: the widget object |
| 49 | + |
| 50 | +**sortable** _bool_: whether need to enable sorting or not |
| 51 | + |
| 52 | +**modelClass** _string_: a class of model which is used to render `TabularInput`. You must specify this property when a list of `models` is empty. If this property is not specified the widget will detect it based on a class of `models` |
| 53 | + |
| 54 | +**cloneButton** _bool_: whether need to enable clone buttons or not |
| 55 | + |
| 56 | +**extraButtons** _string\|\Closure_: the HTML content that will be rendered after the buttons. It can be either string or an anonymous function that returns a string which will be treated as HTML content. It should have the following signature: |
| 57 | + |
| 58 | +```php |
| 59 | +function ($model, $index, $context) |
| 60 | +``` |
| 61 | + |
| 62 | +* `$model`: the current data model being rendered |
| 63 | +* `$index`: the zero-based index of the data model in the model array |
| 64 | +* `$context`: the MultipleInput widget object |
| 65 | + |
| 66 | +**layoutConfig** _array_: CSS grid classes for horizontal layout \(only supported for `ListRenderer` class\). This must be an array with these keys: |
| 67 | + |
| 68 | +* `'offsetClass'`: the offset grid class to append to the wrapper if no label is rendered |
| 69 | +* `'labelClass'`: the label grid class |
| 70 | +* `'wrapperClass'`: the wrapper grid class |
| 71 | +* `'errorClass'`: the error grid class |
| 72 | + |
| 73 | +**showGeneralError** _bool_: whether need to show error message for main attribute, when you don't want to validate particular input and want to validate a filed in general. |
| 74 | + |
| 75 | +## Column options |
| 76 | + |
| 77 | +**name** _string_: input name. _Required options_ |
| 78 | + |
| 79 | +**type** _string_: type of the input. If not set will default to `textInput`. Read more about the types described below |
| 80 | + |
| 81 | +**title** _string_: the column title |
| 82 | + |
| 83 | +**value** _Closure_: you can set it to an anonymous function with the following signature: |
| 84 | + |
| 85 | +```php |
| 86 | +function($data) {} |
| 87 | +``` |
| 88 | + |
| 89 | +**defaultValue** _string_: default value of input |
| 90 | + |
| 91 | +**items** _array_\|_Closure_: the items for input with type dropDownList, listBox, checkboxList, radioList or anonymous function which return array of items and has the following signature: |
| 92 | + |
| 93 | +```php |
| 94 | +function($data) {} |
| 95 | +``` |
| 96 | + |
| 97 | +**options** _array_\|_Closure_: the HTML attributes for the input, you can set it as array or an anonymous function with the following signature: |
| 98 | + |
| 99 | +```php |
| 100 | +function($data) {} |
| 101 | +``` |
| 102 | + |
| 103 | +**headerOptions** _array_: the HTML attributes for the header cell |
| 104 | + |
| 105 | +**enableError** _boolean_: whether to render inline error for the input. Default to `false` |
| 106 | + |
| 107 | +**errorOptions** _array_: the HTMl attributes for the error tag |
| 108 | + |
| 109 | +**nameSuffix** _string_: the unique prefix for attribute's name to avoid id duplication e.g. in case of using several copies of the widget on a page and one column is a Select2 widget |
| 110 | + |
| 111 | +**tabindex** _integer_: use it to customize a form element `tabindex` |
| 112 | + |
| 113 | +## Input types |
| 114 | + |
| 115 | +Each column in a row can has their own type. Widget supports: |
| 116 | + |
| 117 | +* all yii2 html input types: |
| 118 | + * `textInput` |
| 119 | + * `dropDownList` |
| 120 | + * `radioList` |
| 121 | + * `textarea` |
| 122 | + * For more detail look at [Html helper class](http://www.yiiframework.com/doc-2.0/yii-helpers-html.html) |
| 123 | +* input widget \(widget that extends from `InputWidget` class\). For example, `yii\widgets\MaskedInput` |
| 124 | +* `static` to output a static HTML content |
| 125 | + |
| 126 | +For using widget as column input you may use the following code: |
| 127 | + |
| 128 | +```php |
| 129 | +echo $form->field($model, 'phones')->widget(MultipleInput::className(), [ |
| 130 | +... |
| 131 | + 'columns' => [ |
| 132 | + ... |
| 133 | + [ |
| 134 | + 'name' => 'phones', |
| 135 | + 'title' => $model->getAttributeLabel('phones'), |
| 136 | + 'type' => \yii\widgets\MaskedInput::className(), |
| 137 | + 'options' => [ |
| 138 | + 'class' => 'input-phone', |
| 139 | + 'mask' => '999-999-99-99', |
| 140 | + ], |
| 141 | + ], |
| 142 | + ], |
| 143 | +])->label(false); |
| 144 | +``` |
| 145 | + |
0 commit comments