API: Gui

Filename:
fwpGui_valueList

Released With:
5.2.2

Current Version:
1.0.0

Status: Active

Min Lasso Tested: 8.1.0

Max Lasso Tested: 8.5.3

Related:

API Reference

fwp_valueList (Type)

Description

The fwp_valueList type creates independent objects which can be rendered as an HTML value list in the form of a popup menu, checkboxes, radio buttons, or list box. Each value list has one or more options and behaviors unique to its list type, but for the most part, all share a majority of common features and programming requirements.

Each value list style is able to display any combination of default selection(s) which represents an initial state or the state of an application variable, database field, or other data container. The draw code of the data type will generate all necessary HTML to display and control the value list including customized HTML attributes.

The list of selection options can be supplied to a value list object from an array of pairs, from a specially formatted text file, or from a specially structured data table. Generally speaking, the text files are the most common source as theyre convenient for grouping multiple lists in one place and, like many PageBlocks features, allow for site and module-specific versions. File contents are cached so performance is not hindered by repeated reading of the text file. The database table source is more effective for situations where several applications maintained as separate PageBlocks projects need to share a common value list source to avoid having to maintain redundant copies of config files.

Syntax

//------ performed in the logic file ------------

var:'listName' = (fwp_valueList:
    -withoutCaching,
    -asVertical, 
    -asHorizontal,
    -file            = fileName,
    -table           = tableName,
    -scope           = 'site'|moduleName,
    -list            = array_of_pairs | listName,
    -titleOption     = '',
    -currentValue    = '',
    -attributes      = (map:
        'disabled'   = 'disabled'|optionsToDisable,
        'id'         = string,
        'name'       = string,
        'class'      = string,
        'tabindex'   = string|integer,
        'onblur'     = string,
        'onfocus'    = string,
        'onchange'   = string));

//------ performed in the display file ------------

$listName->(draw:
    -diabled      = string,
    -currentValue = string,
    -tabIndex     = string|integer,
    -id           = string,
    -class        = string);

Parameters & Member Tags

Creating vList Objects

Parameters Common to All Value List Types

-file - optional : defines which config file to use. Config file names follow the naming convention of valueList_{name}_ {language}.cnfg. The -file parameter declares the {name} part. The internal code will automatically determine language if is not passed by the -language parameter. So, to use the vaue list file valueLists_products_en-us.cnfg, you'd declare -file='products'. Refer to the section Preparing Value List Text Files for detailed information about file format.

-table - optional : the reference name of the data table to use from the $fw_gTables map. Pass just the reference name, not the $fw_gTables value. So, if $fw_gTables has entries like this

'pbrefc' = 'pbReference',
'vlists_en-us' = 'valueLists_en_us',
'vlists_it' = 'valueLists_it',
'appstrings_en-us' = 'appStrings_en_us',
'appstrings_it' = 'appStrings_it',

define the table like one of these methods

-table = 'vlists_en-us'
or
-table = 'vlists_' + ($fw_client:'language')

-scope - optional : applicable only if the -table parameter is used, this option defines whether a list defined as having site scope or module scope should be used. In the database table, lists which are applicable to the whole site are defined in the listScope field with "site" as the scope. Lists which are applicable to a specifc module are defined with listScope as the name of that module (using the module folder name).

-list - required : defines the exact list to use. This can either be an array or an array of pairs to hard code a list or pass a dynamic list. It will most typically be the list name of a list definition from a config file or data table.

-titleOption - optional : the behavior of this one changes depending on list style. For popup and listbox lists, this defines a extra selection option to appear at the top of the list. Typically this would be used to add a "Please select..." or a blank entry at the top of the list. This allows the same list to be used for multiple displays. For example, in a data entry form, the list can have "Please Select..." at the top while in a search form could have "All" at the top. For checkbox and radio buttons, this parameter will add a <fieldset> around the tag with the <legend> containing the titleOption value.

-currentValue - optional : declares a value that should be selected/checked when the list is drawn. For popups and radio buttons, this must be a single value. For checkboxes and list boxes, this can be a single value or multiple values declared as a single string delimited with \r. This format was chosen to make it easier to pass field contents which retain the \r formatting of the original selection.

-withoutCaching - optional : this parameter has no value. It declares that the resulting HTML generated from this list should not be cached. usually lists should be cached for better performance, but there are occasions where the list should not be cached because it is subject to dynamic content changes.

-attributes - required : a map of HTML attribute name-value pairs. For popups and list boxes, this declares the attributes of the <select> tag. For radios and checkboxes, this declares the attributes of each <input> tag. The minimum requirement is for the attribute name to be declared. All others are optional. See the Defining Attributes section for more details.

Parameters Specific to Radio Buttons and List Box Lists

-asVertical - optional : declares the the list should be displayed vertically. Each list item is separated with a <br />.

-asHorizontal - optional : declares the the list should be displayed horizontally. Each list item will have three trailing  

Defining the Attributes Map

For popups and list boxes, attributes are applied to the <select> tag. For radios and checkboxes, attributes apply to each <input> tag. The minimum requirement is for the attribute name to be declared. All others are optional, some are added with default values (explained below).

The attributes values are supplied as a map when the object is created. Each attribute in the map is added exactly as submitted (exceptions are explained in the Default Attributes section below). This allows the developer to customize attributes as needed, and even allows for non-standard or future standards to be accommodated.

Default Attributes

• name will always be added, even if empty.
• id will always be added. It will be the same as name if an alternate value is not specified. For radios and checkboxes, id is automatically incremented with a numer appended to the name supplied (e.g. myIDName1, myIDName2, myIDName3...).
• class will always be added. Default values depend on the list type and will be fwppopup, fwplistbox, fwpradiobtn, or fwpcheckbox if an alternate is not specified.
• size is hard coded as 1 for popups. It defaults to 4 for list boxes if an alternate is not specified.
• tabindex is automatically incremented for radios and checkboxes if an initial value is provided. The tabindex value is not cached, so the same list can be used from cache in different cases with unique tabindex values for each use.
• disabled will disable the entire list for popups and listboxes, but for checkboxes and radio buttons, if specific options are defined, only they will be disabled (use a \r or comma delimited list of options).

Drawing

There are member tags for drawing each list type:
->drawAsPopup
->drawAsRadioButtons
->drawAsCheckBoxes
->drawAsListBox

Parameters for Drawing

If all parameters are defined at the vlist creation, the drawing tags need no parameters, However, while all parameters can be defined at object creation, there maybe occassion to specify some details at the time the HTML is drawn. The draw tags allow for the these parameters to be defined:
-disabled
-currentValue
-tabIndex
-id
-class

Examples

This code creates a popup menu where the list options have been pulled from the file valueLists_general_en-us.cnfg, the current month will be preselected, and where upon selecting a value, the onchange attribute will run the JavaScript function jumpToPage.

var:'jumpToMonth' = (fwp_valueList
    -file           = 'genl',
    -list           = 'monthsLong',
    -titleOption    = 'Pick a calendar to view...',
    -currentValue   = (date->month:-long),
    -attributes     = (map:
        'name'      = 'jumpToMonth',
        'tabIndex'  = 9,
        'onchange'  = 'jumpToPage(this.value)'));

$jumpToMonth->drawAsPopup

This list will display the days of the week as horizontal checkboxes, and disable the Sun and Sat boxes.

var:'m_availableDays' = (fwp_valueList:
    -file           = 'genl',
    -list           = 'daysShort',
    -attributes     = (map:
        'name'      = 'm_availableDays'));

$m_availableDays->(drawAsCheckBoxes:
    -disable = 'Sun\rSat')