Rvsjoen/tutorial/Developing an MVC Component/Part 13
From Joomla! Documentation
< User:Rvsjoen | tutorial/Developing an MVC Component
Adding component options[edit]
If we want our component to be configurable, then we have to go ahead and add some options, we can add options on several levels. Menu items may have options, the component may have options or the individual items (greetings in our case) may have their own set of options. In this part we will cover how to implement global component options, and how to be able to override them with item-specific options for more granularity. Options are also knows as parameters.
Adding the configuration XML[edit]
With your favorite editor, create the following file
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>
Adding parameters to the database[edit]
While the previous XML configuration file pretty much takes care of the "global" component options, in order to support a bit more granularity and use the parameters in Joomla! on a per-item basis we need to add a field to our table in the database.
With your favorite editor, modify the following file to look like this
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!');
NOTE: You WILL need to completely uninstall and reinstall the component for these changes to take effect if you have any of the previous parts installed.
Update the form definition[edit]
We are going to have to modify our helloworld form in order to add a fieldset for the parameters so they can be edited by the user when editing the items.
With your favorite editor, modify the following file to look like this
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>
Updating the toolbar[edit]
With your favorite editor, modify the following files to look like this
admin/views/helloworld/view.html.php
// No direct access to this file
defined('_JEXEC') or die;
jimport('joomla.application.component.view');
class HelloWorldViewHelloWorlds extends JView
{
function display($tpl = null)
{
// Get data from the model
$items = $this->get('Items');
$pagination = $this->get('Pagination');
// 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();
}
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');
}
protected function setDocument()
{
$document = JFactory::getDocument();
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION'));
}
}
Updating the frontend view[edit]
With your favorite editor, modify the following files to look like this
site/views/helloworld/tmpl/default.php
// No direct access to this file
defined('_JEXEC') or die;
?>
<h1>
<?php echo $this->item->greeting; ?>
<?php if($this->item->category && $this->item->params->get('show_category')): ?>
<?php echo ' ('.$this->item->category.') '; ?>
<?php endif; ?>
</h1>
Updating the table to support parameters[edit]
admin/tables/helloworld.php
// No direct access to this file
defined('_JEXEC') or die;
jimport('joomla.database.table');
class HelloWorldTableHelloWorld extends JTable
{
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
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);
}
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;
}
}
}
Updating the model to support parameters[edit]
Update the language files[edit]
With your favorite editor, modify the following files to look like this
admin/language/en-GB/en-GB.com_helloworld.ini
COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC="This message will be displayed"
COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL="Message"
COM_HELLOWORLD_HELLOWORLD_HEADING_GREETING="Greeting"
COM_HELLOWORLD_HELLOWORLD_HEADING_ID="ID"
COM_HELLOWORLD_HELLOWORLD_DETAILS="Details"
COM_HELLOWORLD_MANAGER_HELLOWORLDS="HelloWorld manager"
COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW="HelloWorld manager: New Message"
COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT="HelloWorld manager: Edit Message"
COM_HELLOWORLD_N_ITEMS_DELETED_1="One message deleted"
COM_HELLOWORLD_N_ITEMS_DELETED_MORE="%d messages deleted"
COM_HELLOWORLD_ADMINISTRATION="HelloWorld - Administration"
COM_HELLOWORLD_HELLOWORLD_CREATING="HelloWorld - Creating"
COM_HELLOWORLD_HELLOWORLD_EDITING="HelloWorld - Editing"
COM_HELLOWORLD_SUBMENU_MESSAGES="Messages"
COM_HELLOWORLD_SUBMENU_CATEGORIES="Categories"
COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_DESC="The category the messages belongs to"
COM_HELLOWORLD_HELLOWORLD_FIELD_CATID_LABEL="Category"
COM_HELLOWORLD_ADMINISTRATION_CATEGORIES="HelloWorld - 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"
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."
Installation manifest[edit]
In the installation manifest, we have updated the version number and added config.xml
helloworld.xml
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">
<name>COM_HELLOWORLD</name>
<!-- The following elements are optional and free of formatting constraints -->
<creationDate>June 2011</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>
<!-- The version string is stored in the components table -->
<version>0.0.13</version>
<!-- The description is optional and defaults to the name -->
<description>COM_HELLOWORLD_DESCRIPTION</description>
<install>
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<!-- Note the folder attribute: This attribute describes the folder
to copy FROM in the package to install therefore files copied
in this section are copied from "site/" in the package -->
<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>
<folder>js</folder>
</media>
<administration>
<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>
<submenu>
<menu view="helloworlds">COM_HELLOWORLD_SUBMENU_MESSAGES</menu>
<menu link="option=com_categories&view=categories&extension=com_helloworld">COM_HELLOWORLD_SUBMENU_CATEGORIES</menu>
</submenu>
<!-- Note the folder attribute: This attribute describes the folder
to copy FROM in the package to install therefore files copied
in this section are copied from "admin/" in the package -->
<files folder="admin">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>config.xml</filename>
<folder>sql</folder>
<folder>tables</folder>
<folder>models</folder>
<folder>views</folder>
<folder>language</folder>
<folder>controllers</folder>
<folder>helpers</folder>
</files>
</administration>
</extension>
Testing your component[edit]
For details on how to install the component into your Joomla! site, refer to the information provided in Part 01.
File listing[edit]
- 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.php
- site/views/helloworld/tmpl/default.xml
- 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/helloworld.php
- admin/controller.php
- admin/config.xml
- admin/helpers/index.html
- admin/helpers/helloworld.php
- admin/controllers/index.html
- admin/controllers/helloworld.php
- admin/controllers/helloworlds.php
- admin/models/index.html
- admin/models/helloworld.php
- admin/models/helloworlds.php
- admin/models/fields/index.html
- admin/models/fields/helloworld.php
- admin/models/forms/index.html
- admin/models/forms/helloworld.xml
- admin/models/rules/index.html
- admin/models/rules/greeting.php
- admin/models/helloworld.php
- admin/views/index.html
- admin/views/helloworld/index.html
- admin/views/helloworld/view.html.php
- admin/views/helloworld/tmpl/index.html
- admin/views/helloworld/tmpl/edit.php
- admin/views/helloworlds/index.html
- admin/views/helloworlds/view.html.php
- admin/views/helloworlds/tmpl/index.html
- admin/views/helloworlds/tmpl/default.php
- admin/views/helloworlds/tmpl/default_head.php
- admin/views/helloworlds/tmpl/default_body.php
- admin/views/helloworlds/tmpl/default_foot.php
- admin/tables/index.html
- admin/tables/helloworld.php
- admin/sql/index.html
- admin/sql/install.mysql.utf8.sql
- admin/sql/uninstall.mysql.utf8.sql
- admin/language/index.html
- admin/language/en-GB/index.html
- admin/language/en-GB/en-GB.com_helloworld.ini
- admin/language/en-GB/en-GB.com_helloworld.sys.ini
- media/index.html
- media/images/index.html
- media/images/tux-16x16.png
- media/images/tux-48x48.png
- media/js/index.html
- media/js/helloworld.js
Download this part[edit]
Articles in this series[edit]
This tutorial is supported by the following versions of Joomla!
- Introduction
- Part 01 - Developing a Basic Component
- Part 02 - Adding a view to the frontend
- Part 03 - Adding a menu item type to the frontend
- Part 04 - Adding a model to the frontend
- Part 05 - Adding options to menu items
- Part 06 - Using a database
- Part 07 - Basic backend
- Part 08 - Adding language translation
- Part 09 - Adding actions to backend
- Part 10 - Adding decorations to the backend
- Part 11 - Adding validation
- Part 12 - Adding categories
- Part 13 - Adding component options
- Part 14 - Adding ACL
- Part 15 - Adding a script file