As outlined in our installation tutorial here, BreezingCommerce plugins are small functional bits that add features and themes to BreezingCommerce. In this article, you will explore how the plugin infrastructure works and getting prepared to create your own plugins.
Content:
4 - INSTALL, UPDATE, UNINSTALL
In the following we will call BreezingCommerce plugins simply "BC Plugins" to not mix them up with Joomla! plugins. Classic Joomla! plugins are still useful for BreezingCommerce but they aren't the topic in this series.
1 - Anatomy of BC Plugins
BC Plugins are managed in BreezingCommerce => Plugins and currently there are the following types of BC Plugins:
- Product Details: Plugins that will be executed in product details or complex categories.
- Payment: Plugins that are responsible connecting payment gateways, such as PayPal, to your shop.
- Shipping: Plugins that calculate shipping costs which may be selectable by the customer or pre-selected (depends on the implementation).
- Product Price: Plugins that alter the price of a product or a product variation.
- Product Images: Plugins for displaying product images (an example would be our Zoom plugin).
- Cart: Plugins that show up in the cart and offer any sort of extra functionality like collecting data from the customer before he checks out (an example would be our EU VAT deduction plugin).
- User Location: Plugins that determine the customer's user location and handing it to BreezingCommerce for further processing (e.g. location based taxes)
- Themes: Plugins that serve as themes
Every BC Plugin type is divided into 2 parts, the admin and site, where the product price type only has the admin part.
All plugins are stored in the folder /media/breezingcommerce/plugins/ and are protected from updates of the main component.
The file structure of a typical BC Plugin looks like this:
/media/breezingcommerce/plugins/*PLUGIN TYPE*/*PLUGIN NAME*/ ----- admin/ --------- language/ -------------- en-GB/ ------------------- en-GB.breezingcommerce.ini --------- tmpl/ -------------- details.php --------- index.php ----- site/ --------- language/ -------------- en-GB/ ------------------- en-GB.breezingcommerce.ini --------- index.php ----- install.php ----- update.php ----- uninstall.php
You already can see the main differences between Joomla! native and BC Plugins:
- There is no XML file or any other kind of setup required at all.
- The language files aren't moved over into Joomla!'s language folders. They can be used right away using JText within your plugin.
- All logic goes right into the index.php files of each part (admin/site)
- Each index.php includes a class with the business logic and the class actually "knows" about its purpose.
- Install, update and uninstall actions will be performed by their corresponding files as soon as they exist (where the install.php is required).
This structure is supposed to simplify and speed up the development time of a given plugin as you can start to develop right away without too much setup hassle and moving language files around the system. As further advantage, all of these plugins are uninstalled automatically when BreezingCommerce is uninstalled (if you prefix your custom db tables by #__breezingcommerce*, even those will be removed).
NOTE: language overrides for your plugins should be created by users in Joomla!'s "/language/en-GB/" folder by using the global override file (e.g. en-GB.ini).
However, the above is an example of a typical fully blown plugin, a minimum example would look like this:
/media/breezingcommerce/plugins/*PLUGIN TYPE*/*PLUGIN NAME*/ ----- admin/ --------- index.php ----- site/ --------- index.php ----- install.php
As you can see, it depends what you actually need for your plugin. You can simply leave out non-required files if you don't need all BC Plugin features.
In the end, the contents of your plugin must be zipped and it will be ready for installing in the BreezingCommerce plugin manager.
NOTE: Unlike Joomla! extensions, you must zip the plugin contents and not the folder of your plugin, otherwise the plugin won't be installable!
2 - Naming Conventions
In order to register a BC Plugin you will need to specify its type and its name. While there is no specific convention in naming your BC Plugin installable zips, it is recommended to name them
bc_plugin_TYPE_NAME.zip
Where NAME is the actual name of your plugin and TYPE the context the plugin is operating in.
Types are reserved within BreezingCommerce. Possible types are (exact case):
- productdetails
- productprice
- productimages
- payment
- cart
- shipping
- theme
- userlocation
Your plugin name itself must consist of alphanumeric characters (no special characters, no blanks, no underscores or dashes) and mustn't start with a number.
This naming convention will play an important role within the index.php files as they are used for class naming. The plugin name in fact is a key for the plugin, so it should be unique. There is still an option for every plugin to display a more readable format a we will see later.
NOTE: It's a good idea to prefix your plugin name to prevent collisions. If your company name would for example be 'megaplugins' and your plugin name would be 'myplugin', then your plugin name should be 'megapluginsmyplugin' and result e.g. into a zip file name like 'bc_plugin_payment_megapluginsmyplugin.zip'. Plugins developed by Crosstec don't use such a prefix.
3 - BC Plugin Entry Points
Each admin and site's index.php acts itself as entry point as it must contain a class following the naming convention as described above.
We won't address a specific plugin type here but give you an overview how such an entry point is defined and what methods / functions are shared across all types. For specific details of a plugin type, please read further tutorial parts in this series (as soon as they are available) or use the existing plugins as reference.
However, admin entry points signal BreezingCommerce to provide administrative interfaces or workflow features that are only relevant for administrational purposes. An example would be a BC Plugin of the type "productdetails", as it may provide a viewport within a product configuration (Product Detail Plugins Tab) to display options for a plugin.
In general, every admin entry point may (but not necessarily) provide a main configuration in BreezingCommerce => Plugins that you can use to create backend applications for the setup of your plugin. You could for example create a theme plugin and create an administration for this theme right in the main plugin setup.
To activate an entry point, an admin folder and add a file called "index.php" have to be created with the following contents and placeholders being replaced as described in the code comments:
$libpath = JPATH_ADMINISTRATOR . DS . 'components' . DS . 'com_breezingcommerce' . DS . 'classes' . DS . 'plugin' . DS;
require_once($libpath . 'CrBcA**TYPE**AdminPlugin.php'); // replace **TYPE** by the plugin type, first character uppercase
require_once($libpath . 'CrBc**TYPE**AdminPlugin.php'); // replace **TYPE** by the plugin type, first character uppercase
// replace **TYPE** and **PLUGINNAME** by the plugin type, first character uppercase
class CrBc_Plugins_**TYPE**_**PLUGINNAME**_Admin extends CrBcA**TYPE**AdminPlugin implements CrBc**TYPE**AdminPlugin
{
// IMPORTANT:.... more required methods as of the interface for this type
public function getPluginDisplayName(){
return JText::_('HUMAN READABLE NAME OF YOUR PLUGIN');
}
public function getPluginDescription(){
return JText::_('A BRIEF DESCRIPTION OF YOUR PLUGIN');
}
}
The 2 methods getPluginDisplayName() and getPluginDescription() are required for all BC Plugins, while there might be more methods required, depending on the interface that must be implemented. All methods defined in the extended parent class are optional.
The site's index.php class will be defined in the exact same way but instead of the keyword "Admin" the keyword "Site" is used:
$libpath = JPATH_ADMINISTRATOR . DS . 'components' . DS . 'com_breezingcommerce' . DS . 'classes' . DS . 'plugin' . DS;
require_once($libpath . 'CrBcA**TYPE**SitePlugin.php'); // replace **TYPE** by the plugin type, first character uppercase
require_once($libpath . 'CrBc**TYPE**SitePlugin.php'); // replace **TYPE** by the plugin type, first character uppercase
// replace **TYPE** and **PLUGINNAME** by the plugin type, first character uppercase
class CrBc_Plugins_**TYPE**_**PLUGINNAME**_Site extends CrBcA**TYPE**SitePlugin implements CrBc**TYPE**SitePlugin
{
// IMPORTANT:.... more required methods as of the interface for this type
public function getPluginDisplayName(){
return JText::_('HUMAN READABLE NAME OF YOUR PLUGIN');
}
public function getPluginDescription(){
return JText::_('A BRIEF DESCRIPTION OF YOUR PLUGIN');
}
}
It's the same thing here as it is for the admin side of the plugin. Now the outcome of the plugin depends on the type and interface that must be implemented. As stated above, you can either read more parts of this series about specific plugin types or check out one of the existing plugins as references (e.g. the payment plugins PayPal, Cash On Delivery and Stripe).
In the end, you would simply zip both folders admin and site, install and use it or keep developing on it.
4 - Install, Update, Uninstall
To perform actions on installation, updates and uninstalls, you simply need to create a file for each purpose called install.php, update.php and uninstall.php into the root folder of your plugin. if you don't need for example an update action, simply don't create that file. The install.php however is required.
For install actions, the install.php must include this content (please edit according to your plugin type and name):
class CrBcInstallation extends CrBcInstaller {
public $type = '**TYPE**';
public $name = '**PLUGINNAME**';
function install(){
// your install logic, e.g. database population
}
}
For update actions, the update.php file must include this content (please edit according to your plugin type and name):
class CrBcUpdate extends CrBcUpdater {
public $type = '**TYPE**';
public $name = '**PLUGINNAME**';
function update() {
// your update logic
}
}
For uninstall actions, the uninstall.php file must include this content (please edit according to your plugin type and name):
class CrBcUninstallation extends CrBcUninstaller {
public $type = '**TYPE**';
public $name = '**PLUGINNAME**';
function uninstall(){
// your uninstall logic
}
}
With the information above you now should be able to to move over and create a BC Plugin for a specific type.
Part 2 will get into details on how to create payment plugins (as soon as it is available) but you can already go ahead and use existing plugins as references for your own plugins. Have a look at how it's done with the PayPal as it provides all possible cases.
If you created a plugin that you want to share with the community, just let us know in our forums, so we can help you promoting it.
