NAME

CGI::PageValidator::MainLib::UserLib - User-modifiable library for CGI::PageValidator.

REQUIRES

Perl5.005

SYNOPSIS

One could make use of the library explicitly in this fashion:

        use ValidateLibraries::Lib::UserLib;
        my $userLibRef = UserLib();
        ... process $userLibRef ...

but it is suggested to use it automatically, wherein it is converted to Perl, loaded, and used by CGI::PageValidator::LibraryMgr.

DESCRIPTION

This user library UserLib works in conjunction with the system library SysLib. Definitions in SysLib are processed first. UserLib may therefore be used to redefine existing SysLib entries by creating ones of the same name which will override those in SysLib. With overriding you can add, subtract, or change properties of an existing definition.

You may also use the extension principle to base a new new definition on an existing one (from either SysLib or UserLib) with the base property. Extension allows you to: create an alias identical to an existing definition, change one or more properties in a definition under a new name, or add properties to a definition under a new name.

Note that definitions should be added to the JavaScript version of this file, not the Perl version, since the latter is automatically generated from the former (unless you're not using the JavaScript version at all).

The properties listed below are used by either the validation engine (CGI::PageValidator) or the page generator (CGI::PageGenerator) or both. Most of them are used by the validation engine, except for those beginning with the display prefix, which are for the page generator only.

Definition Syntax

Both SysLib and UserLib use identical formats. Each contains a list of library definitions. Each library definition contains one or more property definitions as shown:

        {
                <property definition>,
                . . .   
                <property definition>
        }

Each property definition contains a label and a value.

        [JavaScript] <label> : <value>
        [Perl] <label> => <value>

Again, it is recommended that you work only with the JavaScript file and let the system automatically generate the Perl. Note that only a subset of JavaScript syntax is allowed when doing this, though, which can be accommodated by the SimpleJs2Perl converter.

Each property is described below. The only required property is the name; all others are optional.

name: [value: identifier] This internal name uniquely defines a library definition. If you reuse an existing name, it overrides the former definition completely. See also: base property
displayName: [value: string] This is the external display name used to report validation errors (via CGI::PageValidator) and to generate web pages (via CGI::PageGenerator). If omitted, the name property is used. Example => a cardholder name for a credit card might have a name of CCName, and a displayName of Name on Card.
fieldGroupName: [value: identifier] This string corresponds to the internal name for a group definition. Each definition in the group should typically contain the same fieldGroupName property. A group defines the items which will all appear on one line, such as a city/state/zip-code group. See also: displayGroupName property
displayGroupName: [value: string] This string corresponds to the external name for a group definition. Each definition in the group should typically contain the same displayGroupName property. You may, however, use different names for greater flexibility. First, note that the CGI::PageGenerator will use the displayGroupName for the first group item encountered. Say, then, you have a date group consisting of a year, a month, and a day. For month you might use a displayGroupName of Month/Day/Year while for day, Day/Month/Year. See also: fieldGroupName property
displayWidth: [value: integer] Used by CGI::PageGenerator, this property specifies the width (in characters) of the element on the web page. If omitted, it defaults to the maxLen property.
displayHeight: [value: integer] Used by CGI::PageGenerator, this property specifies the height (in lines) of the element on the web page. If a scrolling list is being used, i.e. the enumList property is defined, this determines the size of the containing box. If a scrolling list is not used, this turns the plain text field into a text area, even if set to 1.
base: [value: other-name] Specifies another definition from which to inherit properties. All properties of the other-name are inherited, but any may then be overridden in the current definition.
dependsOn: [value: other-name | [ <other-name-1>,...,<other-name-n>] Specifies dependencies for the current definition. This provides a mechanism to link definitions for validation. For example, a credit card month depends on a credit card year. Note that to actually validate the linked items together, you must also specify a plugin property.
required: [value: boolean] Indicates to CGI::PageValidator whether this item is required, i.e. whether it may be left blank.
concealWeb: [value: boolean] Indicates whether the input value should be echoed when typed, i.e. should the HTML element be a text field or a password field. Used by CGI::PageGenerator. Note that concealWeb and concealLog are independent; to hide the typed value and to hide the value in messages you must specify both concealWeb and concealLog as true.
concealLog: [value: boolean] Indicates whether the input value of this item should be displayed or concealed in log files and messages. A credit card number, for example, would appear as "***********3214", giving a couple digits to identify the card number to one who would know it, but no one else would find it useful. Note that concealWeb and concealLog are independent; to hide the typed value and to hide the value in messages you must specify both concealWeb and concealLog as true.
enumList: [value: array of strings] A list of values to validate against CGI::PageValidator as well as a list of values to display in a scrolling field CGI::PageGenerator. If omitted, a plain text field is created rather than a scrolling enumerated list.
enumValues: [value: array of strings] You may separate the values to display from the values to return in a scrolling field. If this property is defined, these specify the return values, which must match the enumList property in a one-for-one correspondence.
minLen: [value: integer] The minimum number of characters to pass validation.
maxLen: [value: integer] The maximum number of characters to pass validation.
minVal: [value: integer] The minimum numeric value to pass validation.
maxVal: [value: integer] The maximum numeric value to pass validation.
pat: [value: pattern] A regular expression which must be matched to pass validation. This is where you have the most expressive input to define what is and is not acceptable input (not counting plugins).
patMsg: [value: string] This string is used for validation in conjunction with page generation, on both the front-end and back-end. The CGI::PageGenerator builds a page containing hidden error messages for every field using this string as the text of the message. Front-end validation will activate the error message. On some older browsers this text cannot be dynamically updated, so that is the one-and-only error text. Newer browsers (IE5.0+, NS6.0+) may have the text updated, depending on the particular validation error. Back-end validation will return an error message to the front-end which will again start with this string, but it may be changed depending on the particular validation violation.
plugin: [value: plugin-name] A string identifying your unique plugin class name. See CGI::PageValidator::Plugin for details on how to hookup and use plugins.
pluginOption: [value: string] A supplemental input to the plugin specified by the plugin property. This property is available if you need an additional input beyond what is provided by the dependsOn property.

Notes and Restrictions

--Any property may use a variable instead of a constant for its value.

--Variables must be defined before the main function (UserLib or SysLib) in this file and are thus global.

--Being global, variables defined in SysLib may also be used in UserLib, and vice versa.

--Each property must be on a separate line (i.e. do not put multiple properties on a line).

--Each property or variable must be wholly contained on one line; variable definitions, however, may run across multiple lines.

BUGS

None

AUTHOR

Michael Sorens

VERSION

$Revision: 7 $ $Date: 2006-12-19 21:11:31 -0800 (Tue, 19 Dec 2006) $

SINCE

CleanCode 0.9

CleanCode Perl Libraries