Class: cSelectionSource

cObject
---cSelectionSource

The selection source represents the source of options/items provided for the cTagsForm, cDbTagsForm and cWebTagsForm classes.

It is expected to be used as a sub-object of these controls, but it could also be placed elsewhere and attached by setting a property (phoSelectionSource). Selection sources can be shared by multiple controls.

The controls access the source to load a list of options, which can happen in three different modes: AllData, Paged, and Suggestions.

AllData
In this mode, determined by pbAllData, the items are all loaded at once. They will be cached on the client. Filtering is supported and happens on the client. If the list of items is expanded without filtering, all items will be shown with a scrollbar.

Paged
In this mode, determined by pbPaged, the data is loaded in pages. So, when the user expands the list without entering data, it will show a fixed number of items and a 'load more' button or link at the end. In this mode, data will be freshly loaded from the server every time the control is opened.

Suggestions
In this mode, determined by pbSuggestions, a fixed number of items is loaded, based on a filter. This happens as the user types in the control. This can be either a full-text search or an incremental filter based on the pbFullText setting.

The control will query the supported modes on initialization.

The selection list can operate in multiple modes. When opening the list without having typed a filter, it will show all the items and allow scrolling or paging. If a filter is typed and the selection list supports suggestion mode or uses the AllData mode, in which case filtering happens on the client, it will show only items that match the filter.

Data Aware

cWebTagsForm controls have a separate object, the cSelectionSource, that allows for distinct data biding. It alse offers great flexibility of loading data from a different table (or the same table) than the one that the control is bound to.

This is configured using Entry_Item and, optionally, the Server object. By default, a data-aware selection source supports paged data-loading and suggestions mode. It can explicitly be set to AllData by setting pbAllData to True.

Object oWebTagsForm1 is a cWebTagsForm
    Set piColumnSpan to 12
    Set psLabel to "Tags:"
        
    Entry_Item Customer.Likes

    Object oSelection is a cSelectionSource
        Set Server to oVehicles_DD
        Entry_Item LovableVehicles.Name
    End_Object
End_Object 

Note that in this case it does perform paged data loading, but since there are fewer items than the default page size (piPageSize), it does not show the 'load more' button.

Manual Loading

The selection source can also manually load its suggestions. In this case, it needs to indicate which type of tag-loading is supported and implement the right event for loading the data. The data can be provided by filling an array of tSelectionItem structs.

Object oWebTagsForm1 is a cWebTagsForm
    Set piColumnSpan to 12
    Set psLabel to "Tags:"
    Set psValue to "Firetruck, Ambulance"
    
    Entry_Item Customer.Likes
    
    Object oSelection is a cSelectionSource
        Set pbAllData to True
        
        Procedure OnLoadAllItems tSelectionItem[] ByRef aItems
            Move "Firetruck" to aItems[0].aValues[0]
            Move "Police Car" to aItems[1].aValues[0]
            Move "Ambulance" to aItems[2].aValues[0]
        End_Procedure
    End_Object
End_Object

To support the suggestion mode, pbSuggestions needs to be set to True and OnLoadItems needs to be implemented. This procedure gets a search string and a maximum number of results that should be returned as extra parameters. Paged data-loading can be supported by setting pbPaged to True and implementing OnLoadItems, which will get the expected number of items and the last item of the previous page.