NAME

SchemaField - class to represent and manipulate a schema field

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

Copyright 1999-2011 Applied Testing and Technology, Inc. All Rights Reserved.

SYNOPSIS

use Schema;
    use SchemaField;

    # create a schema object
    $schema = new Schema(suiteName);

    # get an individual field
    $field = $schema->field(fieldName);

    # get the prompt for a field
    $prompt = $field->prompt();

The SchemaField object is used by Schema objects to access and manipulate their fields. It is also available directly to applications, should they need to access the attributes of a schema field.

METHODS

new - open the Schema

$field = new SchemaField(hash);

Creates a new SchemaField object and associates its attributes with the object.

hash

a hash of field attributes

returns a reference to the SchemaField object.

name - return the name of the field

$name = $field->name();

parent - return reference to parent schema object

$schemaH = $field->parent();

asHtml - render a field in HTML format

$output = $field->asHtml($value [, $oval] ) ;

value is the value to render.

oval is a supporting value that will be used as a URL when interpreting atm_prid fields.

Returns the content, annotated according to its style.

calculated - if the field is derived from other fields

$field->calculated() ;

cantSelect - see if a field is not selectable inherently

$field->cantSelect();

canSearch - see if a field is string searchable

$field->canSearch();

descs - retrieve the list of descriptions associated with a schema field

@descs = $field->descs( [ $valStr ] );

valStr is an optional string of comma-separated values. If supplied, the description list is updated.

Returns a list of descriptions.

descOf - return the description of a value

$desc = $field->descOf($value [, $annotate] ) ;

value is the value to describe.

annotate inidicates whether the description should be annotated if the item is marked as obsolete.

Returns the associated description if the variable is a list. If value if a reference to an array, then returns a reference to an array of descriptions.

descMap - return a hash map of values to descriptions

$mapRef = $field->descMap() ;

Returns a reference to a hash that maps values to descriptions. Caches the map so that subsequent lookups are faster.

getFlags - create a FLAGS field from settings

$flags = $field->getFlags();

Returns a value for the FLAGS field of a field.

hidden - is this field hidden?

$field->hidden();

highlight - highlight data that matches field rules

If there are hRules defined for the field, highlight the data that matches those rules.

$output = $field->highlight($input) ;

input is a string to highlight.

Output is returned with any matching data highlighted.

prepHighlight - mark areas that match field highlighting rules

If there are hRules defined for the field, mark the data that matches those rules, ready for doHighlight() later.

$output = $field->highlight( input, displayStr );

input is a string to highlight.

if displayStr is specified, then if input matches a rule, display displayStr instead, highlighted. This is used for menu fields.

Returns input (or displayStr, where appropriate) with matching areas bounded by \03 and \04.

doHighlight - add HTML for highlighting fields

$output = $field->doHighlight( value );

value is the string to process.

Returns value, after replacing \03 and \04 (inserted by prepHighlight) with HTML for applying highlighting.

If the field is markup, doHighlight also escapes the markup so the field is displayed "as is".

graphable - get/set the graphable flag for a field

$graphable = $field->graphable();

hRules - set up highlighting rules

$status = $field->hRules(pattern [, isCaseSensitive [, isRE]]) ;

pattern is the pattern to highlight.

isCaseSensitive indicates the pattern is case sensitive (defaults to no).

isRE indicates the pattern is a regular expression (defaults to no).

Returns 1 if successful, 0 if it failed for some reason.

isBulkEditable - is this field simple?

$field->isBulkEditable();

inHistory - what history list is this field within?

$field->inHistory( [ fname ] );

fname - the name of the field.

inTable - what table is this field within?

$field->inTable( [ fname ] );

fname - the name of the field.

isDate - is this field a date type

$field->isDate() ;

Returns 1 if the field is date only, 2 if it is a date/time field, and 0 if it is neither.

isList - is this field a list type

$field->isList();

isNamepart - is this field in the name?

$field->isNamepart()

Returns true if this field is part of the name.

isNumber - is this field numeric

$field->isNumber() ;

Returns true if it is numeric, and false if it is not.

isRange - is this field a bounded range

$field->isRange();

isMarkup - does this field contain markup (eg HTML)

$field->isMarkup();

isTable - is this a table type field

$field->isTable();

isText - is this a freeform field

$field->isText();

isImportable - can this field be imported into?

$field->isImportable();

Returns false for table fields, and any built-in fields marked as not importable, and true for anything else.

label - get/set the label for a field

$label = $field->label();

searchable - is it searchable

$searchable = $field->searchable();

selectable - get/set the selectable flag for a field

$selectable = $field->selectable();

fixFlags - ensure that any reserved settings are maintained

$field->fixFlags() ;

Returns nothing.

setFlags - set various flags by parsing a "FLAGS" field

$field->setFlags(flags);

Returns nothing

size - get/set the size for a field

$size = $field->size(size);

Returns the current size of the field.

sizeAsHtml - get the size for a field

$size = $field->sizeAsHtml(limit);

returns a string suitable for use in the appropriate input element.

type - get/set the type for a field

$type = $field->type();

importable - get/set the importable flag for a field

$importable = $field->importable();

prompt - get/set the prompt for a field

$prompt = $field->prompt();

valueOf - return the value for a description

$cal = $field->valueOf($desc) ;

desc is the value to describe.

Returns the associated value if the variable is a list. If desc if a reference to an array, then returns a reference to an array of descriptions.

valMap - return a hash map of descriptions to values

$mapRef = $field->valMap() ;

Returns a reference to a hash that maps descriptions to values. Caches the map so that subsequent lookups are faster.

values - retrieve the list of values associated with a schema field

@vlist = $field->values( [ $valStr ] );

valStr is an optional string of comma separated values to store.

Returns a list of values derived by splitting the stored comma-separated string. Caches the results of the split for use in subsequent calls.

valuesList - accessor for list of values

@vlist = $field->valuesList( [ $lRef ] ) ;

lRef is an optional reference to a list of values. If supplied, the stored list of values will be updated.

Returns a list of values.

style - get/set the style associated with a schema field

$style = $field->style();

visible - get/set the visible flag for a field

$visible = $field->visible();

release - release the object

Really a no-op, since this object does not have a database.

SQL_value - do a SQL transformation on a value for a field

my $val = $field->SQL_value($val) ;

Returns the value of the field after interpretation by TestDB object.

AUTOLOAD - catchall for undefined methods

$value = $field->WHATEVER();

    $value = $field->WHATEVER(newvalue);

Updates the setting of the WHATEVER attribute. Returns the current or new setting.

DESTROY() - tidy up

Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.