KTDocumentUtil

From KnowledgeTree Document Management Made Simple

Updated as of KT 3.2 (SVN) on 25-09-2006

The DocumentUtil is probably the most important API in KnowledgeTree, since it represents the key means of interacting with Document objects.

1 :: add()
2 ::checkin()
3 ::checkout()
4 ::storeContents()
5 ::validateMetadata()
6 ::saveMetadata()
7 ::move()
8 ::copy()
9 ::rename()
10 ::reindexDocument()
11 ::fileExists()
12 ::nameExists()

[edit]

:: add()

function add($oFolder, $sFilename, $oUser, $aOptions)

Add a document to the reposity, in $oFolder.

always check for a PEAR::raiseError() response using PEAR::isError. See Errors
returns a Document Entity

The arguments:

$oFolder - the folder to which to add the document
$sFilename - the basic name of the file (e.g. my_document.doc)
$oUser - a User Entity (usually the current user)
$aOptions - an Options Array. Options are:
- contents (required) - an FSFilelike containing the document contents.
- metadata (required) - a metadata array, or null. null indicates that no metadata has been selected, not that no metadata is to be added (the document will be marked as incomplete). Passing an empty array is the same as associating empty metadata. You may also want to add novalidate to the options array if you can't handle metadata, but please don't do this unless its really not possible to associate metadata. For the metadata format, see metadata array format.
- documenttype - the id of a document type, or an instance of a document type.
- description - the document's title.

[edit]

::checkin()

function checkin($oDocument, $sFilename, $sCheckInComment, $oUser, $aOptions = false)

Always check the return value for a PEAR::raiseError. Returns true or a PEAR::Error

$oDocument - the document to be checked-in
$sFilename - the document filename as stored on the server (e.g. /tmp/SADFXXSAER not myfilename.doc)
$sCheckInComment - a comment to be added to the transaction.
$oUser - the user to credit with the checkin.
$aOptions - an Options Array with format:
- major_update - whether to bump the major version number up 1, or to simply increase the minor version number.
- newfilename - if set, the Document Entity will have its name set to this value.

[edit]

::checkout()

function checkout($oDocument, $sCheckoutComment, $oUser)

returns true or a PEAR::Error

$oDocument - the Document Entity to checkout.
$sCheckoutComment - a comment for the transaction log
$oUser - the document to check the document out as.

[edit]

::storeContents()

function storeContents(&$oDocument, $oContents, $aOptions = null)

Note: you should not be using this function to create a new version of the document. For that, use checkin. This is to be used if (for some bizarre reason) you have a DocumentContentVersion Entity with the wrong file in it.

returns true or a PEAR::Error

$oDocument - the document object to update with the new file.
$oContents - a FSFilelike containing the data for the document.
$aOptions - an Options Array with format:
- move - a boolean indicating whether the file can be "mv"'d, rather than copied.
- cleanup_initial_file - whether the original file should be deleted when we're done.

[edit]

::validateMetadata()

function validateMetadata(&$oDocument, $aMetadata)

returns the original metadata array ($aMetadata) or a PEAR::Error

$oDocument - the document which would be updated.
$aMetadata - a metadata array format object, with the metadata.

[edit]

::saveMetadata()

function saveMetadata(&$oDocument, $aMetadata, $aOptions = null)

Update the metadata for a given document.

$oDocument - the document to be updated
$aMetadata - the metadata array format object
$aOptions - an Options array with format
- novalidate - do not validate the metadata, just accept it. Useful if you can't prompt the user for metadata about this document.

[edit]