NAME

Schema - class to represent and manipulate test suite schemas

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use Schema;

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

# get a handle to the hash of a schema field
$field = $schema->field(name);

# get a handle to a hash of all fields
$fieldHash = $schema->field();

# structure a value in a schema instance
$output = $schema->print(fieldName, value, edit);

The Schema object is a tool to instantiate the schema for a test suite.

METHODS

new - open the Schema

$schema = new Schema(suite, edit);

Creates a new schema object.

suite

the name of a test suite to access.

returns a reference to the schema object.

descsOf - return the legal description values for a field

@descs = $schema->descsOf(name);

searches the schema for a field with the given name. Returns an array of legal descriptions for that field.

delRow - delete a row from a table-style element

$schema->delRow(testCase, fieldName, row);

testCase is a handle to a test case.

fieldName is the name of the field.

row is the row number to delete. If row is greater than the number of rows defined in a table, the command is silently ignored.

edit - get/set the edit flag

$state = $schema->edit();
$state = $schema->edit(boolean);

mode - get/set the mode

$mode = $schema->mode();
$mode = $schema->mode( string );

The mode is one of 'view', 'edit', 'run', 'report'.

multiLists - return a list of multi-select lists

@mlists = $schema->multiLists() ;

field - get a handle for a field or all fields

$ref = $schema->field();
$ref = $schema->field(name);

fieldList - return a list of defined schema fields

@list = $schema->fieldList() ;

Returns the list of fields defined in the schema.

fieldEntryWrap - output an entry, wrapping the content

$output = $schema->fieldEntryWrap(testcase, test, field, value, fn);

testcase - reference to a TestCase object

test - a handle to the test case instance

field - the field we are using

value - the value the field has in the test case

fn - pointer to a function to call to wrap each value. The arguments passed to the function are the field name and the value (which may be special in the case of an menu).

fieldEntryVar - output an entry with a special variable suffix

$output = $schema->fieldEntryVar(test, field, value, suffix, fn);

test - a handle to the test case instance

field - the field we are using

value - the value the field has in the test case

suffix - a suffix to attach to HTML form variable names

fn - the name of a javascript function to call on change

fieldEntry - output an entry for a schema field

$output = $schema->fieldEntry(test, field, value [, row]);

testcase - reference to a TestCase object

test - a handle to the test case instance

name - the field we are using

value - the value the field has in the test case

row - the row in an inset table. If defined, is used as a suffix for the CGI variable name.

buildSelectorTable - return HTML for an efficiently organised table of selectors

$table = $schema->buildSelectorTable( currentSelection, allowNonSelectable, showSpecials, multiple, showDynamic );

The arguments are passed through to fieldSelection().

getSelsFromArgs - build selector collection from an ARGS hash

($testSels, $warnings) = $s->getSelsFromArgs( $hashRef ) ;

hashRef is a reference to a hash of CGI parameters and their values.

If there are any issues with parsing, those issues are pushed into the referenced hash as key_WARNING.

Returns a reference to a hash of selectors suitable for pushing into the selector method, and a string of warnings suitable for displaying (if any).

fieldSelection - return a selection input item for a field

$output = $schema->fieldSelection( field, currentSelection, allowNonSelectable, showSpecials, $multiple, $showDynamic );

field is the field to present

currentSelection is a reference to an array of existing selections or a comma-separated string of current selections.

allowNonSelectable is a boolean that indicates whether even non-selectable fields should be presented (for use in report and edit selectors).

showSpecials is a boolean that indicates whether the special isCS and isRE selectors should also be shown on items that support those flags.

showDynamic is a boolean that indicates whether fields that can have dynamic selectors should show these as options. The default is false.

returns an input field appropriate for the field. If $field is empty, returns an empty string. If the field doesn't exist, returns undef. if field is not selectable, returns an empty string.

fieldPrint - emit the value(s) for a field

$output = $schema->fieldPrint(fname, ref, useLabels) ;

fname is the name of the field

ref is a reference to a selector-style hash (pat, isCS, isRE).

useLabels is true if the label should be emitted as well.

Returns the output formatted appropriately for the field. Note that this does not work with field type "table", since that is necessarily only emitted in the context of a test case.

hRules - set up highlighting rules

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

field is the field to set up rules for.

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, and undef if the field does not exist.

flist - retrieve an ordered list of fields

@list = $schema->flist();

sortedFlist - get a list of rundata fields ordered by label

@sFlist = $schema->sortedFlist() ;

Returns a list of field names that are sorted by field label case insensitively.

insRow - insert a row into each field of a table

$schema->insRow(testHandle, fieldName, rowNumber);

testHandle - a Framework handle to an active test case

fieldName - the name of the field in the schema

rowNumber - the row to insert before. If not defined, then just add a row to the end.

looks up fieldName in the current schema, finds the associated fields, and performs the operation on those fields

makeValid - method to ensure that the value for a field is valid

$newval = $schema->makeValid($field, $value);

returns a valid value, which may have been reordered if it is a list field.

nameParts - return a list of fields that are parts of the name

@fList = $schema->nameParts() ;

Returns an ordered list of the fields that should be used in the displayID of the requirement.

numFields - accessor for the number of fields in a schema

$num = $schema->numFields();

returns the number of fields defined in a schema

print - print the contents of the Schema object field

$schema->print();
$schema->print(field);

returns the string-ified version of the entire database, or just the contents of field

release - release the object

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

selDesc - get a description for a schema selector

$desc = $schema->selDesc(field, selRef, noShowName, updateDynamic) ;

field is the name of the field.

selRef is a hash reference to a selector.

noShowName is a boolean. If true, the field name is suppressed. Defaults to false.

updateDynamic is a boolean. If true, dynamic selectors will have their values refreshed before the description is produced. Defaults to true.

Returns a string that is a description of the selection in the context of the field type.

selectableList - return a list of selectable fields

@slist = $schema->selectableList( menuOnly [, prefix [, sort ] ] ) ;

menuOnly is a flag that indicates only menu fields should be included in the list. It defaults to false.

prefix is an optional string to attach to the front of the fieldnames.

sort is a flag that indicates the returned list should be sorted by field label. The default is true.

Returns a list of fields that are not hidden and are marked as selectable.

session - accessor for a session handle

Gets/sets a handle to a test session from which variables can be extracted and interpolated into field values during formatting.

sessVars - accessor for session variable values

$val = $schema->sessVars(vname) ;

Returns the value of the session variable, or undef if the variable is not defined for the session. Also returns undef if the schema object does not have a sessionVarHandle.

stripBR - strip trailing BR elements from a string

$newstr = stripBR($oldStr) ;

Removes any trailing BR elements. Note that this is just a function, not an object method.

suiteDir - accessor for test suite root

$dir = $schema->suiteDir();
$schema->suiteDir(suite);

Gets/sets the path to the test suite data root.

tables - return a list of fields that are "tables"

@tlist = $schema->tables() ;

typeOf - return the type of a field

$type = $schema->typeOf(name);

searches the schema for a field with the given name. Returns the type of that field as a string.

usesStaffTime - check if staff time tracking is enabled

$bool = $schema->usesStaffTime() ;

Returns true if staff time tracking is active for the suite.

usesClockTime - check if clock time tracking is enabled

$bool = $schema->usesClockTime() ;

Returns true if clock time tracking is active for the suite.

valueAsList - return a value as a list

@list = $schema->valueAsList(fieldName, value) ;

Returns a list that contains all the discrete values from 'value' when interpreted as a field named fieldName. If fieldName is in a table, then appropriate unescaping is done first.

In a scalar context, returns a reference to the list.

valuesOf - return the legal values for a field

@values = $schema->valuesOf(name);

searches the schema for a field with the given name. Returns an array of legal values for that field.

visibleList - return a list of visible schema fields

@list = $schema->visibleList( [ $sort ] ) ;

write - write out the schema file

my $status = $schema->write() ;

Updates the schema file for the current suite / profile with the current state of the schema.

Returns 1 on success, 0 on failure.

serialize - create a serialized version of the object

my $text = $schema->serialize() ;

Returns a text representation of the object, suitable for saving.

idField - accessor for a ref to the idField

$ref = $schema->idField ( [ $ref ] ) ;

ref is an optional reference to an ID field object. If supplied, that ref is used to update the idField.

Returns the reference to the idField, or undef if there is no field of type id.

inHistory - return whether a field is a component of a history item

$schema->inHistory(name);

searches the schema for a field with the given name. Returns the name of the history field a field is contained within, or false if the field is NOT in a history table.

inTable - return whether a field is a component of a table

$schema->inTable(name);

searches the schema for a field with the given name. Returns true if that field is in a table.

historyTable - find the history table (if any)

my $field = $schema->historyTable();

Returns the name of the field that contains the history table definition.

If there is no historyTable, returns undef.

tableSize - return the number of rows required for a table

my $size = $schema->tableSize(tableName, testReference);

tableName - the name of a table field.

testReference - a reference to a test case object.

Returns the number of rows the table will require. Returns undef if the field is not a table field, does not exist, or has no fields.

historyTextarea - find the field to add system comments to

my $field = $schema->historyTextarea();

Returns the name of the field to put automated revision history entries in.

Chooses the atm_mcomments field if present and in a history table, otherwise the first textarea in a history table.

Returns undef if no field matches.

isBulkEditable - return whether a field can be included in the bulk editor

$schema->isBulkEditable(name) ;

searches the schema for a field with the given name. Returns true if that field should be not bulk editable.

isHidden - return whether a field is hidden.

$schema->isHidden(name);

searches the schema for a field with the given name. Returns true if that field should be not displayed.

isList - return whether a field type is a "list" or not

$schema->isList(name);

searches the schema for a field with the given name. Returns true if that field is a list type field.

styleOf - return the style of a field

$schema->styleOf(name);

searches the schema for a field with the given name. Returns the style of that field as a string.

labelOf - return the label of a field

$schema->labelOf(name [, includeMarkers] );

searches the schema for a field with the given name. Returns the label of that field as a string. If includeMarkers is true, also annotates the label with mandatory and namepart markers.

isGraphable - return whether a field is graphable

$schema->isGraphable(name);

searches the schema for a field with the given name. Returns true if the field is graphable, or false if it is not.

isNamepart - return whether a field is part of the name

$schema->isNamepart(field)

Searches the test case fields for a field named field. Returns true if the field is a namepart, or false if it is not.

isNumber - return whether a field is to be treated as numeric

$schema->isNumber(field)

Searches the test case fields for a field named field. Returns true if the field has a numeric style, or false if it does not.

isOutline - return whether this suites's tests are in outline mode

$schema->isOutline()

Returns true if the test cases are using outline numbering mode, and false if not. Returns undef if there is no ID field (which is, of course, impossible).

isSelectable - return whether a field is selectable

$schema->isSelectable(name);

searches the schema for a field with the given name. Returns true if the field is selectable, or false if it is not.

isVisible - return whether a field is visible for reports

$schema->isVisible(name);

searches the schema for a field with the given name. Returns true if the field is visible in reports.

getFieldsByType - get a list of fields of a given type and/or style

$schema->getFieldsByType(type[,style]);

searches the schema for fields of a given type, and optionally a given style. Returns a list of field names.

javaScriptDependencies - determine the dependency rules for JS

Returns JavaScript code that defines the dependencies among schema fields for use in the schema editor and also in selector pages.

SQL_tname - table name accessor

my $tname = $schema->SQL_tname ;

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