Developing actions

From KnowledgeTree Document Management Made Simple

Contents 1 What are actions? 2 Registering actions 3 Action classes 3.1 Attributes 3.2 Inheritance 3.3 Methods 3.4 Expectations 3.5 Immutability

What are actions?

Actions that can be performed on a document or folder are handled through the plugin system.

Actions are displayed in a portlet on the left-hand side of the screen when the folder or document view pages are being displayed.

Actions that can be performed on a document usually extend the KTDocumentAction class:

require_once(KT_LIB_DIR . '/actions/documentaction.inc.php');
class KTDocumentViewAction extends KTDocumentAction {
...
}

Similarly, actions that can be performed on a folder usually extend the KTFolderAction class:

require_once(KT_LIB_DIR . '/actions/folderaction.inc.php');
class KTFolderAddDocumentAction extends KTFolderAction {
...
}

Registering actions

To register the action, use the registerAction method on your plugin object (see the instructions on developing plugins on how to create the plugin object).

$oPlugin->registerAction('documentaction', 'KTDocumentViewAction', 'ktcore.actions.document.view', 'action/view.php');

• The first parameter is the type of action. This is usually 'documentaction' or 'folderaction'.
• The second parameter is the name of the class.
• The third parameter is a unique namespaced name for this action.
• The fourth parameter is the location of the file that contains the implementation of the class.

The actions portlet gets the list of actions from the actionregistry, which will instantiate each action of the correct type, and call its getInfo() method to find out if the action should be displayed, what the display details of the action are, and where the action will take the user. Actions should avoid overriding the getInfo() method, and use the standard implementation, which is described below:

Action classes

Attributes

Actions, once instantiated, must contain the following information:

class KTDocumentArchiveAction extends KTDocumentAction {
    var $sDisplayName = 'Archive';
    var $sName = 'ktcore.actions.document.archive';
    var $_sShowPermission = "ktcore.permissions.write";
    
    ...
}

• sDisplayName is the name to display on the actions portlet.
• sName is the namespaced name of the action, which is used to generate URLs to the action
• _sShowPermission is a permission to ensure the user has before showing the action to them (and allowing them to use the action if accessed directly). If not set, it defaults to "ktcore.permissions.read".

Inheritance

The KTDocumentAction and KTFolderAction classes both extend from the KTDispatcher class, making them web pages too. By default, the action is located at /action.php/$sName (/action.php/ktcore.actions.document.archive for the above example). They then follow the KTDispatcher rules on what pages to show.

Methods

Of importance is the check() function, which the KTDispatcher class uses to see if the page should be shown or not. This is overridden in KTDocumentAction and KTFolderAction to ensure that the permissions in $_sShowPermission are held by the user, and that the document or folder referred to in the fDocumentId or fFolderId respectively is a valid id. KTDocumentAction then sets the oDocument attribute on the object, and KTFolderAction sets the oFolder attribute on the object. That means that no validation of permissions or document or folder identifiers is necessary in these actions directly.

If an action does not want to be displayed due to certain circumstances - such as not being available if a document is checked out, it should override the getInfo() method, and ensure that it calls the parent getInfo() afterwards:

    function getInfo() {
        if ($this->oDocument->getIsCheckedOut()) {
            return null;
        }
        return parent::getInfo();
    }

Expectations

When actions have finished their work (whether successfully or not), they should generally return to the view page:

    function do_archive() {
        $this->startTransaction();
        $this->oDocument->setStatusID(ARCHIVED);
        if (!$this->oDocument->update()) {
            $_SESSION['KTErrorMessage'][] = _("There was a database error while trying to archive this file");
            controllerRedirect('viewDocument', 'fDocumentId=' .  $this->oDocument->getId());
            exit(0);
        }
        $this->commitTransaction();
        controllerRedirect('viewDocument', 'fDocumentId=' .  $this->oDocument->getId());
        exit(0);
    }

Since redirecting to the view page doesn't use the usual successRedirectTo() method, the action must specifically commit any transactions.

Immutability

class KTDocumentCheckOutAction extends KTDocumentAction {
    var $_bMutator = true;
    var $_bMutationAllowedByAdmin = false;
    
    ...
}

The _bMutator attribute tells KnowledgeTree whether the action changes the document in any way ("mutates" the document). If the document is immutable, then the action will not be available.

The _bMutationAllowedByAdmin attribute, defaulting to true, means that system administrators (or unit administrators within their units), in admin mode, can perform the action on the document. For example, admins can edit metadata on an immutable document to correct mistakes in the metadata.