Archived:Developing a MVC Component/Adding configuration

This page has been archived. This page contains information for an unsupported Joomla! version or is no longer relevant. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

Under Construction

Articles in this series

Articles in this Series

1. Introduction
2. Developing a Basic Component
3. Adding a view to the site part
4. Adding a menu type to the site part
5. Adding a model to the site part
6. Adding a variable request in the menu type
7. Using the database
8. Basic backend
9. Adding language management
10. Adding backend actions
11. Adding decorations to the backend
12. Adding verifications
13. Adding categories
14. Adding configuration
15. Adding ACL
16. Adding an install/uninstall/update script file
17. Using the language filter facility
18. Adding an update server
19. Example of a Frontend Update Function
20. Example of Menu Parameters & Stylesheets

Introduction

This tutorial is part of the Developing a Model-View-Controller (MVC) Component for Joomla!1.6 tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

Adding configuration parameters

The Joomla!1.6 framework allows the use of parameters stored in each component. With your favorite file manager and editor, put a file admin/config.xml file containing these lines:

admin/config.xml

<?xml version="1.0" encoding="utf-8"?>
<config>
	<fieldset
		name="greetings"
		label="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL"
		description="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC"
	>
		<field
			name="show_category"
			type="radio"
			label="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL"
			description="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC"
			default="0"
		>
			<option value="0">JHIDE</option>
			<option value="1">JSHOW</option>
		</field>
	</fieldset>
</config>

This file will be read by the com_config component of the Joola!1.6 core. For the moment, we defined only one parameter: is the category title displayed or not in the frontend?.

the best way to set the parameters is to put a Preferences button in a toolbar.

With your favorite editor, put these lines in admin/views/helloworlds/view.html.php

admin/views/helloworlds/view.html.php

<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
 * HelloWorlds View
 */
class HelloWorldViewHelloWorlds extends JView
{
	/**
	 * HelloWorlds view display method
	 * @return void
	 */
	function display($tpl = null) 
	{
		// Get data from the model
		$items = $this->get('Items');
		$pagination = $this->get('Pagination');

		// Check for errors.
		if (count($errors = $this->get('Errors'))) 
		{
			JError::raiseError(500, implode('<br />', $errors));
			return false;
		}
		// Assign data to the view
		$this->items = $items;
		$this->pagination = $pagination;

		// Set the toolbar
		$this->addToolBar();

		// Display the template
		parent::display($tpl);

		// Set the document
		$this->setDocument();
	}

	/**
	 * Setting the toolbar
	 */
	protected function addToolBar() 
	{
		JToolBarHelper::title(JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLDS'), 'helloworld');
		JToolBarHelper::deleteListX('', 'helloworlds.delete');
		JToolBarHelper::editListX('helloworld.edit');
		JToolBarHelper::addNewX('helloworld.add');
		JToolBarHelper::preferences('com_helloworld');
	}
	/**
	 * Method to set up the document properties
	 *
	 * @return void
	 */
	protected function setDocument() 
	{
		$document = JFactory::getDocument();
		$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION'));
	}
}

Using configuration parameters as default value

We want to define this parameter individually on all HelloWorld data. With your favorite editor, put these lines into the admin/models/forms/helloworld.xml

admin/models/forms/helloworld.xml

<?xml version="1.0" encoding="utf-8"?>
<form
	addrulepath="/administrator/components/com_helloworld/models/rules"
>
	<fieldset name="details">
		<field
			name="id"
			type="hidden"
		/>
		<field
			name="greeting"
			type="text"
			label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
			description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
			size="40"
			class="inputbox validate-greeting"
			validate="greeting"
			required="true"
			default=""
		/>
		<field
			name="catid"
			type="category"
			extension="com_helloworld"
			class="inputbox"
			default=""
			label="COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_LABEL"
			description="COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_DESC"
			required="true"
		>
			<option value="0">JOPTION_SELECT_CATEGORY</option>
		</field>
	</fieldset>
	<fields name="params">
		<fieldset
			name="params"
			label="JGLOBAL_FIELDSET_DISPLAY_OPTIONS"
		>
			<field
				name="show_category"
				type="list"
				label="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL"
				description="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC"
				default=""
			>
				<option value="">JGLOBAL_USE_GLOBAL</option>
				<option value="0">JHIDE</option>
				<option value="1">JSHOW</option>
			</field>
		</fieldset>
	</fields>
</form>

We define the same parameter for each message with an additional value: Use global.

Modifying the SQL

Data now contains a new parameter: params. The SQL structure has to be modified.

With your favorite editor, put these lines into admin/sql/install.mysql.utf8.sql:

admin/sql/install.mysql.utf8.sql

DROP TABLE IF EXISTS `#__helloworld`;
 
CREATE TABLE `#__helloworld` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `greeting` varchar(25) NOT NULL,
  `catid` int(11) NOT NULL DEFAULT '0',
  `params` TEXT NOT NULL DEFAULT '',
   PRIMARY KEY  (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8;
 
INSERT INTO `#__helloworld` (`greeting`) VALUES
        ('Hello World!'),
        ('Good bye World!');

With your favorite editor, put these lines into admin/sql/updates/mysql/0.0.13.sql:

admin/sql/updates/mysql/0.0.13.sql

ALTER TABLE `#__helloworld` ADD `params` VARCHAR(1024) NOT NULL DEFAULT '';

The TableHelloWorld has to be modified in order to deal with these parameters: they will be stored in a JSON format and get in a JParameter class. We have to overload the bind and the load method. With your favorite editor, put these lines into admin/tables/helloworld.php

admin/tables/helloworld.php

<?php
// No direct access
defined('_JEXEC') or die('Restricted access');

// import Joomla table library
jimport('joomla.database.table');

/**
 * Hello Table class
 */
class HelloWorldTableHelloWorld extends JTable
{
	/**
	 * Constructor
	 *
	 * @param object Database connector object
	 */
	function __construct(&$db) 
	{
		parent::__construct('#__helloworld', 'id', $db);
	}
	/**
	 * Overloaded bind function
	 *
	 * @param       array           named array
	 * @return      null|string     null is operation was satisfactory, otherwise returns an error
	 * @see JTable:bind
	 * @since 1.5
	 */
	public function bind($array, $ignore = '') 
	{
		if (isset($array['params']) && is_array($array['params'])) 
		{
			// Convert the params field to a string.
			$parameter = new JRegistry;
			$parameter->loadArray($array['params']);
			$array['params'] = (string)$parameter;
		}
		return parent::bind($array, $ignore);
	}

	/**
	 * Overloaded load function
	 *
	 * @param       int $pk primary key
	 * @param       boolean $reset reset data
	 * @return      boolean
	 * @see JTable:load
	 */
	public function load($pk = null, $reset = true) 
	{
		if (parent::load($pk, $reset)) 
		{
			// Convert the params field to a registry.
			$params = new JRegistry;
			$params->loadJSON($this->params);
			$this->params = $params;
			return true;
		}
		else
		{
			return false;
		}
	}
}

Modifying the backend

The backend edit view has to display the options to the administrator. With your favorite editor, put these lines into the admin/views/helloworld/tmpl/edit.php file:

admin/views/helloworld/tmpl/edit.php

<?php
// No direct access
defined('_JEXEC') or die('Restricted access');
JHtml::_('behavior.tooltip');
JHtml::_('behavior.formvalidation');
$params = $this->form->getFieldsets('params');
?>
<form action="<?php echo JRoute::_('index.php?option=com_helloworld&layout=edit&id='.(int) $this->item->id); ?>" method="post" name="adminForm" id="helloworld-form" class="form-validate">

	<div class="width-60 fltlft">
		<fieldset class="adminform">
			<legend><?php echo JText::_( 'COM_HELLOWORLD_HELLOWORLD_DETAILS' ); ?></legend>
			<ul class="adminformlist">
<?php foreach($this->form->getFieldset('details') as $field): ?>
				<li><?php echo $field->label;echo $field->input;?></li>
<?php endforeach; ?>
			</ul>
	</div>

	<div class="width-40 fltrt">
		<?php echo JHtml::_('sliders.start', 'helloworld-slider'); ?>
<?php foreach ($params as $name => $fieldset): ?>
		<?php echo JHtml::_('sliders.panel', JText::_($fieldset->label), $name.'-params');?>
	<?php if (isset($fieldset->description) && trim($fieldset->description)): ?>
		<p class="tip"><?php echo $this->escape(JText::_($fieldset->description));?></p>
	<?php endif;?>
		<fieldset class="panelform" >
			<ul class="adminformlist">
	<?php foreach ($this->form->getFieldset($name) as $field) : ?>
				<li><?php echo $field->label; ?><?php echo $field->input; ?></li>
	<?php endforeach; ?>
			</ul>
		</fieldset>
<?php endforeach; ?>

		<?php echo JHtml::_('sliders.end'); ?>
	</div>

	<div>
		<input type="hidden" name="task" value="helloworld.edit" />
		<?php echo JHtml::_('form.token'); ?>
	</div>
</form>

Modifying the frontend

The frontend has to be modified according to the new show_category parameter.

We have to modified the model:

• it has to merge global parameters and individual parameters
• it has to provide the category

With your favorite editor, put these lines into the site/models/helloworld.php file:

site/models/helloworld.php

<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
 * HelloWorld Model
 */
class HelloWorldModelHelloWorld extends JModelItem
{
	/**
	 * @var object item
	 */
	protected $item;

	/**
	 * Method to auto-populate the model state.
	 *
	 * This method should only be called once per instantiation and is designed
	 * to be called on the first call to the getState() method unless the model
	 * configuration flag to ignore the request is set.
	 *
	 * Note. Calling getState in this method will result in recursion.
	 *
	 * @return	void
	 * @since	1.6
	 */
	protected function populateState() 
	{
		$app = JFactory::getApplication();
		// Get the message id
		$id = JRequest::getInt('id');
		$this->setState('message.id', $id);

		// Load the parameters.
		$params = $app->getParams();
		$this->setState('params', $params);
		parent::populateState();
	}

	/**
	 * Returns a reference to the a Table object, always creating it.
	 *
	 * @param	type	The table type to instantiate
	 * @param	string	A prefix for the table class name. Optional.
	 * @param	array	Configuration array for model. Optional.
	 * @return	JTable	A database object
	 * @since	1.6
	 */
	public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array()) 
	{
		return JTable::getInstance($type, $prefix, $config);
	}

	/**
	 * Get the message
	 * @return object The message to be displayed to the user
	 */
	public function getItem() 
	{
		if (!isset($this->item)) 
		{
			$id = $this->getState('message.id');
			$this->_db->setQuery($this->_db->getQuery(true)
				->from('#__helloworld as h')
				->leftJoin('#__categories as c ON h.catid=c.id')
				->select('h.greeting, h.params, c.title as category')
				->where('h.id=' . (int)$id));
			if (!$this->item = $this->_db->loadObject()) 
			{
				$this->setError($this->_db->getError());
			}
			else
			{
				// Load the JSON string
				$params = new JRegistry;
				$params->loadJSON($this->item->params);
				$this->item->params = $params;

				// Merge global params with item params
				$params = clone $this->getState('params');
				$params->merge($this->item->params);
				$this->item->params = $params;
			}
		}
		return $this->item;
	}
}

The view has to ask the model for the category. With your favorite editor, put these lines into the site/views/helloworld/view.html.php

site/views/helloworld/view.html.php

<?php
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
 * HTML View class for the HelloWorld Component
 */
class HelloWorldViewHelloWorld extends JView
{
	// Overwriting JView display method
	function display($tpl = null) 
	{
		// Assign data to the view
		$this->item = $this->get('Item');

		// Check for errors.
		if (count($errors = $this->get('Errors'))) 
		{
			JError::raiseError(500, implode('<br />', $errors));
			return false;
		}
		// Display the view
		parent::display($tpl);
	}
}

The layout can now display correctly the category or not. With your favorite editor, put these lines into site/views/helloworld/tmpl/default.php

site/views/helloworld/tmpl/default.php

<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');
?>
<h1><?php echo $this->item->greeting.(($this->item->category and $this->item->params->get('show_category')) ? (' ('.$this->item->category.')') : ''); ?></h1>

Adding some translation strings

Some strings have to be added in the admin/language/en-GB/en-GB.com_helloworld.ini file

admin/language/en-GB/en-GB.com_helloworld.ini

COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_ADMINISTRATION="HelloWorld - Administration"
COM_HELLOWORLD_ADMINISTRATION_CATEGORIES="HelloWorld - Categories"
COM_HELLOWORLD_HELLOWORLD_CREATING="HelloWorld - Creating"
COM_HELLOWORLD_HELLOWORLD_DETAILS="Details"
COM_HELLOWORLD_HELLOWORLD_EDITING="HelloWorld - Editing"
COM_HELLOWORLD_HELLOWORLD_ERROR_UNACCEPTABLE="Some values are unacceptable"
COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_DESC="The category the messages belongs to"
COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_LABEL="Category"
COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC="This message will be displayed"
COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL="Message"
COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL="Show category"
COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC="If set to Show, the title of the message’s category will show."
COM_HELLOWORLD_HELLOWORLD_HEADING_GREETING="Greeting"
COM_HELLOWORLD_HELLOWORLD_HEADING_ID="Id"
COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT="HelloWorld manager: Edit Message"
COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW="HelloWorld manager: New Message"
COM_HELLOWORLD_MANAGER_HELLOWORLDS="HelloWorld manager"
COM_HELLOWORLD_N_ITEMS_DELETED_1="One message deleted"
COM_HELLOWORLD_N_ITEMS_DELETED_MORE="%d messages deleted"
COM_HELLOWORLD_SUBMENU_MESSAGES="Messages"
COM_HELLOWORLD_SUBMENU_CATEGORIES="Categories"
COM_HELLOWORLD_CONFIGURATION="HelloWorld Configuration"
COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL="Messages settings"
COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC="Settings that will be applied to all messages by default"

Packaging the component

Content of your code directory

• helloworld.xml
• site/index.html
• site/helloworld.php
• site/controller.php
• site/views/index.html
• site/views/helloworld/index.html
• site/views/helloworld/view.html.php
• site/views/helloworld/tmpl/index.html
• site/views/helloworld/tmpl/default.xml
• site/views/helloworld/tmpl/default.php
• site/models/index.html
• site/models/helloworld.php
• site/language/index.html
• site/language/en-GB/index.html
• site/language/en-GB/en-GB.com_helloworld.ini
• admin/index.html
• admin/config.xml
• admin/helloworld.php
• admin/controller.php
• admin/sql/index.html
• admin/sql/install.mysql.utf8.sql
• admin/sql/uninstall.mysql.utf8.sql
• admin/sql/update.mysql.utf8.sql
• admin/models/index.html
• admin/models/fields/index.html
• admin/models/fields/helloworld.php
• admin/models/forms/index.html
• admin/models/forms/helloworld.xml
• admin/models/forms/helloworld.js
• admin/models/rules/index.html
• admin/models/rules/greeting.php
• admin/models/helloworld.php
• admin/models/helloworldlist.php
• admin/views/index.html
• admin/views/helloworldlist/index.html
• admin/views/helloworldlist/view.html.php
• admin/views/helloworldlist/tmpl/index.html
• admin/views/helloworldlist/tmpl/default.php
• admin/views/helloworldlist/tmpl/default_head.php
• admin/views/helloworldlist/tmpl/default_body.php
• admin/views/helloworldlist/tmpl/default_foot.php
• admin/views/helloworldlist/index.html
• admin/views/helloworld/view.html.php
• admin/views/helloworld/submitbutton.js
• admin/views/helloworld/tmpl/index.html
• admin/views/helloworld/tmpl/edit.php
• admin/tables/index.html
• admin/tables/helloworld.php
• admin/language/en-GB/en-GB.com_helloworld.ini
• admin/language/en-GB/en-GB.com_helloworld.menu.ini
• admin/controllers/index.html
• admin/controllers/helloworld.php
• admin/controllers/helloworldlist.php
• language/en-GB/en-GB.ini
• media/index.html
• media/images/index.html
• media/images/tux-16x16.png
• media/images/tux-48x48.png

Create a compressed file of this directory or directly download the archive and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

helloworld.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">
	<name>Hello World!</name>
	<creationDate>November 2009</creationDate>
	<author>John Doe</author>
	<authorEmail>john.doe@example.org</authorEmail>
	<authorUrl>http://www.example.org</authorUrl>
	<copyright>Copyright Info</copyright>
	<license>License Info</license>
	<version>0.0.13</version>
	<description>com_helloworld_Description</description>

	<install> <!-- Runs on install -->
		<sql>
			<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
		</sql>
	</install>
	<uninstall> <!-- Runs on uninstall -->
		<sql>
			<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
		</sql>
	</uninstall>
	<update> <!-- Runs on update -->
		<sql>
			<file driver="mysql" charset="utf8">sql/update.mysql.utf8.sql</file>
		</sql>
	</update>

	<files folder="site">
		<filename>index.html</filename>
		<filename>helloworld.php</filename>
		<filename>controller.php</filename>
		<folder>views</folder>
		<folder>models</folder>
		<folder>language</folder>
	</files>

	<media destination="com_helloworld" folder="media">
		<filename>index.html</filename>
		<folder>images</folder>
	</media>
	
	<administration>
		<menu img="../media/com_helloworld/images/tux-16x16.png">Hello World!</menu>
		<files folder="admin">
			<filename>index.html</filename>
			<filename>config.xml</filename>
			<filename>helloworld.php</filename>
			<filename>controller.php</filename>
			<folder>sql</folder>
			<folder>tables</folder>
			<folder>models</folder>
			<folder>views</folder>
			<folder>controllers</folder>
			<folder>helpers</folder>
		</files>		
		<languages folder="admin">
			<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
			<language tag="en-GB">language/en-GB/en-GB.com_helloworld.menu.ini</language>
		</languages>
	</administration>
</extension>

Contributors

• Christophe Demko