Instructions for correcting the code of your own plugins
Instructions for adapting individual plugins for Visforms 5
This guide describes the necessary steps for customizing a simple custom plugin called myplugin.
This fictional plugin implements an event handler for the Visforms event onVisformsAfterFormSave.
Changes are necessary in the following areas:
- Directory structure,
- File structure,
- Code adjustment in the affected files.
The adjustments must be made on a Joomla 5 installation with Visforms 5. Any Visforms Subscription must also have version 5.
Directory structure under Joomla 4
On Joomla 4 the plugin myplugin is in the directory
plugins/visforms/myplugin
and has the following file structure
plugins/visforms/myplugin
plugins/visforms/myplugin/index.html
plugins/visforms/myplugin/myplugin.php
plugins/visforms/myplugin/myplugin.xml
Directory structure under Joomla 5
On Joomla 5 the plugin myplugin is also in the directory
plugins/visforms/myplugin
and has the following directory and file structure
plugins/visforms/myplugin
plugins/visforms/myplugin/index.html
plugins/visforms/myplugin/myplugin.xml
plugins/visforms/myplugin/services
plugins/visforms/myplugin/services/provider.php
plugins/visforms/myplugin/src
plugins/visforms/myplugin/src/Extension
plugins/visforms/myplugin/src/Extension/Myplugin.php
The procedure
Create directories
As a first step, create the new directories.
plugins/visforms/myplugin/services/provider.php
plugins/visforms/myplugin/src
plugins/visforms/myplugin/src/Extension
Note: Pay attention to upper and lower case letters.
Adjustments to the files
Copy the file provider.php
from
plugins/visforms/vfcustomplugin/services
to
plugins/visforms/myplugin/services
Moving the file myplugin.php
from
plugins/visforms/myplugin
to
plugins/visforms/myplugin/src/Extension
Rename file myplugin.php
in Myplugin.php
plugins/visforms/myplugin/src/Extension/Myplugin.php
Adjustments to the file provider.php
Line 24:
old: use Visolutions\Plugin\Visforms\Vfcustomplugin\Extension\Vfcustomplugin;
new: Visolutions\Plugin\Visforms\Myplugin\Extension\Myplugin
Line 35:
old: $plugin = new Vfcustomplugin(
new: $plugin = new Myplugin(
Line 37:
alt: (array) PluginHelper::getPlugin('visforms', 'vfcustomplugin')
new: (array) PluginHelper::getPlugin('visforms', 'myplugin')
Adjustments to the file Myplugin.php
Add namespace (first line of code directly after the opening php tag)
namespace Visolutions\Plugin\Visforms\Myplugin\Extension;
General use statements
Add the general use statements.
use Joomla\CMS\MVC\Factory\MVCFactoryAwareTrait;
use Joomla\Database\DatabaseAwareTrait;
use Joomla\Event\SubscriberInterface;
Event-specific use statements
Add an event-specific use statement.
For each Visforms event for which an event handler is implemented, a corresponding use statement must be added.
Below is where you can find a list of all Visforms events and their use statements:
List of all Visforms events and their use statements .
The fictional plugin implements an event handler for the event onVisformsAfterFormSave.
So the following use statement is added for this specific event:
use Visolutions\Component\Visforms\Site\Event\Visforms\VisformsAfterFormSaveEvent;
Adjustment of the class definition
old:
class plgVisformsMyplugin extends CMSPlugin {
new:
class Myplugin extends CMSPlugin implements SubscriberInterface {
use MVCFactoryAwareTrait;
use DatabaseAwareTrait;
Register events and their handlers
Adding the getSubscribedEvents() function:
public static function getSubscribedEvents(): array {
return [
'onVisformsAfterFormSave' => 'onVisformsAfterFormSave',
];
}
You must add an entry for each supported event and its event handler to the returned array of this function.
Example with multiple event handlers
In the following file you will find an example that contains several events and their respective event handlers:
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php
Adjustments to the event handler function onVisformsAfterFormSave()
old:
public function onVisformsAfterFormSave($context, $form, $fields): bool {
// context = 'com_visforms.form'
return true;
}
new:
public function onVisformsAfterFormSave(VisformsAfterFormSaveEvent $event): void {
// context = 'com_visforms.form'
$context = $event->getContext();
$form = $event->getForm();
$fields = $event->getFields();
}
The event object as the only parameter
Instead of a list of function parameters, there is only the event object as the only parameter. The event object contains all the old function parameters. You can access these using the corresponding member functions of the event object.
Example with all Visforms event objects
In the following file you will find examples of all events supported by Visforms as well as the functions to use. The listing in this sample code is complete:
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php
Return values: parameters
A parameter that the plugin code has changed to control Visforms directly must be written back to the event to be returned to Visforms. In some cases this is even absolutely necessary. How this happens is also shown in the example code. There is then the following call in the event handler:
$event->setArgument();
Return values: Result
Some events can also return a result (true/false), such as the event onVisformsBeforeEditSave. In Visforms 4 this was, for example:
return true;
return false;
In Visforms 5 you use the following function to do this:
$event->addResult(true);
$event->addResult(false);
For all events that actually evaluate a Boolean return value, the function $event->addResult() is explicitly listed in the event handler in the following example code.
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php
Adjust constructor for very old plugins
If you have a very old plugin, it may also be necessary to adapt the constructor.
The correct signature is:
public function __construct(DispatcherInterface $subject, array $config)
If you call a parent::__construct() in the constructor, the line of code is as follows:
parent::__construct($subject, $config);
Adjustments to the file myplugin.xml
Adjustments are also necessary to the plugin’s manifest file.
Add the namespace to the extension node:
<namespace path="src">Visolutions\Plugin\Visforms\Myplugin</namespace>
Adaptation of the files node:
old:
<files>
<filename plugin="myplugin">myplugin.php</filename>
<filename>index.html</filename>
</files>
new:
<files>
<folder plugin="myplugin">services</folder>
<folder>src</folder>
<filename>index.html</filename>
</files>
Note: The plugin either needs to be reinstalled or you register the namespace manually.
Since the plugin is now registered under a namespace, you must either:
- Reinstall the plugin explicitly.
- Zip the directory.
- Install the zip file via the Joomla Installer.
- Register the namespace manually.
This happens in the fileadministrator/cache/autoload_psr4.php.Just add the following line:
'Visolutions\\Plugin\\Visforms\\Myplugin\\' => [JPATH_PLUGINS . '/visforms/myplugin/src'],
List of all Visforms events and their use statements:
In the following file you will find a complete list of all Visforms events and their use statements:
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php