$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.

@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.

$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.

$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.

$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.

$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.

$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.

$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.

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

name is the name of a file in the tree.

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

uuid is the uuid of a file in the tree.

$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.

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

name is the name of a folder in the tree.

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

name is the name of a folder in the tree.

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

dir is a folder to get the outline number for.

Returns the prefix to use on items in that folder.

$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.

$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.

@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.

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.

$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.

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.

@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.

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.

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.

my $listRef = $ref->orderedFilesAsListWithDepth( directory, requiredFolders [, includeCount ] )

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

requiredFolders is a reference to a list of folders that need to be recursed into (because there are some pre-selected items in those folders).

includeCount is a flag that indicates whether file counts should be included or not. Default 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.

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.

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.

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.

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.

$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.

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.

$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.

$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.

$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.

$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.

$ref->buildOrderCache;

Rebuilds the order cache.

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

time is a timestamp.

Returns the time when the order cache was last updated.

$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.

$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.

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

Ensures the cache entry is moved and links updated.

$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.

$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.

@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.