Plugins

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.

See Plugins Creation and Installation section in the Framework guide for more information.

XML Descriptor

In the following snippet we have named our plugin document. However, you are free to name your plugin anything you like.

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.0" type="plugin" group="docman">
    <name>DOCman Document Plugin</name>
    <author>YOUR NAME</author>
    <creationDate>October 2016</creationDate>
    <version>1.0.0</version>
    <description>PLUGIN DESCRIPTION</description>
    <files>
        <filename plugin="document">document.php</filename>
    </files>
</extension>

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:

<?php
class PlgDocmanDocument extends PlgKoowaSubscriber
{
    public function onBeforeDocmanDocumentControllerAdd(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
        );
    }
}

Two things are being done:

1. make sure that the document is not published right away
2. notification of the submission

The onBeforeDocmanDocumentControllerAdd method follows a specific naming convention.

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.