Introduction

There are times when you may want to alter or augment the functionality of DOCman to suit a specific need in a given situation:

send an email when a document is uploaded

add some data to the list of documents before it gets rendered to the screen

Whatever you would like to do is possible with Plugins and our Event driven architecture. Almost any action in DOCman can have an event listener registered against it. Multiple listeners can be registered for a single event.

In the majority of cases, you will want to register an event listener against a controller action. However, you can also register listeners against all model, view and controller actions.

There are a number of entities in DOCman for whose MVC actions you may wish to register an event handler against:

Site component

Administrator component

Document

Document

Download

Category

List

File

To get a sense of the granularity of the events that a plugin can subscribe to have a look at “What is Possible?” in the Framework Plugins guide.

Setup

A plugin consists of at least 2 files, a PHP class and an XML descriptor.

The group attribute specifies docman. The system will make sure that this group of plugins is loaded whenever a DOCman event is broadcast.

PHP Class

The example below might help moderate document submissions:

<?phpclassPlgDocmanDocumentextendsPlgKoowaSubscriber{publicfunctiononBeforeDocmanDocumentControllerAdd(KEventInterface$event){//Do something like sending an email to an administrator and disabling the document
$event->request->data->enabled=0;mail('admin@yoursite.com','New document added','A new document has been added with title:'.$event->request->data->title);}}

For controller focused events the $event variable gets the data property. This is made up of the input data of the request coming into the action. We intercept it with a Before event handler because we want to disable the document before we add it to the database.

Refer to MVC Actions and Events for detailed information about specific $event variable properties and the actions they are geared towards.

Example

The document description will contain keywords for special tagging (year of publishing, author, etc). When the document is saved or modified the keywords are extracted from the description and stored in a custom database table.

Events to respond to:

When: After - we do this after the action has run so that if the action were to fail, our event listener won’t run.

Edit event

We want to react to certain keywords in the description for special tagging, like:

{year:2015}

{author:StephenHawking}

The description field of the document that was added or edited is contained within the result property of the $event object. It’s the result of the action performed.

<?phppublicfunctiononAfterDocmanDocumentControllerEdit(KEventInterface$event){//The result of the controller action is stored in the "result" property
$row=$event->result;//The row contains properties that map to the database table columns
$description=$row->description;}

Extract tags

Some simple regular expression matches will extract the year and the author:

<?phppublicfunctiononAfterDocmanDocumentControllerEdit(KEventInterface$event){//The result of the controller action is stored in the "result" property
$row=$event->result;//The row contains properties that map to the database table columns
$description=$row->description;//Get the year
$year=$author=null;if(preg_match('#{year:([\s0-9]*)}#',$description,$match)){$year=trim($match[1]);}//Get the author
if(preg_match('#{author:([\s\w]*)}#',$description,$match)){$author=trim($match[1]);}//Now do some custom query to store these values, perhaps store in a table using $row->id as an index?
if($year){//Do something
}if($author){//Do something
}}

This example plugin can be found on GitHub. You can even install it with Composer.

Need Help?

Let our developers personally assist you. You can ask development related questions in our Support Center. Only for Business or Agency subscribers.