UWAGA: Strona zawiera materiały archiwalne. Większość artykułów dotyczy Joomla! 1.0
Start arrow Programowanie arrow Moduły arrow Moduł Witaj świecie 1
Moduł Witaj świecie 1 Drukuj Email


This tutorial aims to give you a grounding in the basic concepts for writing Joomla Modules. It will develop a very simple Hello World Module and then extend it using patTemplate for the presentation layer.


You need for this tutorial:

  • Joomla 1.0 or greater

Let's Roll

We will be creating two files in this tutorial in the folder called /modules/. Let's look at the files we need.

This file is the actually engine for the module.
This file is the xml setup files for the module. It defines the information required for the module to be installed.

Installing the Basic Module

You cannot create a module from scratch from the Joomla Administrator, so we have to make some basic files first and then install them as a module.

Let's make the actually module first. Save the following code as mod_helloworld.php.

* @version 1.0 $
* @package HelloWorld
* @copyright (C) 2005 Andrew Eddie
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
/** ensure this file is being included by a parent file */
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
<h1>Hello World</h1>

Next save the following code in a file named  mod_helloworld.xml.

<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall type="module" version="4.5.2">
  <name>Hello World</name>
  <Author>Andrew Eddie</author>
  <creationDate>February 2005</creationDate>
  <copyright>(C) 2005 Andrew Eddie</copyright>
  <license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
  <description>A module that says hello</description>
    <filename module="mod_helloworld">mod_helloworld.php</filename>
  <params />

The first line of the file is a definition statement. You do not have to worry to much about what it means, but it must be in the file and it must be the first line (there cannot be any spaces before it). The other tags mean:

This is the parent tag that defines the rest of the installer file for Joomla. It has an attribute for type which in this case is module. It also takes a value for the version of Joomla it can run on.
This is the name of your module.
This is the name of the author for the module.
This is the date the module was created.
This is the copyright holder of the module's code.
This is the name of, or a reference to, the license under which the module is released.
This is the version of the module.
This is a free text description of the module.
This is a collection of the files included with the module.
This is a file that is used by the module. Any number of files can be listed, including files in a subdirectory. The file that Joomla calls to invoke the module  must contain the module attribute that takes a value of the name of the file without the .php extension.

Now, zip these two files up into a file called mod_helloworld.zip or you can download a copy here (mod_helloworld.zip).

Follow these instructions to install the basic module:

  1. Log into the Joomla Administrator.
  2. Select Modules ⇒ Install/Uninstall from the menu.
  3. In the Upload Package File area, click the Browse button and select the zip file you just created for downloaded.  Then click the Upload File and Install button.

Successfull module install

If all goes well, you should now see a message indicating a successful install. Click on the Continue link.

While you are still logged into the Joomla Administrator, select Modules ⇒ Site Modules from the Menu.  Scroll down until you see the listing for Hello World. You will see that the module is Unpublish(ed) and assigned to the left position in the template. Click on the red X in the Publish(ed) column to publish the module.

Hello World ModulePreview your site. You should see your module saying hi to you.

Congratulations, you have built and deployed your first module. Now that it is installed we can modify the files directly to add more features.

Improving the Presentation

You will find that you new module has been installed in the /modules directory of your site.  First we will separate the presentation layer from the module file.

Create a new directory under /modules called  /mod_helloworld.  In this new directory create a file called default.html. Copy the following code in this file:

@version 4.5.2
@package HelloWorld
@copyright (C) 2005 Andrew Eddie
@license http://www.gnu.org/copyleft/gpl.html GNU/GPL
<mos:tmpl name="helloworld">
  <h1>Hello World</h1>
  The time is {TIME}

We have added a little extra code here to demonstrate how to add a variable to your module template. You will also notice that the HTML is wrapped in a mos:tmpl tag. This defines a template and we have given the template the name of helloworld.

Now, find mod_helloworld.php in the /modules directory and open it in your Editor.

Tip: There are many quality editors that are available for free, PSPad and HTML-Kit to name a few. For something a little more powerful, you might like to try out Eclipse.

Delete the existing code and replace it with the following:

* @version 1.0
* @package HelloWorld
* @copyright (C) 2005 Andrew Eddie
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
/** ensure this file is being included by a parent file */
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
// load the patTemplate library
require_once( $mosConfig_absolute_path . '/includes/patTemplate/patTemplate.php' );
// create the template
$tmpl =& patFactory::createTemplate( '', false, false );
// set the path to look for html files
$tmpl->setRoot( dirname( __FILE__ ) . '/mod_helloworld' );
$tmpl->readTemplatesFromInput( 'default.html' );
$tmpl->addVar( 'helloworld', 'time', date( 'H:i:s' ) );
$tmpl->displayParsedTemplate( 'helloworld' );

Let's examine what is happening in this file.

  • The comment block at the top of the file defines meta data about the file, in particular the license and the copyright. This block has some special notations that are able to be parse by and application called phpDocumentor. It is used to assemble API (Application Programmer Interface) documentation. The important thing here is to have a version and explicitly state the copyright and license terms for the file.
  • Next we look for a constant called _VALID_MOS. Because this constant is defined elsewhere in Joomla, it ensures that only Joomla is able to access this file. It prevents a user from opening the file explicitly in a Browser.
  • We then include the patTemplate library.
  • The patTemplate object is created and then we set the root directory for template (HTML) files to the /mod_helloworld directory in your module.
  • Because we have set the root directory, we can just read in the default.html file with the readTemplatesFromInput method.
  • Next we want to give the {TIME} variable in our template a value. To do this we use the addVar method of the template object. The method takes three arguments. The first is the name of the template, the second is the name of the template variable and the last is the actual value to assign to it.
  • Last of all we display the helloworld template.

Save all your files and refresh your browser. You should see that the module now displays the time.

You can download the files for the final part of the tutorial here (mod_helloworld_1.zip).  Note that the XML file has been updated to include the new HTML file.

Zmieniony ( 19.06.2007. )
« poprzedni artykuł   następny artykuł »