Actions

J2.5

Developing a MVC Component/Adding configuration

From Joomla! Documentation

< J2.5:Developing a MVC Component
Revision as of 13:12, 27 November 2010 by Cdemko (Talk | contribs)

Documentation all together tranparent small.png
Under Construction

This article or section is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well. If this article or section has not been edited in several days, please remove this template.
This article was last edited by Cdemko (talk| contribs) 3 years ago. (Purge)

Template:Future

Articles in this series


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

# Joomla16.Tutorials
# Copyright (C) 2005 - 2009 Open Source Matters. All rights reserved.
# License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM
 
COM_HELLOWORLD_ADMINISTRATION=HelloWorld administration
COM_HELLOWORLD_CATEGORIES=Categories
COM_HELLOWORLD_MANAGER=HelloWorld manager
COM_HELLOWORLD_MESSAGES=Messages
COM_HELLOWORLD_HELLOWORLD_CATEGORY=Category
COM_HELLOWORLD_HELLOWORLD_CATEGORY_DESC=Category of the message
COM_HELLOWORLD_HELLOWORLD_CREATING=Creating
COM_HELLOWORLD_HELLOWORLD_DETAILS=Details
COM_HELLOWORLD_HELLOWORLD_OPTIONS=Options
COM_HELLOWORLD_HELLOWORLD_EDITING=Editing
COM_HELLOWORLD_HELLOWORLD_ERROR_SOME_VALUES_ARE_UNACCEPTABLE=Some values are unacceptable
COM_HELLOWORLD_HELLOWORLD_GREETING_DESC=Message to be displayed
COM_HELLOWORLD_HELLOWORLD_GREETING=Greeting
COM_HELLOWORLD_HELLOWORLDLIST_ARE_YOU_SURE_YOU_WANT_TO_DELETE_THESE_GREETINGS=Are you sure you want to delete these greetings?
COM_HELLOWORLD_HELLOWORLDLIST_GREETING=Greeting
COM_HELLOWORLD_HELLOWORLDLIST_GREETINGS_REMOVED=Greetings removed
COM_HELLOWORLD_HELLOWORLDLIST_ID=Id
COM_HELLOWORLD_HELLOWORLDLIST_ONE_OR_MORE_GREETINGS_COULD_NOT_BE_DELETED=One or more greetings could not be deleted: %s
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_MSG_DESC=This message will be displayed
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_MSG_LABEL=Message
 
COM_HELLOWORLD_CONFIGURATION=Configuration
COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL=Greeting settings
COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC=Greetings settings description
COM_HELLOWORLD_PARAMS_SHOW_CATEGORY_LABEL=Show category
COM_HELLOWORLD_PARAMS_SHOW_CATEGORY_DESC=Display the category after the message

Packaging the component

Content of your code directory

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