File and Function Reference

The following functions are available to template developers.

mosLoadComponent

Syntax:

mosLoadComponent( $name )

Loads a component. For example "banners". Do not include the "com_" prefix.

mosCountModules

Syntax:

mosCountModules( $position_name )

Counts the number of modules that may be shown on the current page in the "position_name" position.

mosLoadModules

Syntax:

mosLoadModules( $position_name [, $style] )

Displays all modules that are assigned to the "position_name" position for the current page. The "style" argument is optional but may be:

0 = (default display) Modules are displayed in a column. The following shows an example of the output:

·

· <table cellpadding="0" cellspacing="0" class="moduletable[suffix]">

· <tr>

· <th valign="top">Module Title</th>

· </tr>

· <tr>

· <td>

· Module output

· </td>

· </tr>

· </table>

·

1 = Modules are displayed horizontally. Each module is output in the cell of a wrapper table. The following shows an example of the output:

·

· <table cellspacing="1" cellpadding="0" border="0" width="100%">

· <tr>

· <td align="top">

·

· <table cellpadding="0" cellspacing="0" class="moduletable[suffix]">

· <tr>

· <th valign="top">Module Title</th>

· </tr>

· <tr>

· <td>

· Module output

· </td>

· </tr>

· </table>

·

· </td>

· <td align="top">

·

· </td>

· </tr>

· </table>

-1 = Modules are displayed as raw output and without titles. The following shows an example of the output

· Module 1 OutputModule 2 OutputModule 3 Output

-2 = Modules are displayed in X-Joomla format. The following shows an example of the output:

·

· <div class="moduletable[suffix]">

· <h3>Module Title</h3>

· Module output

· </div>

·

-3 = Modules are displayed in a format that allows, for example, stretchable rounded corners. This option was introduced in Mambo 4.5.2.1.

·

· <div class="module[suffix]">

· <div>

· <h3>Module Title</h3>

· Module output

· </div>

Note in all cases that an optional class "suffix" can be applied via the module parameters.

mosShowHead

Syntax:

<?php mosShowHead(); ?>

Assembles various head tags including the title tag and several meta tags.

mosMainBody

Syntax:

<?php mosMainBody(); ?>

Includes the output of the component as determined by the value of option in the URL.

Template Standards

Standards (DRAFT)

Identify the Language in the Head Tag

The HTML element must include the lang attribute.

<head>

Note: From Joomla 1.1 onwards it will be possible to use $_LANG->isoCode() instead

of _LANGUAGE.

Reference:

Provide a Summary for Tables

The TABLE element should include the summary attribute to describe it's structure and purpose.

<table summary="Hits on news compared to help">

<caption>Hits on news compared to help</caption>

</table>

The use of the summary attribute for layout tables is at the discretion of the designer but is

generally not recommended.

Reference:

Link Text

Make link text phrases make sense when they are read out in context and also ensure that

different link addresses have different text. For example, avoid the use of "click here".

Reference:

Link text

Associate Form Controls with the LABEL Element

A LABEL element is able to directly associate a description of a form element to the element itself.

The LABEL for attribute must uniquely match the id attribute of the form element.

<?php echo $_LANG->_( '_USERNAME' ); ?>

</label>

<br />

<input id="mod_login_username" name="username" type="text"

class="inputbox<?php echo $moduleclass_sfx; ?>" alt="username"

size="10" />

With this association, some browsers allow for the clicking of the label to acquire focus for the

control.

Reference:

Administrator Templates

At this time the model for Administrator Templates is still being formed. It is intended that both

the Site and Administrator templating systems will merge into a common API in a future version.

However, some notes are provided here for reference.

Module Support

You may include modules in your Administrator templates directly with mosLoadAdminModule or in groups, like for the site templates, with mosLoadAdminModules. For example:

<tr>

<?php mosLoadAdminModules( 'header', 2 );?>

</div>

</td>

<a href="index2.php?option=logout" style="color: #333333; font-weight: bold">Logout</a>

<strong><?php echo $my->username;?> 

</td>

</tr>

</table>

The mosLoadAdminModule function takes one argument, the name of the module less the

"mod_" prefix. The first cell of the example table loads the Full Menu module (that is, mod_fullmenu).

In the second table cell, all the modules assigned to the "header" position are loaded. The second argument is a style setting:

0 = just output sequentially what the modules output
1 = display each module in a "Tab"
2 = display each module wrapped in a <div> tag

Formatting for the "header" modules is done completely via CSS. For example, the "wrapper1" style is defined as:

#wrapper1 div {

border: 0px;

margin: 0px;

margin-left: auto;

margin-right: auto;

padding: 0px 5px 0px 5px;

display: inline;

}

The modules are enclosed in plain <div> tags. To display modules in a column you may add a width attribute and change the display attribute appropriately.

The following modules are available with the Joomla distribution.

mod_fullmenu

The Full Menu module displays the traditional DHTML Adminstrator menu. Content Sections

and Components are dynamically added with the remainder of the menu being statically defined.

mod_components

The Components module displays a full list of the Components and sub-menu items. This

is useful where many components are installed and the capacity of the DHTML menus is exceeded.

mod_latest

The Lastest Items module displays the most recently created content items.

mod_mosmsg

The Message module displays the message passed in the URL.

mod_online

The Users Online module displays the number of users logged in.

mod_pathway

The Pathway module displays an Administrator pathway.

mod_popular

The Most Popular module displays a list of the most "hit" content items.

mod_stats

The Menu Stats module shows some statistics about the menus.

mod_toolbar

The Toolbar module displays the icon toolbar.

mod_unread

The Unread Messages module displays the number of unread private messages.

mod_logged

This Logged module displays a list of the currently logged in users.

mod_quickicon

The Quick Icon module displays an array of shortcut icons.

The Control Panel

The Control Panel for the Administrator is a separate file, cpanel.php, that is included with the

template. It is a separate file to allow for customisation of this area as different sites and users are

likely to have different needs for this valuable piece of screen real estate.

The Control Panel file does not need to be included but if it is included it will simply display any Administrator Modules published in the "cpanel" position.

The cpanel.php file could be as simple as the following example:

<?php

/**

* @version $ Id: cpanel.php,v 1.3 2004/08/12 08:29:21 rcastley Exp $

* @package Joomla

* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL, see LICENSE.php

* Joomla! is free software and parts of it may contain or be derived from the

* GNU General Public License or other free or open source software licenses.

* See COPYRIGHT.php for copyright notices and details.

/** ensure this file is being included by a parent file */

defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );

<tr>

<?php mosLoadAdminModules( 'cpanel', 1 ); ?>

</td>

</tr>

</table>

Overview

This chapter includes some more advanced features such as hiding template columns and designing templates for the Administrator.

Hiding Modules

Sometimes it is desirable to hide certain module areas if there are no modules assigned to

that region. You can hide these areas by using the mosCountModules function.

<?php if (mosCountModules( 'right' )) { ?>

<td>

<?php mosLoadModules( 'right' ); ?>

</td>

<?php } ?>

If the mosCountModules function returns a value greater than 1, the table cell will be displayed. If

there are no modules defined for the "right" position for this particular page, then the cell will not be displayed. This is a good technique for increasing the horizontal screen width on certain pages.

Using Class Suffixes

TODO

Module Hello World 1

Introduction

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, a powerful set of functions that help separate the presentation (HTML) from the application logic (PHP) using templates. Full documentation for patTemplate can be found on their website.

Requirements

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.

mod_helloworld.php

This file is the actually engine for the module.

mod_helloword.xml

This file is the XML setup file 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 actual module first. Save the following code as mod_helloworld.php.

<?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>

  <version>1.0</version>

  <description>A module that says hello</description>

  <files>

    <filename module="mod_helloworld">mod_helloworld.php</filename>

  </files>

  <params />

</mosinstall>

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:

mosinstall

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.

name

This is the name of your module.

author

This is the name of the author for the module.

creationDate

This is the date the module was created.

This is the copyright holder of the module's code.

license

This is the name of, or a reference to, the license under which the module is released.

version

This is the version of the module.

description

This is a free text description of the module.

files

This is a collection of the files included with the module.

filename

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:

Log into the Joomla! Administrator.
Select Installers -> Modules from the menu.
In the Upload Package File area, click the Browse button and select the zip file you just created or downloaded. Then click theUpload File and Install button.

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 unpublished and assigned to the left position in the template. Click on the red X in the published column to publish the module.

Preview 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:

<mos:comment>

@version 4.5.2

@package HelloWorld

@copyright (C) 2005 Andrew Eddie

@license http://www.gnu.org/copyleft/gpl.html GNU/GPL

</mos:comment>

<mos:tmpl name="helloworld">

  <h1>Hello World</h1>

  The time is {TIME}

</mos:tmpl>

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:

<?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.' );

// 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 parsed by an application
called phpDocumentor. It is used to assemble API (Application Programming 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 J
oomla!, 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.

Module Hello World 2

Introduction

This tutorial aims to build on the helloworld module started in part one. You will learn how to retrieve information from the database and how to present this data is a table using patTemplate.

Requirements

You need for this tutorial:

Joomla 1.0 or greater

Let's Roll

You will recall that we finished part 1 with your module displaying a message and the current time. This is all very interesting but far more interesting is the information held in the tables of the Joomla database. What we will do in this example is develop a type of Current News module.

The Presentation Layer

Let's start with the output of the module. Because the code (or the logic) of the module is now separated from the presentation layer (the HTML), it gives the graphic designer an opportunity to design the output separate from the module.

The module code designer has informed us that a list of content items will be provided to the template. The content item data will include the item id, the title of the item, and the number of hits the item has received.

Now, open the default.html file (remember we saved this in the /mod_helloworld directory). Delete what is there and replace it with the following code:

<mos:comment>

@version 1.0

@package HelloWorld

@copyright (C) 2005 Andrew Eddie

@license http://www.gnu.org/copyleft/gpl.html GNU/GPL

</mos:comment>

<mos:tmpl name="helloworld">

  <h1>Hello World</h1>

  This is the latest and the greatest from <strong>{SITENAME}</strong>

  <table>

    <tr>

      <th>

        Title

      </th>

      <th>

        Hits

      </th>

      </tr>

      <mos:tmpl name="rows">

      <tr>

        <td>

          {ROW_TITLE}

        </td>

        <td>

          {ROW_HITS}

        </td>

      </tr>

      </mos:tmpl>

    </table>

</mos:tmpl>

As in part 1, we wrap our whole module output in a template that we've named helloworld. It all looks like standard HTML except for a few things.

You'll see we display a message with the {SITENAME} variable. This variable has already been defined for you in the template. It's equivalent to printing the $mosConfig_sitename variable. Other predefined variables include {SITEURL} and {ADMINURL}. These map to the URL of the site and administrator repsectively.

The other thing you'll notice is an embedded template that we have named rows. It enclosed a single row of the HTML table. The module designer has told us that he has prefixed all variables in the rows template with "row_", and that he has provided at least the Title, which therefore maps to {ROW_TITLE}, and the Hits, which maps to {ROW_HITS}.

Well, that's the template finished (is it that easy I hear you say?).

The Data Layer

Let's move back to the module file, mod_helloworld.php, where we will assemble the data to pass to the template. Open the file in your editor, delete the code and replace it with the following:

<?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.' );

// COLLECT DATA

// assemble query

$query = '

    SELECT id, title, hits

    FROM #__content

    ORDER BY hits DESC

    LIMIT 5

';

// prepare the query in the database connector

$database->setQuery( $query );

// retrieve the rows as objects

$rows = $database->loadObjectList();

// DISPLAY DATA

// 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' );

// load the template

$tmpl->readTemplatesFromInput( 'default.html' );

// add the 'rows' to the rows template with a prefix

$tmpl->addObject( 'rows', $rows, 'row_' );

// output the template

$tmpl->displayParsedTemplate( 'helloworld' );

?>

Let's examine what's happening here:

We start with the standard comment and security block.
We then prepare our query. The data we want is in the mos_content table. Because we don't always know if the "mos_" prefix has been used, we use "#__" (hash, underscore, underscore) instead. This is automatically replaced with the correct database table prefix. You'll notice we are retrieving three fields, the id, the title and the hits. We are ordering them by the number of hits in descending order and limiting the number of results to a maximum of five (that is, the top five).
Next we initialise the query in the database connector ($database, which is always available to module files) using the setQuerymethod.
Following this we call the loadObjectList method to retrieve the results from the database as an array of PHP objects. This is stored in the variable $rows.

That's it for the first half of the module, that is, the collecting of the data. The last half of the module is much that same as our original module from part 1. The only difference is that we use the addObject method to add the array to the rows template.

Note: the addObject method can take either a single object or an array of objects.

The thing to note here is that for each array member in $rows, the rows template in the HTML file will display a copy of itself. In other words, if there are five elements in the $rows array (that is, the database was able to retrive five rows of records), then the rowstemplate will cycle, or iterate, five times. The rows template acts much like a foreach loop in PHP.

Save all files and refresh your browser. You should see that the module now displays an opening message that includes the name of your site, and also a table of the most hit content items.

What's wrong with this picture. Well, you'll see that the query takes no account for publishing dates, whether they are indeed published at all and the security level of the items. You have to apply that logic yourself. To do this, modifying the query variable in the following way:

// assemble query

global $mosConfig_offset;

$now = date( 'Y-m-d H:i:s', time() + $mosConfig_offset * 3600 );

$query = '

    SELECT id, title, hits

    FROM #__content

    WHERE ( state = \'1\' AND checked_out = \'0\' )

        AND ( publish_up = \'0000-00-00 00:00:00\'

            OR publish_up <= \'' . $now . '\' )

        AND ( publish_down = \'0000-00-00 00:00:00\'

            OR publish_down >= \'' . $now . '\' )

        AND access <= \'' . $my->gid .'\'

    ORDER BY hits DESC

    LIMIT 5

';

In the next part of this series, we will look at adding parameters to the module.

You can download the files for the final part of the tutorial here (mod_helloworld_2.zip).

Module Hello World 3

Introduction

This tutorial aims to further build on the helloworld module we expanded in part three. You will learn how to use parameters to fine tune some of the information that is displayed. We will also look at looking at ways to 'skin' your module output..

Requirements

You need for this tutorial:

Joomla 1.0 or greater

Let's Roll

You will recall that we finished part 2 with your module displaying a list of the most hit times. Unfortunately we were stuck with displaying only 5 items and could not change the ordering. What we will do in this example is learn how to add parameters to the module so that you can vary these conditions.

Setting up the Parameters

We need to revisit the XML file that we created in part 1. We define all our parameters in this file. First let's consider what variables we want to allow the user to change:

We want a variable to change the number of items displayed.
We want to be able to select the ordering of the items from a list.
We want to be able to select a template to use to change the display of the items (sort of like skinning).

To do this we add a number of param tags to the params tag. Open the mod_helloworld.xml file. Delete its contents and replace it with the following code:

<?xml version="1.0" encoding="iso-8859-1"?>

<mosinstall type="module" version="4.5.2">

  <name>Hello World</name>

  <author>Andrew Eddie</author>

  <creationDate>March 2005</creationDate>

  <copyright>(C) 2005 Andrew Eddie</copyright>

  <license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>

  <version>2.0</version>

  <description>A module that says hello and displays a list of the

               most hit content items</description>

  <files>

    <filename module="mod_helloworld">mod_helloworld.php</filename>

    <filename>mod_helloworld/default.html</filename>

  </files>

  <params>

    <param name="moduleclass_sfx" type="text" default=""

           label="Module Class Suffix"

           description="A suffix to be applied to the css class of the module

                       (table.moduletable), this allows individual module styling" />

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

    <param name="count" type="text" size="20" default=""

           label="Number of items" description="The number of items to display" />

    <param name="ordering" type="list" default="hits" label="Back Button"

           description="Show/Hide a Back Button, that returns you to the previously

                        view page">

      <option value="hits">Hits</option>

      <option value="title">Title</option>

    </param>

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

    <param name="skin" type="list" default="default" label="Module Skin"

           description="The skin for the module display">

      <option value="default">Default</option>

      <option value="bullets">Bullets</option>

    </param>

  </params>

</mosinstall>

Each param tag has a number of common attributes:
nameThe name of the html form field and also the name of the paremeter that you will access in your module code.typeThis is the type of field. The standard types are:

text - a normal text field
textarea - a normal textarea field. You can also add attributes for the rows and cols.
list - a normal select list form field. Lists can have any number of option child tags.
radio - a radio group. The radio type can have any number of option child tags
spacer - shows a html horizontal rule.
imagelist - shows a select list of images. You also provide a required directory attibute (the default is /images/stories), an optional hide_none attribute (either 0 or 1, where 1 will show a "Use no image" option) and a hide_default attribute (either 0 or 1, where 1 will show a "Use default image" option).
mos_category - shows a select list of Joomla content categories
mos_section - shows a select list of Joomla content sections.
mos_menu - shows a list of Joomla menu items.

defaultA default value for the form field if no value is provided.
labelA label for the form field.descriptionA description (or tooltip) for the form field
There are some additonal attributes based on the type of parameter as described above. For those parameters that allow for options, a standard html option tag is used, usually with a value attribute.

Let's have a look at each param tag in the params tag (each parameter will be identified by it's name attribute): moduleclass_sfx This is a standard parameter to include in all modules. Most modules are placed in a wrapper (unless you are using the loadModules template macro with a style of less than zero) and this wrapper has a css class of moduleclass. You can include your own variant of this class and suffix it with a unique identifier, for example, moduleclass_hello. To use your custom class you would enter _hello in this field@spacerThis param simply displays as a horizontal rule. It is useful for visually separating groups of associated parameters.countThis will define the number of items we will showorderingThis will show a list of possible options for ordering the list of items@spacerAnother spacer.skinThis will show a list of the available 'skins' for the output of the module.

When you updated the xml file, navigate to Modules -> Site Modules from the menu in the Administrator. Click on the linked name for the Hello World module (it might be on another page of the list depending on it's position).

When the edit screen appears you should see that the parameters show at the bottom of the first column of the form.

You can see how the spacer works, separating the parameters into groups. You can also see that the lists are populated with the options defined in the xml file. For now you can leave the count blank, but when we have finished altering all the code, come back to this edit form and experiment with different values. Note that the Page Class Suffix will only be relevant if you have a custom style in the style sheet for your site template.

Coding for Module Parameters

Our next step is to retrieve the parameters in our module and apply them. Open the module php file, mod_helloworld.php, in your editor, delete the code and replace it with the following:

<?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.' );

// COLLECT DATA

// assemble query

global $mosConfig_offset;

$now = date( 'Y-m-d H:i:s', time() + $mosConfig_offset * 3600 );

// Retreive parameters

$count = intval( $params->get( 'count', 10 ) );

$ordering = $params->get( 'ordering', 'hits' );

$skin = $params->get( 'skin', 'default' );

// Assign ordering

switch ($ordering) {

  case 'title':

    $orderBy = 'title ASC';

    break;

  case 'hits':

  default:

    $orderBy = 'hits DESC';

    break;

$query = '

  SELECT id, title, hits

  FROM #__content

  WHERE ( state = \'1\' AND checked_out = \'0\' )

    AND ( publish_up = \'0000-00-00 00:00:00\' OR publish_up <= \''

                . $now . '\' )

    AND ( publish_down = \'0000-00-00 00:00:00\' OR publish_down >= \''

                . $now . '\' )

      AND access <= \'' . $my->gid .'\'

  ORDER BY ' . $orderBy . '

  LIMIT ' . $count

// prepare the query in the database connector

$database->setQuery( $query );

// retrieve the rows as objects

$rows = $database->loadObjectList();

// DISPLAY DATA

// 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' );

// load the template based on the selected skin

$tmpl->readTemplatesFromInput( $skin . '.html' );

// add the 'rows' to the rows template with a prefix

$tmpl->addObject( 'rows', $rows, 'row_' );

// output the template

$tmpl->displayParsedTemplate( 'helloworld' );

?>

You will see that after the "retrieve parameters" comment we've added a few lines. An object variable called $params is already made available to the module. It has a method called get. This method takes two arguments; the first is the name of the parameter, the second is the default value to assign it if the user has not given it a value.

Once we have the parameters in variable form, you'll see we use them to modify the ordering of the query and also the number of items returned by the query. Further down you can see we use the $skin variable to load the selected skin for the output.

Adding Another Skin

Last of all we need to add our alternative skin. We are going to display the resulted in a bullet list instead of a table. Recall that our template current template file is called default.html in the mod_helloworld directory. In that same directory create a new file called bullets.html and copy the following code into it:

<mos:comment>

@version 1.0

@package HelloWorld

@copyright (C) 2005 Andrew Eddie

@license http://www.gnu.org/copyleft/gpl.html GNU/GPL

</mos:comment>

<mos:tmpl name="helloworld">

    <h1>Hello World</h1>

    How is this for a change.

    <ul>

        <mos:tmpl name="rows">

        <li>

            {ROW_TITLE} <em>( {ROW_HITS} )</em></li>

        </mos:tmpl>

    </ul>

</mos:tmpl>

When you are finished, go back to the module edit screen and change some of the values and see what happens.

What we are demonstrating here is the ability to present the same data in different ways without having to re-engineer the core php code. The change to the presentation layer is done in familiar HTML files, making Joomla even easier to tune to your specific needs.

You can download the files for this tutorial mod_helloworld_3.zip.

Chapter 5. Components

Overview Components are the main functional units that display in your template, like the content management system, contact forms, web links and the like. This chapter serves to provide you with a number of useful examples that helps you learn how to create Components. While we have gone to great lengths to make Joomla easy for content providers to use, we have equally spent a lot of time developing a flexible framework for developers to extend the capabilities of Joomla without having to touch the core code. Please note that line numbers shown in code examples may not be sequential.
Hello World 1 - The first steps

Introduction

If anyone has every picked up a book on programming, the first things they get you to do is complete a very simple exercise to write "Hello World" on the screen. This is usually a very exhilarating experience when you complete it because you know you are on the way to bigger and better things.

This tutorial aims to give you a grounding in the basic concepts for writing Joomla components. It will develop a very simple Hello World administrator component using patTemplate for the presentation layer.

Requirements

You need for this tutorial:

Joomla 1.0 or greater

Let's Roll

We will be creating three files in this tutorial in a folder called /administrator/components/com_hello. Our component is called "hello" so the folder is given this name prefixed by "com_". Let's look at the files we need.
admin.hello.php
This file represents the main task handling file. The Joomla Administrator looks for this file, "admin.component_name.php", when it first loads the component.
admin.hello.html.phpThis file represents the preprocessor for final presentation. As for the previous file, this file needs to the named "admin.component_name.html.php".
tmpl/helloworld.htmlThis file represents that presentation layer, or the output, that will be displayed. There is no special naming convention for this file, although it is a good idea to have a name that closely relates to the task used to display it.

The Event Handler

Let's look at our first file, the task handler, admin.hello.php.

<?php

/**

* @version 4.5.2

* @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.' );

// include support libraries

require_once( $mainframe->getPath( 'admin_html' ) );

// handle the task

$task = mosGetParam( $_REQUEST, 'task', '' );

switch ($task) {

    default:

        helloScreens::helloWorld();

        break;

?>

Here is an outline of what this file is doing:

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 parsed by an 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 trying to access this file. It prevents a user from opening the file explicitly in a browser.
We then include the file that will support the presentation layer. $mainframe is a global variable in Joomla that has lots of useful methods attached to it. One of these methods is getPath. It helps you find common types of files. In this instance we want the admin.hello.html.php file to be include, so we pass 'admin_html' to the getPath method.
Next we determine what task has been passed through the URL. To do this we use a utility function in Joomla called mosGetParam. It takes three arguments, a source array, a key in the array to search for and a default value to assign if that key is not found. In most instances we are not sure if the task is going to come through the URL or a form post, so we use $_REQUEST as the source array.
We then pass the task to a switch control structure. We only have one thing to do in this example so it doesn't much matter if a task has been nominated or not. Whatever the case, we are going to call a static class method called helloScreens::helloWorld.

Preparing for Output

The helloScreens class is defined in admin.hello.html.php so let's look at that file now:

<?php

/**

* @version 4.5.2

* @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.' );

/**

 * @package HelloWorld

*/

class helloScreens {

/**

     * Static method to create the template object

     * @return patTemplate

*/

    function &createTemplate() {

        global $option, $mosConfig_absolute_path;

        require_once( $mosConfig_absolute_path

            . '/includes/patTemplate/patTemplate.php' );

        $tmpl =& patFactory::createTemplate( $option, true, false );

        $tmpl->setRoot( dirname( __FILE__ ) . '/tmpl' );

        return $tmpl;

/**

     * A simple message

*/

    function helloWorld() {

        // import the body of the page

        $tmpl =& helloScreens::createTemplate();

        $tmpl->setAttribute( 'body', 'src', 'helloworld.html' );

        $tmpl->displayParsedTemplate( 'form' );

?>

As you can see, the start of the file is the same as our previous file. It includes a single class called helloScreens. The first method of the class, createTemplate, is a standard format for creating the template object we will be using to generate output. This method includes the required patTemplate library file, creates a patTemplate object and then sets the root directory for template (html) files to the /tmpl directory in your component.

Now, there is a lot going on behind the scenes here. The template object has already loaded and parsed another template file called page.html which includes many standard wrappers and other things. One of the standard templates is called form and this one will help us with our display for our component.

The next method is helloWorld and you will recall invoking this method in the admin.hello.php file. After it creates the template object it sets an attribute in the preloaded template called form that I mentioned before. In the form template is a sub-template called body. This sub-template is where we graft in the output from our component. You don't have to understand how all this is happening yet. Just appreciate that the setAttribute method is telling the template object to set the source of the body template to your html file, helloworld.html.

The last thing to do is to display the "form" template.

The HTML Output File

So now let's look at that html file:

<mos:comment>

@version 4.5.2

@package HelloWorld

@copyright (C) 2005 Andrew Eddie

@license http://www.gnu.org/copyleft/gpl.html GNU/GPL

</mos:comment>

<h1>Hello World<h1>

There's not really much to this file at all. We have a comment block at the top similar to our php files above. In patTemplate, text enclosed in an xml comment tag is not displayed. The mos: is called the namespace and it distinguishes the xml tags for patTemplate from any other html or xml tags that may be in your html file.

After the comment block we can include any valid html we like.

That's all the preparation done. Save all these files, log into the Joomla Adminisrator and change the last

portion of the URL to:
index2.php?option=com_hello

You should see a message announcing your successful completion of this tutorial.

You can download the files for the tutorial here (helloworld_1.zip).

Hello World 2 - Getting personal

Introduction

In our first tutorial we created a very simple component that just displayed information. In this tutorial we will show you how to add a toolbar, create a help file and also pass some dynamic data to your html file using patTemplate.

Requirements

You need for this tutorial:

Joomla 1.0 or greater
The files from the Hello World 1 tutorial

Let's Roll

We will be creating four new files in this tutorial:

toolbar.hello.php

This file represents the task handler for the toolbar (like the task handler for the component). The Joomla Administrator looks for this file, "toolbar.component_name.php", when it first loads the component.

toolbar.hello.html.php

This file actually displays the toolbar for a given task. As for the previous file, this file needs to the named "toolbar.component_name.html.php".

tmpl/politehello.html

The is the html file for a new task that we will be adding.

help/helloworld.html

This is a plain html file with some sort of helpful message in it.

The Toolbar Event Handler

The toolbar task handler, toolbar.hello.php, is very similar in structure to the event handler of the component:

<?php

/**

* @version $Id: toolbar.languages.php,v 1.4 2005/01/06 01:13:18 eddieajau Exp $

* @package Joomla

* @subpackage Languages

* @copyright Copyright (C) 2005 Open Source Matters. All rights reserved.

* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL, see LICENSE.php

* Joomla! is free software and parts of it may contain or be derived from the

* GNU General Public License or other free or open source software licenses.

* See COPYRIGHT.php for copyright notices and details.

*/

/** ensure this file is being included by a parent file */

defined( '_VALID_MOS' ) or

    die( 'Direct Access to this location is not allowed.' );

// include support libraries

require_once( $mainframe->getPath( 'toolbar_html' ) );

// handle the task

$task = mosGetParam( $_REQUEST, 'task', '' );

switch ($task) {

    default:

        helloToolbar::helloWorld();

        break;

?>

From this you can deduce that "toolbar_html" includes the html support for the toolbar which is based on the helloToolbar class. At the moment we will have the same toolbar regardless of the task.

The Toolbar HTML Handler

The file, toolbar.hello.html.php, actually does the work of displaying the toolbar:

<?php

/**

* @version 1.0

* @package HelloWorld

* @copyright Copyright (C) 2005 Open Source Matters. All rights reserved.

* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL, see LICENSE.php

* Joomla! is free software and parts of it may contain or be derived from the

* GNU General Public License or other free or open source software licenses.

* See COPYRIGHT.php for copyright notices and details.

*/

/** ensure this file is being included by a parent file */

defined( '_VALID_MOS' ) or

    die( 'Direct Access to this location is not allowed.' );

/**

* @package HelloWorld

*/

class helloToolbar {

/**

     * Displays toolbar

*/

    function helloWorld(){

        mosMenuBar::startTable();

        mosMenuBar::apply( 'polite', 'Be Polite' );

        mosMenuBar::spacer();

        mosMenuBar::help( 'helloworld.html', true );

        mosMenuBar::endTable();

?>

As for component task, we define a method in the toolbar class for each different toolbar layout we want to provide. So, in this exampe, we have our helloWorld method to display the toolbar. It is made up of a number of static methods in the mosMenuBar class (found in/adminsitator/includes/menubar.html.php).

You must start the toolbar by using the startTable method and finish it with the endTable method. What we have done is to use the standard Apply button but redefine the task it will call, "polite", and the text that displays beside it, "Be Polite". We then add a spacer and then a help button. When you click on the help button it will load the helloworld.html file; we will create this later. The second true argument indicates that the help file is found the component's help directory.

Adding the New Event

Using your code from Hello World 1, add the following case statement to the switch block in admin.hello.php:

    case 'polite':

        politeHello();

        break;

Then add the following function to the end of the file:

/**

 * Polite hello event

*/

function politeHello() {

    global $my;

    helloScreens::politeHello( $my->username );

You can see that we must have set up a new screen method called politeHello. This method takes the name of the user to insert into the final display. We are making use of a global Joomla variable called $my. This is an object that has information about you, the user logged in at the time. It has a property called username.

You may ask why we pass the name to the screen function? Why can't we just grab it there? Well, the reason is that this way, we are separating all of the data assembly operations from the presentation layer. The purpose of the helloScreens class is merely to insert the data into the html template. Similarly, the component , this politeHello function is not allowed to output any information or even add any html to the data, that's all to be done by the presentation layer. The principal here is to keep your business logic out of the html, and your html out of the business logic.

Preparing the Template

Using your code from Hello World 1, add this new method to the helloScreens class in admin.hello.html.php:

/**

     * A polite hello

     * @param string The name of a person

*/

    function politeHello( $name ) {

        // import the body of the page

        $tmpl =& helloScreens::createTemplate();

        $tmpl->setAttribute( 'body', 'src', 'politehello.html' );

        $tmpl->addVar( 'body', 'name', $name );

        $tmpl->displayParsedTemplate( 'form' );

It's very similar to our previous example. The differences are that we are using the politehello.html file as the basis for output and we also add the users name as a variable to the html template. We do this by invoking the addVar method. It takes three arguments, the name of the template, the name of the variable in the

template and then the value to insert in the variable. So, what we are saying is put the value of $name into

the

name variable in the body template. Now, remember from the previous tutorial, that the body template

has already

been loaded and we are grafting in the contents of politehello.html.

The last thing to do is to display the "form" template.

A Well Mannered Template

First, we have to fixed something up so that we can use the toolbar. Open helloworld.html from the

previous tutorial and add the following lines to the end of the file:

<input type="hidden" name="option" value="{OPTION}" />

<input type="hidden" name="task" value="" />

The toolbar requires a hidden form element called task in order to operate. The other hidden element, option, tells Joomla to come back to this component when the form is submitted. Now, you ask, what is the {OPTION}

thing. This is a template variable. In this case, the value for option has already been assigned in the

template (in the same way we did for the name of the user above). All you have to do is place the name of

the variable in uppercase and wrap it in curly braces.

Now we need to create our new html template file for our new screen. It's easiest to manage each screen in

it's own html file (it gets too confusing otherwise). Create a file called politehello.html in your /tmpl

directory with the following code::

<mos:comment>

@version 1.0

@package HelloWorld

@copyright (C) 2005 Andrew Eddie

@license http://www.gnu.org/copyleft/gpl.html GNU/GPL

</mos:comment>

<h1>Hello World</h1>

Welcome, <strong>{NAME}</strong>, to the Hello World tutorial.

<input type="hidden" name="option" value="{OPTION}" />

<input type="hidden" name="task" value="" />

You'll see that that we have a similar layout to what we had before except that we have place {NAME}

where we want the name to be displayed. We finish off the file with the hidden form fields to ensure that the

toolbar works properly.

A Bit More Help

There's on last thing to do, and that's to create the screen help file. Create a file called helloworld.html

and place it in a new directory called /help under your component directory (that is, com_hello).

Insert the following code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">

<head>

<title>Hello World</title>

<link href="../../../../help/css/help.css" rel="stylesheet" type="text/css" />

<meta name="copyright" content="(C) 2005 Andrew Eddie" />

<meta name="license" content="http://www.gnu.org/copyleft/gpl.html GNU/GPL" />

</head>

<body>

<h1>Hello World</h1>

Congratulations on completing the <strong>Hello World</strong> tutorials.

</body>

</html>

There's nothing special about this file, it's just regular html.

That's it. We're done. Save all these files, log into the Joomla Administrator and change the last portion of

the URL to:
index2.php?option=com_hello

You will see the plain old hello message but also the new toolbar. Click on the Help button first. You new

help file should pop up and give you some meaningful message to inspire you. Next, click on the Be Polite

button. Your screen should update with a message politely acknowledging you by name (well, user login

name anyway).

You can download the files for the tutorial here (helloworld_2.zip).

2 comments:

jextnNovember 22, 2011 at 5:20 AM
Thanks for the information..
joomla auction component
sathyaDecember 8, 2011 at 10:51 PM
Great posting.Great information.It is really different from other site.It is explain new knowledge.Thanks for making it.

Joomla developer

Thank you for your Comment....

Web Guru...

Monday, May 23, 2011

Joomla File and Function Reference

Introduction

Requirements

Let's Roll

Installing the Basic Module

Improving the Presentation

Introduction

Requirements

Let's Roll

The Presentation Layer

The Data Layer

Introduction

Requirements

Let's Roll

Setting up the Parameters

Coding for Module Parameters

Adding Another Skin

Introduction

Requirements

Let's Roll

The Event Handler

Preparing for Output

The HTML Output File

Introduction

Requirements

Let's Roll

The Toolbar Event Handler

The Toolbar HTML Handler

Adding the New Event

Preparing the Template

A Well Mannered Template

A Bit More Help

2 comments:

Popular Posts

Total Pageviews

Categories