Read the Framework Plugins guide to get the absolute most out of this tutorial. We build on concepts that are covered in that guide.
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|
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.
A plugin consists of at least 2 files, a PHP class and an XML descriptor.
Note: See Plugins Creation and Installation section in the Framework guide for more information.
In the following snippet we have named our plugin
document. However, you are free to name your plugin anything you like.
group attribute specifies
docman. The system will make sure that this group of plugins is loaded whenever a DOCman event is broadcast.
The example below might help moderate document submissions:
Two things are being done:
- make sure that the document is not published right away
- notification of the submission
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.
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.
- Component: Docman - This is to only affect the DOCman extension.
- Name: Document - We’re only interested in documents
- Action: Add & Edit - Save/modify events
Therefore the event method names we need are:
Save events cover both
Edit. The simplest way to have both of these methods run the same code is have one call the other.
We want to react to certain keywords in the description for special tagging, like:
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.
Some simple regular expression matches will extract the year and the author:
This example plugin can be found on GitHub. You can even install it with Composer.
Let our developers personally assist you. You can ask development related questions in our Support Center. Only for Business or Agency subscribers.