Web Developer and Joomla! CMS Solutions Specialist

Joomla! Module Administrator Parameters - Multiple Select Lists

Joomla! provides an easy way to add parameters to modules in the administrator control panel. Each module has its own folder inside the modules/ directory. In this directory, an xml file describes the admin control panel parameter options. The file name is modules/mod_YOURMODULENAME/mod_YOURMODULENAME.xml. It's possible to customize these options, create new options, or even create your own custom module, with its own xml parameter file.

The parameters available to you in modules are the ones found in libraries/joomla/html/parameter/element/. The files in this directory all correspond to parameter types you can use in your module xml file. You can also define your own module parameter types, to give you different html list behaviors, or custom data. I recommend packaging these custom elements with the module in the directory modules/mod_YOURMODULENAME/elements/, but you can put them anywhere you want. Perhaps you will have several modules using these resources, in which case you may want to create a system plugin to include your custom library files. In any case, a example of a file in elements/ would look something like this...

In this example, we have an element file named /modules/mod_YOURMODULENAME/element/categories.php. The purpose of this file is to provide a multi-option select list element, based on the Joomla! categories available. These articles can then be displayed in a variety of ways. This list simply allows the admin to select any number of categories, and then makes those category ids available to the module helper. The ids are used to generate the sql SELECT query, and then other filters can be applied based on the other module parameters.

Example: /modules/mod_YOURMODULENAME/element/categories.php

class JElementCategories extends JElement {

  var   $_name = 'Categories';

  function fetchElement($name, $value, &$node, $control_name)
  {
    $db = &JFactory::getDBO();

    $section  = $node->attributes('section');
    $class    = $node->attributes('class');
    if (!$class) {
      $class = "inputbox";
    }

    if (!isset ($section)) {
      // alias for section
      $section = $node->attributes('scope');
      if (!isset ($section)) {
        $section = 'content';
      }
    }

    if ($section == 'content') {
      // This might get a conflict with the dynamic translation
      // - TODO: search for better solution
      $query = 'SELECT c.id AS value, CONCAT_WS( "/",s.title, c.title ) AS text' .
        ' FROM #__categories AS c' .
        ' LEFT JOIN #__sections AS s ON s.id=c.section' .
        ' WHERE c.published = 1' .
        ' AND s.scope = '.$db->Quote($section).
        ' ORDER BY s.title, c.title';
    } else {
      $query = 'SELECT c.id AS value, c.title AS text' .
        ' FROM #__categories AS c' .
        ' WHERE c.published = 1' .
        ' AND c.section = '.$db->Quote($section).
        ' ORDER BY c.title';
    }
    $db->setQuery($query);
    $options = $db->loadObjectList();
  
    return JHTML::_('select.genericlist',  $options, ''.$control_name.'['.$name.'][]', 
      'class="inputbox" size="15" multiple="multiple"',
      'value', 'text', $value, $control_name.$name);
  
  }
}

This version allows for multiple categories to be selected. Also, it auto-selects the values that is finds in the parameters for the module, so that it preserves the selected choices when edited.

By itself, the above code will not do anything, because the Joomla! module is not aware of it. To tell Joomla! that we want to add this file, we edit the element in the file modules/mod_YOURMODULENAME/mod_YOURMODULENAME.xml. We also need to add the element/ directory, and everything in it. Or we could also just include the single element file instead. My examples includes the whole directory / folder. Here's an example of how this is done in the xml file...

...
<files>
	<filename module="mod_YOURMODULENAME">mod_YOURMODULENAME.php</filename>
	<folder>element</folder>
</files>

<params addpath="/modules/mod_YOURMODULENAME/element">
<param name="catids" type="categories"  default="" label="Categories" description="Categories" />
...

The things to note here...

• The element folder is being included within the block
• The path to the element folder is also being added to the group
• Because the custom element categories is now available, it can be used like any other built in param

Here's the example of how this parameter can be used in your module helper code. This is based around the Joomla! 'Latest News' module helper.

$catids	= $params->get('catids');

if ($catids)
{ 
    if( is_array( $catids ) ) {
        $catCondition = ' AND (cc.id IN ( ' . implode( ',', $catids ) . ') )';
	    } else {
	$catCondition = ' AND (cc.id = '.$catids.')';
	}	
}

From there, the $catCondition gets included in the sql SELECT query. This is just one example of how custom module parameters are available to developers, and how they can be made into any type of html form element needed for the Joomla! admin section.

Add Comment