Date: Thu, 28 Mar 2024 17:28:12 -0400 (EDT) Message-ID: <1063379558.4953.1711661292863@docs.blesta.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_4952_455587903.1711661292862" ------=_Part_4952_455587903.1711661292862 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Plugins can do just about anything. Cr= eate custom cron tasks, listen for events, create pages, create widgets, extend= the API, etc., etc. If it's not a Module or a Payment Gateway= , it's a plugin. So let's dig in.
As of Blesta 4.12 we've included a useful tool to help developers get st= arted and save time. Blesta's Extension Generator can be used to generate many the files neces= sary for a plugin and will create basic code with an option to include comm= ents to help you understand each part of the code.
Plugins follow the same MVC design pattern that Blesta adheres to. The p= lugin system is provided as a feature of the minPHP framework, Blesta simpl= y defines the naming convention. For the purpose of this manual, the plugin= name we'll refer to is my_plgn. Your plugin name will, of= course, differ.
Plugin names must be unique
A user will not be able to install two plugins with the same name, so tr= y to use descriptive and non-generic terms for your plugin name.
Plugins are fully contained within their named plugin directory and plac= ed in the /plugins/ directory. Below is the minimum required file = structure for a plugin:
my_plgn_controller.php is the plugin's parent controlle= r. This controller can be used to add supporting methods for the other cont= rollers to inherit. Similarly, my_plgn_model.php is the pl= ugin's parent model and can be used to add supporting methods for the other= models to inherit.
Because plugins inherit from the application stack their views default t= o the view directory defined for application. For this reason, you should a= lways declare the view directory for the views within your plugin. The exam= ple below requires that you place all views (.pdt files) into /plugins/= my_plgn/views/default/.
= <?php class MyPlgnController extends AppController { public function preAction() { // Set the view directory to the default core view directory so tha= t AppController preAction code uses the appropriate // directory for the structure file $this->structure->setDefaultView(APPDIR); parent::preAction(); // Override default view directory with that of the plugin=20 $this->view->view =3D "default"; } } ?>
Finally, my_plgn_plugin.php is a special class that mus= t extend the Plugin class of /components/plugins/l= ib/plugin.php. This class is used for installing, upgrading, unins= talling, and branding the plugin in conjunction with the config.jso= n file.
If your plugin requires any code to execute when installed, place that l= ogic in your plugin's install() method.
<?php class MyPlgnPlugin extends Plugin { ... public function install($plugin_id) { # # TODO: Place installation logic here # } } ?>
Need access to the database?
See how you can use the Record component to manipulate the database in t= he Database Access section of = this manual.
If your plugin required code to install, it likely requires code to unin= stall. Place that logic in your plugin's uninstall() metho= d.
There are two parameters passed to the uninstall() method. The first ($plugin_id) is the ID of the plugin being uninstalled. Becau=
se a plugin can be installed independently under different companies you ma=
y need to perform uninstall logic for a single plugin instance. The second =
parameter ($last_instance) identifies whether or not this =
is the last instance of this type of plugin in the system. If true<=
/strong>, be sure to remove any remaining remnants of the plugin.
<?php=20 class MyPlgnPlugin extends Plugin {=20 ...=20 public function uninstall($plugin_id, $last_instance) { # # TODO: Place uninstallation logic here=20 # }=20 }=20 ?>
When the version of your code differs from that recorded within Blesta a= user may initiate an upgrade, which will invoke your plugin's upgr= ade() method.
The $current_version is the version currently installed= . That is, the version that will be upgraded from. The $plugin_id= strong> is the ID of the plugin being upgraded.
<?php class MyPlgnPlugin extends Plugin { ... public function upgrade($current_version, $plugin_id) { # # TODO: Place upgrade logic here # } } ?>
Blesta facilitates error message passing through the use of the = Input component. Simply load the Input component into your plugin = and set any errors you encounter using Input::setErrors().= The setErrors() method accepts an array of errors. This can be a multi-dim= ensional array (in the case of multiple errors triggered for the same input= or criteria) or a single dimensional array. The first dimension should be = the name of the input that triggered the error. The second dimension, if ne= cessary, is used to identify the type of error encountered.
1 !=3D 0
Data validation is an important part of logic, and user friendly applica= tion design. Be sure to check out the Error Checking section of this manual for a full explanation on erro= r handling.
<?php class MyPlgnPlugin extends Plugin { public function __construct() { Loader::loadComponents($this, array("Input")); } ... public function upgrade($current_version, $plugin_id) { // Ensure new version is greater than installed version if (version_compare($this->version, $current_version) < 0) { $this->Input->setErrors([ 'version' =3D> [ 'invalid' =3D> "Downgrades are not allowed." ] ]); return; } } } ?>
For version 3.1+ simply create a config.json file and include it in the = constructor of your plugin.
{ "version": "1.0.0", "name": "My Plugin Name", "description": "A plugin like no other!", "authors": [ { "name": "Phillips Data, Inc.", "url": "http://www.blesta.com" } ] }
<?php class MyPlgnPlugin extends Plugin { public function __construct() { $this->loadConfig(dirname(__FILE__) . DS . "config.json"); } } ?>
For version 3.0, you must define all of the branding details through met= hods.
Internationalize it!
Use the Language library to help internationalize your plugin. Just crea= te a language directory in your plugin, then a directory for each = language (i.e. /plugins/my_plgn/language/en_us/) and plac= e your language files in there. See Translating Blesta for how to load, format, and use language defin= itions.
If your plugin requires certain configurable options, you can create a m= anagement link viewable to staff members that have access to installed plug= ins. To do so, all you need to do is create an AdminManagePlugin controller. This is a special controller that is initialized by Bles= ta internally, so all views must be returned (as strings) from the requeste= d action methods.
<?php class AdminManagePlugin extends AppController { /** * Performs necessary initialization */ private function init() { // Set the view to render for all actions under this controller $this->view->setView(null, 'MyPlgn.default'); } public function index() { $this->init(); =09=09$var1 =3D "hello"; =09=09$var2 =3D "world"; =09=09return $this->partial("admin_manage_plugin", compact("var1", "var2= ")); } =09public function foo() { $this->init(); =09=09return $this->partial("admin_manage_plugin_foo"); =09} } ?>
By default the index() method is called. You can link t= o other controller and actions from your views using the following URL form= at:
<a href=3D"= <?php echo $this->Html->safe($this->base_uri . "settings/compan= y/plugins/manage/" . $this->Html->_($plugin_id, true) . "/?controller= =3Dadmin_manage_plugin&action=3Dfoo");?>">Link to other action<= ;/a>
The above link would render the AdminManagePlugin::foo() method.
So far all we've see is how to build a plugin that can be installed, uni= nstalled, upgraded, and managed, but that's the just tip of the iceberg. As= we discussed earlier, plugins can do so much more.
By register actions, a plugin makes itself available in the interface in= certain areas. See Plugin Actions<= /a> for how to register actions.
Some plugins need to be executed when certain events occur outside of th= e plugin's control. This is accomplished by registering events. See Plugin Events for how to register event= s.
Plugins that need to perform certain tasks automatically at either set i= ntervals are certain times of the day can register cron tasks. See Plugin Cron Tasks for how to regist= er cron tasks.