Plugins

There are times when you may want to alter or augment the functionality of FILEman to suit a specific need. You might want to:

  • send an email when a file is submitted
  • create a simple log of FILEman events

Whatever you would like to do is possible with Plugins and our Event-driven architecture. Event listeners can be registered to almost any action in FILEman. More so, multiple listeners can be registered to a single event.

In most cases, you will want to register an event listener to a controller action. However, you can also register listeners to model and view actions.

There are a number of entities in FILEman whose MVC actions can have event listeners. Some examples are:

Site component Administrator component
File File
Folder Folder
Submit

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 file. 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 fileman. The system will make sure that this group of plugins is loaded whenever a FILEman event is broadcast.

PHP Class

The example below might help with keeping track of file submissions:

<?php
class PlgFilemanFile extends PlgKoowaSubscriber
{
    public function onAfterFilemanSubmitControllerAdd(KEventInterface $event)
    {
        //Do something like sending an email to an administrator
        mail('admin@example.com',
            'New File Submission',
            'A new file has been submitted with the filename: '.$event->request->data->name
        );
    }
}

This class sends an email to the admininstrator whenever someone submits a file using the Submit menu item in the frontend.

The onAfterFilemanSubmitControllerAdd 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 an After event handler in order to get information about the file after it is added.

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