Joomla! Documentation - User contributions [en]

J1.5:Developing a MVC Component/Basic Backend Framework

2010-08-08T18:41:44Z

Upendotech: /* Tutorial specific naming */

== Introduction ==
This article focuses on the entry page/article for the administrator. Whilst the MVC pattern is the same as for the frontend user, this chapter will rapidly go though all steps and setup the backend counter part in the admin section. This article will only focus on setting up the Basic Framework with a list of all the ''Hellos'' but without user interaction. The actual user interaction is added in the succeeding article [[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]].

== Tutorial specific naming ==
Within the next articles the explanation of this administrator section we will keep as close as possible to the component name. For the general overview, lists from the database, we will use ''Hellos'' as identification. The ''Hellos'' naming will be used for viewing and controlling multiple Hellos at once from the database. When selecting a single Hello for Editing or Adding we will use the singular ''Hello'' as naming for the Controller and View. This ''Admin Hello'' has no functional relation with the ''Site Hello'' (the only dependency is the database content, of course).

Where parts 1,2 and 3 of the MVC explanation were working in the site directory tree of com_hello, part 5 and 6 will focus on the admin directory tree. Part 5 and 6 will not add or change files in the site directory tree. Look at the XML file in the attached example of the full com_hello implementation. The XML configuration file will help you with the exact location of the different files being used in this and the following chapter.

== Creating the Basic Framework ==

The basic framework of the administrator panel is very similar to the site portion. The main entry point for the administrator section of the component is hello.php. This file is identical to the hello.php file that was used in the site portion except the name of the controller it loads will be changed to HellosController. The default controller is also called controller.php and this file is identical to the default controller in the site portion, with the exception that the controller is named HellosController instead of HelloController. This difference is so that JController will by default load the hellos view, which will display a list of our greetings.

Here is the listing for hello.php:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

// Require the base controller

require_once( JPATH_COMPONENT.DS.'controller.php' );

// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
$path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
if (file_exists($path)) {
require_once $path;
} else {
$controller = '';
}
}

// Create the controller
$classname = 'HellosController'.$controller;
$controller = new $classname( );

// Perform the Request task
$controller->execute( JRequest::getVar( 'task' ) );

// Redirect if set by the controller
$controller->redirect();</source>

The view and model that we will start with is the hellos view and the hellos model. We will start with the model.

==== The Hellos Model ====

The Hellos Model will be very simple. The only operation that we currently need is the ability to retrieve the list of hellos from the database. This operation will be implemented in a method called getData().

The JModel class has a built in protected method called _getList(). This method can be used to simplify the task of retrieving a list of records from the database. We simply need to pass it the query and it will return the list of records.

At a later point in time, we might want to use our query from within another method. Therefore, we will create a private method called _buildQuery() which will return the query that will be passed to _getList(). This makes it easier to change the query as well since it is localized in one place.

Therefore we need two methods in our class: getData() and _buildQuery().

_buildQuery() simply returns the query. It looks like:

<source lang="php">/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;

return $query;
}</source>

getData() will obtain the query and retrieve the records from the database. Now it might happen that we need to retrieve this list of data twice in one page load. It would be a waste to have to query the database twice. Therefore, we will have this method store the data in a protected property so that on subsequent requests it can simply return the data it has already retrieved. This property will be called _data. (''<-- Naming convention conflict. Private or Protected data should be preceded with a '_' but as this reference is returned to the view where this data is directly accessed, this data can only be considered as public.'')

Here is the getData() method:

<source lang="php">/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}</source>

The completed model looks like:

<source lang="php"><?php
/**
* Hellos Model for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.model' );

/**
* Hello Model
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosModelHellos extends JModel
{
/**
* Hellos data array
*
* @var array
*/
var $_data;

/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;
return $query;
}

/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}
}</source>

This file is saved as models/hellos.php.

==== The Hellos View ====

Now that we have a model to retrieve our data, we need to display it. This view will be fairly similar to the view from the site section as well.

Just as our model was automatically instantiated in the site, so it is in the administrator. Methods that start with "get" [e.g. getData()] in the model can be accessed using the get() method of the JView class. So our view has three lines: one to retrieve the data from the model, one to push the data into the template, and one to invoke the display method to display the output. Thus we have:

<source lang="php"><?php
/**
* Hellos View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.view' );

/**
* Hellos View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHellos extends JView
{
/**
* Hellos view display method
* @return void
**/
function display($tpl = null)
{
JToolBarHelper::title( JText::_( 'Hello Manager' ), 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();

// Get data from the model
$items =& $this->get( 'Data');

$this->assignRef( 'items', $items );

parent::display($tpl);
}
}</source>

This file is saved as views/hellos/view.html.php.

Look carefully at the almost hidden differences compared to ''site'' example. The data is stored in a variable that is encapsulated within the model. Because the data amount is huge due to using the very handy _getList(), the need for returning a reference instead of a value is obvious. This is handled in:
$items =& $this->get( 'Data');
Looking again at this line and you will notice another difference with respect to the ''site'' view.html.php. The calling of the model function is done implicitly. The actual model function name is getData(). In the ''site'' example you had to call following two lines:
$model =& $this->getModel();
$greeting = $model->getData();
Both lines are now taken care of by calling: <code>$this->get( 'Data');</code>. Under the surface of this <code>get()</code> the 'Data' is prefixed with 'get' so when using this function make sure the model functions are preceded with 'get'. This function can also be used in the ''site'' section. Keeping the data in the model and accessing it by reference, via <code>get()</code> methods, is the preferred way of getting data from the model.

==== The Hellos Template ====

The template will take the data pushed into it from the view and produce the output. We will display our output in a simple table. While the frontend template was very simple, in the administrator we will need a minimal amount of extra logic to handle looping through the data.

Here is our template:

<source lang="php"><?php defined('_JEXEC') or die('Restricted access'); ?>
<form action="index.php" method="post" name="adminForm">
<div id="editcell">
<table class="adminlist">
<thead>
<tr>
<th width="5">
<?php echo JText::_( 'ID' ); ?>
</th>
<th>
<?php echo JText::_( 'Greeting' ); ?>
</th>
</tr>
</thead>
<?php
$k = 0;
foreach ($this->items as &$row)
{
?>
<tr class="<?php echo "row$k"; ?>">
<td>
<?php echo $row->id; ?>
</td>
<td>
<?php echo $row->greeting; ?>
</td>
</tr>
<?php
$k = 1 - $k;
}
?>
</table>
</div>

<input type="hidden" name="option" value="com_hello" />
<input type="hidden" name="task" value="" />
<input type="hidden" name="boxchecked" value="0" />
<input type="hidden" name="controller" value="hello" />

</form></source>

This template is saved as views/hellos/tmpl/default.php.

You will notice that our output is enclosed in a form. Though this is not necessary now, it will be soon.

We have now completed the basic part of the first view. We have added five files to the admin section of our component:

* hello.php
* controller.php
* models/hellos.php
* views/hellos/view.html.php
* views/hellos/tmpl/default.php

You can now add these files to the XML install file and give it a try!

== Conclusion ==

We have now implemented a basic framework for the backend admin component. A list where all of the Hellos are displayed. The next chapter will extend this framework and add user interaction / database manipulation.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

== Download ==

The full admin component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8111/29436/com_hello4_01.zip com_hello4_01].

[[Category:Development]]

J1.5:Developing a MVC Component/Basic Backend Framework

2010-08-08T18:40:26Z

Upendotech:

== Introduction ==
This article focuses on the entry page/article for the administrator. Whilst the MVC pattern is the same as for the frontend user, this chapter will rapidly go though all steps and setup the backend counter part in the admin section. This article will only focus on setting up the Basic Framework with a list of all the ''Hellos'' but without user interaction. The actual user interaction is added in the succeeding article [[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]].

== Tutorial specific naming ==
Within the next articles the explanation of this administrator section we will keep as close as possible to the component name. For the general overview, lists from the database, we will use ''Hellos'' as identification. The ''Hellos'' naming will be used for viewing and controlling multiple Hellos at once from the database. When selecting a single Hello for Editing or Adding we will use the singular ''Hello'' as naming for the Controller and View. This ''Admin Hello'' has no functional relation with the ''Site Hello'' (the only dependency is the database content, of cause).

Where parts 1,2 and 3 of the MVC explanation were working in the site directory tree of com_hello, part 5 and 6 will focus on the admin directory tree. Part 5 and 6 will not add or change files in the site directory tree. Look at the XML file in the attached example of the full com_hello implementation. The XML configuration file will help you with the exact location of the different files being used in this and the following chapter.

== Creating the Basic Framework ==

The basic framework of the administrator panel is very similar to the site portion. The main entry point for the administrator section of the component is hello.php. This file is identical to the hello.php file that was used in the site portion except the name of the controller it loads will be changed to HellosController. The default controller is also called controller.php and this file is identical to the default controller in the site portion, with the exception that the controller is named HellosController instead of HelloController. This difference is so that JController will by default load the hellos view, which will display a list of our greetings.

Here is the listing for hello.php:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

// Require the base controller

require_once( JPATH_COMPONENT.DS.'controller.php' );

// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
$path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
if (file_exists($path)) {
require_once $path;
} else {
$controller = '';
}
}

// Create the controller
$classname = 'HellosController'.$controller;
$controller = new $classname( );

// Perform the Request task
$controller->execute( JRequest::getVar( 'task' ) );

// Redirect if set by the controller
$controller->redirect();</source>

The view and model that we will start with is the hellos view and the hellos model. We will start with the model.

==== The Hellos Model ====

The Hellos Model will be very simple. The only operation that we currently need is the ability to retrieve the list of hellos from the database. This operation will be implemented in a method called getData().

The JModel class has a built in protected method called _getList(). This method can be used to simplify the task of retrieving a list of records from the database. We simply need to pass it the query and it will return the list of records.

At a later point in time, we might want to use our query from within another method. Therefore, we will create a private method called _buildQuery() which will return the query that will be passed to _getList(). This makes it easier to change the query as well since it is localized in one place.

Therefore we need two methods in our class: getData() and _buildQuery().

_buildQuery() simply returns the query. It looks like:

<source lang="php">/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;

return $query;
}</source>

getData() will obtain the query and retrieve the records from the database. Now it might happen that we need to retrieve this list of data twice in one page load. It would be a waste to have to query the database twice. Therefore, we will have this method store the data in a protected property so that on subsequent requests it can simply return the data it has already retrieved. This property will be called _data. (''<-- Naming convention conflict. Private or Protected data should be preceded with a '_' but as this reference is returned to the view where this data is directly accessed, this data can only be considered as public.'')

Here is the getData() method:

<source lang="php">/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}</source>

The completed model looks like:

<source lang="php"><?php
/**
* Hellos Model for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.model' );

/**
* Hello Model
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosModelHellos extends JModel
{
/**
* Hellos data array
*
* @var array
*/
var $_data;

/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;
return $query;
}

/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}
}</source>

This file is saved as models/hellos.php.

==== The Hellos View ====

Now that we have a model to retrieve our data, we need to display it. This view will be fairly similar to the view from the site section as well.

Just as our model was automatically instantiated in the site, so it is in the administrator. Methods that start with "get" [e.g. getData()] in the model can be accessed using the get() method of the JView class. So our view has three lines: one to retrieve the data from the model, one to push the data into the template, and one to invoke the display method to display the output. Thus we have:

<source lang="php"><?php
/**
* Hellos View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.view' );

/**
* Hellos View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHellos extends JView
{
/**
* Hellos view display method
* @return void
**/
function display($tpl = null)
{
JToolBarHelper::title( JText::_( 'Hello Manager' ), 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();

// Get data from the model
$items =& $this->get( 'Data');

$this->assignRef( 'items', $items );

parent::display($tpl);
}
}</source>

This file is saved as views/hellos/view.html.php.

Look carefully at the almost hidden differences compared to ''site'' example. The data is stored in a variable that is encapsulated within the model. Because the data amount is huge due to using the very handy _getList(), the need for returning a reference instead of a value is obvious. This is handled in:
$items =& $this->get( 'Data');
Looking again at this line and you will notice another difference with respect to the ''site'' view.html.php. The calling of the model function is done implicitly. The actual model function name is getData(). In the ''site'' example you had to call following two lines:
$model =& $this->getModel();
$greeting = $model->getData();
Both lines are now taken care of by calling: <code>$this->get( 'Data');</code>. Under the surface of this <code>get()</code> the 'Data' is prefixed with 'get' so when using this function make sure the model functions are preceded with 'get'. This function can also be used in the ''site'' section. Keeping the data in the model and accessing it by reference, via <code>get()</code> methods, is the preferred way of getting data from the model.

==== The Hellos Template ====

The template will take the data pushed into it from the view and produce the output. We will display our output in a simple table. While the frontend template was very simple, in the administrator we will need a minimal amount of extra logic to handle looping through the data.

Here is our template:

<source lang="php"><?php defined('_JEXEC') or die('Restricted access'); ?>
<form action="index.php" method="post" name="adminForm">
<div id="editcell">
<table class="adminlist">
<thead>
<tr>
<th width="5">
<?php echo JText::_( 'ID' ); ?>
</th>
<th>
<?php echo JText::_( 'Greeting' ); ?>
</th>
</tr>
</thead>
<?php
$k = 0;
foreach ($this->items as &$row)
{
?>
<tr class="<?php echo "row$k"; ?>">
<td>
<?php echo $row->id; ?>
</td>
<td>
<?php echo $row->greeting; ?>
</td>
</tr>
<?php
$k = 1 - $k;
}
?>
</table>
</div>

<input type="hidden" name="option" value="com_hello" />
<input type="hidden" name="task" value="" />
<input type="hidden" name="boxchecked" value="0" />
<input type="hidden" name="controller" value="hello" />

</form></source>

This template is saved as views/hellos/tmpl/default.php.

You will notice that our output is enclosed in a form. Though this is not necessary now, it will be soon.

We have now completed the basic part of the first view. We have added five files to the admin section of our component:

* hello.php
* controller.php
* models/hellos.php
* views/hellos/view.html.php
* views/hellos/tmpl/default.php

You can now add these files to the XML install file and give it a try!

== Conclusion ==

We have now implemented a basic framework for the backend admin component. A list where all of the Hellos are displayed. The next chapter will extend this framework and add user interaction / database manipulation.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

== Download ==

The full admin component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8111/29436/com_hello4_01.zip com_hello4_01].

[[Category:Development]]

J1.5:Developing a MVC Component/Creating an Administrator Interface

2010-08-08T16:28:54Z

Upendotech:

{{ambox
| type = notice
| image = notice
| text = This {{thingamabob}} has been divided into three sections, two new articles are added. Especially this page needs a review
<small>(August 2009)</small>}}
== Introduction ==

In the first three Parts, we have developed a MVC component that retrieves its data from a table in the database. Currently, there is no way to add data to the database except to do it manually using another tool. In the next Parts of this tutorial, we will develop an administrator section for our component which will make it possible to manage the entries in the database.

This Part, [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface | Part 4 - Creating an Administrator Interface]], will be an article with no new source code for our Hello component but will describe some basic details and in-depth explanation of the MVC pattern. This intermediate chapter is not required to complete the Hello model so if you think you understand the basics continue with [[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]].

In the frontend solution (site section, parts 1,2 and 3) we developed the first part of our component. The frontend solution is based upon default Controllers, Views and Templates and you were "taken by the hand" and "left to trust" the default handling of the code. This is going to change in the Backend or Administration section of our Hello component ( parts 5 and 6) - we will have to develop all of the code that manages the application flow.

== Site / Admin ==
Joomla! is a content management system. The '''frontend''' is used for presenting the users with content and allows certain logged in users to manipulate the content. The '''backend''' is responsible for administering the website framework (structuring / managing / controlling / maintaining). This division between (frontend) site-content and (backend) administration is a fundamental aspect of the Joomla! architecture.

=== Entrance points ===
From the XML file of our frontend example it was already obvious that there would be an administration part:
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
...
<administration>

<menu>Hello World!</menu>

<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
</administration>
...
</source>
Only the .sql files were of use and only during installation for our frontend view, the other two files have no content besides generating a blank page. Access your websites' file system at your hosting provider (or on your own server) and browse through the directories after installing the frontend com_hello component. You may have noticed that our Hello component is to be found twice:
<root>/components/com_hello
<root>/administrator/components/com_hello

These two sub-directories link to the previously explained site-content and administration. Administrator interactions explicitly go via the administrator sub-directory, where guest or registered users will enter the default entrance on the root:
<root>/index.php
Administrative users will have to log in, and after logging in they will enter your site via:
<root>/administrator/index.php

With the different access points it is easy to grasp that with setting up the administrator section the naming conventions have no dependency with the site section. Whilst the MVC pattern is also applicable for the administrator section this implies that identical Controllers, Views and Models naming can (and sometimes must) be used as in the site section.

== MVC pattern interaction ==
[[image:MVC joomla.png|frameless|right]]In [[Developing a Model-View-Controller Component - Part 1]] the figure on the right was used to explain the focus of the first three parts of this ''Developing a Model-View-Controller Component tutorial''. Now we will use this figure to explain how decisions are made on what is going to be displayed and how to manipulate this.

=== Example roll-out ===
For explanation purposes an easy to grasp example will be used. A library has the main function of lending books to registered users. Simply laid out there are three tables:
* users
* books
* relation

Lets keep it all very simple. The users are addressed by Id and Name. The books are identified by Id and Title and the relation contains both Ids and the date of lending.

[[image:Library Example.png|400px|frameless|center]]

The example is carefully chosen and will help in explaining the Joomla! architecture in more detail. The administrative side of our Hello component is not even that complex with only one table to manage. After the explanation of this Part it should be easy to follow the tutorial in the succeeding Parts.

=== Mapping a Joomla! MVC component from the example ===
In this example we will assume that administrative actions (add, edit, delete) are tasks that are to be performed by the administrator. For the frontend user only the view of the Relation table is interesting ("when do I have to bring back the books?"). This example shows the entire list and ignores all privacy stuff that could be taken care of by letting registered users only see their own books. (''See'': [http://api.joomla.org/Joomla-Framework/User/JUser.html JUser object] for making user deviations in template module).

Just like our frontend Hello component, for this library component only the default view is being used in the frontend. It lists the relational table, left joining the other two tables to obtain a human readable list of books with their corresponding due date.
Alice | One flew over ... | 12-aug-2009
Alice | Celeb talk | 12-aug-2009
Mark | Joomla! | 15-aug-2009

With respect to the administration part it is important to understand that we have one default and three dedicated views, each controlling three tasks:
* <Component name default view>
* User administration
** Add
** Change
** Delete
* Book administration
** Add
** Change
** Delete
* Relation administration
** Add
** Change
** Delete

==== Controllers ====
The main controller of the admin section needs to differentiate between the different Adds, Changes or Deletes that are requested. This is taken care of by creating sub-controllers for each view for handling their specific tasks.
<root>/administrator/controller.php
<root>/administrator/controllers/users.php
<root>/administrator/controllers/books.php
<root>/administrator/controllers/relation.php

The controller is an important part of the MVC pattern. Not only does it take care of the requested tasks, it is also the initiator of instantiating the model with the same name and it is responsible for setting the view and the desired form for that view. The controller really justifies its name.

Within the controller it is good to make a difference between '''activating tasks''' (for example the edit selection from a menu) and '''resulting tasks''' (for example the result of an edit trigger is the posted data).

Typical controller functions look like:
<source lang="php">
function <activating task>() // <-- edit, add, delete
{
JRequest::setVar( 'view', '[<componentname> | users | books | relation ]' );
JRequest::setVar( 'layout', 'default' ); // <-- The default form is named here, but in
// some complex views, multiple layouts might
// be needed.
parent::display();
}

function <resulting task>() // <-- save, remove
{
$model = $this->getModel('[<componentname> | users | books | relation ]');
if(!$model->action() ) { // <-- action could be delete() or store()
$msg = JText::_( 'Error: Could not perform action' );
} else {
$msg = JText::_( 'Action executed' );
}

$this->setRedirect( 'index.php?option=<componentname>', $msg );
}
</source>
A controller takes care of all tasks for that dedicated controller. After completing a resulting task the module will return to the main administration entrance point for that component, the main controller with the default view. Activating tasks enforce a new view with a form to display after first defining it.

The explicit definition of the form within a view might raise some eyebrows but our examples are too simple. For the general understanding and consistency this field should mostly be ''default''. In complex views multiple forms could be defined within one view.

==== Models ====
The Controllers interact with their equally named Model counter part. In the frontend view the Model was only used to retrieve data. The backend has more controllers and thus also more model files. The backend model files not only are responsible for delivering data to the viewer but also take care of tasks initiated from the controller. A good model contains all actions required to manage a single table in the database.
<root>/administrator/models/<componentname>.php
<root>/administrator/models/users.php
<root>/administrator/models/books.php
<root>/administrator/models/relation.php

==== Views ====
Separate views are of course also required. For views and subsequent forms no forced naming conventions are required (linking to views is taken care of in the controller). In the following listing the Administrative tasks are identified as a subset for the different views. This choice is totally random and maybe even non-logical but that doesn't matter for the explanation. Just for example purposes I added also a different view, a delete view, that could be used for all the deletes for all administrative tasks asking an "Are you sure" display.

<root>/administrator/views/<componentname>/view.html.php + .../tmpl/default.php
<root>/administrator/views/users/view.html.php + .../tmpl/default.php
<root>/administrator/views/books/view.html.php + .../tmpl/default.php
<root>/administrator/views/relation/view.html.php + .../tmpl/default.php
 
<root>/administrator/views/delete/view.html.php + .../tmpl/default.php

''Note'': In general it is good practice to maintain one form per view because the view.html.php still has to deliver the content. With some basic logic you can enable, disable certain content but if this logic is becoming too complex start considering splitting up the view.

''Note'': Sharing template parts amongst the different views (for uniform layouting of headers and titles of your component) can be done using the PHP <code>include / require;</code>. There is one slight problem ... how to make the logical reference? In my modules I have a collector bin for general to use sniplets. Because it involved the views and forms I put this general bin in the views directory. The variable $pathToGeneralView needs to be defined somewhere in the first lines of your file and you have to make sure that the logical reference path is correct (the '..'s). In the following example the files marked with a '*' use the following code:

./com_compname/views/general/navigate.header.php <-- sniplet code for the header
./com_compname/views/general/navigate.footer.php <-- sniplet code for the footer
./com_compname/views/mngtable1/view.html.php
./com_compname/views/mngtable1/tmpl/default.php *
./com_compname/views/mngtable2/view.html.php
./com_compname/views/mngtable2/tmpl/default.php *

<source lang=php>
$pathToGeneralView = strchr(dirname(__FILE__), dirname($_SERVER['SCRIPT_NAME']));
$pathToGeneralView = str_replace(dirname($_SERVER['SCRIPT_NAME']),'.',$pathToGeneralView );
$pathToGeneralView = $pathToGeneralView . "/../../general/"; <-- returning path from current position.
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>
Another Way to do the same thing:
<source lang=php>
$pathToGeneralView = JPATH_COMPONENT_ADMINISTRATOR.DS. "views".DS."general".DS; <-- will return 'path/Joomla/administrator/components/com_example/views/general/
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Also, having that many ''default'' forms can make it difficult to determine the context. On the other hand, the view.html.php cannot be renamed, and one is always forced to look at the directory name for the view.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated models;
* different views and their forms.

Just one big question remains: '''How to use them'''!

Three parameters are mandatory for letting Joomla! do its job:
* option
* controller
* task

These three parameters are almost self explaining ;). The ''option'' part when developing a component is easy, always assign your component name to it. For component development consider this one as a constant, of course the Joomla! engine has more options than only components.

The ''controller'' and ''task'' parameters can be manipulated within your component anyway you want it to.

==== How it all works together ====
Looking at the simplified MVC picture Joomla! the logical flow of interaction goes the following way:
# What is my entrance point?
#*The Joomla! engine discovers a logged in administrator and sets the entrance point to <root>/administrator/index.php otherwise it will go to the <root>/index.php entrance.
# What option is requested?
#*The Joomla! engine reads the option variable and discovers that a component named <componentname> is requested. The entrance point becomes: <root>/administrator/components/com_<componentname>/<componentname>.php
# Is there need to access a dedicated controller?
#* The Joomla! engine reads the controller variable and discovers that a dedicated controller is required: <root>/administrator/components/com_<componentname>/controllers/<dedicatedcontroller>.php
# Is there a task that needs to be addressed?
#* The identified controller is handed the task value as parameter.
# The Model is derived from the controller and instantiated.
# The View and Form are set in the controller and initiated to become active.

=== How to add interaction ===
Within HTML there are two common ways to interact with Joomla!:
# reference to a link
# form submission post / get

==== Link reference for the Joomla! engine ====
Remember the '''activating tasks''' and '''resulting tasks''' mentioned earlier? Most activating tasks are initiated by a link. In case of the Library example the site section overview could be copied to the admin section. This default view will now be extended and every cell will become a link for editing the specific database element.

Using the Library example, the template PHP code without looping control will contain the following code:
<source lang=php>
$link = JRoute::_( 'index.php?option=com_library&controller=users&task=edit&cid='. $row->idu );
echo "<td><a href=\"".$link."\">$row->name</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=books&task=edit&cid='. $row->idb );
echo "<td><a href=\"".$link."\">$row->title</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=relation&task=edit&cid='. $row->idr );
echo "<td><a href=\"".$link."\">$row->date</a></td>";
</source>

Within each clickable field the three mandatory parameters to manipulate Joomla! can be identified. In addition there is one user parameter for handling the correct index in the controller task (cid). These parameter are separated by '&'. Do not use spaces in your variables, as this might screw-up parameter handling in certain browsers. After looping, all text entries will be clickable and trigger the corresponding controller with the correct row id in the associated table.

[Alice} | [One flew over ...] | [12-aug-2009]
[Alice] | [Celeb talk] | [12-aug-2009]
[Mark] | [Joomla!] | [15-aug-2009]

==== Posting Form Data to the Joomla! Engine ====
After being initiated by an activating task, an input form view might be the result. The snippet of code below could be the result of clicking the first cell of the default component view that is clicked for editing ([Alice]:cid=3).

<source lang="php">
<form action="index.php" method="post">
<input type="text" name="username" id="username" size="32" maxlength="250" value="<?php echo $this->user->name;?>" />

<input type="submit" name="SubmitButton" value="Save" />

<input type="hidden" name="option" value="com_library" /> // <-- mandatory
<input type="hidden" name="controller" value="hello" /> // <-- mandatory
<input type="hidden" name="task" value="save" /> // <-- mandatory
<input type="hidden" name="id" value="<?php echo $this->user->id; ?>" /> // <-- user parameter, index in database for [Alice]
</form>
</source>

The three Joomla! mandatory parameters are placed as hidden in the form. Hidden parameters are not shown in any way but will be added to the posting data.

''Tip'': when debugging this form, replace in the form tag <code>method="post"</code> temporarily with <code>method="get"</code>. All posted parameters will be shown in the URL of your browser. If the module is working undo this change. For one reason it looks sharper without all the parameters being shown in the URL and you avoid motivating people to manipulate the browser URL themselves. Of course one can look at the source code but using ''Post'' instead of ''Get'', but this eliminates the first 90% of the earth population. The other reason is more technical and the simple explanation is that post methods (i.e. method="post") can contain more (complex) data.

''Remark'': In some developed modules you may notice that developers have also added the ''view'' parameter. This is bad programming whilst the controller(s) should take care of the ''view'' and the ''form''.

== Conclusion ==

The use of the three mandatory parameters and the different access points are clarified. Let's do something with this knowledge and extend the Hello component to the administrative section in the succeeding articles of this tutorial.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]