Written by Nick A. Thursday, 21 September 2006 21:02
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.
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:
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):
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.
|Discuss this article on the forums. (30 posts)|