Class: cWebTagsForm
Properties | Events | Methods | Index of Classes
Web Framework form control for selecting or creating multiple items (tags) from a source.
Hierarchy
Library: Web Application Class Library
Package: cWebTagsForm.pkg
Description
The cWebTagsForm is a cWebForm-like control that allows for selecting 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"
End_Object
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
End_Object
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.