Yii 2 Number

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.

An advanced number input for Yii Framework 2 based on jQuery input mask plugin (which internally is available via 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:
  • default styling for Bootstrap 3 and supports Yii Active Field validations
  • automatically read a float/decimal and convert it to the number format on field load
  • automatically convert back the field to a float/decimal for saving once the mask is changed (maintains an internal hidden field)

Note

This extension replaces the yii2-money extension since Jan 2018. The yii2-money will not be enhanced or supported further.

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

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

or add:

"kartik-v/yii2-number": "*"

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 NumberControl widget supports all the parameters similar to the \yii\widgets\InputWidget widget. The following additional properties are important for the plugin configuration:

disabled

boolean whether the input widget is to be entirely disabled. Defaults to false.

readonly

boolean whether the input widget is to be entirely readonly. Defaults to false.

options

array the HTML attributes for the base model input that will be saved typically to database. The following special options are recognized:

  • type: string, whether to generate a 'hidden' or 'text' input. Defaults to 'hidden'.

  • label: string, any label to be placed before the input. Will be only displayed if 'type' is 'text'.

displayOptions

array the HTML attributes for the displayed masked input

saveInputContainer

array the HTML attributes for the container enclosing the save input. This will default to ['style' => 'display:none'] for a hidden type save input.

maskedInputOptions

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,
]

Simplest use of NumberControl without ActiveForm or model with default settings. Initial value is set to 20322.22.


Money 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.

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.


Example of money 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.


Number mask widget to display an integer with zero precision along with only a prefix.


A disabled NumberControl input.


Number mask widget with a default placeholder and null values allowed.

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
]);

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