Skip to content

Class: cSelectionSource

Properties | Events | Methods | Index of Classes

Source of options/items provided in cWebTagsForm

Hierarchy

cObject > cSelectionSource

Show full hierarchy and direct subclasses

Library: Common Class Library

Package: cSelectionSource.pkg

Mixins: cBaseDEO_Mixin, cFilterExpression_mixin

Description

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 the SelectionSource property. Selection sources can be shared by multiple controls.

The controls access the source to load a list of options in one of three mutually exclusive modes: AllData, Paged, or Suggestions.

AllData In this mode, determined by pbAllData, the items are all loaded at once and cached on the client. Filtering happens locally. Use this mode only for smaller data sets.

Paged In this mode, determined by pbPaged, data is loaded in pages. The list shows a fixed number of items and adds a show-more action when another page is available.

Suggestions In this mode, determined by pbSuggestions, the current filter is sent to the server and the returned matches replace the suggestion list. This can be either a full-text search or an incremental filter based on pbFullText. Suggestion mode does not add a show-more action.

The control queries the supported mode on initialization. Set exactly one of pbAllData, pbPaged, or pbSuggestions to True; enabling more than one is invalid.

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. A data-aware source must use one loading mode: paged loading, server-backed suggestions, or AllData. Set the corresponding property explicitly when selecting a non-default mode.

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.