J3.x:Developing an MVC Component/Adding backend actions

Joomla! 

3.x

Tutorial

Developing an MVC Component

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. Adding a Frontend Form
18. Adding an Image
19. Adding a Map
20. Adding AJAX
21. Adding an Alias
22. Using the Language Filter Facility
23. Adding a Modal
24. Adding Associations
25. Adding Checkout
26. Adding Ordering
27. Adding Levels
28. Adding Versioning
29. Adding Tags
30. Adding Access
31. Adding a Batch Process
32. Adding Cache
33. Adding a Feed
34. Adding an Update Server
35. Adding Custom Fields
36. Upgrading to Joomla4

This is a multiple-article series of tutorials on how to develop a Model-View-Controller Component for Joomla! Version.

Begin with the Introduction, and navigate the articles in this series by using the navigation button at the bottom or the box to the right (the Articles in this series).

Introduction

This tutorial is part of the Developing an MVC Component for Joomla! 3.2 tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

There is a series of five videos associated with this step in the tutorial, covering (1) Changes to the Helloworlds view and layout, (2) Handling Deletes, and then three on the functionality required to support New and Edit: (3) Handling New/Edit Redirect, (4) Display the Helloworld message editing form and (5) Handling Save and Cancel.

In conjunction with this step, you will probably find it useful to read this description of Joomla's implementation of MVC

Adding a Toolbar

In Joomla, the Administrator interacts generally with components through the use of a toolbar. In the file admin/views/helloworlds/view.html.php put this content. It will create a basic toolbar and a title for the component.

The arguments used in, for example, JToolbarHelper::addNew is used to set a controller instance which will be used after button is clicked. Further details below in the adding specific controllers section.

admin/views/helloworlds/view.html.php

<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

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

/**
 * HelloWorlds View
 *
 * @since  0.0.1
 */
class HelloWorldViewHelloWorlds extends JViewLegacy
{
	/**
	 * Display the Hello World view
	 *
	 * @param   string  $tpl  The name of the template file to parse; automatically searches through the template paths.
	 *
	 * @return  void
	 */
	function display($tpl = null)
	{
		// Get data from the model
		$this->items		= $this->get('Items');
		$this->pagination	= $this->get('Pagination');

		// Check for errors.
		if (count($errors = $this->get('Errors')))
		{
			JError::raiseError(500, implode('<br />', $errors));

			return false;
		}

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

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

	/**
	 * Add the page title and toolbar.
	 *
	 * @return  void
	 *
	 * @since   1.6
	 */
	protected function addToolBar()
	{
		JToolbarHelper::title(JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLDS'));
		JToolbarHelper::addNew('helloworld.add');
		JToolbarHelper::editList('helloworld.edit');
		JToolbarHelper::deleteList('', 'helloworlds.delete');
	}
}

You can find other classic backend actions in the administrator/includes/toolbar.php file of your Joomla installation.

Since the view can perform some actions, we have to add some input data. With your favourite file manager and editor, put in the file admin/views/helloworlds/tmpl/default.php

admin/views/helloworlds/tmpl/default.php

<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

// No direct access to this file
defined('_JEXEC') or die('Restricted Access');
?>
<form action="index.php?option=com_helloworld&view=helloworlds" method="post" id="adminForm" name="adminForm">
	<table class="table table-striped table-hover">
		<thead>
		<tr>
			<th width="1%"><?php echo JText::_('COM_HELLOWORLD_NUM'); ?></th>
			<th width="2%">
				<?php echo JHtml::_('grid.checkall'); ?>
			</th>
			<th width="90%">
				<?php echo JText::_('COM_HELLOWORLD_HELLOWORLDS_NAME') ;?>
			</th>
			<th width="5%">
				<?php echo JText::_('COM_HELLOWORLD_PUBLISHED'); ?>
			</th>
			<th width="2%">
				<?php echo JText::_('COM_HELLOWORLD_ID'); ?>
			</th>
		</tr>
		</thead>
		<tfoot>
			<tr>
				<td colspan="5">
					<?php echo $this->pagination->getListFooter(); ?>
				</td>
			</tr>
		</tfoot>
		<tbody>
			<?php if (!empty($this->items)) : ?>
				<?php foreach ($this->items as $i => $row) :
					$link = JRoute::_('index.php?option=com_helloworld&task=helloworld.edit&id=' . $row->id);
				?>
					<tr>
						<td><?php echo $this->pagination->getRowOffset($i); ?></td>
						<td>
							<?php echo JHtml::_('grid.id', $i, $row->id); ?>
						</td>
						<td>
							<a href="<?php echo $link; ?>" title="<?php echo JText::_('COM_HELLOWORLD_EDIT_HELLOWORLD'); ?>">
								<?php echo $row->greeting; ?>
							</a>
						</td>
						<td align="center">
							<?php echo JHtml::_('jgrid.published', $row->published, $i, 'helloworlds.', true, 'cb'); ?>
						</td>
						<td align="center">
							<?php echo $row->id; ?>
						</td>
					</tr>
				<?php endforeach; ?>
			<?php endif; ?>
		</tbody>
	</table>
	<input type="hidden" name="task" value=""/>
	<input type="hidden" name="boxchecked" value="0"/>
	<?php echo JHtml::_('form.token'); ?>
</form>

The underscore function of JRoute is used so that the site displays SEF URLs. See Supporting SEF URLs in your component.

The task field is used to define the controller.task parameter which will be sent to the server in the POST request when the form is submitted.

The boxchecked field is used to keep track of the number of checkboxes ticked.

Using the form token helps prevent CSRF attacks.

Adding Specific Controllers

Three actions have been added:

• helloworlds.delete
• helloworld.edit
• helloworld.add

These are compound tasks (controller.task). So two new controllers HelloWorldControllerHelloWorlds and HelloWorldControllerHelloWorld have to be coded. (To understand the difference between the two types of subcontrollers read more in this article: subcontrollers...).

admin/controllers/helloworlds.php

<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

/**
 * HelloWorlds Controller
 *
 * @since  0.0.1
 */
class HelloWorldControllerHelloWorlds extends JControllerAdmin
{
	/**
	 * Proxy for getModel.
	 *
	 * @param   string  $name    The model name. Optional.
	 * @param   string  $prefix  The class prefix. Optional.
	 * @param   array   $config  Configuration array for model. Optional.
	 *
	 * @return  object  The model.
	 *
	 * @since   1.6
	 */
	public function getModel($name = 'HelloWorld', $prefix = 'HelloWorldModel', $config = array('ignore_request' => true))
	{
		$model = parent::getModel($name, $prefix, $config);

		return $model;
	}
}

admin/controllers/helloworld.php

<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

/**
 * HelloWorld Controller
 *
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 * @since       0.0.9
 */
class HelloWorldControllerHelloWorld extends JControllerForm
{
}

Adding an Editing View

With your favourite file manager and editor, put a file admin/views/helloworld/view.html.php containing:

admin/views/helloworld/view.html.php

<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

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

/**
 * HelloWorld View
 *
 * @since  0.0.1
 */
class HelloWorldViewHelloWorld extends JViewLegacy
{
	/**
	 * View form
	 *
	 * @var         form
	 */
	protected $form = null;

	/**
	 * Display the Hello World view
	 *
	 * @param   string  $tpl  The name of the template file to parse; automatically searches through the template paths.
	 *
	 * @return  void
	 */
	public function display($tpl = null)
	{
		// Get the Data
		$this->form = $this->get('Form');
		$this->item = $this->get('Item');

		// Check for errors.
		if (count($errors = $this->get('Errors')))
		{
			JError::raiseError(500, implode('<br />', $errors));

			return false;
		}


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

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

	/**
	 * Add the page title and toolbar.
	 *
	 * @return  void
	 *
	 * @since   1.6
	 */
	protected function addToolBar()
	{
		$input = JFactory::getApplication()->input;

		// Hide Joomla Administrator Main menu
		$input->set('hidemainmenu', true);

		$isNew = ($this->item->id == 0);

		if ($isNew)
		{
			$title = JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW');
		}
		else
		{
			$title = JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT');
		}

		JToolbarHelper::title($title, 'helloworld');
		JToolbarHelper::save('helloworld.save');
		JToolbarHelper::cancel(
			'helloworld.cancel',
			$isNew ? 'JTOOLBAR_CANCEL' : 'JTOOLBAR_CLOSE'
		);
	}
}

This view will display data using a layout.

Put a file admin/views/helloworld/tmpl/edit.php containing:

admin/views/helloworld/tmpl/edit.php

<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

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

?>
<form action="<?php echo JRoute::_('index.php?option=com_helloworld&layout=edit&id=' . (int) $this->item->id); ?>"
    method="post" name="adminForm" id="adminForm">
    <div class="form-horizontal">
        <fieldset class="adminform">
            <legend><?php echo JText::_('COM_HELLOWORLD_HELLOWORLD_DETAILS'); ?></legend>
            <div class="row-fluid">
                <div class="span6">
                    <?php
                        foreach($this->form->getFieldset() as $field) {
                            echo $field->renderField();
                        }
                    ?>
                </div>
            </div>
        </fieldset>
    </div>
    <input type="hidden" name="task" value="helloworld.edit" />
    <?php echo JHtml::_('form.token'); ?>
</form>

Adding a Model and Modifying the Existing One

The HelloWorldViewHelloWorld view asks form and data from a model. This model has to provide a getTable, a getForm method and a loadData method (called from the JModelAdmin controller).

admin/models/helloworld.php

<?php
/**
 * @package     Joomla.Administrator
 * @subpackage  com_helloworld
 *
 * @copyright   Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

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

/**
 * HelloWorld Model
 *
 * @since  0.0.1
 */
class HelloWorldModelHelloWorld extends JModelAdmin
{
	/**
	 * Method to get a table object, load it if necessary.
	 *
	 * @param   string  $type    The table name. Optional.
	 * @param   string  $prefix  The class prefix. Optional.
	 * @param   array   $config  Configuration array for model. Optional.
	 *
	 * @return  JTable  A JTable object
	 *
	 * @since   1.6
	 */
	public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
	{
		return JTable::getInstance($type, $prefix, $config);
	}

	/**
	 * Method to get the record form.
	 *
	 * @param   array    $data      Data for the form.
	 * @param   boolean  $loadData  True if the form is to load its own data (default case), false if not.
	 *
	 * @return  mixed    A JForm object on success, false on failure
	 *
	 * @since   1.6
	 */
	public function getForm($data = array(), $loadData = true)
	{
		// Get the form.
		$form = $this->loadForm(
			'com_helloworld.helloworld',
			'helloworld',
			array(
				'control' => 'jform',
				'load_data' => $loadData
			)
		);

		if (empty($form))
		{
			return false;
		}

		return $form;
	}

	/**
	 * Method to get the data that should be injected in the form.
	 *
	 * @return  mixed  The data for the form.
	 *
	 * @since   1.6
	 */
	protected function loadFormData()
	{
		// Check the session for previously entered form data.
		$data = JFactory::getApplication()->getUserState(
			'com_helloworld.edit.helloworld.data',
			array()
		);

		if (empty($data))
		{
			$data = $this->getItem();
		}

		return $data;
	}
}

This model inherits from the JModelAdmin class and uses its loadForm method. This method searches for forms in the forms folder. With your favourite file manager and editor, put a file admin/models/forms/helloworld.xml containing:

admin/models/forms/helloworld.xml

<?xml version="1.0" encoding="utf-8"?>
<form>
	<fieldset>
		<field
				name="id"
				type="hidden"
				/>
		<field
				name="greeting"
				type="text"
				label="COM_HELLOWORLD_HELLOWORLD_GREETING_LABEL"
				description="COM_HELLOWORLD_HELLOWORLD_GREETING_DESC"
				size="40"
				class="inputbox"
				default=""
				/>
	</fieldset>
</form>

Note: COM_HELLOWORLD_HELLOWORLD_GREETING_LABEL and COM_HELLOWORLD_HELLOWORLD_GREETING_DESC are aliases for COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL and COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC respectively.

Here we are using different label and description to convey two different meanings in two different sections, but they can be easily kept equal.

Packaging the Component

Content of your code directory

• helloworld.xml
• site/helloworld.php
• site/index.html
• 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/helloworld.php
• admin/controller.php
• admin/sql/index.html
• admin/sql/install.mysql.utf8.sql
• admin/sql/uninstall.mysql.utf8.sql
• admin/sql/updates/index.html
• admin/sql/updates/mysql/index.html
• admin/sql/updates/mysql/0.0.1.sql
• admin/sql/updates/mysql/0.0.6.sql
• admin/models/index.html
• admin/models/fields/index.html
• admin/models/fields/helloworld.php
• admin/models/helloworlds.php
• admin/models/helloworld.php
• admin/models/forms/index.html
• admin/models/forms/helloworld.xml
• admin/controllers/helloworld.php
• admin/controllers/helloworlds.php
• admin/controllers/index.html
• admin/views/index.html
• admin/views/helloworld/index.html
• admin/views/helloworld/view.html.php
• admin/views/helloworld/tmpl/edit.php
• admin/views/helloworld/tmpl/index.html
• admin/views/helloworlds/index.html
• admin/views/helloworlds/view.html.php
• admin/views/helloworlds/tmpl/index.html
• admin/views/helloworlds/tmpl/default.php
• admin/tables/index.html
• admin/tables/helloworld.php
• 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

Create a compressed file of this directory or directly download the archive and install it using the Extension Manager of Joomla. 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="3.0" method="upgrade">

	<name>COM_HELLOWORLD</name>
	<!-- The following elements are optional and free of formatting constraints -->
	<creationDate>January 2018</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.9</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 since J2.5 -->
		<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>
	</files>

        <languages folder="site/language">
		<language tag="en-GB">en-GB/en-GB.com_helloworld.ini</language>
        </languages>

	<administration>
		<!-- Administration Menu Section -->
		<menu link='index.php?option=com_helloworld'>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>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>
		</files>
		<languages folder="admin/language">
        		<language tag="en-GB">en-GB/en-GB.com_helloworld.ini</language>
                        <language tag="en-GB">en-GB/en-GB.com_helloworld.sys.ini</language>
		</languages>
	</administration>

</extension>

General Information

Contributors

• Christophe Demko
• Ozgur Aksu
• Matt Thomas
• Gunjan Patel
• Scionescire

Prev: Adding Language Management

Next: Adding Decorations to the Backend