Yii 2 Field Range   Tips

Latest Stable Version Latest Unstable Version Total Downloads Monthly Downloads Daily Downloads
Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the kartik-v/yii2-krajee-base extension which in turn depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

The yii2-field-range extension enables you to easily manage Yii 2 ActiveField ranges (e.g. from date / to date or from amount / to amount). The features supported by this widget extension are:
  • display the two range fields as a single grouped block using Bootstrap 3 addons
  • tweak yii active form validation to display validation errors as one single block instead of separate error blocks under each field. This allows you to style your field range inputs better for various form layouts. No more misalignment of adjacent fields due to yii validation error messages.
  • ability to use any input from yii\helpers or any widget class for rendering the from and to fields.
  • enhanced usage with \kartik\widgets\ActiveField that allows you to add custom addons to prepend and append to your inputs.
  • default support for all widgets under \kartik\widgets. Special enhanced support for \kartik\widgets\DatePicker to render date ranges.
  • ability to use the kartik\datecontrol\DateControl widget which in turn can use any Date or Time widgets.

Note

  • The FieldRange validation routine displays only the first error encountered in validation of either of the attributes. The extension tries its best to trap yii ActiveForm client events to display client validation errors. There may be some scenarios where this could be improved, if there is an ability to trap events client validation errors better from the core framework. Having said this, it is to be noted, that the validation at form submission works more perfectly.

  • For setting up your model validation rules to use with this extension, refer this wiki.

  • You can use this extension with Bootstrap 3 horizontal form layouts. The widget by default supports the horizontal form layout setting of \kartik\widgets\ActiveForm. Refer this wiki for using different form layouts.

The preferred way to install this extension is through composer. Either run:

$ php composer.phar require kartik-v/yii2-field-range "*"

or add:

"kartik-v/yii2-field-range": "*"

to the require section of your composer.json file. Then run:

php composer.phar update

to get the updated package on your application install.

The Field Range allows you to configure the following properties:
  • form: ActiveForm, the form instance, if used with yii active form.

  • model: Model, the data model that this widget is associated with.

  • type: string, the input type for rendering the range attributes. If not provided, this defaults to FieldRange::INPUT_TEXT. All common input types are supported including widgets. This should be one of the following:

    Inputs

    • FieldRange::INPUT_TEXT or 'textInput'

    • FieldRange::INPUT_PASSWORD or 'passwordInput'

    • FieldRange::INPUT_TEXTAREA or 'textArea'

    • FieldRange::INPUT_CHECKBOX or 'checkbox'

    • FieldRange::INPUT_RADIO or 'radio'

    • FieldRange::INPUT_LIST_BOX or 'listBox'

    • FieldRange::INPUT_DROPDOWN_LIST or 'dropDownList'

    • FieldRange::INPUT_CHECKBOX_LIST or 'checkboxList'

    • FieldRange::INPUT_RADIO_LIST or 'radioList'

    • FieldRange::INPUT_FILE or 'fileInput'

    • FieldRange::INPUT_HTML5_INPUT or 'input'

    • FieldRange::INPUT_WIDGET or 'widget', use this for any custom widget class to be used

    Widgets

    • FieldRange::INPUT_DEPDROP or '\kartik\widgets\DepDrop'

    • FieldRange::INPUT_SELECT2 or '\kartik\widgets\Select2'

    • FieldRange::INPUT_TYPEAHEAD or '\kartik\widgets\Typeahead'

    • FieldRange::INPUT_SWITCH or '\kartik\widgets\Switch'

    • FieldRange::INPUT_SPIN or '\kartik\widgets\TouchSpin'

    • FieldRange::INPUT_STAR or '\kartik\widgets\StarRating'

    • FieldRange::INPUT_DATE or '\kartik\widgets\DatePicker'

    • FieldRange::INPUT_TIME or '\kartik\widgets\TimePicker'

    • FieldRange::INPUT_DATETIME or '\kartik\widgets\DateTimePicker'

    • FieldRange::INPUT_RANGE or '\kartik\widgets\RangeInput'

    • FieldRange::INPUT_COLOR or '\kartik\widgets\ColorInput'

    • FieldRange::INPUT_RATING or '\kartik\widgets\StarRating'

    • FieldRange::INPUT_FILEINPUT or '\kartik\widgets\FileInput'

  • widgetClass: string, the widget class to use if type is FieldRange::INPUT_WIDGET

  • label: string, the label to be displayed. Positioning of the label can be controlled by the template property. Defaults to an empty string.

  • labelOptions: array the HTML attributes for the label.

  • template: string, the template to render the widget. The following special tags will be replaced:

    • {label}: will be replaced by the value set in the label property

    • {widget}: will be replaced by the generated input markup for the field range widget.

    • {error}: will be replaced by the common error block for the range widget.

  • separator: string, the field separator string between first and second field. Defaults to ← to →.

  • useAddons: boolean, whether to use bootstrap 3 addons using \kartik\widgets\ActiveField. If set to true, the form instance must be based on \kartik\widgets\ActiveForm. If set to false you can use your own form widget based on \yii\widgets\ActiveForm. Defaults to true.

  • attribute1: string, the first field's model attribute that this widget is associated with.

  • fieldConfig1: array, the active field configuration for attribute1, which is used when the form property is set. You can use \kartik\widgets\ActiveField advanced features like Bootstrap addons.

  • name1: string, the first field's input name. This must be set if model and attribute1 are not set.

  • value1: string, the first field's input value when model is not set.

  • items1: array the option data items for first field if type is dropDownList, listBox, checkBoxList, or radioList. Refer the \yii\helpers\Html::dropDownList documentation on how this is to be rendered.

  • options1: array the HTML attributes for the first field's input tag.

  • widgetOptions1: array the widget options for the first field if type is FieldRange::INPUT_WIDGET or one of the inputs from '\kartik\widgets'.

  • attribute2: string, the second field's model attribute that this widget is associated with.

  • fieldConfig2: array, the active field configuration for attribute2, which is used when the form property is set. You can use \kartik\widgets\ActiveField advanced features like Bootstrap addons.

  • name2: string, the second field's input name. This must be set if model and attribute2 are not set.

  • value2: string, the second field's input value when model is not set.

  • items2: array the option data items for second field if type is dropDownList, listBox, checkBoxList, or radioList. Refer the \yii\helpers\Html::dropDownList documentation on how this is to be rendered.

  • options2: array the HTML attributes for the second field's input tag.

  • widgetOptions2: array the widget options for the second field if type is FieldRange::INPUT_WIDGET or one of the inputs from '\kartik\widgets'.

  • options: array the HTML attributes for the generated widget input. This has the input-group CSS class set by default.

  • widgetContainer: array the HTML attributes for the widget container.

  • errorContainer: array the HTML attributes for the common error block container.

← to →
Simple string/text range validation configured with the Html::dropDownList. Try setting both values the same to get a validation error.

← to →
Simple numeric/amounts range validation using \kartik\widgets\Spinner widget.

.txt
and
.txt
Simple text validation configured using Html::textInput with custom separator and addons. Use \kartik\widgets\ActiveField features to generate your own Bootstrap 3 addons.

← to →
Date range validation using \kartik\widgets\DatePicker widget and special additional RANGE validation routine available within DatePicker plugin.

Input saved as:
← to →
Input saved as:
Advanced usage with the \kartik\datecontrol\DateControl extension, which in turn is configured to use \kartik\widgets\DatePicker for displaying date inputs. The saved formats are displayed below each field (for this example, the dates are saved as Unix Timestamp).

← to →
DateTime range validation using \kartik\widgets\DateTimePicker widget.

← to →
Time range validation using \kartik\widgets\TimePicker widget.

 
Click these action buttons to see form validation errors getting cleared on reset & displayed on form submission.

← to →

Usage of the widget using Bootstrap 3 HORIZONTAL form layout and with kartik\datecontrol\DateControl widget. The horizontal layout formatting by default works only with \kartik\widgets\ActiveForm

.
use kartik\field\FieldRange;
use kartik\widgets\ActiveForm;

$form = ActiveForm::begin();

// Simple string/text range validation configured with the Html::dropDownList.
echo FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter start and end place',
    'attribute1' => 'start_place',
    'attribute2' => 'end_place',
    'type' => FieldRange::INPUT_DROPDOWN_LIST,
    'items1' => [''=>'Select...', 1 => 'New York', 2 => 'London', 3 => 'Bangalore'],
    'items2' => [''=>'Select...', 1 => 'New York', 2 => 'London', 3 => 'Bangalore'],
]);

// Simple numeric/amounts range validation using \kartik\widgets\Spinner widget.
FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter amount range',
    'attribute1' => 'from_amount',
    'attribute2' => 'to_amount',
    'type' => FieldRange::INPUT_SPIN,
]);

// Simple text validation configured using Html::textInput with custom separator and 
// addons. Use \kartik\widgets\ActiveField features to generate your own Bootstrap 3 addons.
echo FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter the two files',
    'attribute1' => 'attachment_1',
    'attribute2' => 'attachment_2',
    'type' => FieldRange::INPUT_TEXT,
    'separator' => 'and',
    'fieldConfig1' => ['addon'=>[
        'prepend' => ['content'=>'<i class="glyphicon glyphicon-paperclip"></i>'], 
        'append' => ['content'=>'.txt']
    ]],
     'fieldConfig2' => ['addon'=>[
        'prepend' => ['content'=>'<i class="glyphicon glyphicon-paperclip"></i>'], 
        'append' => ['content'=>'.txt']
    ]],
]);

// Date range validation using \kartik\widgets\DatePicker widget and special additional
// RANGE validation routine available within DatePicker plugin.
echo FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter date range',
    'attribute1' => 'begin_date',
    'attribute2' => 'end_date',
    'type' => FieldRange::INPUT_DATE,
]);

// Advanced usage with the \kartik\datecontrol\DateControl extension, which in turn is configured to
// use \kartik\widgets\DatePicker for displaying date inputs. The saved formats are displayed below
// each field (for this example, the dates are saved as Unix Timestamp).
use kartik\datecontrol\DateControl;
FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter date range',
    'attribute1' => 'from_date',
    'attribute2' => 'to_date',
    'type' => FieldRange::INPUT_WIDGET,
    'widgetClass' => DateControl::classname(),
    'widgetOptions1' => [
        'saveFormat' => 'php:U'
    ],
    'widgetOptions2' => [
        'saveFormat' => 'php:U'
    ],
]);

// DateTime range validation using \kartik\widgets\DateTimePicker widget.
echo FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter time range',
    'attribute1' => 'datetime_start',
    'attribute2' => 'datetime_end',
    'type' => FieldRange::INPUT_DATETIME,
]);

// Time range validation using \kartik\widgets\TimePicker widget.
echo FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter time range',
    'attribute1' => 'datetime_start',
    'attribute2' => 'datetime_end',
    'type' => FieldRange::INPUT_DATETIME,
]); ?>

ActiveForm::end();

// Usage of the widget with Bootstrap 3 HORIZONTAL form layout and using 
// \kartik\datecontrol\DateControl widget. The horizontal layout formatting
// only works with \kartik\widgets\ActiveForm
use kartik\widgets\ActiveForm;
$form = ActiveForm::begin([
    'type' => ActiveForm::TYPE_HORIZONTAL,
    'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL],
]);
echo $form->field($model, 'username');
echo FieldRange::widget([
    'form' => $form,
    'model' => $model,
    'label' => 'Enter date range',
    'attribute1' => 'from_date_1',
    'attribute2' => 'to_date_1',
    'type' => FieldRange::INPUT_WIDGET,
    'widgetClass' => DateControl::classname(),
    'widgetOptions1' => [
        'saveFormat'=>'php:U',
        'options'=>[
            'pluginOptions' => ['autoclose' => true,],
        ],                
    ],
    'widgetOptions2' => [
        'saveFormat'=>'php:U',
        'options'=>[
            'pluginOptions' => ['autoclose' => true,],
        ],                
    ],
]);
ActiveForm::end();

yii2-field-range is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.