Joomla! Documentation - User contributions [en]

J1.5:Plugin/Events/System

2009-10-13T19:15:36Z

Memberclicks: /* onAfterRoute */

[[Category:Development]]
[[Category:Plugins]]
===Overview===
In a standard installation of Joomla! 1.5 we have several predefined events which, when triggered, call functions in the associated plugins. For more information on plugins, look [[plugins:create_plugin|here]].

This topic is aimed at "global" system events, including those triggered on every page load (onAfterInitialise, onAfterRoute, onAfterDispatch, onAfterRender), those supporting search within multiple plugins (onSearch, onSearchArea) and those supporting the presentation of web services (onGetWebServices). Visit [[Tutorial:Plugins|the plugins tutorial]] for a complete list over available core events.

=== onAfterInitialise ===
'''Description'''

This event is triggered after the framework has loaded and the applicaiton initialise method has been called.

'''Parameters'''

None.

'''Return Value'''

None.

'''Called in files'''

*index.php
*administrator/index.php

===onAfterRoute===
'''Description'''

This event is triggered after the framework has loaded and initialised and the router has route the client request.

Routing is the process of examining the request environment to determine which component should receive the request. The component optional parameters are then set in the request object to be processed when the application is being dispatched.

When this event triggers the router has parsed the route and pushed the request parameters into JRequest for retrieval by the application.

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

===onAfterDispatch===
'''Description'''
This event is triggered after the framework has dispatched the application.

Dispatching is the process of pulling the option from the request object and mapping them to a component. If the component do not exist, it handles determining a default component to dispatch.

When this event is triggered the output of the component is available in the document buffer.

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

===onAfterRender===
'''Description'''
This event is triggered after the framework has rendered the application.

Rendering is the process of pushing the document buffers into the template placeholders, retrieving data from the document and pushing it into the into the JResponse buffer.

When this event is triggered the output of the application is available in the response buffer.

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

===onSearch===
'''Description'''

This event is triggered by a variety of search related operations. It is a request for a
plugin to return the result of a search request. The rows must return the following fields, which are used in a common display routine:

* href
* title
* section
* created
* text
* browsernav

'''Parameters'''

* The target search string.
* A string matching option (exact|any|all).
* A string ordering option (newest|oldest|popular|alpha|category)
* An array if restricted to areas, null if search all.

'''Return Value'''

Array of stdClass objects with members as described above.

'''Used in files'''

* administrator/components/com_statistics/admin.statistics.php
* components/com_search/search.php
* plugins/search/categories.php
* plugins/search/contacts.php
* plugins/search/content.php
* plugins/search/newsfeeds.php
* plugins/search/sections.php
* plugins/search/weblinks.php
* plugins/xmlrpc/joomla.php

===onSearchAreas===
'''Description'''

This appears to be a request for plugins to identify which "areas" they provide
search facilities for.

'''Parameters'''

None.

'''Return Value'''

An associative array of area names, indexed by the area identifier. For example, array( 'categories' => 'Categories' ).

'''Used in files'''

* components/com_search/search.php
* plugins/search/categories.php
* plugins/search/contacts.php
* plugins/search/content.php
* plugins/search/newsfeeds.php
* plugins/search/sections.php
* plugins/search/weblinks.php

===onGetWebServices===

'''Description'''

This is an introspection request for plugins that provide web services.

'''Parameters'''

None.

'''Return Value'''

An array of associative arrays. The outer array is indexed by the service method name and
contains an array with the following elements:

* ['function'] The method to be invoked, typically a string like 'ClassName::staticMethod'
* ['docstring'] A human-readable definition of the method's purpose.
* ['signature'] An array identifying the types of the method's parameters. See the global variables $xmlrpc* for more information.

'''Used in files'''

* plugins/xmlrpc/blogger.php
* plugins/xmlrpc/joomla.php
* xmlrpc/index.php

===Example===

This is an example system plugin. Please note that because system plugins are loaded before any other event group, they may also contain any other event.

The following class would be located in the file <code>/plugins/system/example.php</code>.

<pre><?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.plugin.plugin' );

/**
* Example system plugin
*/
class plgSystemExample extends JPlugin
{
/**
* Constructor
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
* This causes problems with cross-referencing necessary for the observer design pattern.
*
* @access protected
* @param object $subject The object to observe
* @param array $config An array that holds the plugin configuration
* @since 1.0
*/
function plgSystemCache( &$subject, $config )
{
parent::__construct( $subject, $config );

// Do some extra initialisation in this constructor if required
}

/**
* Do something onAfterInitialise
*/
function onAfterInitialise()
{
}

/**
* Do something onAfterRoute
*/
function onAfterRoute()
{
}

/**
* Do something onAfterDispatch
*/
function onAfterDispatch()
{
}

/**
* Do something onAfterRender
*/
function onAfterRender()
{
}
}</pre>

The following XML document would be located in the file <code>/plugins/system/example.xml</code>.

<pre><?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="system">
<name>System - Example</name>
<author>Author</author>
<creationDate>Month 2008</creationDate>
<copyright>Copyright (C) 2008 Holder. All rights reserved.</copyright>
<license>GNU General Public License</license>
<authorEmail>email</authorEmail>
<authorUrl>url</authorUrl>
<version>1.0.1</version>
<description>An example system plugin</description>
<files>
<filename plugin="example">example.php</filename>
</files>
<params>
<param name="example"
type="text"
default=""
label="Example"
description="An example text parameter" />
</params>
</install></pre>

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

2009-10-12T21:05:07Z

Memberclicks: /* Link reference for the Joomla! engine */

{{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 tutorials, 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 articles 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 article, [[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 we will go into some basic details of the MVC pattern. In the frontend solution (site section) we have 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 to trust the default handling of the code. This is going to change in the Backend or Administration section of our Hello component.

== Site / Admin ==
Joomla! is a content management system. The frontend is used for presenting the users with content and allowing certain logged in users to manipulate the content, the backend is responsible for administrating the website framework (structuring / managing / controlling / maintaining). This division between site-content and 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 Controls, 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 chapter it should be easy to follow the tutorial in the succeeding chapters

=== 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 (''Hint'': <code>if ($user->registered) {}</code> ).

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 lend books.
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 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>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* 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 wil 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/modules/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/modules/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 MVC 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 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 sniplet 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 simply explained the 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

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

2009-10-12T21:03:26Z

Memberclicks: /* Link reference for the Joomla! engine */

{{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 tutorials, 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 articles 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 article, [[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 we will go into some basic details of the MVC pattern. In the frontend solution (site section) we have 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 to trust the default handling of the code. This is going to change in the Backend or Administration section of our Hello component.

== Site / Admin ==
Joomla! is a content management system. The frontend is used for presenting the users with content and allowing certain logged in users to manipulate the content, the backend is responsible for administrating the website framework (structuring / managing / controlling / maintaining). This division between site-content and 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 Controls, 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 chapter it should be easy to follow the tutorial in the succeeding chapters

=== 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 (''Hint'': <code>if ($user->registered) {}</code> ).

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 lend books.
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 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>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* 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 wil 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/modules/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/modules/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 MVC can be identified. In addation 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 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 sniplet 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 simply explained the 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

J1.5:Developing a MVC Component/Adding Backend Actions

2009-10-09T19:56:56Z

Memberclicks: /* Introduction */

== Introduction ==

This article focuses on adding functionality to the current ''dumb'' page/article for the administrator. For an administrator the current default view is pretty useless. It doesn't really do anything - all it does is display the entries that we have in our database.

In order to make it useful, we need to add some buttons and links. This article extends the component with content management tasks. Add, Change and Delete are the typical tasks that will be added.

==Adding interaction ==
Interaction will be added on two levels. Within the administrator framework by means of Toolbar extension and within the article itself by means of reference links and form postings. For basic understanding see [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]].

=== The Toolbar ===

You may have noticed the toolbar that appears at the top of other Joomla! component administrator panels. Our component needs one as well. Joomla! makes this very easy to do. We will add buttons Delete records, Edit records, and create New records. We will also add a title that will be displayed on our toolbar.

This is done by adding code to the view. To add the buttons, we use static methods from the Joomla! JToolBarHelper class. The code looks like:

<source lang="php">JToolBarHelper::title( JText::_( 'Hello Manager' ), 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();</source>

These three methods will create the appropriate buttons. The deleteList() method can optionally take up to three parameters - the first parameter is a string to display to the user to confirm that they want to delete the records. The second is the task that should be sent with the query (the default is 'remove'), and the third is the text that should be displayed below the button.

The editListX() and addNewX() methods can each take two optional parameters. The first is the task (which are by default edit and add, respectively), and the second is the text that should be displayed below the button.

*You may have noticed the use of the JText::_ method in the template before and here as well. This is a handy function that makes component translation much easier. The JText::_ method will look up the string in your component language file and return the translated string. If no translation text is found, it will return the string that you passed to it. If you want to translate your component into another language, all you have to do is create a language file that will map the strings within the quotes to the translated version of the string.

=== Checkboxes and Links ===

We now have buttons. Two of those buttons operate on existing records. But how do we know which records to operate on? We have to let the user tell us. To do this, we need to add checkboxes to our table so that the user can select certain records. This is done in our template.

In order to the add the checkboxes, we need to add an extra column into our table. We will add the column in between the two that we already have.

In the header of the column, we will add a checkbox which can be used to toggle all the boxes below it on or off:

<source lang="php"><th width="20">
<input type="checkbox" name="toggle" value="" onclick="checkAll(<?php echo count( $this->items ); ?>);" />
</th></source>

The Javascript checkAll function is a function that is built into the Joomla! base Javascript package that provides the functionality that we want here.

Now we need to add the checkboxes into the individual rows. Joomla!'s JHTML class has a method, JHTML::_(), which will generate our checkbox for us. We will add the following line to our loop:

<source lang="php">$checked = JHTML::_( 'grid.id', $i, $row->id );</source>

after the line:

<source lang="php">$row =& $this->items[$i];</source>

Then we will add a cell in between the two that we already have:

<source lang="php"><td>
<?php echo $checked; ?>
</td></source>

It can be cumbersome to have to check the box that we want to edit and then move up and click the edit button. Therefore, we will add a link so that it will go straight to the greeting's edit form. We will add the following line after the call to the JHTML::_() method to generate the link HTML:

<source lang="php">$link = JRoute::_( 'index.php?option=com_hello&controller=hello&task=edit&cid[]='. $row->id );</source>

And we include the link in the cell showing the greeting text:

<source lang="php"><td>
<a href="<?php echo $link; ?>"><?php echo $row->greeting; ?></a>
</td></source>

You will notice that this link points to the hello controller. This controller will handle the data manipulation of our greetings.

If you recall from above, we had four hidden input fields at the bottom of our form. The first input field was named 'option'. This field is necessary so that we stay in our component. The second input field was task. This form property gets set when one of the buttons in the toolbar is clicked. A Javascript error will result and the buttons will not work if this input field is omitted. The third input field is the boxchecked field. This field keeps track of the number of boxes that are checked. The edit and delete buttons will check to ensure that this is greater than zero and will not allow the form to be submitted if it is not. The fourth input field is the controller field. This is used to specify that tasks fired from this form will be handled by the hello controller.

Here is the code for the completed default.php file:

<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 width="20">
<input type="checkbox" name="toggle" value="" onclick="checkAll(<?php echo count( $this->items ); ?>);" />
</th>
<th>
<?php echo JText::_( 'Greeting' ); ?>
</th>
</tr>
</thead>
<?php
$k = 0;
for ($i=0, $n=count( $this->items ); $i < $n; $i++)
{
$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello&controller=hello&task=edit&cid[]='. $row->id );

?>
<tr class="<?php echo "row$k"; ?>">
<td>
<?php echo $row->id; ?>
</td>
<td>
<?php echo $checked; ?>
</td>
<td>
<a href="<?php echo $link; ?>"><?php echo $row->greeting; ?></a>
</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>

Our hellos view is now complete.

== Getting Down and Dirty: Doing the Real Work ==

Now that the Hellos view is done, it is time to move to the Hello controller and model. This is where the real work will get done.

==== The Hello Controller ====

Our default controller just isn't going to cut it when it comes to doing work - all it is capable of doing is displaying views.

We need to be able to handle the tasks that we are launching from the Hellos view: add, edit and remove. The singular named Hello controller is created (and located in the controllers sub-directory) to actually add, edit and remove the individual entries.

Add and edit are essentially the same task: they both display a form to the user that allows a greeting to be edited. The only difference is that new displays a blank form, and edit displays a form with data already in it. Since they are similar, we will map the add task onto the edit task handler. This is specified in our constructor:

<source lang="php">/**
* constructor (registers additional tasks to methods)
* @return void
*/
function __construct()
{
parent::__construct();

// Register Extra tasks
$this->registerTask( 'add' , 'edit' );
}</source>

The first parameter of JController::registerTask is the task to map, and the second is the method to map it to.

We will start with handling the edit task. The controller's job is fairly simple for the edit task. All it has to do is specify the view and layout to load (the hello view and the form layout). We will also tell Joomla! to disable the mainmenu while we are editing our greeting. This prevents users from leaving unsaved records open.

Our edit task handler looks like:

<source lang="php">/**
* display the edit form
* @return void
*/
function edit()
{
JRequest::setVar( 'view', 'hello' );
JRequest::setVar( 'layout', 'form' );
JRequest::setVar('hidemainmenu', 1);

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

NOTE on naming conventions: The top calling program (hello.php) makes assumptions about the file names and class names of the controllers. To summarize for this example:

Default controller path: .../controller.php
Default controller class name: HellosController

Requested controller path .../controllers/<requestName>.php
Requested controller class name: HellosController<requestName>

==== The Hello View ====

The Hello view will display a form which will allow the user to edit a greeting. The display method if the hello view has to do a few simple tasks:

* retrieve the data from the model
* create the toolbar
* pass the data into the template
* invoke the display() method to render the template

This becomes a bit more complicated because the one view handles both the edit and add tasks. In our toolbar we want the user to know whether they are adding or editing, so we have to determine which task was fired.

Since we are already retrieving the record that we want to display from the model, we can use this data to determine what task was fired. If the task was edit, then the id field of our record will have been set. If the task was new, then it will not have been set. This can be used to determine if we have a new record or an existing record.

We will add two buttons to the toolbar: save and cancel. Though the functionality will be the same, we want to display different buttons depending on whether it is a new or existing record. If it is a new record, we will display cancel. If it already exists, we will display close.

Thus our display method looks like this:

<source lang="php">/**
* display method of Hello view
* @return void
**/
function display($tpl = null)
{
//get the hello
$hello =& $this->get('Data');
$isNew = ($hello->id < 1);

$text = $isNew ? JText::_( 'New' ) : JText::_( 'Edit' );
JToolBarHelper::title( JText::_( 'Hello' ).': <small><small>[ ' . $text.' ]</small></small>' );
JToolBarHelper::save();
if ($isNew) {
JToolBarHelper::cancel();
} else {
// for existing items the button is renamed `close`
JToolBarHelper::cancel( 'cancel', 'Close' );
}

$this->assignRef('hello', $hello);
parent::display($tpl);
}</source>

==== The Hello Model ====

Our view needs data. Therefore, we need to create a model to model a hello.

Our model will have two properties: _id and _data. _id will hold the id of the greeting and data will hold the data.

We will start with a constructor, which will attempt to retrieve the id from the query:

<source lang="php">/**
* Constructor that retrieves the ID from the request
*
* @access public
* @return void
*/
function __construct()
{
parent::__construct();

$array = JRequest::getVar('cid', 0, '', 'array');
$this->setId((int)$array[0]);
}</source>

The JRequest::getVar() method is used to retrieve data from the request. The first parameter is the name of the form variable. The second parameter is the default value to assign if there is no value found. The third parameter is the name of the hash to retrieve the value from (get, post, etc), and the last value is the data type that should be forced on the value.

Our constructor will take the first value from the cid array and assign it to the id.

Our setId() method can be used to set our id. Changing the id that our model points to will mean the id points to the wrong data. Therefore, when we set the id, we will clear the data property:

<source lang="php">/**
* Method to set the hello identifier
*
* @access public
* @param int Hello identifier
* @return void
*/
function setId($id)
{
// Set id and wipe data
$this->_id = $id;
$this->_data = null;
}</source>

Finally, we need a method to retrieve our data: getData()

getData will check if the _data property has already been set. If it has, it will simply return it. Otherwise, it will load the data from the database.

<source lang="php">/**
* Method to get a hello
* @return object with data
*/

function &getData()
{
// Load the data
if (empty( $this->_data )) {
$query = ' SELECT * FROM #__hello '.
' WHERE id = '.$this->_id;
$this->_db->setQuery( $query );
$this->_data = $this->_db->loadObject();
}
if (!$this->_data) {
$this->_data = new stdClass();
$this->_data->id = 0;
$this->_data->greeting = null;
}
return $this->_data;
}</source>

==== The Form ====

Now all that is left is to create the form that the data will go into. Since we specified our layout as form, the form will go in a file in the tmpl directory of the hello view called form.php:

<source lang="php"><?php defined('_JEXEC') or die('Restricted access'); ?>

<form action="index.php" method="post" name="adminForm" id="adminForm">
<div class="col100">
<fieldset class="adminform">
<legend><?php echo JText::_( 'Details' ); ?></legend>
<table class="admintable">
<tr>
<td width="100" align="right" class="key">
<label for="greeting">
<?php echo JText::_( 'Greeting' ); ?>:
</label>
</td>
<td>
<input class="text_area" type="text" name="greeting" id="greeting" size="32" maxlength="250" value="<?php echo $this->hello->greeting;?>" />
</td>
</tr>
</table>
</fieldset>
</div>

<div class="clr"></div>

<input type="hidden" name="option" value="com_hello" />
<input type="hidden" name="id" value="<?php echo $this->hello->id; ?>" />
<input type="hidden" name="task" value="" />
<input type="hidden" name="controller" value="hello" />
</form></source>

Notice that in addition to the input field, there is a hidden field for the id. The user doesn't need to edit the id (and shouldn't), so we silently pass it along in the form.

==== Implementing the Functionality ====

So far, our controller only handles two tasks: edit and new. However, we also have buttons to save, delete and cancel records. We need to write code to handle and perform these tasks.

=== Saving a Record ===

The logical next step is to implement the functionality to save a record. Normally, this would require some switches and logic to handle various cases, such as the difference between creating a new record (an INSERT query), and updating an existing query (an UPDATE query). Also, there are complexities involved in getting the data from the form and putting it into the query.

The Joomla! framework takes care of a lot of this for you. The JTable class makes it easy to manipulate records in the database without having to worry about writing the SQL code that lies behind these updates. It also makes it easy to transfer data from an HTML form into the database.

== Creating the Table Class ==

The JTable class is an abstract class from which you can derive child classes to work with specific tables. To use it, you simply create a class that extends the JTable class, add your database fields as properties, and override the constructor to specify the name of the table and the primary key.

Here is our JTable class:

<source lang="php"><?php
/**
* Hello World table class
*
* @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');

/**
* Hello Table class
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class TableHello extends JTable
{
/**
* Primary Key
*
* @var int
*/
var $id = null;

/**
* @var string
*/
var $greeting = null;

/**
* Constructor
*
* @param object Database connector object
*/
function TableHello( &$db ) {
parent::__construct('#__hello', 'id', $db);
}
}</source>

You will see here that we have defined our two fields: the id field and the greeting field. Then we have defined a constructor, which will call the constructor of the parent class and pass it the name of the table (hello), the name of the field which is the primary key (id), and the database connector object.

This file should be called hello.php and it will go in a directory called tables in the administrator section of our component.

== Implementing the Function in our Model ==

We are now ready to add the method to the model which will save our record. We will call this method store. Our store() method will do three things: bind the data from the form to the TableHello object, check to ensure that the record is properly formed, and store the record in the database.

Our method looks like:

<source lang="php">/**
* Method to store a record
*
* @access public
* @return boolean True on success
*/
function store()
{
$row =& $this->getTable();

$data = JRequest::get( 'post' );
// Bind the form fields to the hello table
if (!$row->bind($data)) {
$this->setError($this->_db->getErrorMsg());
return false;
}

// Make sure the hello record is valid
if (!$row->check()) {
$this->setError($this->_db->getErrorMsg());
return false;
}

// Store the web link table to the database
if (!$row->store()) {
$this->setError($this->_db->getErrorMsg());
return false;
}

return true;
}</source>

This method gets added to the hello model.

The method takes one parameter, which is an associative array of data that we want to store in the database. This can easily be retrieved from the request as will be seen later.

You will see that the first line retrieves a reference to our JTable object. If we name our table properly, we don't have to specify its name - the JModel class knows where to find it. You may recall that we called our table class TableHello and put it in a file called hello.php in the tables directory. If you follow this convention, the JModel class can create your object automatically.

The second line will retrieve the data from the form. The JRequest class makes this very easy. In this case, we are retrieving all of the variables that were submitted using the 'POST' method. These will be returned as an associative array.

The rest is easy - we bind, check and store. The bind() method will copy values from the array into the corresponding property of the table object. In this case, it will take the values of id and greeting and copy them to our TableHello object.

The check() method will perform data verification. In the JTable() class, this method simply returns true. While this doesn't provide any value for us currently, by calling this method we make it possible to do data checking using our TableHello class in the future. This method can be overridden in our TableHello class with a method that performs the appropriate checks.

The store() method will take the data that is in the object and store it in the database. If the id is 0, it will create a new record (INSERT), otherwise, it will update the existing record (UPDATE).

== Adding the Task to the Controller ==

We are now ready to add our task to the controller. Since the task that we are firing is called 'save', we must call our method 'save'. This is simple:

<source lang="php">/**
* save a record (and redirect to main page)
* @return void
*/
function save()
{
$model = $this->getModel('hello');

if ($model->store()) {
$msg = JText::_( 'Greeting Saved!' );
} else {
$msg = JText::_( 'Error Saving Greeting' );
}

// Check the table in so it can be edited.... we are done with it anyway
$link = 'index.php?option=com_hello';
$this->setRedirect($link, $msg);
}</source>

All we do is get our model and invoke the store() method. Then we use the setRedirect() method to redirect back to our list of greetings. We also pass a message along, which will be displayed at the top of the page.

=== Deleting a Record ===

=== Implementing the Function in the Model ===

In the model, we will retrieve the list of IDs to delete and call the JTable class to delete them. Here it is:

<source lang="php">/**
* Method to delete record(s)
*
* @access public
* @return boolean True on success
*/
function delete()
{
$cids = JRequest::getVar( 'cid', array(0), 'post', 'array' );
$row =& $this->getTable();

foreach($cids as $cid) {
if (!$row->delete( $cid )) {
$this->setError( $row->getErrorMsg() );
return false;
}
}

return true;
}</source>

We invoke the JRequest::getVar() method to get the data from the request, then we invoke the $row->delete() method to delete each row. By storing errors in the model we make it possible to retrieve them later if we so choose.

=== Handling the Remove Task in the Controller ===

This is similar to the save() method which handled the save task:

<source lang="php">/**
* remove record(s)
* @return void
*/
function remove()
{
$model = $this->getModel('hello');
if(!$model->delete()) {
$msg = JText::_( 'Error: One or More Greetings Could not be Deleted' );
} else {
$msg = JText::_( 'Greeting(s) Deleted' );
}

$this->setRedirect( 'index.php?option=com_hello', $msg );
}</source>

==== Cancelling the Edit Operation ====

To cancel the edit operation, all we have to do is redirect back to the main view:

<source lang="php">/**
* cancel editing a record
* @return void
*/
function cancel()
{
$msg = JText::_( 'Operation Cancelled' );
$this->setRedirect( 'index.php?option=com_hello', $msg );
}</source>

== Conclusion ==

We have now implemented a basic backend to our component. We are now able to edit the entries that are viewed in the frontend. We have demonstrated the interaction between models, views and controllers. We have shown how the JTable class can be extended to provide easy access to tables in the database. It can also be seen how the JToolBarHelper class can be used to create button bars in components to present a standardized look between components.

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

2009-10-09T19:43:47Z

Memberclicks: /* Link reference for the Joomla! engine */

{{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 tutorials, 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 articles 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 article, [[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 we will go into some basic details of the MVC pattern. In the frontend solution (site section) we have 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 to trust the default handling of the code. This is going to change in the Backend or Administration section of our Hello component.

== Site / Admin ==
Joomla! is a content management system. The frontend is used for presenting the users with content and allowing certain logged in users to manipulate the content, the backend is responsible for administrating the website framework (structuring / managing / controlling / maintaining). This division between site-content and 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 Controls, 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 chapter it should be easy to follow the tutorial in the succeeding chapters

=== 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 (''Hint'': <code>if ($user->registered) {}</code> ).

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 lend books.
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 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>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* 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 wil 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/modules/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/modules/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 ====
Again the '''activating tasks''' and '''resulting task''' definitions drop by. 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 MVC can be identified. In addation 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 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 sniplet 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 simply explained the 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

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

2009-10-09T19:42:59Z

Memberclicks: /* Link reference for the Joomla! engine */

{{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 tutorials, 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 articles 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 article, [[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 we will go into some basic details of the MVC pattern. In the frontend solution (site section) we have 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 to trust the default handling of the code. This is going to change in the Backend or Administration section of our Hello component.

== Site / Admin ==
Joomla! is a content management system. The frontend is used for presenting the users with content and allowing certain logged in users to manipulate the content, the backend is responsible for administrating the website framework (structuring / managing / controlling / maintaining). This division between site-content and 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 Controls, 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 chapter it should be easy to follow the tutorial in the succeeding chapters

=== 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 (''Hint'': <code>if ($user->registered) {}</code> ).

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 lend books.
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 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>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* 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 wil 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/modules/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/modules/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 ====
Again the '''activating tasks''' and '''resulting task''' definitions drop by. 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 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 MVC can be identified. In addation 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 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 sniplet 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 simply explained the 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

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

2009-10-09T18:23:34Z

Memberclicks: /* Mapping the example to a new to develop Joomla! component */

{{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 tutorials, 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 articles 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 article, [[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 we will go into some basic details of the MVC pattern. In the frontend solution (site section) we have 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 to trust the default handling of the code. This is going to change in the Backend or Administration section of our Hello component.

== Site / Admin ==
Joomla! is a content management system. The frontend is used for presenting the users with content and allowing certain logged in users to manipulate the content, the backend is responsible for administrating the website framework (structuring / managing / controlling / maintaining). This division between site-content and 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 Controls, 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 chapter it should be easy to follow the tutorial in the succeeding chapters

=== 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 (''Hint'': <code>if ($user->registered) {}</code> ).

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 lend books.
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 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>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* 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 wil 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/modules/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/modules/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 ====
Again the '''activating tasks''' and '''resulting task''' definitions drop by. 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 become a link for editing the specific database element.

Using the Library example, the template PHP code without looping control will contain 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 MVC can be identified. In addation 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 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 sniplet 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 simply explained the 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