API: Gui

Filename:
fwpGui_listbox.ctag

Released With:
5.0.0

Current Version:
1.5.0

Status: Active

Min Lasso Tested: 8.1.0

Max Lasso Tested: 8.5.3

Related:

vlist_{name}

fwpGui_checkbox

fwpGui_radiobtns

fwpGui_popup

API Reference

fwpGui_listbox (Tag)

Description

(Though marked as active, this tag should no longer be used for new application development. Instead use the new fwp_valueList data type.)

Creates a listbox menu from a delimited list or array.

Syntax

[fwpGui_listbox: 
   -name = string,
   -id = string,
   -file = string,
   -indx = string,
   -list = string or array,
   -dflt = string,
   -var = string,
   -delimiter = string,
   -subdelimiter = string,
   -blank = 'Y'|'N'
   -size = integer,
   -css = string,
   -tab = integer,
   -dim = boolean]

Parameters & Member Tags

Parameters unique to this vlist tag

-blank - optional : 'Y' or 'N' to indicate whether the list should start with an empty option. If unspecified, an empty option is included.

-size - optional : an integer defining how many lines to display in the list box. If unspecifed, four lines are shown.

Parameters common to all vlist tags

-name - required : a string containing the value for the HTML name property of the field object (this also becomes the action_param name for Lasso).

-id - optional : a string containing the value for the HTML id attribute of the field object. If not specified the name attribute is used for id.

-list - optional : a delimited string, an array of delimited items, or an array of pairs containing the list of items to display in the value list field. The list can be constructed so that the displayed text and the selection value are the same or different. Therefore, a list of Small, Medium, Large can yield selected values of Small, Medium, Large or corresponding values such as sm, md, and lg.

Delimited strings use ``` between items and ___ between display and value sets, though it is also possible to define custom delimiters (see the delimiter parameters later in this section).

Arrays can define display items or display/value pairs. The latter can be delimited with ___ as a default or with a specified subdelimiter, or as an array of pairs.

Most of these options are automatically detected, so there is no need to specify which of the formats is being used except for custom delimiters.
Standard Delimiters:
Small```Medium```Large
Small___sm```Medium___md```Large___lg
Custom Delimiters:
Small--Medium--Large
Small/sm--Medium/md--Large/lg
Arrays:
(array:'Small', 'Medium', 'Large')
(array:'Small___sm', 'Medium___md', 'Large___'lg')
(array:'Small'='sm', 'Medium'='md', 'Large'='lg')

-file - optional : a valid Lasso file pathname to a file containing one or more delimited lists of items to display. See the {link=vlist_{name}:::/refc/vlist_{name}} config file for format rules. Requires only the name portion of the vlist_name.cnfg filename.

-indx - optional : the name of the map item from the config file indicating which list to display.

-dflt - optional : a string equal to the initial menu item value that is selected when the menu is displayed. For checkbox and scroll list tags, multiple defaults can be passed as an array, as a string delimited by the subDelimiter, or as a string delimited by \r as would be typical from a database field.

-var - optional : a string containing the name of a page variable into which the contents of the source list will be copied for the programmer's use elsewhere on the page. The variable will contain the list in the same format that was supplied to the tag. If the source was an array, the variable defined by -var will also be an array, etc.

-delimiter - optional : a string identifying the delimiter to use between displayed items (example: delimiter =':::' for One:::Two:::Three).

-subDelimiter - optional : a string identifying the delimiter to use between display and value items (example: subdelimiter ='--' for One--1:::Two--2:::Three--3).

-css - optional : a string equal to the name of the CSS class to be applied to the form input tag. Each tag has its own default value corresponding to the list type: fwppopup, fwpcheckbox, fwpradiobtns, fwplistbox. If CSS is not specified, the preceding class names will automatically be used.

Examples

[fwpGui_listbox: 
   -name='colors',
   -list='Red```Blue```Yellow```Green```Orange']

[fwpGui_listbox: 
   -name = 'smpl',
   -list = (array:'Red'='Red','Blue'='blu','Yellow'='ylw'),
   -dflt = var:'smpl',
   -blank = 'N',
   -]

[fwpGui_listbox: 
   -name = 'depts',
   -file = 'misc',
   -indx = 'departments',
   -dflt = (field:'myDept'),
   -var = 'companyDepts',
   -css = 'adminPopups',
   -tab = 1]