Many Joomlapolitans have asked (here) for a basic plugin example illustrating a skeleton CB tab based on the CB API published here. As with most first efforts in a new programming environment such a task is usually tagged as a "hello world" script. You can access the helloworld plugin package here.
The API document (written by Beat) is an excellent description of the very powerfull CB application framework interface. However, it does assume that the reader is a descent PHP coder in the Joomla environment. If I was to propose a path to learning for Joomla development, I would start with Joomla modules first and then continue with CB plugins and finally go on with Joomla components. Somewhere in between there are mambots.
There are some basic Joomla module development tutorials that you can find and study. You can also just study existing modules that you like and figure out how they work. In the long run, this is the only way to really learn (reverse engineering) in this opensource Joomla environment.
As with any Joomla extension, CB plugins are also comprised of at least an xml file, a php file and an (almost empty) index.html file. All files placed in a folder and packaged as a compressed (zip) file. If packaged and written correctly, this CB plugin package can be installed via the CB Plugin management backend. A CB plugin may contain additional files of different types depending on the actual plugin needs. For example the CB Gallery plugin has multiple php files, image files, html files and javascript files. The structure of a CB plugin is described in section 1.4 of the CB API document.
The XML installation file of a CB plugin follows very closely the logic that is present in Joomla module, mambot or component XML installation files. For the CB API, the XML structure is explained in section 1.5 of the CB API document.
Lets set the requirements of this CB Hello World plugin. This basic plugin should create 1 CB profile tab and display some specific content in it. To make things just a little bit more complicated (mainly to demonstrate additional API functions) we will also have a plugin parameter to enable or disable the plugin/tab and also have a tab parameter that is used to store the actual hello-world message to display in the new profile tab (if of course the previous plugin parameter we discussed is enabled).
The actual package plug_helloworld.zip is produced by creating and compressing a folder named plug_helloworld that contains 3 files:
- index.html (this is basically a place holder file to be installed in the root folder of the plugin to prevent file browsing)
- helloworld.xml (this contains the credentials of the plugin, the installation process of the plugin, the tabs, the parameters, fields, etc)
- helloworld.php (this is the main plugin code that contains all plugin tab classes and supporting functions)
The actual helloworld.xml file instructs the CB plugin installer API to do the following actions (when the plugin package is installed via the CB Plugin Management backend):
- line 14: <cbinstall version="1.0.0" type="plugin" group="user">
This tag tells the CB API which version of the installer to use and that the type of the package is a plugin and that the plugin group is a user plugin (as opposed to a language plugin or a template plugin) - line 22: <version>1.0</version>
This tag basically tells the installer that this plugin is only compatible with version 1.0 (and above) of Community Builder. So, if someone with CB 1.0 RC2 tries to install this plugin package, the CB installer will refuse installation and return a failure message. - lines 27-30 instruct the installer to place 2 files in the plug_helloworld folder (in the components\com_comprofiler\plugin\user area) and that the name of the plugin is helloworld. Please note that the actual XML file is not included in this list of files but the installer copies is over to the newly created plugin folder root just the same.
- lines 31-39 instruct the CB installer to create the plugin parameters. There are basically 4 parameters defined here - the last 3 of which are just spacer parameter fields used to display some information (credits, etc) for the backend user to read. The first parameter field is a radio parameter that is used by the plugin code to see if the plugin is enabled or not.
- lines 40-48 instruct the CB plugin installer to create a tab that is managed my the class gethelloworldTab (this object is declared in the helloworld.php file) and the tab has one tab parameter (used to store the actual helloworld message).
The CB API plugin installer has many more features than the few that are utilized in this basic CB plugin. Some of these are demonstrated in the CB ProfileBook plugin and the CB Gallery plugin.
Now back to our hello world plugin!
Iif you install the plug_helloworld.zip plugin package using the CB Plugin Management backend, you should see the following message-page:
Notice that the title of the plugin is taken from line 15 of the XML file (name tag) and that the description from lines 23-26 (description tag). Clicking on the [Continue ...] link will render the installed plugin list were we should be able to identify a line similar to the following:
Notice that by default, all new plugins are not published (red x). Also notice the helloworld text in the directory column (last column). This is taken from line 28 (plugin="helloworld").
Now, if we open the actual plugin we will see all relevant plugin information (including the 4 plugin parameters we defined in lines 31-39 of the XML file:
Notice that the Hello World Plugin Enabled radio field parameter defaults to Yes (which means "1" as specified in line 35 of the XML file). This field also has a nice tooltip (blue i) that is used to provide the backend user additional information. Also take note of all the spacer type parameters defined in the plugin and how they appear.
So is this all our XML file accomplished? Nope! Remember that we also instructed the CB installer to create a new tab with a parameter. Looking at the CB Tab Management backend we can easily identify the newly created tab, named Hello World with the description and values given in line 41 of the XML file. By selecting this tab we should see a page similar to this one:
Well, this about covers the XML file of this plugin. Now on to the actual php code!
When this plugin is published and a CB profile is rendered the CB plugin infrastructure knows that it must use the getHelloWorldTab class (mentioned earlier) to perform all the plugin/tab actions. This class is located in the cb.helloworld.php file - so lets take a closer look at it.
As with most Joomla php files, the helloworld.php file starts with a line 14 that ensures that this file is not called directly. Now that this check is over the CB plugin as described in section 1.7 of the CB API doc (specifically look at section 1.7.4) must interact with the CB core via objects - the main object being based on the class cbTabHandler. So the next thing the php file does is to create a new class for our plugin/tab that is named getHelloWorldTab that is an extension of the cbTabHandler object (defined in the CB plugin API). For our purposes, this class has 2 extended functions: one is the constructor gethelloworldTab() and the other is the getDisplayTab() that is used to display the actual tab contents.
This getDisplayTab function is the main function that the CB plugin framework executes to display the tab defined in our plugin. Looking at the code in this function we see that the first thing we do is to read our plugin and tab parameter values. This is accomplished in lines 40-43. Notice that the names used in the 2 $params->get() functions (described in section 1.7.1 of the API document) correspond to the parameter names defined in the XML file.
Once the plugin/tab parameters are read, the code will just create the HTML statements needed to display the content we want in the tab. This HTML code is placed in a php variable ($return) and at the end is just returned as the getDisplayTab function terminates. Take notice of the portion of the code that displays that renders the HTML code needed to display the tab description (if it exists) using the CB template defined CSS class.
One could probably write a lot more explaining the various php statements and the possibilities. Unfortunately, this is not the purpose of this small article. There is a ton of information in Beat's excellent API document and there are a lot of plugins already around that people can study and learn. This is highly encouraged.
Now, if we publish this plugin (remember by default the installer leaves plugins unpublished) then we will see the following newly created tab when we visit a CB profile:
Welcome to the wonderfull world of CB Plugin development! Please rate and discuss this article - depending on the feedback I might be persuaded to continue the series.
| {mos_sb_discuss:7} |