Class: cWebTagsForm

Properties  Events  Methods    Index of Classes

Web Framework form control for selecting or creating multiple items (tags) from a source



Library: Web Application Class Library

Package: cWebTagsForm.pkg


The cWebTagsForm is a cWebForm-like control that allows for selecting of multiple items from a source (which can be a table or anything else) or even creating new items. The selected or created items are visually represented by boxes/balloons called tags.

A cWebTagsForm with several tags in it:

A cWebTagsForm with a dropped down suggestion list:

Selection is done by typing text into the form and, optionally, a list of items to select from is displayed. See cSelectionSource for information on how this list can be controlled and seeded. Without a cSelectionSource configured, it can still be used to show and edit tags using free text entry (if pbAllowCreate is True).

Items are presented by a comma-separated list of strings or as an array of strings. This is a simplification regarding the previous implementations. The control does not keep extra data for the items. Only CSS classes can be set for the items, but this happens through separate APIs. Another simplification is that when filling the control, it does not check if items are actually part of the selection set, that is considered application logic.

Simple Usage

The code below shows the most basic instantiation of the cWebTagsForm and what it will display. Notice that psValue can be set to a comma-separated list of tags.

Object oWebTagsFormBasic is a cWebTagsForm
    Set piColumnSpan to 12
    Set psLabel to "Tags:"
    Set psValue to "DataFlex, CSS, SQL"

By default, new tags can be created by typing and pressing enter. This performs no database operations whatsoever, but it will display a popup indicating that a new item will be created when Enter is pressed.

Values can be queried by using psValue, which always returns a comma-separated list of values, and updating can be done via a WebSet of psValue.

WebGet psValue of oWebTagsFormBasic to sVal
Move (sVal + ", Police Car") to sVal
WebSet psValue of oWebTagsFormBasic to sVal

Escaped Characters

Commas in values are escaped using the backslash - \. So when the user types a , (comma) it will be presented in the value as \,. When the user types a \ (backslash) it will be escaped as \\.

Data Binding

The form can be data bound by simply adding an Entry_Item. Doing this will make it save the comma-separated list into the database.

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

Array Access

As an alternative to working with the raw comma-separated list, two simple methods are available to get the tags as a string array and update them from a string array. The methods (GetTags and UpdateTags) internally just WebGet and WebSet psValue. They also take care of escaping / unescaping the items.

String[] aTags

Get GetTags of oWebTagsFormBasic to aTags
Move "Police Car" to aTags[SizeOfArray(aTags)]
Send UpdateTags of oWebTagsFormBasic aTags

Drag and Drop Support

Drag Support

This control allows parts of itself to be picked up and dragged to other places in your interface. To do this, register it as a drag source in a cWebDragDropHelper.

Supported drag actions for this control are:
- C_WebDragTagsFormTag

Drop Support

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

The supported drop actions for this control are:
- C_WebDropOnControl, C_WebDropTagsFormInput

File Drop Support

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.

WebContextMenu Support

cWebContextMenu support is provided through the C_WebUIContextTagsFormTag Context, then the psContextValue property will be filled with a comma separated list of items.