Joomla! Documentation - User contributions [en]

J1.5:Creating a simple module

2009-07-17T20:21:15Z

Lhollopeter:

{{review}}
== Basic Hello World Module ==

A Joomla! 1.5 Module is in its most basic form two files: an XML configuration file and a PHP controller file. The XML configuration file contains general information about the module (as will be displayed in the Module Manager in the Joomla! administration interface), as well as module parameters which may be supplied to fine tune the appearance / functionality of the module. The PHP file provides the controlling logic for the module. A very simple "Hello World" module might looking something like this.

'''/modules/mod_hello_world/mod_hello_world.xml:'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">

<name>Hello World - Hello</name>


<author>Ambitionality Software LLC</author>


<creationDate>2008-06-23</creationDate>


<copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright>


<license>GPL 2.0</license>


<authorEmail>info@ambitionality.com</authorEmail>


<authorUrl>www.ambitionality.com</authorUrl>


<version>1.0.0</version>


<description>Provides a basic "Hello World" notice</description>


<files>

<filename module="mod_hello_world">mod_hello_world.php</filename>
<filename>index.html</filename>
</files>


<params />
</install>
</source>

Basically, this XML file just lines out basic information about the module such as the owner, version, etc. for identification by the Joomla! installer and then provides optional parameters which may be set in the Module Manager and accessed from within the module's logic to fine tune its behavior. Additionally, this file tells the installer which files should be copied and installed. Notice that we DO NOT include a reference in the files section for the XML file.

'''/modules/mod_hello_world/mod_hello_world.php:'''

<source lang="php">
<?php
//don't allow other scripts to grab and execute our file
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
?>

Hello World

</source>

What happens when this module is loaded is that Joomla! includes (via the PHP include directive) the mod_hello_world.php file and stores the output into an output buffer which is then rendered onto the page output. This file would simply produce Hello World to the final page.

'''/modules/mod_hello_world/index.html:'''

<source lang="html4strict">
<html><body bgcolor="#FFFFFF"></body></html>
</source>

This really just helps to ensure that a default page is displayed if direct access to the directory is attempted without listing all of the other files in the directory. It's not necessary, but is good practice.

To package this module for distribution and installation, simply zip the files together, e.g.,

<source lang="text">
% cd mod_hello_world
% zip mod_hello_world.zip mod_hello_world.php mod_hello_world.xml index.html
</source>

The resulting mod_hello_world.zip file may be uploaded and installed through the standard Joomla! 1.5 Extension Manager.

== Real Joomla! 1.5 Style Module Implementation ==

Now that was easy...too easy. In fact, that was pretty much the simplest form of a module possible. In reality a module will probably be doing something much more substantial. Let's assume that our modules are going to be more complex - we need to take advantage of the MVC (Model View Controller) design pattern and consider using the following file layout for a "Hello World 2" module instead:

<source lang="text">
/modules/mod_hello_world2/index.html
/modules/mod_hello_world2/mod_hello_world2.php
/modules/mod_hello_world2/mod_hello_world2.xml
/modules/mod_hello_world2/helper.php
/modules/mod_hello_world2/en-GB.mod_hello_world2.ini
/modules/mod_hello_world2/tmpl/index.html
/modules/mod_hello_world2/tmpl/default.php
</source>

The differences to note here are that there are three additional files beyond what the "Hello World" module had, namely helper.php, tmpl/default.php, and the en-GB.mod_hello_world2.ini file. The purpose in adding the first two files is two-fold. Firstly, we separate the module's logic into the helper.php file to ensure that all of the thinking and data access is performed here and separate out the module's presentation / template into the tmpl/default.php file (the (X)HTML). I argue that this is just good programming - separating logic from presentation. There is a second advantage to this, however, which is that it will allow the HTML / presentation to be overridden easily by any Joomla! 1.5 template for optimal integration into any site. (Overriding module and component presentation in templates is beyond the scope of this article, however it should be addressed as it's really useful).

Let's take a look at what these files might look like and discuss what's going on.

'''/modules/mod_hello_world2/mod_hello_world2.php:'''

<source lang="php">
<?php
//no direct access
defined('_JEXEC') or die('Direct Access to this location is not allowed.');

// include the helper file
require_once(dirname(__FILE__).DS.'helper.php');

// get a parameter from the module's configuration
$userCount = $params->get('usercount');

// get the items to display from the helper
$items = ModHelloWorld2Helper::getItems($userCount);

// include the template for display
require(JModuleHelper::getLayoutPath('mod_hello_world2'));
</source>

The important differences to note are that (1) we include a helper file which will be the work-horse of our logic and data access and (2) once we have our data, we just load a template which will use our data and render it as it sees fit.

'''/modules/mod_hello_world2/mod_hello_world2.xml'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">

<name>Hello World 2 - Hello</name>


<author>Ambitionality Software LLC</author>


<creationDate>2008-06-23</creationDate>


<copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright>


<license>GPL 2.0</license>


<authorEmail>info@ambitionality.com</authorEmail>


<authorUrl>www.ambitionality.com</authorUrl>


<version>1.0.0</version>


<description>Provides a random listing of registered users</description>


<files>

<filename module="mod_hello_world2">mod_hello_world2.php</filename>
<filename>index.html</filename>
<filename>helper.php</filename>
<filename>tmpl/default.php</filename>
<filename>tmpl/index.html</filename>
</files>

<languages>

<language tag="en-GB">en-GB.mod_hello_world2.ini</language>
</languages>


<params>

<param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />


<param name="@spacer" type="spacer" default="" label="" description="" />


<param name="usercount" type="text" default="5" label="LABEL USER COUNT" description="DESC USER COUNT" />
</params>
</install>
</source>

The main differences to note here are that we have added a language file reference (we could have added more) and we added some parameters.

'''/modules/mod_hello_world2/helper.php:'''

<source lang="php">
<?php
defined('_JEXEC') or die('Direct Access to this location is not allowed.');

class ModHelloWorld2Helper
{
/**
* Returns a list of post items
*/
public function getItems($userCount)
{
// get a reference to the database
$db = &JFactory::getDBO();

// get a list of $userCount randomly ordered users
$query = 'SELECT a.name FROM `#__users` AS a ORDER BY rand() LIMIT ' . $userCount . '';

$db->setQuery($query);
$items = ($items = $db->loadObjectList())?$items:array();

return $items;
} //end getItems

} //end SimplestForumLatestPostsHelper
</source>

This helper class (note that it is named for the module name so that it doesn't collide with other class names) simply retrieves a list of all users in the database and randomly selects a subset of those based upon the number supplied as $userCount.

'''/modules/mod_hello_world2/tmpl/default.php:'''

<source lang="php">
<?php defined('_JEXEC') or die('Restricted access'); // no direct access ?>
<?php echo JText::_('RANDOM USERS'); ?>
<ul>
<?php foreach ($items as $item) { ?>
<li>
<?php echo JText::sprintf('USER LABEL', $item->name); ?>
</li>
<?php } ?>
</ul>
</source>

Here we simply create an unordered HTML list and then iterate through the items returned by our helper (in mod_hello_world2.php), printing out a message with each user's name.

'''/modules/mod_hello_world2/en-GB.mod_hello_world2.ini:'''

<source lang="text">
LABEL USER COUNT=User Count
DESC USER COUNT=The number of users to display
RANDOM USERS=Random Users for Hello World2
USER LABEL=%s is a randomly selected user
</source>

Here we simply identify strings which appear in the module configuration file and the module template which appear in JText::_ or JText::sprintf statements. This allows someone to easily write a new language file without editing any of the HTML or code for the module.

Now all we have to do is zip up these files, as in:

<source lang="text">
% pwd
/somesite/modules/mod_hello_world2
% zip -r ../mod_hello_world2.zip *
% ls ..
mod_hello_world2.zip
</source>

The resulting mod_hello_world2.zip file is ready for installation and distribution. When the ZIP file is installed, the en-GB.mod_hello_world2.ini file is copied to /language/en-GB/en-GB.mod_hello_world2.ini and is loaded each time the module is loaded. All of the other files are copied to the /modules/mod_hello_world2 subfolder of the Joomla! installation.
<noinclude>[[Category:Development]]</noinclude>

Administrator (Application)

2009-07-17T18:59:28Z

Lhollopeter:

<noinclude>{{review}}</noinclude>

Joomla! consists of several [[Application]]s:
* [[Site (Application)|Site]], also known as the "Front-end".

* [[Administrator (Application)|Administrator]], also known as the "Back-end". It is here that you can make your major customizations for your site or front-end. You can set up how your template looks or you can add new extensions such as components, languages, modules, plugins and templates from Joomla's web site at [http://extensions.joomla.org/ Joomla extensions].

* [[Installer (Application)|Installer]] is an application that helps you to install and configure Joomla on your web site. Follow the next steps at [http://docs.joomla.org/Installer Installer].

* [[XML-RPC (Application)|XML-RPC]], known as eXtensible Markup Language Remote Procedure Call, is a method of sharing messages between client and server.

<noinclude>[[Category:Application]]</noinclude>

Adding a menu item which points to an Article

2009-07-17T18:44:22Z

Lhollopeter: /* Tutorial */

{{review}}

The following tutorial will show you how to create a new item in the main menu that points to the article called Support and Documentation. Based on this information you will be able to add a new menu item to any of your defined menus pointing to any article you have previously created for your site.

==Tutorial==
If you are not currently logged in to the administration panel, you will need to do so. If you are already logged in, you do not need to complete this step.

# Open a new browser window and type in the URL, which will be similar to http://www.your_site_name_here.com/administrator or, if you have Joomla installed on your local computer, http://localhost/administrator. Here you will have to log in as an Administrator or Super Administrator.
# Within the site administration panel, select '''Menu''' from the menu bar in the upper left corner. From the drop-down list, choose the menu you wish to work with. The menu can be Main Menu, available by default, or any other menu. This will open the Menu Item Manager page. [[Image:Edit-Main-Menu.png|Select Main Menu]]
# From the row of actions in the upper-right corner, select '''New''' (represented by the green icon with the plus sign). This will open the Menu Item: [New] page. [[Image:Main-Menu-Editor.png|Click New]]
# From the list titled "Select Menu Item Type," choose '''Articles''' (You'll find Articles under the Internal Link.) [[Image:NewMenuItem-Articles.png|Select Articles]]
# Choose '''Article Layout''' in the previously expanded Articles section. [[Image:Select-Article-Layout.png|Select Article Layout]]
# We are getting really close. Hold on! On the new page fill in the different fields like this: [[Image:NMI-Article-Details.png|Enter Article Details]] '''Menu Item Details''' 
#* '''Title''' This will be the text displayed for the newly added menu item. For this particular case let's use the word '''Documentation'''.
#* '''Alias''' Usually, you will leave this empty and Joomla! will fill this in for you automatically. The content of this field will determine the page URL when SEF is activated.
#* '''Display in''' This should already be set to Main Menu (or the menu you have previously chosen ). Here you have the possibility to move the item to another menu if you wish. This field is quite useful when you decide to change the item location later.
#* '''Parent Item''' Here you can specify where to place the new menu item. You can make it a top item or a sub-item of an already existing item. We will choose '''Top'''.
#* '''Published''' If you wish your new item to be shown on your site, set this to '''Yes'''. If you would like to remove this menu item from the site, simply set this to No. It will ''not'' delete the item but will make it invisible to your visitors.
#* '''Access Level''' This option will specify who will be able to see this new menu item:
#** ''Public'' - All visitors
#** ''Registered'' - Registered users only
#** ''Special'' - users assigned to any group besides "Registered"
#* '''On Click, Open in''' Here you can specify how to open the article. It can be the same browser window (Parent Window with Browser Navigation), a new browser window (New Window with Browser navigation) or a pop-up window (New Window without Browser Navigation)
# Now, let's get to the right side of this page...
#* '''Parameters (Basic)''' The most important part in this section is the Parameters (Basic) setting. Here you can specify the article that will be opened when the user clicks the newly created menu item.
#** For this press the '''Select''' button near the ''Select Article'' input box. [[Image:SelectWhichArticle.png|Click Select]]
#** In the pop-up window, select ''Support and Documentation'' from the list of articles by clicking on the article name. [[Image:ChooseArticleFromList.png|Choose Article From List]] Please note that you can choose any of the existing articles at this point.
#* '''Parameters (Component)''' Here you will find different options to help you customize the way your article will be displayed. Normally, you won't need to change anything in this section. If you decide to explore it, you will find good help in the tool tips that appear when you move your mouse over the labels (Show Unauthorized Links, etc)
#* '''Parameters (System)''' This section will let you customize the way the page containing the article gets downloaded and displayed.
#** '''Page Title''' - If this parameter is left blank, Joomla! will generate a Page Title automatically. This can be used to over-ride the page title set in the article. Don't forget! Page titles are one of the most important points when it comes to search engine optimization (SEO)! Use them wisely.
#** '''Show Page Title''' - display (Yes) or not (No) the page title set in the previous parameter
#** '''Page Class Suffix''' - this allows you to generate unique CSS classes for this page. This comes in usefull when you would like to change the look of the page to differentiate it from the rest of the site. If you don't need this, simply leave the field empty.
#** '''Menu Image''' - let's you choose an image to be displayed along with this item in the menu. The image you would like to associate with the item must be stored in the images/stories folder. You can upload your own image using the Media Manager or by FTP.
#** '''SSL Enabled''' Specify how a page is displayed:
#*** ''On'' - As a secure page
#*** ''Off'' - As a standard page
#*** ''Ignore'' - Displayed as the other pages - secure or not
# Once you are done, click the '''Save''' button in the upper-right corner (the floppy disk icon). [[Image:SaveArticleMenuItem.png|Click Save]] This will save the new item and place it as the last element (or sub-element, in case of sub-menu items) in the menu. You can use the green arrows in the Order column to change the item position within the menu.
# Now, get back to the front-end and refresh the page. [[Image:VerifyArticleMenuItem.png|Verify New Menu Item]]

Voilà! The new menu item is shown. Please note that you might need to log in as a registered user or administrator to view the new item. It all depends on the Access Level you have set (see above). When you click the new item, the article will be opened.

[[Category:Tutorials]]