NAME

Framework - catchall package for broadly used methods

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use Framework ;

METHODS

uri_encode - ensure a string is safe for use in a uri

my $safe = uri_encode(string)

returns a string with non-portable characters URI-escaped.

uri_decode - transform a URI-escaped string back

my $orig = uri_decode(string);

returns a string with URI-escaped content unescaped.

cgi_encode - ensure a string is safe for use in a cgi paramater

my $safe = cgi_encode(string)

returns a string with non-portable characters URI-escaped.

cgi_decode - transform a CGI-escaped string back

my $orig = cgi_decode(string);

returns a string with URI-escaped content unescaped.

HTMLtoText - transform markup into raw, formatted text

my $textOutput = HTMLtoText($string) ;

REReturns output formatted.

textToHTML - transform text into markup

my $htmlOutput = textToHTML($string) ;

Returns output marked up as "formatted".

shell_encode - encode a string so it is safe for a shell call

my $safe = shell_encode($string) ;

Returns a string that has non-safe shell chars for the current operating system escaped.

checkTemplate - check to ensure a template is okay

See Report::checkTemplate for documentation.

checkSuite - return the name of the suite to use

my $suite = checkSuite(userInfo, suite, select) ;

suiteVersion - get/set the ATM version for a test suite

$version = suiteVersion(suite [, version]) ;

isSuiteLocked - is this test suite tied up?

my $status = isSuiteLocked(suite);

lockSuite - set the lock on a suite and return the handle

my $h = lockSuite(suite) ;

unlockSuite - release the exclusive lock on a suite

my $status = unlockSuite(suite, handle);

csvClean - clean CSV input

my $clean = csvClean(string) ;

js_qescape - escape quotes for javascript

my $out = js_qescape(string) ;

xml_qdecode - decode xml-escaped content including quotes

my $out = xml_qdecode(string);

xml_qencode - encode xml content including quotes

my $out = xml_qencode(string);

xml_decode - decode xml entities

my $out = xml_decode(string);

xml_encode - encode xml entities

my $out = xml_encode(string) ;

authToken - get the authentication token

my $token = Framework::authToken ;

Harvests the authentication token from the cookie.

fixURI - massage the URI to include authentication info

This is actually a no op.

sandboxDir - return the path to a per-session sandbox

my $path = sandboxDir(suite, session [, testnum [, user]]) ;

sessionDir - return the path to a session

my $path = sessionDir(suite, session [, uname]) ;

Returns the path to the session.

sessionName - return a normalized display name for a session

my $name = Framework::sessionName($sessNum) ;

Returns a zero-filled name.

sessionPath - return the web path to a session dir

my $path = sessionPath(suite, session [, uname]) ;

Returns a path that is usable as a URI.

testLogDir - return a path to a directory for logging in a session

my $path = testLogDir(suite, session, test [, stamp [, uname]]) ;

stamp is a unique stamp to use (e.g. a time). If it is -1, then an autoincrementing number is assigned.

Returns the path to the directory, creating the directory if needed.

testLogPath - return a web path to a directory for logging in a session

my $path = testLogDir(suite, session, test [, stamp [, uname]]) ;

stamp is a unique stamp to use (e.g. a time). If it is -1, then an autoincrementing number is assigned.

Returns the web path to the directory, creating the directory if needed.

fetch - fetch data from a store'd file

$reference = Framework::fetch(path) ;

Retrieves the data and returns a reference to it. Returns undef if path is not available.

save - store serialized data

$status = Framework::save(reference, path);

Stores the data identified by reference into the file named by path. The data is portable among systems.

setGroupList - get the list of setGroups in the suite

my @list = setGroupList(suite [, setGroup]) ;

suite is the name of a test suite

setGroup is an optional name of a parent set Group. Note that the setGroup name must NOT contain the .grp suffix.

Returns a list of groups at the top level or within the specified setGroup.

setList - retrieve the list of test sets in the suite

my @list = setList(suite [, setGroup]) ;

Returns the list of sets either at the top level or within the specified setGroup.

allSetList - get a list of all sets

my @list = allSetList(suite [, group [, includeGroup]]) ;

group is the optional name of a group to search within.

if includeGroup is true, then the group name is included along with the set name. The default for includeGroup is false.

getGroupList - get a jsTree suitable list of groups

my $json = Framework::getGroupList( suite ) ;

suite - the name of the suite to traverse

Returns a json structure with test set information suitable for use with jsTree

getGroupListAsJSON

templateDir - get the path to suite or profile templates

$path = Framework::templateDir(suite, profile) ;

suite is a suite to work with.

profile is a profile to work with.

Returns the path to the template collection for the suite or the profile.

If both suite and profile are defined, returns undef.

getTemplate - load a template

$contents = Framework::getTemplate(suite, template, strip, profile);

suite is the name of a suite to load from.

template is the name of the template to load.

strip is a flag that indicates whether to strip off comments or not. Defaults to false.

profile is the name of a profile to operate on instead of a suite.

Returns the contents of the referenced template. Returns undef if the template does not exist. Returns undef if both a suite and a profile are specified.

templatePath - get the path to a template file

$path = Framework::templatePath(suite, template[, library]);

suite is the test suite - if undefined, then go to the master templates

template is the template to load

profile is the optional profile from which to load the template. Note that this ONLY applies if suite is not defined.

Automatically references the "REPORTS" subfolder for things that end in ".rpt".

Returns the path to the template file, or undef if the file cannot be found

absTop - return the absolute URI of the top of ATM

my $top = absTop() ;

imageDir - return the URI of the image directory

my $dir = imageDir() ;

scriptDir - return the URI of the script directory

my $dir = scriptDir() ;

setGroupDir - get the name of the folder for a set group

my $dir = setGroupDir(suite, setGroup [, user]) ;

testsetDir - get the path to a test set folder

my $dir = testsetDir(suite, set [, user]) ;

fullname - get the fullname of the current user

my $fname = fullname() ;

username - get the name of the current user

my $uname = Framework::username() ;

Returns the username of the current user, or 'ATMuser' if the current user is not defined.

If called with a parameter, and if the current username is not already set, attempts to create a UserInfo object for that user. If that succeeds, the new user information is remembered and the username is returned.

userInfo - get the reference to the current user's info object

my $uObj = userInfo() ;

userDir - return the path to this userData area for a user

my $path = userDir( [name] ) ;

name is the username of a user. If not supplied, defaults to the current user.

Returns a relative path to the private data area for this user. Note that this method is DEPRECATED.

reqActive - check whether requirements are in use for a test suite or profile

my $status = reqActive(suite [, profile] ) ;

suite is the name of a test suite.

profile is the optional name of a test suite profile to use instead of a test suite.

reqDir - return the path to the requirements portion of a suite

my $dir = reqDir(suite [, subdir]) ;

cacheDir - return the path to a user's cache for a specific session

my $dir = cacheDir( user, session) ;

dataDir - return the path to the generic data directory OR the data dir for a suite

my $dir = dataDir( [suite] ) ;

tmpDir - return the path to a temp data directory

my $tmp = tmpDir() ;

webReqDir - return the web path to the requirements dir for a suite

my $webdir = webReqDir(suite [, subdir]) ;

webSuiteDir - return the web path to a suite

my $path = webSuiteDir(suite) ;

webTmpDir - return the web path to a temp directory

my $tmp = webTmpDir() ;

getSuiteList - return a list of all test suites

my @list = getSuiteList() ;
    my $listRef = getSuiteList() ;

suiteList - return a selection list of test suites

my $list = suiteList(vname, current) ;

vname if the name of a variable to use for the selection list.

current is the current selection, if any.

suiteDir - return the path to the top of the suite tree or a test suite

my $dir = suiteDir( [suite] ) ;

fixName - ensure a name contains only legal characters

my $fixed = fixName( string ) ;

fixPath - ensure a path contains only legal characters

my $fixed = fixPath(orig) ;

bailOut - master exception handling method

bailOut(error) ;

Does some cleanup, logs the error message, then redirects to the error reporting page.

errorOut - master error handling page

errorOut(error);

Logs the error, then redirects to the error_message page.

isoTime - transform a timestamp into ISO time format

my $time - isoTime(stamp [, needTime [, separator [, needSecs ]]])

stamp is a perl time in seconds since the epoch. If not provided, it defaults to 0.

needTime is a boolean that, if true, means the time should be included as well as the date. If not defined, defaults to false.

separator is the separator to use between components of the time. Defaults to a space.

needSecs is a boolean that, if true, means the seconds are provided with the time. The default is false.

fmtTime - transform a timestamp into ApTest standard format

my $time - fmtTime(stamp [, needTime [, separator [, needSecs [, today ]]]])

stamp is a perl time in seconds since the epoch. If not provided, will return "".

needTime is a boolean that, if true, means the time should be included as well as the date. If not defined, defaults to false.

separator is the separator to use between components of the time. Defaults to a space.

needSecs is a boolean that, if true, means the seconds are provided with the time. The default is false.

today is a boolean that, if true, means the day should be omitted if the stamp is today. The default is false.

Returns the date (and time) in the user's timezone.

fmtTimeThisYear - transform a timestamp into ApTest standard date format omitting the year if it is THIS year

my $time - fmtTimeThisYear(stamp ) ;

stamp is a perl time in seconds since the epoch. If not provided, it defaults to 0.

Returns the date (and time) in the user's timezone. The year is left off if it is the same as the current year.

Note that the configuration parameter ATMConfig::showYear can be set to override so that the year is ALWAYS displayed.

userLocale - return the current user's chose time locale

my $locale = userLocale() ;

userTimestyle - return the current user's chosen timestyle

my $style = userTimeStyle()  ;

defaultLocale - return a default setting for the date locale

my $locale = defaultLocale ;

localeList - return a list reference of locale data for selectionList

my $listRef = localeList() ;

localTimeZone - return the timezone of a user or the server

my $tz = localTimeZone( [noUser] ) ;

If noUser is true, then return the tz of the server.

lorem - return a lorem ipsum string

my $str = lorem(length) ;

Returns a string of length words based upon the classic lorem ipsum pattern,

error - emit a error in HTML format with styles

$output = error($string)

warning - emit a warning in HTML format with styles

$output = warning($string)

- updateActivityLog - add an entry to a per-user log

updateActivityLog(username, message)

note that the suite name and session ID are retrived from the Framework package, and are initialized by the autohandler in the setGlobals sub-component.

updateSystemLog - put information into the log

logic here: if there is a level 1 problem, put that in the log no matter what.

otherwise, if debugging is turned on to a certain level, only record things below that.

updateLog - add entries to the run log file

updateLog(level, message)

note that the suite name and session ID are retrived from the Framework package, and are initialized by the autohandler in the setGlobals sub-component.

nextID - allocate

my $nextItem = Framework::nextID(path [,val] ) ;

path - a directory in which there is a .nextid file.

val - set the value to val

Returns the next incrementable number.

notify - send a notification

my $status = notify(address, subject, message) ;

parseTemplate - get a template and break it down

($head, $body, $foot) = Framework::parseTemplate(suite, template, stripComments, profile);

returns the portion before any thead, the thead portion, the body portion, and the tfoot portion of the template so they can be used in the various portions of a template driven screen

checkPathLength - ensure that a pathname will fit on the current file system

$status = checkPathLength($path) ;

returns true if it will fit, and false if it will not

viaCGI - check whether we are running via CGI or not

Returns 1 if we are, 0 if we are not.

reportRows - return the number of rows the user wants per page in reports

displayName - clean up any name for display purposes

displayTestName - clean up the test name for display.

treeSetList - find all test sets and return in a tree

treeSessionList - return the sessions in a set as a tree

makeUUID - return a unique identifier

$uuid = Framework::makeUUID();

compare - compare the data with another structure

$res = Framework::compare( ref1, ref2 );

Returns 1 if the data in ref1 matches the data in ref2. Returns 0 otherwise.

showSchedule - show schedule selectors

showCal - show a calendar selector

calcPct - calculate a percentage

$res = Framework::calcPct(num, den, includeSuffix)

num is the numerator of the fraction

den is the denominator of the fraction

includeSuffix is true if the percent suffix should be attached. If not, then the value that is returned is a true integer.

Returns a two digit percentage value. If the denominator is 0 or undefined, returns 00.

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