Actions

User

Rvsjoen/tutorial/Developing an MVC Component/Part 12

From Joomla! Documentation

< User:Rvsjoen‎ | tutorial/Developing an MVC Component

Contents

Adding categories

So we want to add the possibility of arranging greetings and putting them into categories, the Joomla! category manager has this functionality readily available for us, all we have to do is use it. The first order of business is to create a submenu in the backend since our greetings and the categories will be managed in different views. We use the helper to build the submenu.

Creating a helper

First of all, we need to create a helper that will help us create the submenu.

With your favorite editor, create the following file

admin/helpers/helloworld.php

// No direct access to this file
defined('_JEXEC') or die;
 
class HelloWorldHelper
{
        public static function addSubmenu($submenu) 
        {
                JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_MESSAGES'), 
                        'index.php?option=com_helloworld', $submenu == 'messages');
                JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_CATEGORIES'), 
                        'index.php?option=com_categories&view=categories&extension=com_helloworld', $submenu == 'categories');
                $document = JFactory::getDocument();
                if ($submenu == 'categories'){ 
                        $document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION_CATEGORIES'));
                }
        }
}

After creating the helper, we also need to modify our entry point to load it

With your favorite editor, modify the following file to look like this

admin/helloworld.php

// No direct access to this file
defined('_JEXEC') or die;
 
jimport('joomla.application.component.controller');
 
// Set some global property
$document = JFactory::getDocument();
$document->addStyleDeclaration('.icon-48-helloworld {background-image: url(../media/com_helloworld/images/tux-48x48.png);}');
 
// Require helper file
JLoader::register('HelloWorldHelper', dirname(__FILE__) . DS . 'helpers' . DS . 'helloworld.php'); 
// Get an instance of the controller prefixed by HelloWorld
$controller = JController::getInstance('HelloWorld');
 
// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
 
// Redirect if set by the controller
$controller->redirect();

Updating the controller

With your favorite editor, modify the following file to look like this

admin/controller.php

// No direct access to this file
defined('_JEXEC') or die;
 
jimport('joomla.application.component.controller');
 
class HelloWorldController extends JController
{
        function display($cachable = false) 
        {
                // Set default view if not set
                JRequest::setVar('view', JRequest::getCmd('view', 'HelloWorlds'));
 
                parent::display($cachable);
 
                // Add submenu
                HelloWorldHelper::addSubmenu('messages');        }
}

After we have added the helper, and told the entry point to load it, our controller can used it in the display() function to add the submenu to the backend.

Adding categories to the database

In order to use the builtin categories in Joomla! 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',   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

We are going to have to modify our helloworld form in order to add a field for selecting a category for each greeting.

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>
                <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>

As you can see, we have added the field catid to the form definition and set it to type categories. With the use of the extension parameter, the category manager will automatically figure out which categories belongs to the com_helloworld component and display only those.

Update the form field

We also need to update the form field which is used to select a greeting to show when you create a new menu item, we would very much like it to show which category the greetings belong to.

With your favorite editor, modify the following files to look like this

admin/models/fields/helloworld.php

<?php
// No direct access to this file
defined('_JEXEC') or die;
 
jimport('joomla.form.helper');
 
JFormHelper::loadFieldClass('list');
 
class JFormFieldHelloWorld extends JFormFieldList
{
        protected $type = 'HelloWorld';
 
        protected function getOptions() 
        {
                $db = JFactory::getDBO();
                $query = $db->getQuery(true);
                $query->select('a.id as id, a.greeting as greeting, b.title as category, b.id as catid');
                $query->from('#__helloworld a');
                $query->leftJoin('#__categories b on a.catid=b.id');
                $db->setQuery((string)$query);
                $messages = $db->loadObjectList();
                $options = array();
                if($messages){
                        foreach($messages as $message){
                                $options[] = JHtml::_('select.option', $message->id, 
                                        $message->greeting . ($message->catid ? ' (' . $message->category . ')' : ''));
                        }
                }
                $options = array_merge(parent::getOptions(), $options);
                return $options;
        }
}

Update the language files

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"

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

COM_HELLOWORLD="Hello World"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_MENU="Hello World"
COM_HELLOWORLD_SUBMENU_MESSAGES="Messages"
COM_HELLOWORLD_SUBMENU_CATEGORIES="Categories"

Installation manifest

In the installation manifest, we have updated the version number, added the helpers folder to the administrator files copy section, and also added a submenu.

helloworld.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.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.12</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&amp;view=categories&amp;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>
                        <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

For details on how to install the component into your Joomla! site, refer to the information provided in Part 01.

You should have a shiny new submenu in the Components menu of the backend, where one menu item is the Categories view, you will be able to assign create/modify/delete categories and assign hello messages to categories.

File listing

Download this part

Download example package

Articles in this series

This tutorial is supported by the following versions of Joomla!

Joomla 2.5