diff --git a/docs/guide/upgrade-from-v1.md b/docs/guide/upgrade-from-v1.md
index 51118d9509..15a00c751b 100644
--- a/docs/guide/upgrade-from-v1.md
+++ b/docs/guide/upgrade-from-v1.md
@@ -331,12 +331,12 @@ introduces the class map (via `Yii::$classMap`) to overcome this difficulty.
------------
Yii 2.0 introduces the *field* concept for building a form using `ActiveForm`. A field
-is a container consisting of a label, an input, and an error message. It is represented
-as an `ActiveField` object. Using fields, you can build a form more cleanly than before:
+is a container consisting of a label, an input, an error message, and/or a hint text.
+It is represented as an `ActiveField` object. Using fields, you can build a form more cleanly than before:
```php
- field($model, 'username')->textInput(); ?>
+ field($model, 'username'); ?>
field($model, 'password')->passwordInput(); ?>
diff --git a/framework/yii/assets/yii.js b/framework/yii/assets/yii.js
index 1e847c4cc2..31a57d5f91 100644
--- a/framework/yii/assets/yii.js
+++ b/framework/yii/assets/yii.js
@@ -32,7 +32,7 @@
* // ... private functions and properties go here ...
*
* return pub;
- * });
+ * })(jQuery);
* ~~~
*
* Using this structure, you can define public and private functions/properties for a module.
diff --git a/framework/yii/debug/views/default/index.php b/framework/yii/debug/views/default/index.php
index 1c8e61e470..59d60b405a 100644
--- a/framework/yii/debug/views/default/index.php
+++ b/framework/yii/debug/views/default/index.php
@@ -25,7 +25,7 @@ $this->title = 'Yii Debugger';
Tag
Time
IP
-
Method
+
Method
URL
diff --git a/framework/yii/helpers/HtmlBase.php b/framework/yii/helpers/HtmlBase.php
index 1e9a6a7458..cfff8f50ce 100644
--- a/framework/yii/helpers/HtmlBase.php
+++ b/framework/yii/helpers/HtmlBase.php
@@ -725,8 +725,10 @@ class HtmlBase
* @param string|array $selection the selected value(s).
* @param array $items the data item used to generate the checkboxes.
* The array keys are the labels, while the array values are the corresponding checkbox values.
- * @param array $options options (name => config) for the checkbox list. The following options are supported:
+ * @param array $options options (name => config) for the checkbox list container tag.
+ * The following options are specially handled:
*
+ * - tag: string, the tag name of the container element.
* - unselect: string, the value that should be submitted when none of the checkboxes is selected.
* By setting this option, a hidden input will be generated.
* - encode: boolean, whether to HTML-encode the checkbox labels. Defaults to true.
@@ -778,7 +780,10 @@ class HtmlBase
}
$separator = isset($options['separator']) ? $options['separator'] : "\n";
- return $hidden . implode($separator, $lines);
+ $tag = isset($options['tag']) ? $options['tag'] : 'div';
+ unset($options['tag'], $options['unselect'], $options['encode'], $options['separator'], $options['item']);
+
+ return $hidden . static::tag($tag, implode($separator, $lines), $options);
}
/**
@@ -836,7 +841,10 @@ class HtmlBase
$hidden = '';
}
- return $hidden . implode($separator, $lines);
+ $tag = isset($options['tag']) ? $options['tag'] : 'div';
+ unset($options['tag'], $options['unselect'], $options['encode'], $options['separator'], $options['item']);
+
+ return $hidden . static::tag($tag, implode($separator, $lines), $options);
}
/**
@@ -945,7 +953,7 @@ class HtmlBase
*
* The following options are specially handled:
*
- * - tag: this specifies the tag name. If not set, "p" will be used.
+ * - tag: this specifies the tag name. If not set, "div" will be used.
*
* @return string the generated label tag
*/
@@ -953,7 +961,7 @@ class HtmlBase
{
$attribute = static::getAttributeName($attribute);
$error = $model->getFirstError($attribute);
- $tag = isset($options['tag']) ? $options['tag'] : 'p';
+ $tag = isset($options['tag']) ? $options['tag'] : 'div';
unset($options['tag']);
return Html::tag($tag, Html::encode($error), $options);
}
@@ -1066,7 +1074,6 @@ class HtmlBase
/**
* Generates a radio button tag for the given model attribute.
- * This method will generate the "name" tag attribute automatically unless it is explicitly specified in `$options`.
* This method will generate the "checked" tag attribute according to the model attribute value.
* @param Model $model the model object
* @param string $attribute the attribute name or expression. See [[getAttributeName()]] for the format
@@ -1102,7 +1109,6 @@ class HtmlBase
/**
* Generates a checkbox tag for the given model attribute.
- * This method will generate the "name" tag attribute automatically unless it is explicitly specified in `$options`.
* This method will generate the "checked" tag attribute according to the model attribute value.
* @param Model $model the model object
* @param string $attribute the attribute name or expression. See [[getAttributeName()]] for the format
@@ -1267,6 +1273,9 @@ class HtmlBase
if (!array_key_exists('unselect', $options)) {
$options['unselect'] = '0';
}
+ if (!array_key_exists('id', $options)) {
+ $options['id'] = static::getInputId($model, $attribute);
+ }
return static::checkboxList($name, $checked, $items, $options);
}
@@ -1304,6 +1313,9 @@ class HtmlBase
if (!array_key_exists('unselect', $options)) {
$options['unselect'] = '0';
}
+ if (!array_key_exists('id', $options)) {
+ $options['id'] = static::getInputId($model, $attribute);
+ }
return static::radioList($name, $checked, $items, $options);
}
diff --git a/framework/yii/widgets/ActiveField.php b/framework/yii/widgets/ActiveField.php
index f42e61135b..e3ac6aff17 100644
--- a/framework/yii/widgets/ActiveField.php
+++ b/framework/yii/widgets/ActiveField.php
@@ -9,6 +9,7 @@ namespace yii\widgets;
use Yii;
use yii\base\Component;
use yii\db\ActiveRecord;
+use yii\helpers\ArrayHelper;
use yii\helpers\Html;
use yii\base\Model;
use yii\web\JsExpression;
@@ -31,23 +32,22 @@ class ActiveField extends Component
* @var string the model attribute that this field is associated with
*/
public $attribute;
- /**
- * @var string the tag name for the field container.
- */
- public $tag = 'div';
/**
* @var array the HTML attributes (name-value pairs) for the field container tag.
* The values will be HTML-encoded using [[Html::encode()]].
* If a value is null, the corresponding attribute will not be rendered.
+ * The following special options are recognized:
+ *
+ * - tag: the tag name of the container element. Defaults to "div".
*/
public $options = array(
'class' => 'form-group',
);
/**
- * @var string the template that is used to arrange the label, the input and the error message.
- * The following tokens will be replaced when [[render()]] is called: `{label}`, `{input}` and `{error}`.
+ * @var string the template that is used to arrange the label, the input field, the error message and the hint text.
+ * The following tokens will be replaced when [[render()]] is called: `{label}`, `{input}`, `{error}` and `{hint}`.
*/
- public $template = "{label}\n{input}\n{error}";
+ public $template = "{label}\n{input}\n{error}\n{hint}";
/**
* @var array the default options for the input tags. The parameter passed to individual input methods
* (e.g. [[textInput()]]) will be merged with this property when rendering the input tag.
@@ -56,13 +56,24 @@ class ActiveField extends Component
/**
* @var array the default options for the error tags. The parameter passed to [[error()]] will be
* merged with this property when rendering the error tag.
+ * The following special options are recognized:
+ *
+ * - tag: the tag name of the container element. Defaults to "div".
*/
- public $errorOptions = array('tag' => 'p', 'class' => 'help-block');
+ public $errorOptions = array('class' => 'help-block');
/**
* @var array the default options for the label tags. The parameter passed to [[label()]] will be
* merged with this property when rendering the label tag.
*/
public $labelOptions = array('class' => 'control-label');
+ /**
+ * @var array the default options for the hint tags. The parameter passed to [[hint()]] will be
+ * merged with this property when rendering the hint tag.
+ * The following special options are recognized:
+ *
+ * - tag: the tag name of the container element. Defaults to "div".
+ */
+ public $hintOptions = array('class' => 'hint-block');
/**
* @var boolean whether to enable client-side data validation.
* If not set, it will take the value of [[ActiveForm::enableClientValidation]].
@@ -101,17 +112,73 @@ class ActiveField extends Component
* You normally do not need to set this property as the default selectors should work well for most cases.
*/
public $selectors;
+ /**
+ * @var array different parts of the field (e.g. input, label). This will be used together with
+ * [[template]] to generate the final field HTML code. The keys are the token names in [[template]],
+ * while the values are the corresponding HTML code. Valid tokens include `{input}`, `{label}`,
+ * `{error}`, and `{error}`. Note that you normally don't need to access this property directly as
+ * it is maintained by various methods of this class.
+ */
+ public $parts = array();
+ /**
+ * PHP magic method that returns the string representation of this object.
+ * @return string the string representation of this object.
+ */
+ public function __toString()
+ {
+ return $this->render();
+ }
+
+ /**
+ * Renders the whole field.
+ * This method will generate the label, error tag, input tag and hint tag (if any), and
+ * assemble them into HTML according to [[template]].
+ * @param string|callable $content the content within the field container.
+ * If null (not set), the default methods will be called to generate the label, error tag and input tag,
+ * and use them as the content.
+ * If a callable, it will be called to generate the content. The signature of the callable should be:
+ *
+ * ~~~
+ * function ($field) {
+ * return $html;
+ * }
+ * ~~~
+ *
+ * @return string the rendering result
+ */
+ public function render($content = null)
+ {
+ if ($content === null) {
+ if (!isset($this->parts['{input}'])) {
+ $this->parts['{input}'] = Html::activeTextInput($this->model, $this->attribute, $this->inputOptions);
+ }
+ if (!isset($this->parts['{label}'])) {
+ $this->parts['{label}'] = Html::activeLabel($this->model, $this->attribute, $this->labelOptions);
+ }
+ if (!isset($this->parts['{error}'])) {
+ $this->parts['{error}'] = Html::error($this->model, $this->attribute, $this->errorOptions);
+ }
+ if (!isset($this->parts['{hint}'])) {
+ $this->parts['{hint}'] = '';
+ }
+ $content = strtr($this->template, $this->parts);
+ } elseif (!is_string($content)) {
+ $content = call_user_func($content, $this);
+ }
+ return $this->begin() . "\n" . $content . "\n" . $this->end();
+ }
+
/**
* Renders the opening tag of the field container.
* @return string the rendering result.
*/
public function begin()
{
- $options = $this->getClientOptions();
- if (!empty($options)) {
- $this->form->attributes[$this->attribute] = $options;
+ $clientOptions = $this->getClientOptions();
+ if (!empty($clientOptions)) {
+ $this->form->attributes[$this->attribute] = $clientOptions;
}
$inputID = Html::getInputId($this->model, $this->attribute);
@@ -126,8 +193,9 @@ class ActiveField extends Component
$class[] = $this->form->errorCssClass;
}
$options['class'] = implode(' ', $class);
+ $tag = ArrayHelper::remove($options, 'tag', 'div');
- return Html::beginTag($this->tag, $options);
+ return Html::beginTag($tag, $options);
}
/**
@@ -136,7 +204,378 @@ class ActiveField extends Component
*/
public function end()
{
- return Html::endTag($this->tag);
+ return Html::endTag(isset($this->options['tag']) ? $this->options['tag'] : 'div');
+ }
+
+ /**
+ * Generates a label tag for [[attribute]].
+ * The label text is the label associated with the attribute, obtained via [[Model::getAttributeLabel()]].
+ * @param array $options the tag options in terms of name-value pairs. It will be merged with [[labelOptions]].
+ * The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded
+ * using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
+ *
+ * The following options are specially handled:
+ *
+ * - label: this specifies the label to be displayed. Note that this will NOT be [[encoded()]].
+ * If this is not set, [[Model::getAttributeLabel()]] will be called to get the label for display
+ * (after encoding).
+ *
+ * @return ActiveField the field object itself
+ */
+ public function label($options = array())
+ {
+ $options = array_merge($this->labelOptions, $options);
+ $this->parts['{label}'] = Html::activeLabel($this->model, $this->attribute, $options);
+ return $this;
+ }
+
+ /**
+ * Generates a tag that contains the first validation error of [[attribute]].
+ * Note that even if there is no validation error, this method will still return an empty error tag.
+ * @param array $options the tag options in terms of name-value pairs. It will be merged with [[errorOptions]].
+ * The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded
+ * using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
+ *
+ * The following options are specially handled:
+ *
+ * - tag: this specifies the tag name. If not set, "div" will be used.
+ *
+ * @return ActiveField the field object itself
+ */
+ public function error($options = array())
+ {
+ $options = array_merge($this->errorOptions, $options);
+ $this->parts['{error}'] = Html::error($this->model, $this->attribute, $options);
+ return $this;
+ }
+
+ /**
+ * Renders the hint tag.
+ * @param string $content the hint content. It will NOT be HTML-encoded.
+ * @param array $options the tag options in terms of name-value pairs. These will be rendered as
+ * the attributes of the hint tag. The values will be HTML-encoded using [[Html::encode()]].
+ *
+ * The following options are specially handled:
+ *
+ * - tag: this specifies the tag name. If not set, "div" will be used.
+ *
+ * @return ActiveField the field object itself
+ */
+ public function hint($content, $options = array())
+ {
+ $options = array_merge($this->hintOptions, $options);
+ $tag = ArrayHelper::remove($options, 'tag', 'div');
+ $this->parts['{hint}'] = Html::tag($tag, $content, $options);
+ return $this;
+ }
+
+ /**
+ * Renders an input tag.
+ * @param string $type the input type (e.g. 'text', 'password')
+ * @param array $options the tag options in terms of name-value pairs. These will be rendered as
+ * the attributes of the resulting tag. The values will be HTML-encoded using [[Html::encode()]].
+ * @return ActiveField the field object itself
+ */
+ public function input($type, $options = array())
+ {
+ $options = array_merge($this->inputOptions, $options);
+ $this->parts['{input}'] = Html::activeInput($type, $this->model, $this->attribute, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a text input.
+ * This method will generate the "name" and "value" tag attributes automatically for the model attribute
+ * unless they are explicitly specified in `$options`.
+ * @param array $options the tag options in terms of name-value pairs. These will be rendered as
+ * the attributes of the resulting tag. The values will be HTML-encoded using [[Html::encode()]].
+ * @return ActiveField the field object itself
+ */
+ public function textInput($options = array())
+ {
+ $options = array_merge($this->inputOptions, $options);
+ $this->parts['{input}'] = Html::activeTextInput($this->model, $this->attribute, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a password input.
+ * This method will generate the "name" and "value" tag attributes automatically for the model attribute
+ * unless they are explicitly specified in `$options`.
+ * @param array $options the tag options in terms of name-value pairs. These will be rendered as
+ * the attributes of the resulting tag. The values will be HTML-encoded using [[Html::encode()]].
+ * @return ActiveField the field object itself
+ */
+ public function passwordInput($options = array())
+ {
+ $options = array_merge($this->inputOptions, $options);
+ $this->parts['{input}'] = Html::activePasswordInput($this->model, $this->attribute, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a file input.
+ * This method will generate the "name" and "value" tag attributes automatically for the model attribute
+ * unless they are explicitly specified in `$options`.
+ * @param array $options the tag options in terms of name-value pairs. These will be rendered as
+ * the attributes of the resulting tag. The values will be HTML-encoded using [[Html::encode()]].
+ * @return ActiveField the field object itself
+ */
+ public function fileInput($options = array())
+ {
+ $options = array_merge($this->inputOptions, $options);
+ $this->parts['{input}'] = Html::activeFileInput($this->model, $this->attribute, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a text area.
+ * The model attribute value will be used as the content in the textarea.
+ * @param array $options the tag options in terms of name-value pairs. These will be rendered as
+ * the attributes of the resulting tag. The values will be HTML-encoded using [[Html::encode()]].
+ * @return ActiveField the field object itself
+ */
+ public function textarea($options = array())
+ {
+ $options = array_merge($this->inputOptions, $options);
+ $this->parts['{input}'] = Html::activeTextarea($this->model, $this->attribute, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a radio button.
+ * This method will generate the "checked" tag attribute according to the model attribute value.
+ * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
+ *
+ * - uncheck: string, the value associated with the uncheck state of the radio button. If not set,
+ * it will take the default value '0'. This method will render a hidden input so that if the radio button
+ * is not checked and is submitted, the value of this attribute will still be submitted to the server
+ * via the hidden input.
+ * - label: string, a label displayed next to the radio button. It will NOT be HTML-encoded. Therefore you can pass
+ * in HTML code such as an image tag. If this is is coming from end users, you should [[Html::encode()]] it to prevent XSS attacks.
+ * When this option is specified, the radio button will be enclosed by a label tag.
+ * - labelOptions: array, the HTML attributes for the label tag. This is only used when the "label" option is specified.
+ *
+ * The rest of the options will be rendered as the attributes of the resulting tag. The values will
+ * be HTML-encoded using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
+ * @param boolean $enclosedByLabel whether to enclose the radio within the label.
+ * If true, the method will still use [[template]] to layout the checkbox and the error message
+ * except that the radio is enclosed by the label tag.
+ * @return ActiveField the field object itself
+ */
+ public function radio($options = array(), $enclosedByLabel = true)
+ {
+ $options = array_merge($this->inputOptions, $options);
+ if ($enclosedByLabel) {
+ if (!isset($options['label'])) {
+ $options['label'] = Html::encode($this->model->getAttributeLabel($this->attribute));
+ }
+ $this->parts['{input}'] = Html::activeRadio($this->model, $this->attribute, $options);
+ $this->parts['{label}'] = '';
+ } else {
+ $this->parts['{input}'] = Html::activeRadio($this->model, $this->attribute, $options);
+ }
+ return $this;
+ }
+
+ /**
+ * Renders a checkbox.
+ * This method will generate the "checked" tag attribute according to the model attribute value.
+ * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
+ *
+ * - uncheck: string, the value associated with the uncheck state of the radio button. If not set,
+ * it will take the default value '0'. This method will render a hidden input so that if the radio button
+ * is not checked and is submitted, the value of this attribute will still be submitted to the server
+ * via the hidden input.
+ * - label: string, a label displayed next to the checkbox. It will NOT be HTML-encoded. Therefore you can pass
+ * in HTML code such as an image tag. If this is is coming from end users, you should [[Html::encode()]] it to prevent XSS attacks.
+ * When this option is specified, the checkbox will be enclosed by a label tag.
+ * - labelOptions: array, the HTML attributes for the label tag. This is only used when the "label" option is specified.
+ *
+ * The rest of the options will be rendered as the attributes of the resulting tag. The values will
+ * be HTML-encoded using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
+ * @param boolean $enclosedByLabel whether to enclose the checkbox within the label.
+ * If true, the method will still use [[template]] to layout the checkbox and the error message
+ * except that the checkbox is enclosed by the label tag.
+ * @return ActiveField the field object itself
+ */
+ public function checkbox($options = array(), $enclosedByLabel = true)
+ {
+ if ($enclosedByLabel) {
+ if (!isset($options['label'])) {
+ $options['label'] = Html::encode($this->model->getAttributeLabel($this->attribute));
+ }
+ $this->parts['{input}'] = Html::activeCheckbox($this->model, $this->attribute, $options);
+ $this->parts['{label}'] = '';
+ } else {
+ $this->parts['{input}'] = Html::activeCheckbox($this->model, $this->attribute, $options);
+ }
+ return $this;
+ }
+
+ /**
+ * Renders a drop-down list.
+ * The selection of the drop-down list is taken from the value of the model attribute.
+ * @param array $items the option data items. The array keys are option values, and the array values
+ * are the corresponding option labels. The array can also be nested (i.e. some array values are arrays too).
+ * For each sub-array, an option group will be generated whose label is the key associated with the sub-array.
+ * If you have a list of data models, you may convert them into the format described above using
+ * [[ArrayHelper::map()]].
+ *
+ * Note, the values and labels will be automatically HTML-encoded by this method, and the blank spaces in
+ * the labels will also be HTML-encoded.
+ * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
+ *
+ * - prompt: string, a prompt text to be displayed as the first option;
+ * - options: array, the attributes for the select option tags. The array keys must be valid option values,
+ * and the array values are the extra attributes for the corresponding option tags. For example,
+ *
+ * ~~~
+ * array(
+ * 'value1' => array('disabled' => true),
+ * 'value2' => array('label' => 'value 2'),
+ * );
+ * ~~~
+ *
+ * - groups: array, the attributes for the optgroup tags. The structure of this is similar to that of 'options',
+ * except that the array keys represent the optgroup labels specified in $items.
+ *
+ * The rest of the options will be rendered as the attributes of the resulting tag. The values will
+ * be HTML-encoded using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
+ *
+ * @return ActiveField the field object itself
+ */
+ public function dropDownList($items, $options = array())
+ {
+ $options = array_merge($this->inputOptions, $options);
+ $this->parts['{input}'] = Html::activeDropDownList($this->model, $this->attribute, $items, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a list box.
+ * The selection of the list box is taken from the value of the model attribute.
+ * @param array $items the option data items. The array keys are option values, and the array values
+ * are the corresponding option labels. The array can also be nested (i.e. some array values are arrays too).
+ * For each sub-array, an option group will be generated whose label is the key associated with the sub-array.
+ * If you have a list of data models, you may convert them into the format described above using
+ * [[\yii\helpers\ArrayHelper::map()]].
+ *
+ * Note, the values and labels will be automatically HTML-encoded by this method, and the blank spaces in
+ * the labels will also be HTML-encoded.
+ * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
+ *
+ * - prompt: string, a prompt text to be displayed as the first option;
+ * - options: array, the attributes for the select option tags. The array keys must be valid option values,
+ * and the array values are the extra attributes for the corresponding option tags. For example,
+ *
+ * ~~~
+ * array(
+ * 'value1' => array('disabled' => true),
+ * 'value2' => array('label' => 'value 2'),
+ * );
+ * ~~~
+ *
+ * - groups: array, the attributes for the optgroup tags. The structure of this is similar to that of 'options',
+ * except that the array keys represent the optgroup labels specified in $items.
+ * - unselect: string, the value that will be submitted when no option is selected.
+ * When this attribute is set, a hidden field will be generated so that if no option is selected in multiple
+ * mode, we can still obtain the posted unselect value.
+ *
+ * The rest of the options will be rendered as the attributes of the resulting tag. The values will
+ * be HTML-encoded using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
+ *
+ * @return ActiveField the field object itself
+ */
+ public function listBox($items, $options = array())
+ {
+ $options = array_merge($this->inputOptions, $options);
+ $this->parts['{input}'] = Html::activeListBox($this->model, $this->attribute, $items, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a list of checkboxes.
+ * A checkbox list allows multiple selection, like [[listBox()]].
+ * As a result, the corresponding submitted value is an array.
+ * The selection of the checkbox list is taken from the value of the model attribute.
+ * @param array $items the data item used to generate the checkboxes.
+ * The array keys are the labels, while the array values are the corresponding checkbox values.
+ * Note that the labels will NOT be HTML-encoded, while the values will.
+ * @param array $options options (name => config) for the checkbox list. The following options are specially handled:
+ *
+ * - unselect: string, the value that should be submitted when none of the checkboxes is selected.
+ * By setting this option, a hidden input will be generated.
+ * - separator: string, the HTML code that separates items.
+ * - item: callable, a callback that can be used to customize the generation of the HTML code
+ * corresponding to a single item in $items. The signature of this callback must be:
+ *
+ * ~~~
+ * function ($index, $label, $name, $checked, $value)
+ * ~~~
+ *
+ * where $index is the zero-based index of the checkbox in the whole list; $label
+ * is the label for the checkbox; and $name, $value and $checked represent the name,
+ * value and the checked status of the checkbox input.
+ * @return ActiveField the field object itself
+ */
+ public function checkboxList($items, $options = array())
+ {
+ $this->parts['{input}'] = Html::activeCheckboxList($this->model, $this->attribute, $items, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a list of radio buttons.
+ * A radio button list is like a checkbox list, except that it only allows single selection.
+ * The selection of the radio buttons is taken from the value of the model attribute.
+ * @param array $items the data item used to generate the radio buttons.
+ * The array keys are the labels, while the array values are the corresponding radio button values.
+ * Note that the labels will NOT be HTML-encoded, while the values will.
+ * @param array $options options (name => config) for the radio button list. The following options are specially handled:
+ *
+ * - unselect: string, the value that should be submitted when none of the radio buttons is selected.
+ * By setting this option, a hidden input will be generated.
+ * - separator: string, the HTML code that separates items.
+ * - item: callable, a callback that can be used to customize the generation of the HTML code
+ * corresponding to a single item in $items. The signature of this callback must be:
+ *
+ * ~~~
+ * function ($index, $label, $name, $checked, $value)
+ * ~~~
+ *
+ * where $index is the zero-based index of the radio button in the whole list; $label
+ * is the label for the radio button; and $name, $value and $checked represent the name,
+ * value and the checked status of the radio button input.
+ * @return ActiveField the field object itself
+ */
+ public function radioList($items, $options = array())
+ {
+ $this->parts['{input}'] = Html::activeRadioList($this->model, $this->attribute, $items, $options);
+ return $this;
+ }
+
+ /**
+ * Renders a widget as the input of the field.
+ *
+ * Note that the widget must have both `model` and `attribute` properties. They will
+ * be initialized with [[model]] and [[attribute]] of this field, respectively.
+ *
+ * If you want to use a widget that does not have `model` and `attribute` properties,
+ * please use [[render()]] instead.
+ *
+ * @param string $class the widget class name
+ * @param array $config name-value pairs that will be used to initialize the widget
+ * @return ActiveField the field object itself
+ */
+ public function widget($class, $config = array())
+ {
+ /** @var \yii\base\Widget $class */
+ $config['model'] = $this->model;
+ $config['attribute'] = $this->attribute;
+ $config['view'] = $this->form->getView();
+ $this->parts['{input}'] = $class::widget($config);
+ return $this;
}
/**
@@ -177,382 +616,11 @@ class ActiveField extends Component
if (isset($this->errorOptions['class'])) {
$options['error'] = '.' . implode('.', preg_split('/\s+/', $this->errorOptions['class'], -1, PREG_SPLIT_NO_EMPTY));
} else {
- $options['error'] = isset($this->errorOptions['tag']) ? $this->errorOptions['tag'] : 'span';
+ $options['error'] = isset($this->errorOptions['tag']) ? $this->errorOptions['tag'] : 'div';
}
return $options;
} else {
return array();
}
}
-
- /**
- * Generates a label tag for [[attribute]].
- * The label text is the label associated with the attribute, obtained via [[Model::getAttributeLabel()]].
- * @param array $options the tag options in terms of name-value pairs. It will be merged with [[labelOptions]].
- * The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded
- * using [[encode()]]. If a value is null, the corresponding attribute will not be rendered.
- *
- * The following options are specially handled:
- *
- * - label: this specifies the label to be displayed. Note that this will NOT be [[encoded()]].
- * If this is not set, [[Model::getAttributeLabel()]] will be called to get the label for display
- * (after encoding).
- *
- * @return string the generated label tag
- */
- public function label($options = array())
- {
- $options = array_merge($this->labelOptions, $options);
- return Html::activeLabel($this->model, $this->attribute, $options);
- }
-
- /**
- * Generates a tag that contains the first validation error of [[attribute]].
- * Note that even if there is no validation error, this method will still return an empty error tag.
- * @param array $options the tag options in terms of name-value pairs. It will be merged with [[errorOptions]].
- * The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded
- * using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
- *
- * The following options are specially handled:
- *
- * - tag: this specifies the tag name. If not set, "p" will be used.
- *
- * @return string the generated label tag
- */
- public function error($options = array())
- {
- $options = array_merge($this->errorOptions, $options);
- return Html::error($this->model, $this->attribute, $options);
- }
-
- /**
- * Renders the field with the given input HTML.
- * This method will generate the label and error tags, and return them together with the given
- * input HTML according to [[template]].
- * @param string $input the input HTML
- * @return string the rendering result
- */
- public function render($input)
- {
- return $this->begin() . "\n" . strtr($this->template, array(
- '{input}' => $input,
- '{label}' => $this->label(),
- '{error}' => $this->error(),
- )) . "\n" . $this->end();
- }
-
- /**
- * Renders a field containing an input field.
- * @param string $type the input type (e.g. 'text', 'password')
- * @param array $options the tag options in terms of name-value pairs. These will be rendered as
- * the attributes of the resulting tag. The values will be HTML-encoded using [[encode()]].
- * @return string the generated input tag
- */
- public function input($type, $options = array())
- {
- $options = array_merge($this->inputOptions, $options);
- return $this->render(Html::activeInput($type, $this->model, $this->attribute, $options));
- }
-
- /**
- * Renders a field containing a text input.
- * This method will generate the "name" and "value" tag attributes automatically for the model attribute
- * unless they are explicitly specified in `$options`.
- * @param array $options the tag options in terms of name-value pairs. These will be rendered as
- * the attributes of the resulting tag. The values will be HTML-encoded using [[encode()]].
- * @return string the rendering result
- */
- public function textInput($options = array())
- {
- $options = array_merge($this->inputOptions, $options);
- return $this->render(Html::activeTextInput($this->model, $this->attribute, $options));
- }
-
- /**
- * Renders a field containing a password input.
- * This method will generate the "name" and "value" tag attributes automatically for the model attribute
- * unless they are explicitly specified in `$options`.
- * @param array $options the tag options in terms of name-value pairs. These will be rendered as
- * the attributes of the resulting tag. The values will be HTML-encoded using [[encode()]].
- * @return string the rendering result
- */
- public function passwordInput($options = array())
- {
- $options = array_merge($this->inputOptions, $options);
- return $this->render(Html::activePasswordInput($this->model, $this->attribute, $options));
- }
-
- /**
- * Renders a field containing a file input.
- * This method will generate the "name" and "value" tag attributes automatically for the model attribute
- * unless they are explicitly specified in `$options`.
- * @param array $options the tag options in terms of name-value pairs. These will be rendered as
- * the attributes of the resulting tag. The values will be HTML-encoded using [[encode()]].
- * @return string the rendering result
- */
- public function fileInput($options = array())
- {
- $options = array_merge($this->inputOptions, $options);
- return $this->render(Html::activeFileInput($this->model, $this->attribute, $options));
- }
-
- /**
- * Renders a field containing a text area.
- * The model attribute value will be used as the content in the textarea.
- * @param array $options the tag options in terms of name-value pairs. These will be rendered as
- * the attributes of the resulting tag. The values will be HTML-encoded using [[encode()]].
- * @return string the rendering result
- */
- public function textarea($options = array())
- {
- $options = array_merge($this->inputOptions, $options);
- return $this->render(Html::activeTextarea($this->model, $this->attribute, $options));
- }
-
- /**
- * Renders a field containing a radio button.
- * This method will generate the "name" tag attribute automatically unless it is explicitly specified in `$options`.
- * This method will generate the "checked" tag attribute according to the model attribute value.
- * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
- *
- * - uncheck: string, the value associated with the uncheck state of the radio button. If not set,
- * it will take the default value '0'. This method will render a hidden input so that if the radio button
- * is not checked and is submitted, the value of this attribute will still be submitted to the server
- * via the hidden input.
- * - label: string, a label displayed next to the radio button. It will NOT be HTML-encoded. Therefore you can pass
- * in HTML code such as an image tag. If this is is coming from end users, you should [[encode()]] it to prevent XSS attacks.
- * When this option is specified, the radio button will be enclosed by a label tag.
- * - labelOptions: array, the HTML attributes for the label tag. This is only used when the "label" option is specified.
- *
- * The rest of the options will be rendered as the attributes of the resulting tag. The values will
- * be HTML-encoded using [[encode()]]. If a value is null, the corresponding attribute will not be rendered.
- * @param boolean $enclosedByLabel whether to enclose the radio within the label.
- * If true, the method will still use [[template]] to layout the checkbox and the error message
- * except that the radio is enclosed by the label tag.
- * @return string the rendering result
- */
- public function radio($options = array(), $enclosedByLabel = true)
- {
- $options = array_merge($this->inputOptions, $options);
- if ($enclosedByLabel) {
- if (!isset($options['label'])) {
- $options['label'] = Html::encode($this->model->getAttributeLabel($this->attribute));
- }
- $checkbox = Html::activeRadio($this->model, $this->attribute, $options);
- return $this->begin() . strtr($this->template, array(
- '{input}' => $checkbox,
- '{label}' => '',
- '{error}' => $this->error(),
- )) . "\n" . $this->end();
- } else {
- return $this->render(Html::activeRadio($this->model, $this->attribute, $options));
- }
- }
-
- /**
- * Renders a field containing a checkbox.
- * This method will generate the "name" tag attribute automatically unless it is explicitly specified in `$options`.
- * This method will generate the "checked" tag attribute according to the model attribute value.
- * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
- *
- * - uncheck: string, the value associated with the uncheck state of the radio button. If not set,
- * it will take the default value '0'. This method will render a hidden input so that if the radio button
- * is not checked and is submitted, the value of this attribute will still be submitted to the server
- * via the hidden input.
- * - label: string, a label displayed next to the checkbox. It will NOT be HTML-encoded. Therefore you can pass
- * in HTML code such as an image tag. If this is is coming from end users, you should [[encode()]] it to prevent XSS attacks.
- * When this option is specified, the checkbox will be enclosed by a label tag.
- * - labelOptions: array, the HTML attributes for the label tag. This is only used when the "label" option is specified.
- *
- * The rest of the options will be rendered as the attributes of the resulting tag. The values will
- * be HTML-encoded using [[encode()]]. If a value is null, the corresponding attribute will not be rendered.
- * @param boolean $enclosedByLabel whether to enclose the checkbox within the label.
- * If true, the method will still use [[template]] to layout the checkbox and the error message
- * except that the checkbox is enclosed by the label tag.
- * @return string the rendering result
- */
- public function checkbox($options = array(), $enclosedByLabel = true)
- {
- if ($enclosedByLabel) {
- if (!isset($options['label'])) {
- $options['label'] = Html::encode($this->model->getAttributeLabel($this->attribute));
- }
- $checkbox = Html::activeCheckbox($this->model, $this->attribute, $options);
- return $this->begin() . strtr($this->template, array(
- '{input}' => $checkbox,
- '{label}' => '',
- '{error}' => $this->error(),
- )) . "\n" . $this->end();
- } else {
- return $this->render(Html::activeCheckbox($this->model, $this->attribute, $options));
- }
- }
-
- /**
- * Renders a field containing a drop-down list.
- * The selection of the drop-down list is taken from the value of the model attribute.
- * @param array $items the option data items. The array keys are option values, and the array values
- * are the corresponding option labels. The array can also be nested (i.e. some array values are arrays too).
- * For each sub-array, an option group will be generated whose label is the key associated with the sub-array.
- * If you have a list of data models, you may convert them into the format described above using
- * [[\yii\helpers\ArrayHelper::map()]].
- *
- * Note, the values and labels will be automatically HTML-encoded by this method, and the blank spaces in
- * the labels will also be HTML-encoded.
- * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
- *
- * - prompt: string, a prompt text to be displayed as the first option;
- * - options: array, the attributes for the select option tags. The array keys must be valid option values,
- * and the array values are the extra attributes for the corresponding option tags. For example,
- *
- * ~~~
- * array(
- * 'value1' => array('disabled' => true),
- * 'value2' => array('label' => 'value 2'),
- * );
- * ~~~
- *
- * - groups: array, the attributes for the optgroup tags. The structure of this is similar to that of 'options',
- * except that the array keys represent the optgroup labels specified in $items.
- *
- * The rest of the options will be rendered as the attributes of the resulting tag. The values will
- * be HTML-encoded using [[encode()]]. If a value is null, the corresponding attribute will not be rendered.
- *
- * @return string the rendering result
- */
- public function dropDownList($items, $options = array())
- {
- $options = array_merge($this->inputOptions, $options);
- return $this->render(Html::activeDropDownList($this->model, $this->attribute, $items, $options));
- }
-
- /**
- * Renders a field containing a list box.
- * The selection of the list box is taken from the value of the model attribute.
- * @param array $items the option data items. The array keys are option values, and the array values
- * are the corresponding option labels. The array can also be nested (i.e. some array values are arrays too).
- * For each sub-array, an option group will be generated whose label is the key associated with the sub-array.
- * If you have a list of data models, you may convert them into the format described above using
- * [[\yii\helpers\ArrayHelper::map()]].
- *
- * Note, the values and labels will be automatically HTML-encoded by this method, and the blank spaces in
- * the labels will also be HTML-encoded.
- * @param array $options the tag options in terms of name-value pairs. The following options are specially handled:
- *
- * - prompt: string, a prompt text to be displayed as the first option;
- * - options: array, the attributes for the select option tags. The array keys must be valid option values,
- * and the array values are the extra attributes for the corresponding option tags. For example,
- *
- * ~~~
- * array(
- * 'value1' => array('disabled' => true),
- * 'value2' => array('label' => 'value 2'),
- * );
- * ~~~
- *
- * - groups: array, the attributes for the optgroup tags. The structure of this is similar to that of 'options',
- * except that the array keys represent the optgroup labels specified in $items.
- * - unselect: string, the value that will be submitted when no option is selected.
- * When this attribute is set, a hidden field will be generated so that if no option is selected in multiple
- * mode, we can still obtain the posted unselect value.
- *
- * The rest of the options will be rendered as the attributes of the resulting tag. The values will
- * be HTML-encoded using [[encode()]]. If a value is null, the corresponding attribute will not be rendered.
- *
- * @return string the rendering result
- */
- public function listBox($items, $options = array())
- {
- $options = array_merge($this->inputOptions, $options);
- return $this->render(Html::activeListBox($this->model, $this->attribute, $items, $options));
- }
-
- /**
- * Renders a field containing a list of checkboxes.
- * A checkbox list allows multiple selection, like [[listBox()]].
- * As a result, the corresponding submitted value is an array.
- * The selection of the checkbox list is taken from the value of the model attribute.
- * @param array $items the data item used to generate the checkboxes.
- * The array keys are the labels, while the array values are the corresponding checkbox values.
- * Note that the labels will NOT be HTML-encoded, while the values will.
- * @param array $options options (name => config) for the checkbox list. The following options are specially handled:
- *
- * - unselect: string, the value that should be submitted when none of the checkboxes is selected.
- * By setting this option, a hidden input will be generated.
- * - separator: string, the HTML code that separates items.
- * - item: callable, a callback that can be used to customize the generation of the HTML code
- * corresponding to a single item in $items. The signature of this callback must be:
- *
- * ~~~
- * function ($index, $label, $name, $checked, $value)
- * ~~~
- *
- * where $index is the zero-based index of the checkbox in the whole list; $label
- * is the label for the checkbox; and $name, $value and $checked represent the name,
- * value and the checked status of the checkbox input.
- * @return string the rendering result
- */
- public function checkboxList($items, $options = array())
- {
- return $this->render(
- '
'
- );
- }
-
- /**
- * Renders a field containing a list of radio buttons.
- * A radio button list is like a checkbox list, except that it only allows single selection.
- * The selection of the radio buttons is taken from the value of the model attribute.
- * @param array $items the data item used to generate the radio buttons.
- * The array keys are the labels, while the array values are the corresponding radio button values.
- * Note that the labels will NOT be HTML-encoded, while the values will.
- * @param array $options options (name => config) for the radio button list. The following options are specially handled:
- *
- * - unselect: string, the value that should be submitted when none of the radio buttons is selected.
- * By setting this option, a hidden input will be generated.
- * - separator: string, the HTML code that separates items.
- * - item: callable, a callback that can be used to customize the generation of the HTML code
- * corresponding to a single item in $items. The signature of this callback must be:
- *
- * ~~~
- * function ($index, $label, $name, $checked, $value)
- * ~~~
- *
- * where $index is the zero-based index of the radio button in the whole list; $label
- * is the label for the radio button; and $name, $value and $checked represent the name,
- * value and the checked status of the radio button input.
- * @return string the rendering result
- */
- public function radioList($items, $options = array())
- {
- return $this->render(
- '
'
- );
- }
-
- /**
- * Renders a field containing an input widget.
- *
- * Note that the widget must have both `model` and `attribute` properties. They will
- * be initialized with [[model]] and [[attribute]] of this field, respectively.
- *
- * If you want to use a widget that does not have `model` and `attribute` properties,
- * please use [[render()]] instead.
- *
- * @param string $class the widget class name
- * @param array $config name-value pairs that will be used to initialize the widget
- * @return string the rendering result
- */
- public function widget($class, $config = array())
- {
- /** @var \yii\base\Widget $class */
- $config['model'] = $this->model;
- $config['attribute'] = $this->attribute;
- $config['view'] = $this->form->getView();
- return $this->render($class::widget($config));
- }
}
diff --git a/tests/unit/framework/helpers/HtmlTest.php b/tests/unit/framework/helpers/HtmlTest.php
index fafc72f39c..6d725de4d0 100644
--- a/tests/unit/framework/helpers/HtmlTest.php
+++ b/tests/unit/framework/helpers/HtmlTest.php
@@ -322,23 +322,23 @@ EOD;
public function testCheckboxList()
{
- $this->assertEquals('', Html::checkboxList('test'));
+ $this->assertEquals('', Html::checkboxList('test'));
$expected = <<