How to Build a Simple Joomla! Module from Scratch

Posted on by

Getting Started

Build a Joomla Module from Scratch

Building a Joomla! module can be as simple or complex as you want it to be. The developers of Joomla! have  thoughtfully provided us with tons of tools which do most of the heavy PHP lifting so even you don’t have much programming experience developing your own module is a snap. Your module will at the very least need to have the following items if it is going to work:

  • A XML file so Joomla! can recognize your module.
  • A mod.php file where the meat of your code will go.
  • A default.php file for displaying your module.
  • A CSS style sheet to control the look and feel of the default.php

For a more detailed look at modules I refer the reader to the Joomla! documentation http://docs.joomla.org/J2.5:Creating_a_simple_module/Developing_a_Basic_Module

Steps

  1. Create a folder on your local machine which will hold your module files and folders.  For naming you should follow the standard convention of using the mod prefix before your module title. For example I called my folder: mod_progress.
  2. Inside your module folder create two new folders, one called ‘tmpl’ and the other called ‘images’.  In the tmpl folder add your styles.css and your main default.php template file. We will be adding code to these files later in the tutorial. The images folder should be added in case your module needs a place to store any graphics it might use.
  3. Navigate back out to your module root directory.
  4. Add your XML file, mod_progress.xml and mod_progress.php file. You can of course name these files anything you want.
  5. The XML file serves as a map which instructs Joomla! on what to do with the module.
  6. The .php file will initialize the module and allow you to define variables for use in the template later on.

First I will  provide a breakdown of the XML file using my own mod_progress.xml. Then I provide a breakdown of the .php file using my own mod_progress.php. I then discuss the style.css and the default.php template files in the tmpl folder. Finally, I summarize and explain how all these files are connected together to form the Joomla! module.

The XML File

The first part of the XML file has all the information about the module. The tags should be self explanatory and your own information should go between them.

<files><filename>mod_progress.xml</filename>
        <filename module="mod_progress">mod_progress.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <folder>tmpl</folder>
         <folder>images</folder>
    </files>

The code below sets the form fields which will show up in the adminstrative section of the module. This particular code creates a series of checkboxes for the user so that they can have a way to specify intervals on the progress bar. The values of each option will be passed to Joomla! in an array. The nice thing about Joomla! is that it already provides us with a wide variety of form fields to use: http://docs.joomla.org/Standard_form_field_types

    <config>
<fields name="params">
            <fieldset name="basic">
                
<field name="amountSet" type="checkboxes"
label="Choose the $ amount on the scale"
description="Check the amount you want to show up">
<option value="K100">$100K</option>
<option value="K150">$150K</option>
...
<option value="M1">$1M</option>
</field>
</fieldset>
</fields>
    </config>
</extension>

 

The .PHP File

Now we will break down the contents of the .php file which resides with the xml in the root directory of the module.

First, make sure to add the no direct access code to prevent direct access to the php code:

defined( '_JEXEC' ) or die( 'Restricted access' );

A helper.php file is optional since our module is not very complicated but its a good idea to add a call to it here in case you want to add one later on.

require_once( dirname(__FILE__).'/helper.php' );

Next set some PHP variables for calling later in your default.php template.

$amount = $params->get('amountSet');

Finally, we call the layout and the style sheet which we will use to control the look and feel of the module.

require( JModuleHelper::getLayoutPath( 'mod_progress' ) );
$document = JFactory::getDocument();
$document-&gt;addStyleSheet(JURI::base() . 'modules/mod_progress/tmpl/styles.css');

The Template

In your tmpl folder you should have added a file called default.php. This is where we are going to add code for the template.

Mine looks like following:

First, like in our mod_progress.php we need to prevent direct access to the code.

<?php defined('_JEXEC') or die;?>

Recall earlier that  in my XML file I defined a field named amountSet. I also defined the PHP variable $amount in my mod_progress.php which pulled out data from the amountSet array. When a user clicks a checkbox in the backend settings of the module Joomla! stores the value selected in the array amountSet. To get to that data all we need to do is loop through the array like below:

<div class="progress_wrapper">
<?php foreach($amount as $a) 
   {
     echo '<div class="'.$a.'"></div>';
   }
?>
<div class="progress_arrow">
<div class="increment-100">$100K</div>
<div class="increment-half">|</div>
...
<div class="increment-half-1m">|</div>
</div>
</div>
<div style="clear:both;"></div>

What follows is a just a little CSS “trickery” to get the progress bar to display images based on the value the user has checked in the backend. If the user has checked only 1 box in the back end then only 1 value will be stored in the array. When the for loop executes only that value will be passed and displayed. In the for loop above you will notice that this value happens to pass into the HTML as a CSS class $a. Assigned to that CSS is class is the image we want to display. Below is the relevant CSS.

.K100 {background-image:url('/images/veg/Carrot.png');}
.K150 {background-image:url('/images/veg/Corn.png');}
...
.M1  {background-image:url('/images/veg/Blueberries.png');}

Summary

Let’s summarize the process to help make the connection between these different files.

  1. The XML file tells Joomla! to display the fields of check boxes in the module backend.
  2. Each of these checkboxes has a value which corresponds to a CSS class.
  3. When the checkbox is checked by the user in the module backed the value of that field gets passed to an array.
  4. The array is accessed and stored in the variable defined in the mod_progress.php file.
  5. This variable is then accessed by the default.php using a for loop to loop through the array and display all the values selected by the user. Since these values correspond to a CSS class we can defined different styles for each class and affect the output of the module.