The TwbsMaxlength widget is a wrapper for the great Bootstrap Maxlength plugin,
a visual feedback indicator for the maxlength attribute. Have a look to the demo page for more !, (*1)
Installation
The preferred way to install this extension is through composer., (*2)
Either run, (*3)
php composer.phar require --prefer-dist raoul2000/yii2-twbsmaxlength-widget "*"
or add, (*4)
"raoul2000/yii2-twbsmaxlength-widget": "*"
to the require section of your composer.json file., (*5)
Basic Usage
Using TwbsMaxlength widget is easy.
In the example below, we are attaching the "Bootstrap Maxlength" plugin to an input text control, with a maximum length of 20 characters set by the
maxlength HTML5 attribute :, (*6)
<input type="text" class="form-control" id="txtinput1" name="xyz" maxlength="20" />
'#txtinput1']);
?>
The user will not be able to enter more than 20 characters in the text input control.
After the 10th character (hard coded default) is entered by the user, a small alert will appear at the bottom of the control., (*7)
Remember to use the selector option only when you need to attach the "Bootstrap Maxlength" plugin to an existing HTML input tag (text or textarea)., (*8)
Most of the time, a text or textarea input control is produced by an ActiveForm widget. The TwbsMaxlength is of course also able to handle such use case., (*9)
field($model, 'name')
->textInput(['maxlength' => true])
->widget(TwbsMaxlength::className());
ActiveForm::end();
?>
The code above only works since Yii2 v2.0.3 which includes a feature to automatically set the maxlength attribute of an ActiveField textInput
based on the related string validation rule (Read more...), (*10)
To use it with a textarea, simply add the typeconfiguration parameter with value TwbsMaxlength::INPUT_TEXTAREA :, (*11)
field($model, 'name')
->textInput(['maxlength' => true])
->widget(TwbsMaxlength::className(),['type' => TwbsMaxlength::INPUT_TEXTAREA]);
ActiveForm::end();
?>
Legacy support
If you are using Yii2 version prior to 2.0.3 no problem : the TwbsMaxlength widget implements the same kind of feature than Yii2 2.0.3.
If you don't set the maxlength HTML5 attribute yourself, the widget will search for this value among the validation rules defined for the model's attribute.
If the rule string is found and if a maximum length is set, it will be used to inject maxlength into the HTML input element. Otherwise the "Bootstrap Maxlength*
plugin will not be enabled., (*12)
Let's see that on an example with the famous ContactForm model. We use the StringValidator
to define the maximum length of the 'subject' attribute (here it will be set to 10) :, (*13)
class ContactForm extends Model
{
public $subject;
/**
* @return array the validation rules.
*/
public function rules()
{
return [
['subject','string', 'length'=> [4,10]],
];
}
// ....
Now, no need to set the maxlength HTML5 attribute because the widget will do it for us. We can simply write :, (*14)
field($model, 'subject')->widget(TwbsMaxlength::className());
ActiveForm::end();
?>
And that's it ! Take a look to the input tag created and you'll see that the maxlength HTML5 attribute
has been set to 10, just like defined in the validation rule of the subject attribute., (*15)
Plugin Options
The Bootstrap Maxlength accepts several options to custoomize its behavior.
These options can be initialized in the clientOptions array, when configuring the widget., (*16)
<?php
use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
$form = ActiveForm::begin();
echo $form->field($model, 'body')
->textinput(['maxlength' => true])
->widget(
TwbsMaxlength::className(),
[
'clientOptions' => [
'threshold' => 10,
'preText' => 'You have ',
'separator' => ' of ',
'postText' => ' chars remaining.',
'warningClass' => "label label-success",
'limitReachedClass' => "label label-danger"
]
]);
ActiveForm::end();
?>
For more information on the plugin options, please refer to bootstrap-maxlength github page., (*17)
textarea
To produce a textarea element instead of the classical text input (produced by default), use the type option when
configuring your widget., (*18)
field($model, 'body')
->textinput(['maxlength' => true])
->widget(
TwbsMaxlength::className(),
[
'type' => TwbsMaxlength::INPUT_TEXTAREA
]
);
ActiveForm::end();
?>
Setting the Threshold
The threshold is a numeric value representing the number of characters left before reaching the maxlength limitation.
When the threshold is reached, an alert is displayed to the user to inform her/him that the max length is about to be reached.
You can set the threshold value option like any other clientOption for the plugin., (*19)
<?php
use raoul2000\widget\twbsmaxlength\TwbsMaxlength;
$form = ActiveForm::begin();
echo $form->field($model, 'body')
->textinput(['maxlength' => true])
->widget(
TwbsMaxlength::className(),
[
'clientOptions' => [ 'threshold' => 10]
]
);
ActiveForm::end();
?>
TwbsMaxlength provide a way to dynamically calculate the threshold value depending on the max length value. This option name is thresholdPolicy.
The TwbsMaxlength widget includes 3 built-in thresholds policies :, (*20)
TwbsMaxlength::THRESHOLD_HALF-
TwbsMaxlength::THRESHOLD_TWO_THIRD (default)
TwbsMaxlength::THRESHOLD_THREE_QUARTERS
In the example below, the alert will be displayed after 3/4 of the total number of character allowed have been entered by the user. So for instance
if the "subject' validation rule set the maximum length to be 40, the alert will show up when 30 characters are entered., (*21)
field($model, 'subject')
->textinput(['maxlength' => true])
->widget(
TwbsMaxlength::className(),
[
'thresholdPolicy' => TwbsMaxlength::THRESHOLD_THREE_QUARTERS,
]
);
ActiveForm::end();
?>
Note that the thresholdPolicy is only available when working with ActiveForms., (*22)
License
yii2-twbsmaxlength-widget is released under the BSD 3-Clause License. See the bundled LICENSE.md for details., (*23)
Wallogit.com
