NAME

ApTest::Base::Ordered - base class for managing object name order caches

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use ApTest::Base::Ordered ;

use base qw( ApTest::Base::Ordered ) ;

METHODS

addToFolder - add an entry to a folder if it isn't already there

$status = $ref->addToFolder(name, uuid, asFolder) ;

Checks the files in a folder, and adds file "name" to that list if it is not already there.

asFolder is a flag - if true then uuid should be a folder name, not a UUID.

Returns true if the file needed to be added, false if it did not.

allFiles - return a list of all files in user-specified order

@list = $ref->allFiles( [ folder [, includeDeleted [, includeRecyc [, incFolderNames ] ] ] ] ) ;

folder is an optional folder name within the tree to start at.

includeDeleted is a flag. If true, then files in the deleted file tree will be included. Defaults to false.

includeRecyc is a flag. If true, then files in the recycle bin will be included. Defaults to false.

incFolderNames if a flag. If true, then names of folders will also be returned in their appropriate places in the list. Defaults to false.

Traverses the tree, getting the list of files in that folder and returning that list in order. NOTE: allFiles is recursive!

Returns the list of files in user-specified order.

allFileOrdinals - return a hashRef of files and their ordinal

$oRef = $ref->allFileOrdinals( [ folder ] ) ;

folder is an optional folder name with the tree to start at.

uses allFiles to traverse the tree and get a list, the populates a hash with that list and each list items index.

allFolderOrdinals - return a hashRef of folders and their ordinal

$oRef = $ref->allFolderOrdinals( ) ;

uses orderedFolders to traverse the tree and get a list, the populates a hash with that list and each list items index.

allUUIDOrdinals - return a hashRef of UUIDs and their ordinal

$oRef = $ref->allUUIDOrdinals( [ folder ] ) ;

folder is an optional folder name within the tree to start at.

uses allFiles to traverse the tree, then populates a hash using that list to look up the UUIDs of each file and map it to the list items index.

fileIndexByName - return the ordinal for a file in a folder

$idx = $ref->fileIndexByName($name)

name is the name of a file. Finds that file and determines its index within its folder. The index is a 1-based number that can be used in outline mode.

fileIndexByUUID - return the ordinal for a file in a folder

$idx = $ref->fileIndexByUUID($uuid)

uuid is the uuid of an indexed item. Finds that item and determines its index within its folder. The index is a 1-based number that can be used in outline mode.

folderIndex - return the ordinal for a folder in a folder

$idx = $ref->folderIndex($name)

name is the name of a folder. Determines the ordinal for that folder within the enclosing folder. The index is a 1-based number that can be used in outline mode.

fileOrdinalByName - return an ordinal for a file

$ord = $ref->fileOrdinalByName(name) ;

name is the name of a file in the tree.

fileOrdinalByUUID - return an ordinal for an item by UUID

$ord = $ref->fileOrdinalByUUID(uuid) ;

uuid is the uuid of a file in the tree.

folderLevelByName - return the depth of a folder

$lvl = $ref->folderLevelByName(name) ;

name is the name of a folder in the tree. The root of the tree is at level 0. Any folder in the root is at level 1. And so on.

folderOrdinalByName - return an ordinal for a folder

$ord = $ref->folderOrdinalByName(name) ;

name is the name of a folder in the tree.

folderUidByName - return the fUid for a folder

$uid = $ref->folderUidByName(name) ;

name is the name of a folder in the tree.

folderOutlineNumber - get the outline prefix for items in a folder

prefix = $ref->folderOutlineNumber( $dir ) ;

dir is a folder to get the outline number for.

Returns the prefix to use on items in that folder.

nameByOutlineNumber - return the filename associated with an outline number

$fName = $ref->nameByOutlineNumber( numStr ) ;

numStr is a string that contains an outline number.

Returns the name of the file associated with the outline number, or undef if there is no such number.

folderNameByOutline - get the folder name for an outline number

$name = $ref->folderNameByOutline( numStr ) ;

numStr = a string that contains a folder outline number.

Returns the folder name for that outline number, or undef if there is no such folder.

orderedFiles - return a list of files in user-defined order

@fList = $ref->orderedFiles( directory );

directory is the relative directory name in which the files are located.

If it doesn't want an array, it will return a reference to the list.

orderedFileHash - return a hash of files and their ordinals from a folder

my $hash = $ref->orderedFileHash( $dir ) ;

dir is the name of the directory to look at.

Returns a reference to a hash of filenames to indexes of items.

clearFileOrderCache - clear the cached file order

$ref->clearFileOrderCache();

Clear the cached list so that it will be rebuilt next time it's needed. Useful if the contents of the folder changes during the life of the object.

deleteFileOrder - destroy the file ordering for a folder

status = $ref->deleteFileOrder( [ dir [ , recurse [, current ] ] ] ) 

dir is an optional directory to start at.

recurse is an optional boolean - if true, then child folders will also have their saved orders deleted. Default is true.

current is an optional boolean - if false, then the current folder will NOT be cleared. Default is true.

Removes the order files. Returns true on success, and false on failure.

orderedFolders - return a list of folders in user-defined order

@fList = $ref->orderedFolders( directory [, recurse [, incDelFolders ] ] );

directory is the relative directory name in which the folders are located.

recurse is an optional flag that indicates whether to drill down into subdirectories. The default is false.

incDelFolders is true if folders in the special deleted files area should be included. Defaults to false.

incRecyc is true if folders in the recycle bin should be included. Defaults to true.

If it doesn't want an array, return a reference to the list.

orderedFilesAsJSON - return a JSON list of folders and files in user-defined order

my $list = $ref->orderedFilesAsJSON( directory [, includeCount [, recurse]] )

directory is the folder name to start at.

includeCount is a flag that indicates if the number of items in a folder and its children should be included. It defaults to true.

recurse is a flag that indicates if subfolder content should be included. It defaults to true.

Returns a hash that contains a recursive list of folders display IDs and ordinals as a JSON structure suitable for use with jsTree.

orderedFilesAsList - return a reference to a list of files and folders in user-defined order

my $listRef = $ref->orderedFilesAsList( directory [, includeCount [, recurse ] ] )

directory is the folder name to start at. Defaults to the top level.

includeCount is a flag that indicates whether file counts should be included or not. Default to true.

recurse is a flag that indicates if subfolder content should be included. It defaults to true.

Returns a list that contains a recursive list of folders display IDs and ordinals as a Hash structure suitable for use in a folder tree with jstree.

orderedFoldersAsJSON - return a JSON list of folders in user-defined order

my $list = $ref->orderedFoldersAsJSON( directory [, $includeCounts [, $recurse]] )

directory is the folder name to start at.

includeCounts is a flag that indicates whether the number of files in folder should be included. Defaults to true.

recurse is a flag that indicates whether contents of subfolders should be included. Defaults to true.

Returns a hash that contains a recursive list of folders display IDs and ordinals as a JSON structure.

orderedFoldersAsList - return a reference to a list of folders in user-defined order

my $listRef = $ref->orderedFoldersAsList( directory [, includeCounts [, recurse ] ] )

directory is the folder name to start at. Defaults to the top level.

includeCounts is a flag that indicates whether the number of files in folder should be included. Defaults to true.

recurse is a flag that indicates whether contents of subfolders should be included. Defaults to true.

Returns a list that contains a recursive list of folders display IDs and ordinals as a Hash structure suitable for use in a folder tree with jstree.

numFiles - return the number of files in a folder or folder tree

my $count = $ref->numFiles( directory [, recursive] ) ;

directory is the directory to count in.

recursive is an optional flag that says the count should be for the current folder and its children or not. It defaults to false.

Returns the number of files in the folder or the folder and its children.

numFolders - return the number of folders in a folder or folder tree

my $count = $ref->numFolders( directory [, recursive] ) ;

directory is the directory to count in.

recursive is an optional flag that says the count should be for the current folder and its children or not. It defaults to false.

Returns the number of folders in the folder or the folder and its children.

clearFolderOrderCache - clear the cached folder order

$ref->clearFolderOrderCache();

Clear the cached list so that it will be rebuilt next time it's needed. Useful if the folders change during the life of the object.

deleteFolderOrder - destroy the ordering for a folder

status = $ref->deleteFolderOrder( [ dir [ , recurse [ , current ] ] ] ) 

dir is an optional directory to start at.

recurse is an optional boolean - if true, then child folders will also have their saved orders deleted.

current is an optional boolean - if false, then the current folder will NOT be cleared. Default is true.

Removes the order files. Returns true on success, and false on failure.

outlineNumberByName - get the outline number for a record by Name

$number = $ref->outlineNumberByName( $name )

$name is the name of an entry in the database.

Returns the outline number for the referenced item. If the item is deleted or in the trash, this number may be somewhat arbitrary.

outlineNumberByUUID - get the outline number for a record

$number = $ref->outlineNumberByUUID( $uuid )

$uuid is the UUID of an entry in the database.

Returns the outline number for the referenced item. If the item is deleted or in the trash, this number may be somewhat arbitrary.

removeFromFolder - remove an item from the order

$status = $ref->removeFromFolder(item, uuid);
$status = $ref->removeFromFolder(item, folderName, 1);

item is the item to remove, including its path.

uuid is the uuid to remove.

folderName is a folder to remove if we are actually dealing with folders, not files - in this instance, the final optional boolean asFolders must be set to true.

asFolders is a boolean - if true then an entry is removed from the list of folders.

updateFileOrders - ensure that the order files reflect all files

$stat = $ref->updateFileOrders;

Walks the tree ensuring that the folder and file order files reflect all files and folders in each folder. This is called by "sync". After that, the lists are maintained as folder contents are manipulated.

buildOrderCache - create the order cache from scratch

$ref->buildOrderCache;

Rebuilds the order cache.

lastCacheUpdate - accessor for time when cache was last updated

$time = $ref->lastCacheUpdate( [ time ] );

time is a timestamp.

Returns the time when the order cache was last updated.

queueCacheUpdate - put a folder into the update queue

$ref->queueCacheUpdate(folder [, oldpath] ) ;

folder is a folder in the tree that needs to have its queue updated.

oldpath is an optional previous path for this folder. Only used in the event of an update so we can find the original cache entry.

Adds the folder to the update queue, ensuring a single folder is never mentioned more than once.

processUpdateQueue - run updates on the folders in the queue

$ref->processUpdateQueue() ;

Handles updating the folder updates, starting with the lowest entries in the tree first. Removes entries from the queue as it goes.

Returns nothing.

updateCacheFromRename - update cache when a folder is renamed

$self->updateCacheFromRename($oldFolderKey, $newPath) ;

Ensures the cache entry is moved and links updated.

updateOrderCache - update/create the cache entry for a folder

$ref->updateOrderCache( fUid, path, parentUid );

fUid is a unique ID for the folder. This is an integer. The root folder is always 0. If this parameter is not supplied, attempt to determine it by using the path.

path is the relative path within the file tree for this folder. If this parameter is not supplied, attempt to determine it using the fUid.

parentUid is the unique folder ID for path's parent folder. This is required when updating an existing cache entry or creating a new entry.

Returns 1 on success. Returns undef on failure.

updateParentCache - update the parent's view

$ref->updateParentCache( pUid, pPath, childRef ) ;

pUid is the UID of a parent folder.

pPath is the path to the parent.

childRef is a reference to a child folder cache.

Updates the parent's cache entry to include the child folder in the correct place.

userOrder - accessor for user specified file order

@order = $ref->userOrder(dir [, $orderRef [, $getFolders ] ]) ;

dir is the name of the directory for which to find the ordering.

orderRef is an optional reference to an ordered list of files. If specified, the folder's order is updated to reflect that order.

getFolders is a boolean. If true, then the order of folders is returned.

Returns a list of ordered files / folders.

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