Skip to Main Content

Breadcrumb

Overview

The FOS - Range Slider item plug-in is a lightweight range slider with multi-touch support and is packed with features. It supports numeric and date ranges, non-linear ranges, has keyboard support, and it works great in responsive designs. You can:

  • Use it vertically or horizontally
  • Use either a single or multiple value range
  • Restrict the minimum/maximum range values
  • Set page items with the range values
  • Control the range colour
  • Control the step size

It's the perfect page item filter for your reports and charts.

This item plug-in integrates the noUISlider JavaScript Range Slider (https://refreshless.com/nouislider/).

Examples

Range and Handles

The range slider can be initialized with one (single) or two (double) handles. Choose the single option when the user needs to select a single value in a predefined range, whilst the multiple option is best suited when the user needs to select a range for a report filter e.g. "From Date" and "To Date"

You can set how much the handles change the value of the slider by using the Step option. It sets the "jump-amount" between the intervals, thus it won't be possible to move the handles in smaller intervals than the set Step.

Getting and Setting Values

With a "single handle" the return value is a string representing the selected value, while with "double handles" the item will return a string of colon-separated values: for the lower and the upper range values.

Based on the number of the "Handles" you have the option to bind the slider's value to page item(s). To do so, the "Bind Value to Item(s)"" option has to be checked and the target page item(s) needs to be listed in the "Set Item(s)" attribute.

Note: if you use a step size greater than 1 and set the page item with a value that is not a valid step value then the number will be rounded to the nearest step size. Similarly if you set the page item with a value outside of the range boundary it will be set to the minimum/maximum respective value.

Changing the value of the slider automatically updates the item's value; the same mechanism applies the other way around, too.

If the provided value is out-of-range, the value will be set to the closest end of the slider.

Styling: Color, Ticks, and Orientation

There're several options available to customize the plug-in so you can provide a more user-friendly experience.

If the Connects Bar option is checked, you have the possibility to change the color of the range using the Range Color attribute.

 

The Ticks attribute defines the number of visible ticks. The ticks are clickable by default - clicking a label directly sets the value of the label, clicking the tick-markers calculates the value of that marker and sets that.

The Tooltip option adds a tooltip to every handle indicating the selected value; the Orientation attribute allows you to create Horizontal or Vertical range sliders.

Number Formatting

The values appearing in the slider can be easily formatted. This applies to ticks, tooltips and (partially) to the value returned by the slider. The only additional requirement is to set the config.numberFormat through the "Initialization JavaScript Code".

By setting the "decimals": 2, "thousand": ".", "suffix": " €" you can achieve the following number format in the demo's below. Here is an example of the "Initialization Javascript Code" config:

function(config) {
    config.numberFormat = {
        "decimals": 2,
        "thousand": ".",
        "suffix": " €"
    };
    return config;
}

Note: the full list of the available settings can be found in the plug-in attribute help text.

Note: the format mask does not have any effect on the item's value, it will always be a number (wrapped in a string - if you are accessing it through Javascript). The only exception (and this is why "partially" was mentioned above) is the decimal separator. The decimal separator set in the config will be always kept to accommodate different locales. See the example below:

Another important thing to note is that from APEX 21.1 onward you must have the same decimal separator on both the range slider and the bound fields if they are "Number Fields" (where the separator is based on your app's language settings). If the bound fields are not "Number Fields", the decimal separators do not have to be the same (although it is recommended for consistency).

Working with Dates

Besides working with number ranges, the range slider also provides date range support in a similar fashion. All the presented features are available with date ranges too.

The date format mask can be set through the native "Format Mask" attribute; the only thing you have to keep in mind, is that the "Minimum Date" and "Maximum Date" values must have the same format as the format mask.

The "Date Steps" attribute provides multiple options ('Daily', 'Weekly', 'Monthly', 'Yearly') to set the range slider steps.

Multiple Handles

Setting "Handles" to "Double" creates a perfect interface to define a specific date-range. And just as with numbers, through items listed in the "Bind Value to Item(s)" attribute, it's very simple to get and set the value of the slider.

Using a Week Format Mask

When using the week format you will need to provide a separate format for your timeline display format. This will avoid "ORA-01820: format code cannot appear in date input format" on the "to_date" function we apply to your min/max value and also allow us to return the value in a format that can be easily saved.

Design

You can preview the plug-in setup as you would see it in page designer. You can either do this by clicking this button in the top right corner of each example, or you can see all the examples together in the region below.

Looking at the examples you'll see just how easy the plug-in is to use. Don't worry about changing any values as they aren't saved. We actually encourage you to change them, so you can see the behaviour of the attributes and their help text.

FAQ

  • My slider's ticks are not distributed in equal distances / intervals. Why does this happen?

    The ticks are always displayed at points which you can set as a value on your slider.

    Let's take this example: Your Step is 10, slider's min is 0 and max is 100. You have 5 ticks which would put them at 0, 25, 50, 75, 100 IF all these values were really settable on your slider. But values 25 and 75 can never be set as your step is 10, so the ticks from these points will be moved to one of the closest settable points (most likely 30 and 80).

  • The monthly steps in the date slider are 1 day off if I use the last day of a 31-day-month as the starting date.

    This is an edge-case if you use the last day of a 31-day-month as the starting date: The next step will be the 30th day of the next month (as it, of course, has only 30 days and not 31 /unless we are talking about Dec and Jan/). After that, the next 31-day-month's day will still be the set to the 30th because of the monthly step from the previous month.

    This is because we cannot determine whether you really meant the last day of the month or not. Should we always move to the last day? But what if you choose a month with 30 days as the starting month? Should we automatically assume that if you move the handle to a month with 31 days, it should take the last - 31st day? Or you just wanted the 30th day?

    See where we are going with this?

    Also, let's not forget about February, leap-years, etc. It just gets more complicated.

    If this is something important for you, it is advisable not to show days at all, format your date to show only the months & years and subsequently you could sanitize your incoming date value and always set it to your desired day.

  • Why does the slider always set the max value when the user tries to set a completely different value?

    The possible reason may be that you are using APEX 21.1 or greater and you have bound fields of type "Number" and your decimal separator of the Range Slider is not the same as the decimal separator coming from your app language settings (and thus applied for the number fields).

    APEX 21.1 changed the return values of number fields meaning that if your decimal separator is wrong, it will just ignore the character. So if the range slider sets the value of this field (with a wrong decimal separator), the field will ignore the separator and remove it and the number will be larger than what you intended to set.

    Please use the same decimal separator or change your field to "Text".