How to use the jQuery UI Spinner Widget in 5.7.4+

The Spinner Widget is part of the jQuery UI library. The jQuery UI library is included in Concrete CMS as an asset that is available by default in the concrete user interface. This makes jQuery UI ready to use without any extra configuration.

https://jqueryui.com/spinner/

in form.php

The form widget is used to create the input field that will be turned into a spinner.

$form->text('spinner_example', $spinner_example)

In a script tag, often included before the closing body tag, include the element selector and the spinner method.

$(document).ready(function() {
    $('#spinner_example').spinner();
});

in db.xml

When using form inputs intended to take decimal numbers. The field requires an "F" type (floating point number). For non-decimal numbers, an "I" type (integer) can be used.

Basic Options:

min - the minimum allowed value
max - the maximum allowed value
step - the size of the step when using the spinner buttons - i.e. a step of 5 would increment or decrement the value by 5
numberFormat - format of input numbers (the "n" format is for decimal numbers)

Example: minimum of 0, maximum of 5, step in 0.1 increments, and set the number format to decimal

$('#spinner_example').spinner({
    min: 0,
    max: 5,
    step: 0.1,
    numberFormat: 'n'
});

Adding form input attributes to the form widget:

text( string $key, string|array $valueOrArray = false, array $miscFields = array() )

The optional third parameter of the text form widget takes an associative array. The associative array is made of key value pairs.
- the key is the attribute name
- the value is the attribute value

Example:

$form->text('spinner_example', $spinner_example, array('style' => 'text-align: center;', 'maxlength' => '4', 'class' => 'validation'))

attributes added:
- style="text-align: center"
- maxlength="4"
- class="validation"

Using the spinner widget on multiple inputs that share the same class:

If a form has multiple inputs that have the same options (the same min, max, step, validation, etc.). They can be targeted with one spinner widget call if they share the same class. When naming the class, it can be helpful for it to be descriptive of what the spinner does.

Example: .spinner-min0-max10-validate
- spinner with a min of 0, max of 10, and has validation
- all inputs with the class "spinner-min0-max10-validate" will become a spinner using these settings

$('.spinner-min0-max10-validate').spinner({
    min: 0,
    max: 10,
    change: function() {
        var min = $(this).spinner('option', 'min');
        var max = $(this).spinner('option', 'max');

        if (isNaN($(this).val())) {
            $(this).spinner("value", min);
        } else if ($(this).val() > max) {
            $(this).spinner("value", max);
        } else if ($(this).val() < min) {
            $(this).spinner("value", min);
        }
    }
});

Validation:

While min and max values can be set for the spinner controls, there is nothing preventing other values from being entered. Number values less than or more than the minimum and maximum and even non-numbers can be entered. Basic validation can be added to restrict the input values to minimum, maximum, and numbers only. Client side validation in the browser with JavaScript is not a substitute for server side validation on public facing forms.

Example: limit input values to the minimum, maximum, and numbers only

$('#spinner_example').spinner({
    min: 0,
    max: 10,
    change: function() {
        var min = $(this).spinner('option', 'min');
        var max = $(this).spinner('option', 'max');

        if (isNaN($(this).val())) {
            $(this).spinner("value", min);
        } else if ($(this).val() > max) {
            $(this).spinner("value", max);
        } else if ($(this).val() < min) {
            $(this).spinner("value", min);
        }
    }
});

The validation runs when the value of the spinner has changed and the input is no longer focused.
- if the input value is NaN (not a number), then the value of the input is set to the minimum
- if the input value is greater than the maximum, then the value of the input is set to the maximum
- if the input value is less than the minimum, then the value of the input is set to the minimum