yii/widgets/MaskedInputAsset). This extension is similar to the DateControl extension for dates, and allows one to control the display and save formats for numbers. The extension thus allows one to setup a number format display mask, use currency prefixes if needed, and modify the decimals and thousand separators. It lastly allow the display fields to be auto calculated as numbers when stored into the database. This extension is more advanced than and replaces the yii2-money extension, which is now discontinued. The yii2-number extension includes these additional enhancements over the jQuery input mask plugin:
Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)
NumberControl supports configuration of the bootstrap library version so that you can use this either with any Bootstrap version 3.x and above. For setting up the bootstrap version for your extension, you can configure the NumberControl::bsVersion property to one of the following.
To use with bootstrap 3 library - you can set NumberControl::bsVersion property to any string starting with 3 (e.g. 3 or 3.3.7 or 3.x)
To use with bootstrap 4 library - you can set NumberControl::bsVersion property to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)
To use with bootstrap 5 library - you can set NumberControl::bsVersion property to any string starting with 5 (e.g. 5 or 5.1.0 or 5.x)
Generally, you may also want to set a default version globally for all Krajee Extensions (instead of setting it for each widget or extension separately). In order to do this, you can setup the bsVersion property within Yii 2 application params (i.e. Yii::$app->params['bsVersion']). To set this up, add this section of code to your application params configuration file (e.g. config/params.php):
'params' => [
'bsVersion' => '5.x', // this will set globally `bsVersion` to Bootstrap 5.x for all Krajee Extensions
// other settings
// 'adminEmail' => 'admin@example.com'
]
If NumberControl::bsVersion property is set, in addition to Yii::$app->params['bsVersion'], the extension level setting (NumberControl::bsVersion property) will override the Yii::$app->params['bsVersion']. If NumberControl::bsVersion property is not set, and Yii::$app->params['bsVersion'] is also not set, NumberControl::bsVersion property will default to 3.x (i.e. Bootstrap 3.x version will be assumed as default).
You need to install one of yiisoft/yii2-bootstrap or yiisoft/yii2-bootstrap4 or yiisoft/yii2-bootstrap5 extensions manually in your application to enable Bootstrap 3.x or 4.x or 5.x functionality respectively. This dependency has not been pre-built into the composer configuration for Krajee extensions, to allow better control to the developers in configuring their bootstrap library version. If bsVersion is set to 5.x and yiisoft/yii2-bootstrap5 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap5 extension. If bsVersion is set to 4.x and yiisoft/yii2-bootstrap4 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap4 extension. Similarly, if bsVersion is set to 3.x and yiisoft/yii2-bootstrap is not installed, an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap extension.
To install yiisoft/yii2-bootstrap5, add the repo to the require section of your application's composer.json.
"yiisoft/yii2-bootstrap5": "@dev"
To install yiisoft/yii2-bootstrap4, add the repo to the require section of your application's composer.json.
"yiisoft/yii2-bootstrap4": "@dev"
To install yiisoft/yii2-bootstrap, add the repo to the require section of your application's composer.json.
"yiisoft/yii2-bootstrap": "@dev"
The Krajee extension asset bundle(s) by default depend on one of the following asset bundles to load the Bootstrap CSS and JS:
yii\bootstrap\BootstrapAsset and/or yii\bootstrap\BootstrapPluginAsset for bootstrap 3.x (bsVersion = 3 setting)
yii\bootstrap4\BootstrapAsset and/or yii\bootstrap4\BootstrapPluginAsset for bootstrap 4.x ( bsVersion = 4 setting)
yii\bootstrap5\BootstrapAsset and/or yii\bootstrap5\BootstrapPluginAsset for bootstrap 5.x (bsVersion = 5 setting)
This is controlled by the property bsDependencyEnabled within the asset bundle (which defaults to true). One can override this and prevent the default yii2 bootstrap assets (CSS & JS) from loading by doing one or all of the following:
Global Override: Set Yii::$app->params['bsDependencyEnabled'] to false in your Yii 2 application config params.php. This setting will be applied for all Krajee Extension Asset Bundles that depend on Bootstrap assets.
'params' => [
'bsDependencyEnabled' => false, // this will not load Bootstrap CSS and JS for all Krajee extensions
// you need to ensure you load the Bootstrap CSS/JS manually in your view layout before Krajee CSS/JS assets
//
// other params settings below
// 'bsVersion' => '5.x',
// 'adminEmail' => 'admin@example.com'
]
Asset Bundle Specific Override: Set bsDependencyEnabled to false for the specific asset bundle within Yii2 Asset Manager component in your Yii 2 application config file.
// ...
'components' => [
'assetManager' => [
'bundles' => [
'kartik\form\ActiveFormAsset' => [
'bsDependencyEnabled' => false // do not load bootstrap assets for a specific asset bundle
],
],
],
],
When setting bsDependencyEnabled to false, you need to ensure that your app code/view layout loads the Bootstrap CSS and JS on your view before the Krajee CSS/JS are loaded to ensure that the Krajee extension JS plugins and CSS styles do not get broken.
Bootstrap 5.x / 4.x does not include glyphicons or any other icons framework bundled with the library. Krajee extensions therefore will use Font Awesome 5.x icons instead of glyphicons when working with Bootstrap 5.x / 4.x. You can download Font Awesome 5.x icons from the icons website. Alternatively, you can load the free version of Font Awesome from their CDN.
For Krajee extensions and demos, the Font Awesome Free version is used and loaded as the Icons Display Package on all the Yii2 demo layouts. To include font awesome assets on your page, include the following markup on the HEAD section of your view layout file, when bsVersion is set to 4.x or 5.x.
Option 1: Font CSS version of Font Awesome:
<!-- on your view layout file HEAD section --> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.3.1/css/all.css">
Option 2: SVG / JS version of Font Awesome (recommended for cleaner scaling vector icons and features like icon layers):
<!-- on your view layout file HEAD section --> <script defer src="https://use.fontawesome.com/releases/v5.3.1/js/all.js" crossorigin="anonymous"></script>
Alternatively, you can use the FontAwesomeAsset from the kartik-v/yii2-icons package to load the SVG/JS version.
// on your view layout file use kartik\icons\FontAwesomeAsset; FontAwesomeAsset::register($this);
The yii2-number extension can be installed automatically or manually using one of these options:
Installation via Composer is the recommended and most easy option to install Krajee Yii2 extensions. You can install yii2-number via composer package manager. Either run:
$ php composer.phar require kartik-v/yii2-number "dev-master"
or add:
"kartik-v/yii2-number": "dev-master"
to your application's composer.json file.
You may also manually install the extension to your project (in case your composer install does not work). Just download the source ZIP or TAR ball and extract the extension asset files and folders into your project. You may need to install dependencies manually and also set the namespaces to the extensions in your Yii2 extensions configurations manually.
To use with Bootstrap library - you can set this to any string starting with
3 (e.g. 3 or 3.3.7 or 4.x / 3.x)
To use with bootstrap 4 - you can set this to any string starting with
4 (e.g. 4 or 4.6.0 or 4.x)
To use with bootstrap 5 - you can set this to any string starting with
4 (e.g. 5 or 5.1.0 or 5.x)
array, the bootstrap grid column css prefixes mapping, the key is the bootstrap versions, and the value is an array containing the sizes and their corresponding grid column css prefixes. The class using this trait, must implement kartik\base\BootstrapInterface. If not set will default to:.
[
3 => [
self::SIZE_X_SMALL => 'col-xs-',
self::SIZE_SMALL => 'col-sm-',
self::SIZE_MEDIUM => 'col-md-',
self::SIZE_LARGE => 'col-lg-',
self::SIZE_X_LARGE => 'col-lg-',
self::SIZE_XX_LARGE => 'col-lg-',
],
4 => [
self::SIZE_X_SMALL => 'col-',
self::SIZE_SMALL => 'col-sm-',
self::SIZE_MEDIUM => 'col-md-',
self::SIZE_LARGE => 'col-lg-',
self::SIZE_X_LARGE => 'col-xl-',
self::SIZE_XX_LARGE => 'col-xl-',
],
5 => [
self::SIZE_X_SMALL => 'col-',
self::SIZE_SMALL => 'col-sm-',
self::SIZE_MEDIUM => 'col-md-',
self::SIZE_LARGE => 'col-lg-',
self::SIZE_X_LARGE => 'col-xl-',
self::SIZE_XX_LARGE => 'col-xxl-',
],
];
The NumberControl widget supports all the parameters similar to the \yii\widgets\InputWidget widget. The
following additional properties are important for the plugin configuration:
array the HTML attributes for the base model input that will be saved typically to database. The following special options are recognized:
type: string, HTML input type. Defaults to 'text'. Note that the saveInputContainer settings will control the display of the saved input.
label: string, any label to be placed before the input. Note that the saveInputContainer settings will control the display of the label.
string the name of the model attribute to read/write the masked number format data and is applicable only when using with a model. If not set a normal native HTML text control will be generated as the display input.
array the HTML attributes for the container in which the saved input will be rendered. This will default to ['style' => 'display:none'] to ensure the save input is hidden by default.
array the plugin options as supported by the jQuery input mask plugin. This defaults to the following setting:
[
'alias' => 'numeric',
'digits' => 2,
'groupSeparator' => ',',
'autoGroup' => true,
'autoUnmask' => true,
'unmaskAsNumber' => true,
]
use kartik\number\NumberControl;
/**
* All the examples below use the following variables for settings
*/
$dispOptions = ['class' => 'form-control kv-monospace'];
$saveOptions = [
'type' => 'text',
'label'=>'<label>Saved Value: </label>',
'class' => 'kv-saved',
'readonly' => true,
'tabindex' => 1000
];
$saveCont = ['class' => 'kv-saved-cont'];
// Simplest use of NumberControl without ActiveForm or model with default settings
// to render a formatted decimal
echo NumberControl::widget([
'name' => 'amount_drcr',
'value' => 20322.22,
'options' => $saveOptions,
'displayOptions' => $dispOptions,
'saveInputContainer' => $saveCont
]);
// Number mask widget with ActiveForm and model validation rule (amounts between 1 to 100000).
// Initial value is set to 1400.50. Note the prefix and suffix settings and how the minus sign
// is disallowed.
echo $form->field($model, 'amount')->widget(NumberControl::classname(), [
'maskedInputOptions' => [
'prefix' => '$ ',
'suffix' => ' ¢',
'allowMinus' => false
],
'options' => $saveOptions,
'displayOptions' => $dispOptions,
'saveInputContainer' => $saveCont
]);
// Example of using plugin's ability to control limits by setting min and max between `1000` to `100000`.
// Initial value is set to `1999.32`.
echo NumberControl::widget([
'name' => 'amount_range',
'value' => 1999.32,
'maskedInputOptions' => [
'prefix' => '₹ ',
'min' => 1000,
'max' => 100000
],
'options' => $saveOptions,
'displayOptions' => $dispOptions,
'saveInputContainer' => $saveCont
]);
// Example of number mask widget for a different locale using comma `,` as the decimal separator and
// dot `.` as the thousands separator. Initial value is set to `78263232.01`.
echo NumberControl::widget([
'name' => 'amount_german',
'value' => 78263232.01,
'maskedInputOptions' => [
'prefix' => '€ ',
'groupSeparator' => '.',
'radixPoint' => ','
],
'options' => $saveOptions,
'displayOptions' => $dispOptions,
'saveInputContainer' => $saveCont
]);
// Number mask widget to display an integer with zero precision along with prefix and suffix.
echo NumberControl::widget([
'name' => 'amount_rounded_1',
'value' => 1000,
'maskedInputOptions' => [
'prefix' => '$ ',
'suffix' => ' €',
'digits' => 0
],
'options' => $saveOptions,
'displayOptions' => $dispOptions,
'saveInputContainer' => $saveCont
]);
// A disabled NumberControl input.
echo NumberControl::widget([
'name' => 'amount_1',
'value' => 28239.35,
'disabled' => true,
'displayOptions' => $dispOptions
]);
// Number mask widget with a default placeholder and null values allowed
echo NumberControl::widget([
'name' => 'amount_ph_1',
'value' => null,
'options' => $saveOptions,
'displayOptions' => $dispOptions + [
'placeholder' => 'Enter a valid amount...'
],
'saveInputContainer' => $saveCont
]);
// Set customized masked input / additional options (e.g. prevent the default right align
// and left align the input text. Also set no group separator and hide decimal digits.
echo NumberControl::widget([
'name' => 'phone_2',
'value' => null,
'options' => $saveOptions,
'displayOptions' => $dispOptions + [
'placeholder' => 'Enter a valid phone number...'
],
'saveInputContainer' => $saveCont,
'maskedInputOptions' => [
'groupSeparator' => '',
'digits' => 0,
'rightAlign' => false
]
]);
yii2-number is released under the BSD-3-Clause License. See the bundled LICENSE.md for details.
Comments & Discussion
Note
You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.
The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.