Writing a Joomla! Module

There is a lovely extension out there for adding attachments to an article. It lets you upload/download files from an article. You install the component and a plugin, and the plugin displays the list of attachments at the base of the article content. You can find that extension here.

There are quite a few tutorials on how to write a Joomla! extension of the HelloWorld variety. I thought it would be amusing to write one with a practical application, for a change. I want the list of downloadable attachments to appear in a module location rather than in the article content.

If you are logged in to this site, you can download the module we will be writing in this article.

First, we need a name for this module. Since the attachments component is com_attachments, we will call this module mod_attachments.

We create a directory called mod_attachments, and create two files (to begin): mod_attachments.xml and mod_attachments.php.

The XML file is a definition file that tells the Joomla installer, among other things, what files are required and other metadata about the module.

mod_attachments.xml

<?@xml version=”1.0″ encoding=”utf-8″?>
<install type=”module” version=”1.5.0″>
    <name>Attachments List</name>
    <author>jennifer nodwell</author>
    <creationDate>March 2009</creationDate>
    <copyright>Copyright (C) 2008 – 2010 Jennifer Nodwell. All rights reserved.</copyright>
    <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
    <authorEmail>jennifer@nodwell.net</authorEmail>
    <authorUrl>www.nodwell.net</authorUrl>
    <version>1.5.0</version>
    <description>This module shows the attachments in a module position</description>
    <files>
        <filename>mod_attachments.xml</filename>
        <filename module=”mod_attachments”>mod_attachments.php</filename>
        <filename>index.html</filename>
        <filename>tmpl/default.php</filename>
        <filename>tmpl/index.html</filename>
        <filename>styles/attachments.css</filename>
    </files>
    <params>
        <param name=”cache” type=”list” default=”1″ label=”Caching” description=”Select whether to cache the content of this module”>
            <option value=”1″>Use global</option>
            <option value=”0″>No caching</option>
        </param>
    </params>
</install>

The <name> tag is the name of the module as you will see it when you add a new module from the back-end under Extensions->Module Manager->New.

The PHP file will communicate with the component and generate the list of attachments for the given article being displayed. It will call on the tmpl/default.php file to actually write the information to the browser. If there were no component in play here, it would be typical to write a helper file for the module. However, we’re going to use the helper file in the com_attachments component.

mod_attachments.php

<?@php // no direct access
defined(‘_JEXEC’) or die(‘Restricted access’);

// get the current article id and call the
// component helper to build the list of
// attachments for the current article

require_once(JPATH_SITE.DS.’components’.DS.’com_attachments’.DS.’helper.php’);

// Generate the HTML for the attachments for the specified article
$article_id = (int) JRequest::getVar(‘id’, false);
$attachments = “”;
$db =& JFactory::getDBO();
$query = “SELECT count(*) FROM #__attachments WHERE article_id='” . $article_id . “‘ AND published=’1′”;
$db->setQuery($query);
$total = $db->loadResult();

if ( $total > 0 ) {
    // Get the component parameters
    jimport(‘joomla.application.component.helper’);
    $params = JComponentHelper::getParams(‘com_attachments’);

    // Check the security status
    $attach_dir = JPATH_SITE.DS.$params->get(‘upload_dir’, ‘attachments’);
    $secure = $params->get(‘secure’, false);
    $hta_filename = $attach_dir.DS.’.htaccess’;
    if ( ($secure && !file_exists($hta_filename)) ||
         (!$secure && file_exists($hta_filename)) ) {
        AttachmentsHelper::setup_upload_directory($attach_dir, $secure);
    }

    $attachments = AttachmentsHelper::attachmentsTableHTML($article_id, false, true, true, $from);

}
   
//display the list of attachments
require_once(JPATH_SITE.DS.’modules’.DS.’mod_attachments’.DS.’tmpl’.DS.’default.php’);

?>

This line

defined(‘_JEXEC’) or die(‘Restricted access’); 

ensures that this file only runs under Joomla! and isn’t accessed directly.

This line

require_once(JPATH_SITE.DS.’components’.DS.’com_attachments’.DS.’helper.php’);

gets the helper file (in our case from the component).

This line

$article_id = (int) JRequest::getVar(‘id’, false);

gets the article id so we know what attachments should be displayed

These lines

$db =& JFactory::getDBO();
$query = “SELECT count(*) FROM #__attachments WHERE article_id='” . $article_id . “‘ AND published=’1′”;
$db->setQuery($query);
$total = $db->loadResult();

connect to the Joomla! database and get a list of attachments associated to the article.

These lines

    jimport(‘joomla.application.component.helper’);
    $params = JComponentHelper::getParams(‘com_attachments’);
 

connect to the component’s helper and get the component’s parameters.

This line

$attachments = AttachmentsHelper::attachmentsTableHTML($article_id, false, true, true, $from);

calls the appropriate function in the helper class to get the information we want.

This line 

require_once(JPATH_SITE.DS.’modules’.DS.’mod_attachments’.DS.’tmpl’.DS.’default.php’);

passes control over to the tmpl/default.php file to display the information.

tmpl/default.php

<?@php // no direct access
defined(‘_JEXEC’) or die(‘Restricted access’);

$document = & JFactory::getDocument();
$document->addStyleSheet( JURI::base() . ‘modules/mod_attachments/styles/attachments.css’, ‘text/css’, null, array() );
echo $attachments;
?>

Now all we need is a style sheet and some dummy index.html files, and we can install the module. Zip all the files listed in the XML file into an archive, and upload it through the back end.

One Reply to “Writing a Joomla! Module”

Leave a Reply

Your email address will not be published. Required fields are marked *