Plugins

Read the Framework Plugins guide to get the absolute most out of this tutorial. We build on concepts that are covered in that guide.

Introduction

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.

Note: 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="1.0" type="plugin" group="fileman">
    <name>FILEman File Plugin</name>
    <author>YOUR NAME</author>
    <creationDate>March 2018</creationDate>
    <version>1.0.0</version>
    <description>PLUGIN DESCRIPTION</description>
    <files>
        <filename plugin="file">file.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.

Example

Let’s take a look at a plugin for logging of FILEman events. This plugin will get information from the event and let you add the information to 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: Fileman & Files - This is to only affect the FILEman and Files extensions.
  • Name: Files - We’re only interested in files.
  • Action: Add & Delete - Add/delete events.

The event method names we need for this example are:

<?php
class PlgFilemanFile extends PlgKoowaSubscriber
{
    onAfterFilesFileControllerAdd(KEventInterface $event){}
    onAfterFilesFileControllerDelete(KEventInterface $event){}
    onAfterFilemanFileControllerDelete(KEventInterface $event){}
}

Add event

We want to get the following information about this event: (1) What file was added? (2) Who added the file?

<?php
public function onAfterFilesFileControllerAdd(KEventInterface $event)
{
    // The result of the controller action is stored in the "result" property
    $entity = $event->result;

    // The entity contains the result's properties
    $filename = $entity->name;

    // Get the user who performed the action
    $username = $this->getObject('user');
    
    // Now do some custom query to store the values. Perhaps store in a table using $entity->id as an index.
}

Note that we used Files instead of Fileman. This is because FILEman makes use of the built-in Joomlatools com_files component especially for managing files and folders in the backend.

Delete event

Our delete event will use both Files and Fileman. The onAfterFilemanFileControllerAdd event will be triggered when a user deletes a file from the frontend while onAfterFilesFileControllerAdd will be triggered from the admin.

Normally, your methods would have different functions. But for this example, we will have one method call the other since they have the same function.

<?php
// Frontend event
public function onAfterFilemanFileControllerAdd(KEventInterface $event)
{
    $this->onAfterFilesFileControllerAdd($event);
}
<?php
// Backend event
public function onAfterFilesFileControllerAdd(KEventInterface $event)
{
    // The result of the controller action is stored in the "result" property
    $entity = $event->result;

    // The entity contains the result's properties
    $filename = $entity->name;

    // Get the user who performed the action
    $username = $this->getObject('user');
    
    // Do some query to store the values.
}

Need Help?

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