Writing a simple Joomla Module

Akin to extending an existing module in Joomla, it is also incredibly easy to writing your own. Using this post, we want to give a quick run through of how quick and painless it is to design your own modules to be included in various areas of your website. To provide a useful example, we will be leveraging Google's Books Search API to embed a preview of a book of our choosing based on it's ISBN number. This way we could, for example, feature recommended reading on a website by providing an interactive and rewarding experience. Lets jump right in!

The first thing we need to note is the structure of a module. Modules are usually installed as a compressed zip file in Joomla and require a specific file to instruct Joomla on how to install the contents of the module. Canonically, we can refer to this to the module manifest or install file. The easiest way to go about setting up a module development environment is to create a folder with the name of the module, so for example we have chosen: mod_googlebookpreview

Inside our mod_googlebookpreview folder we now create the basic file layout for all modules according to the following structure:

• mod_googlepreview - Our top level folder which you just created
  • mod_googlebookpreview.xml - Our manifest file
  • mod_googlebookpreview.php - Our controller script to control the module
  • index.html - An empty file to stop people from browsing our folder directly
  • tmpl - Another folder to hold our display files
    • default.php - Our display script that renders our elements to the screen
    • index.html - An empty file to stop people from browsing our folder directly

Lets start by looking at the contents of our manifest file mod_googlebookpreview.xml:

<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
    <name>Google Book Preview</name>
    <author>Max Neuvians</author>
	<creationDate>Jan 4, 2010</creationDate>
	<authorUrl>http://vergegraphics.com</authorUrl>
    <version>1.0</version>
    <licence>GNU/GPL http://www.gnu.org/licenses/gpl.html</licence>
	<description>
    	<![CDATA[Module to show book preview based on ISBN Number]]>
	</description>
	
    <files>
        <filename module="mod_googlebookpreview">mod_googlebookpreview.php</filename>
        <filename>index.html</filename>
        <filename>tmpl/default.php</filename>
        <filename>tmpl/index.html</filename>
    </files>
    
    <params>
    	<param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />
	<param name="@spacer" type="spacer" default="" label="" description="" />
        <param name="ISBN" type="text" size="32" default="" label="ISBN #" description="The ISBN Number of the Book to preview" />
        <param name="Width" type="text" size="32" default="" label="Width" description="The Width of the Frame" />
        <param name="Height" type="text" size="32" default="" label="Height" description="The Height of the Frame" />
    </params>
</install>

The layout of this xml file is predefined according to Joomla standards and it should not be too hard to replace the appropriate fields with your own information. The first section basically covers who you are and what the purpose of this module. Pay special attention to the files sections as you need to declare all files that are part of the module, otherwise Joomla will not install them in their proper place. You will see how we arranged the files according to the module layout we presented above. Note that the manifest file is not part of this list.

Next we have the module parameters section which defines what options the module will present in the administrative back end of your Joomla website. We have chosen three custom parameters here: ISBN number, width, and height. Width and height determine how large our preview is, while the ISBN number determines the book we want to preview. The moduleclass_sfx is a Joomla standard that helps you customize the displayed content in conjunction with css. This is not necessary but provides some flexibility when customizing content, so we are leaving it in.

After we have completed the manifest file, we turn to mod_googlebookpreview.php, which is the main controller script for the module. All it is responsible for doing is making sure that all dependencies are loaded and that the module renders the right output when called upon. Our mod_googlebookpreview.php looks like this:

<?php
	// no direct access
	defined( '_JEXEC' ) or die( 'Restricted access' );
	$document = &JFactory::getDocument();
	$document->addScript( 'http://www.google.com/jsapi' );
	require( JModuleHelper::getLayoutPath( 'mod_googlebookpreview' ) );
?>

What this small piece of code does is make sure that there is no illegal access to the module in Line 1. The next two lines make sure that the Google javascript API script is loaded as part of our web page's header. To use Google Book Preview we need to load the appropriate javascript and sticking it in the header makes sure that it is included before the rest of the body loads. The last line in the file is simply a function to load the default layout for our module which is the default.php file in the tmpl directory of our module. default.php and tmpl are Joomla standards and it will know to look for these specific files and folders.

Now to default.php file which renders our output. In here we will need to run some additional javascript and display some html. Below is an example of what an ouput might look like:

<?php
// no direct access
defined('_JEXEC') or die('Restricted access');
?>
<script type="text/javascript">
      google.load("books", "0");
      function GBPalertNotFound() {
        alert("Book could not be loaded");
      }
      function GBPinitialize() {
          var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
          viewer.load('ISBN:<?php echo $params->get('ISBN')?>', GBPalertNotFound);
      }
      google.setOnLoadCallback(GBPinitialize);
</script>
<div class="googlebookpreview<?php echo $params->get('moduleclass_sfx'); ?>">
	<div id="viewerCanvas" style="width: <?php echo $params->get('Width')?>px; height: <?php echo $params->get('Height')?>px">
	</div>	
</div>

Again the first line restricts access to appropriate users. The next chunk of code is the javascript to query Google and load the preview. We start off by loading just the "books" API from the google library. Next we have created a function that will alert us if for some reason we cannot load the book preview, ex. ISBN is wrong or unavailable. Following that is another function that is the main initializer. If first creates a container into which we want to load our book, in our case a DIV with the ID: viewerCanvas. Next it loads the book preview into our container using the ISBN number that we specified in our module options. The second parameter in the viewer.load function is the call back to the error function we defined above. The loader will invoke this function if there is a problem. Note that the snippet of PHP code containing the ISBN number is evaluated as the page loads and the javascript function once it is complete, thus we know the function will only run after the ISBN number already has been included in it. The last piece of code in the javascript section is a method of making sure that the javascript only runs once the page has finished loading completely. This way we know we are not going to run this script before the page has finished loading fully.

Below the javascript is a small section of HTML. It consists of a wrapper DIV that contains a class using the moduleclass_sfx parameter discussed above. Again more of a cosmetic and convenience than an essential to the whole module. Inside it is the DIV that we specified as the container for our preview. Note that we are using the height and width parameters specified as part of the module parameters. This way we can easily adjust the proportions of our preview.

That basically completes the module writing exercise. All that remains is to zip up the files inside your folder (not the folder itself), to upload them into Joomla, and to activate the module. We use 7-zip for all our zipping needs.

Before we show an example of the module, you should check out the Google Book Preview API to see what else you could do. For example you could add inclusion not only by ISBN numbers but also OCLC or LCCN. This module is just a small example of what is possible.

Below is an example of our module, a source version can be found below that.

Attachments:

File	Description	File size
mod_googlebookpreview.zip	A simple module that displays a Google Book Preview based on ISBN number. Part of a blog post on vergegraphics.com	1 Kb

Comments

Posted by shaan (http://www.phandar.com) on April 23, 2010 at 06:39 pm

thanks man was looking for it Reply

Write A Comment

Name:
Email:
Website:

Please input the anti-spam code that you can read in the image.

Powered by !JoomlaComment 4.0 beta2