Class: cWebSlider

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebBaseDEO
------------------cWebSlider

Use the cWebSlider class to create a control capable of manipulating a numeric value belonging to a linear range. A slider displays a horizontal or vertical bar that represents the extent of the range and a slider handle that indicates the control's current value. The handle can be dragged along the bar to alter the current value within the allowed range.



Use a slider to represent any numeric value within a range where it is useful to display and manipulate an analog representation of that value, for example a slider representing a range of temperature values.

A slider can be used with or without a data binding. When used with a data binding the slider provides automatic support to display and manipulate a value from a database table.column. When used without a data binding you will use the class interface to read or write the control value.

Sliders can also be configured to represent two values, i.e. a "from" and a "to" value. In this case the slider control will render two slider handles: one to represent the "from" value and another to represent the "to" value.

Sample

Object oDemoSliders is a cWebView
    Object oCustomer_DD is a Customer_DataDictionary
    End_Object

    Set Main_DD to oCustomer_DD
    Set Server to oCustomer_DD

    Object oCreditLimit is a cWebSlider
        Entry_Item Customer.Credit_Limit
        Set psLabel to "Credit Limit:"
        Set piMinValue to 10000
        Set piMaxValue to 500000
        Set pbShowValue to True
        Set pbShowRange to True

        Procedure OnFillLabels
            Send AddLabel 100000 "Low"
            Send AddLabel 250000 "Medium" 
            Send AddLabel 400000 "High" 
        End_Procedure
    End_Object
End_Object

The above example, a cWebSlider object (oCreditLimit) has a data binding to the Customer.Credit_Limit column. This will indicate the current record's credit limit value by the setting the position of the slider handle within the range specified by the properties piMinValue and piMaxValue.

The OnFillLabels event has been augmented to create three labels along the length of the slider bar using the AddLabel method. The labels "Low", "Medium" and "High" will be displayed at positions 100000, 250000 and 400000 on the slider bar.

Object oSlider is a cWebSlider
    Set psLabel to "1 - 100"
    Set piMaxValue to 100
    Set piMinValue to 1
    Set piInterval to 1
    Set pbShowValue to True
    Set piSliderValue to 50
    Set pbShowMarkers to True
    Set pbShowRange to True
End_Object

The above example demonstrates a simple horizontal slider without a data binding.

Object Name

The Web Framework uniquely identifies each web object via a combination of the object hierarchy (object nesting), and object name. This means that web object names must be unique within their parent (i.e. each sibling web object must have a unique name).

Object Placement

Slider controls must be placed within a web container (e.g. cWebPanel, cWebView or cWebModalDialog).

Slider controls may not be nested inside other web controls. You may not mix web panels and web controls as sibling objects.

Data Binding

Slider objects support a data binding to display values from a database Table.Column. When the control has a data binding, then it will display the column value of the current record in the binding table. Manipulating the slider handle will update the table.column value in the correct way according to DataDictionary data binding rules.

Use the Entry_Item command to set the data binding.

Entry_Item Customer.Credit_Limit

Entry_Item expressions, e.g. (Inventory.Price + 100) are not supported in web object data bindings. Use the OnSetCalculatedValue event to define a data binding expression.

The data binding table.column must map to a data dictionary object (DDO) in the server DDO structure. Refer to the Data Dictionary Guide for more information.
A data binding provides data-aware behaviors that include:
- Finding, clearing, saving, and deleting records
- Prompt-object support
- Change verification (save, delete, and data-loss verifications)

Mapping Non-Numeric Columns

Normally, you would bind a slider control to a numeric column value. However, you can also provide mapping functions to translate the slider position to some arbitrary value and visa-versa. This allows you to bind a column of any data type to a slider control.

Augment ValueToPosition to translate the database column value into a slider position value within the allowed range. Augment PositionToValue to translate the slider position into the desired column value.

Value Range

Sliders configured to represent two values, i.e. a "from" and a "to" value, cannot be used with a data-binding (see Accessing the Control Value below).

Accessing the Control Value

psValue

The slider control can be used without a data binding by accessing the control's value.
WebGet or WebSet the psValue property to get or set the current `value' of the slider control.

OnChange

An event is triggered whenever the control value changes. This event can be handled on the server by writing DataFlex code. It can also be handled on the client (browser) by writing JavaScript code. Writing a server-side DataFlex handler is the simplest way to handle change events.

Set pbServerOnChange to True to instruct the client to send the OnChange event to the Server object whenever the control value is changed. Write an OnChange event handler in your slider object to perform some action when the control value changes. The OnChange event is fired after slider handle is released.

To write a client-side change event handler using JavaScript set the psClientOnChange property to the name of the JavaScript function that will execute when the control value changes.

If the control has a data dictionary server but does not have a data binding then a special event (OnSetCalculatedValue) is triggered for the slider whenever a find or clear operation is performed on the DDO. Write an OnSetCalculatedValue event handler in your slider object to generate a 'calculated' value for the control for each record in the server DDO's table.

Value From and To Range

Sliders can be configured to represent two values, i.e. a "from" and a "to" value. In this case, the slider control will render two slider handles: one to represent the "from" value and another to represent the "to" value.

Set pbRanged to True to configure the slider to display two handles.

WebGet or WebSet piFrom to get or set the first slider handle position. WebGet or WebSet piTo to get or set the second slider handle position. Do not use psValue to access the slider value when pbRanged = True.

Size and Location

Web controls are positioned by HTML flow layout (left to right, top to bottom). The relative position of the control in this flow is determined by the location of the object declaration in your code.

In addition to the flow layout, each web container is divided into a fixed number of equal-width columns (piColumnCount). Child controls are aligned to these columns to determine their horizontal position and width.

Set piColumnIndex to position a slider control in a particular column of the parent container.

Set piColumnSpan to determine the width of the slider control i.e., the number of columns occupied by the control. The actual width is determined by the number of columns and the width of the parent container.

For more information, see Positioning and Layout of Controls.

Each slider control has a pre-determined height according to the web application's CSS theme (psTheme). You can also instruct a slider control to occupy all available vertical height in its parent container by setting pbFillHeight to True.

Horizontal or Vertical Layout

A slider can be rendered either horizontally or vertically. Set pbVertical to True to render the slider vertically, the default value is False (i.e. the slider is horizontal).

When you have a vertical slider, you will adjust the piHeight property to determine the vertical height of the slider bar, or set pbFillHeight to True to occupy the maximum available vertical space.

Configuring the Slider Value

Set piMinValue and piMaxValue to set the upper and lower bounds of the allowed slider values, i.e. in a horizontal slider when the slider handle is in the full left position, the slider value will be equal to piMinValue.

Set piInterval to determine the value interval between each slider handle position, i.e. if you move the slider one position to the right, then the slider value will be incremented by the value of piInterval. Ensure that piInterval is set to a value that fits evenly between piMinValue and piMaxValue.

Configuring the Slider Appearance

Set pbShowMarkers to render marker lines along the length of the slider bar where each line demarks the position of a possible slider value. The number of lines shown is determined by subtracting the min value from the max and dividing by the slider interval ((piMaxValue - piMinValue) / piInterval).

Set piMaxMarkers to limit the number of marker lines rendered when pbShowMarkers is true.

Set pbShowValue to True to display the current slider value as a number above the slider bar. If the slider is configured to show two bars in a range (pbRanged = True), then set pbShowRange instead of pbShowValue.

Label Support

By default, a portion of the control's width is reserved to display a descriptive label. By default the label is displayed to the left of the control and consumes approximately 120px of the total width.

Set psLabel to the text string you want to display as a label.

Set peLabelAlign to position the label text to the left, right or center of the space allocated to the control's label (alignLeft, alignRight, alignCenter).

Set peLabelPosition to change the position of the space allocated to the control's label. By default, the label is positioned to the left of the control (lpLeft). The label can also be positioned above or to the right of the control (lpTop, lpRight).

Set piLabelOffset to change the amount of space that is consumed by the control's label. By default, the label consumes approximately 120px.

The label's text color is determined by the web application's CSS theme (psTheme). Set psLabelColor to directly override the label's CSS themed color.

Set pbShowLabel to False to hide the label and remove space used the control's label. By default, pbShowLabel is True.

Slider-Bar Labels

You can configure your slider to display a set of labels at intervals along the length of the slider bar.

Augment the OnFillLabels event to define each slider-bar label and its associated value.

Drag and Drop Support

This control can be used as a valid drop target by registering it as such in a cWebDragDropHelper object.

The supported actions for this control are:
- C_WebDropOnControl

This allows the control to accept data dragged from elsewhere in the control (if configured that way) and can also be used to accept files when registered within a cWebDragDropFileHelper.

Color

The color of a slider control is determined by the web application's CSS theme (psTheme). You can define additional or replacement CSS styles in your web application's application.css file. Set psCSSClass to the CSS class name you would like to be applied to a slider control.
Set psBackgroundColor and psTextColor to directly override the control's CSS themed color.

Styling Web Applications