Actions

J2.5

Difference between revisions of "Developing a MVC Component/Adding configuration"

From Joomla! Documentation

< J2.5:Developing a MVC Component
Line 1: Line 1:
{{underconstruction}}
+
This tutorial is for {{JVer|1.6}}
{{future|1.6}}
+
  
 
== Articles in this series ==
 
== Articles in this series ==

Revision as of 08:58, 16 January 2011

This tutorial is for Joomla 1.6

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

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&rsquo;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

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>COM_HELLOWORLD</name>
        <!-- The following elements are optional and free of formatting conttraints -->
        <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>
        <!--  The version string is recorded in the components table -->
        <version>0.0.13</version>
        <!-- The description is optional and defaults to the name -->
        <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; New in 1.6 -->
                <schemas>
                        <schemapath type="mysql">sql/updates/mysql</schemapath>
                </schemas>
        </update>
 
        <!-- Site Main File Copy Section -->
        <!-- 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>
        </media>
 
        <administration>
                <!-- Administration Menu Section -->
                <menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>
                <!-- Administration Main File Copy Section -->
                <!-- 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">
                        <!-- Admin Main File Copy Section -->
                        <filename>index.html</filename>
                        <filename>config.xml</filename>
                        <filename>helloworld.php</filename>
                        <filename>controller.php</filename>
                        <!-- SQL files section -->
                        <folder>sql</folder>
                        <!-- tables files section -->
                        <folder>tables</folder>
                        <!-- models files section -->
                        <folder>models</folder>
                        <!-- views files section -->
                        <folder>views</folder>
                        <!-- controllers files section -->
                        <folder>controllers</folder>
                        <!-- helpers files section -->
                        <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.sys.ini</language>
                </languages>
        </administration>
 
</extension>

Navigate

Prev: Adding categories Next: Adding ACL

Contributors