Joomla! Documentation - User contributions [en]

Generating JSON output

2011-11-05T23:44:49Z

Nicholasjohn16:

PHP has native functions to encode and decode [[JSON]] data. You can encode data using the [[php:json_encode|json_encode]] function, like this:
<source lang="php">
<?php
// Set up the data to be sent in the response.
$data = array( 'some data' );

// Output the JSON data.
echo json_encode( $data );
</source>
The json_encode function can encode almost all data types, such as strings, arrays and objects, although you may need to be aware that the corresponding [[php:json_decode|json_decode]] function will only return an object (or optionally, an associative array).

It is good practice to set the MIME-type for the output correctly. In some applications you might also want to change the suggested filename to something other than the "index.php" that you will probably get by default. In the following example the suggested filename is changed to the name of the view, with a ".json" extension added.
<source lang="php">
<?php
// Set up the data to be sent in the response.
$data = array('some data');

// Get the document object.
$document =& JFactory::getDocument();

// Set the MIME type for JSON output.
$document->setMimeEncoding('application/json');

// Change the suggested filename.
JResponse::setHeader('Content-Disposition','attachment;filename="'.$view->getName().'.json"');

// Output the JSON data.
echo json_encode($data);
</source>
<noinclude>[[Category:Development]][[Category:Tutorials]]</noinclude>

J1.5:Ajax client code using MooTools

2011-11-05T23:43:30Z

Nicholasjohn16:

{{notice|This article applies to Joomla! 1.5 only as Joomla! 1.6 ships with a later version of MooTools which has a different way
of handling Ajax requests.}}

In a typical Ajax application you will want to pull some data from a server, which could be your own Joomla site or a remote web service, and update some element on the web page with the data returned by the server. There are three elements to a typical Ajax implementation:
* An HTML element whose change of state will trigger the Ajax request.
* Another HTML element where the response data will be placed. Often this will show an "Ajax loading" icon or message while the response from the server is being awaited.
* The Ajax JavaScript code itself.

Starting with the first of these, you need to identify the element on the page that will trigger the Ajax request. The element needs to be identified by a unique <tt>id</tt> attribute. For example, suppose you have a drop-down select box on your page and you want to do an Ajax request whenever the user changes the item selected. Then you must ensure that the select element has a unique <tt>id</tt> attribute like this:
<source lang="html4strict">
<select name="drop-down" id="drop-down">
<option value="1">Item 1</option>
<option value="2">Item 2</option>
<option value="3">Item 3</option>
</select>
</source>
You can generate this select list programmatically using the [[JHTML]] class like this:
<source lang="php">
<?php
$options = array();
$options[] = JHTML::_( 'select.option', '1', 'Item 1' );
$options[] = JHTML::_( 'select.option', '2', 'Item 2' );
$options[] = JHTML::_( 'select.option', '3', 'Item 3' );
echo JHTML::_( 'select.genericlist', $options, 'drop-down' );
</source>
Secondly, you need to add an HTML element that will hold the output from the Ajax call. This could be a suitably-placed DIV, which must also have a unique <tt>id</tt> attribute, like this:
<source lang="html4strict">
<div id="ajax-container"></div>
</source>
You can, of course, use the <tt>id</tt> in a selector to style the output using CSS.

Thirdly, you need to add the JavaScript code that will make the Ajax request and place the response into the screen output. You generally don't need to be concerned about loading MooTools itself as this is done automatically for you by Joomla, but sometimes you need to do this manually by adding the following code:
<source lang="php">
<?php
JHTML::_( 'behavior.mootools' );
</source>
There are many ways to add JavaScript code to the output from Joomla. One way, which avoids complex quoting, is to use the PHP "heredoc" syntax (see [http://uk.php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc] for more details) like this:
<source lang="php">
<?php
$ajax = <<<EOD
Your JavaScript code goes here.
EOD;

$doc = & JFactory::getDocument();
$doc->addScriptDeclaration( $ajax );
</source>

You can embed PHP variables in the heredoc text by surrounding them with braces, like this:
<source lang="php">
<?php
$ajax = <<<EOD
This is some JavaScript code with {$this->embedded} PHP variable in it.
EOD;

$doc = & JFactory::getDocument();
$doc->addScriptDeclaration( $ajax );
</source>

The JavaScript code must add an event handler to the element that will trigger the Ajax call. This is done in MooTools using the following call:
<source lang="javascript">
window.addEvent( 'domready', function() {

$('drop-down').addEvent( 'change', <function-declaration> );

});
</source>
where <function-declaration> is the JavaScript code that is to be called when the state of the element identified as <tt>drop-down</tt> is changed. Notice that you should always delay the call to <tt>addEvent</tt> until the DOM is ready following a page load. This is done by telling <tt>window.addEvent</tt> to hang the Ajax addEvent function onto the onDomReady event.

You don't have to hang the Ajax call on the onChange event; for example, you could use onClick as the trigger.

The <function-declaration> that you will add will be an instantiation of the MooTools Ajax class, looking something like this:
<source lang="javascript">
var a = new Ajax( {$url}, {
method: 'get',
update: $('ajax-container')
}).request();
</source>
where <tt>{$url}</tt> is a PHP variable containing the URL for the Ajax request. In this example the <tt>update</tt> argument has been used to copy the entire response from the server into the <tt>ajax-container</tt> element. This is quick and convenient, but very often you will want to process the response in some way before showing it to the user. Commonly, the response is JSON-encoded and you must decode the response and format it appropriately before updating <tt>ajax-container</tt>. To do this, use the <tt>onComplete</tt> argument to the <tt>Ajax</tt> object rather than the <tt>update</tt> argument.
<source lang="javascript">
var a = new Ajax( {$url}, {
method: 'get',
onComplete: <completion-function>
}).request();
</source>
where <completion-function> is a JavaScript function that will be called when a response from the remote server is received. Typically, this function will process the raw data from the server before pushing it into the <tt>ajax-container</tt> element.

The following is a more complete example of an Ajax function which receives data from the server in JSON format, decodes it, then pushes data from the response into <tt>ajax-container</tt>.
<source lang="javascript">
window.addEvent('domready',function() {

$('drop-down').addEvent('change',function(){

$('ajax-container').empty().addClass('ajax-loading');

var a = new Ajax({$url},{
method:'get',
onComplete:function(response){
var resp=Json.evaluate(response);

// Other code to execute when the request completes.
$('ajax-container').removeClass('ajax-loading').setHTML(output);
}
}).request();
});
});
</source>
Notice that in this example there is also some code to add, and subsequently remove, an <tt>ajax-loading</tt> CSS class from the <tt>ajax-container</tt> element. Typically, the presence of this class will cause a "spinner" graphic element to be loaded as a background image to make the user aware that the system is still alive.
<noinclude>[[Category:Development]][[Category:Topics]]</noinclude>

J1.5:Avoiding web browser same origin policy in Ajax applications

2011-11-05T23:39:32Z

Nicholasjohn16:

If you need to access a web service, using Ajax, that is running on a server that is not in your domain, then you will run up against the "same origin policy" [http://en.wikipedia.org/wiki/Same_origin_policy] that will prevent you from retrieving data from outside your own domain for security reasons. There needs to be some way to circumvent this restriction on those occasions where the web service is trusted.

The most common method of circumventing the same origin policy in Ajax implementations is to access the remote web service via a proxy running in your domain. The proxy uses an HTTP client library (such as [http://www.phpclasses.org/browse/package/3.html]) to access the remote server. This technique is usually simple enough, but can get tougher if the remote server requires authentication or uses cookies to track state between requests. On the plus side, using a proxy generally makes it easier to cache Ajax responses; something that is normally quite difficult.

To add a simple proxy to your Joomla component you simply need to add an extra task to the controller. The following code shows roughly what it might look like, given a static HTTP client class called <tt>httpClient</tt> with a method that will request a page from a remote server.
<source lang="php">
<?php
/**
* Support cross-domain Ajax request by using the component as a proxy.
* To use this facility replace "option" with "type" and "task" with "request"
* in the query that would otherwise be sent to the remote server.
*/
function proxy()
{
$uri = & JFactory::getURI();
$query = $uri->getQuery( true );
$query['option'] = $query['type'];
unset( $query['type']);
unset( $query['task']);
if (isset( $query['request'] )) {
$query['task'] = $query['request'];
unset( $query['request']);
}

// Make the API call.
$response = httpClient::call( $query );
if ($response->status != '200') {
JError::raiseError( 500, JText::_( 'Remote server error' ) );
return false;
}

// And return the response.
echo $response->data;
jexit();
}
</source>
This example also shows how to work around the situation where the remote server is also running Joomla, in which case it will require a URL containing <tt>option</tt> and <tt>task</tt> arguments that may not match those required by the proxy. For example, suppose you want to make an Ajax request to a remote server using this URL:
<source lang="text">
http://www.remoteserver.com/index.php?option=com_remotecomponent&task=remotetask&arg=something
</source>
To avoid the same origin policy you send the request to the proxy instead using this URL:
<source lang="text">
http://www.localserver.com/index.php
?option=com_localcomponent
&task=proxy&type=com_remotecomponent
&request=remotetask
&arg=something
</source>
You will need to adapt this code to meet your particular requirements, such as if you need to specify the controller in order to reach the proxy.

Adding cookie and cache support is left as an exercise for the reader.
<noinclude>[[Category:Development]]</noinclude>
[[Category:Tutorials]][[Category:Component Development]]

Generating XML output

2011-11-05T23:37:50Z

Nicholasjohn16:

Joomla supports a simple and quite efficient class, [[JSimpleXML]], which can be used to generate XML output in, for example, an Ajax implementation. However, using an object-based XML generator suffers from the drawback that it tends to be slow and memory-intensive, even though [[JSimpleXML]] is a lightweight implementation. Unless your requirements are particularly complex, directly outputting XML in string form will result in faster response times and a lower server footprint.

For example, the following code will output an XML document consisting of a root element, called <root>, containing an <items> element which itself contains one or more <item> elements with the actual data. You will need to adjust the code to cope with your particular data requirements.
<source lang="php">
<?php
$document =& JFactory::getDocument();
$document->setMimeEncoding( 'text/xml' );

// Output XML header.
echo '<?xml version="1.0" encoding="UTF-8" ?>' . "\n";

// Output root element.
echo '<root>'."\n";

// Output the data.
echo "\t".'<items>'."\n";
if(!empty($data)){
foreach($data as $datum){
echo "\t\t".'<item>'."\n";
foreach ($datum as $key => $value) {
echo "\t\t\t".'<'.$key.'>'.htmlspecialchars($value).'</'.$key.'>'."\n";
}
echo "\t\t".'</item>'."\n";
}
}
echo "\t".'</items>'."\n";

// Terminate root element.
echo '</root>'."\n";
</source>
Note that the data should be passed through [[php:htmlspecialchars|htmlspecialchars]] to ensure that HTML characters are properly escaped.

Note also that in this example some attempt has been made to "pretty print" the XML output with tabs and carriage returns. This is not strictly necessary and these extra characters can be removed if you prefer.
<noinclude>[[Category:Development]][[Category:Tutorials]]</noinclude>

Generating XML output

2011-11-05T23:35:55Z

Nicholasjohn16:

Joomla supports a simple and quite efficient class, [[JSimpleXML]], which can be used to generate XML output in, for example, an Ajax implementation. However, using an object-based XML generator suffers from the drawback that it tends to be slow and memory-intensive, even though [[JSimpleXML]] is a lightweight implementation. Unless your requirements are particularly complex, directly outputting XML in string form will result in faster response times and a lower server footprint.

For example, the following code will output an XML document consisting of a root element, called <root>, containing an <items> element which itself contains one or more <item> elements with the actual data. You will need to adjust the code to cope with your particular data requirements.
<source lang="php">
<?php
$document =& JFactory::getDocument();
$document->setMimeEncoding( 'text/xml' );

// Output XML header.
echo '<?xml version="1.0" encoding="UTF-8" ?>' . "\n";

// Output root element.
echo '<root>' . "\n";

// Output the data.
echo "\t" . '<items>' . "\n";
if (!empty( $data )) {
foreach ($data as $datum) {
echo "\t\t" . '<item>' . "\n";
foreach ($datum as $key => $value) {
echo "\t\t\t".'<'.$key.'>'.htmlspecialchars($value).'</'.$key.'>'."\n";
}
echo "\t\t" . '</item>' . "\n";
}
}
echo "\t" . '</items>' . "\n";

// Terminate root element.
echo '</root>' . "\n";
</source>
Note that the data should be passed through [[php:htmlspecialchars|htmlspecialchars]] to ensure that HTML characters are properly escaped.

Note also that in this example some attempt has been made to "pretty print" the XML output with tabs and carriage returns. This is not strictly necessary and these extra characters can be removed if you prefer.
<noinclude>[[Category:Development]][[Category:Tutorials]]</noinclude>

J1.5:Adding sortable columns to a table in a component

2011-05-23T23:50:48Z

Nicholasjohn16: /* Step 1: The model */

Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator? It's not particularly hard to do, but there are several steps required and details you need to be aware of so everything fits together properly. There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.

This procedure assumes that your component is structured according to the [[Model-View-Controller]] (MVC) design pattern. The general idea behind the procedure will still be applicable to non-MVC components if you apply a bit of imagination!

==Step 1: The Model==

The first thing is to add the filter_order and filter_order_Dir request into the __construct() function. If you've used JPagination, this step will already be familiar to you. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the filter order direction if you wish Adding this information to the State object here insures it's accessible to all of the code that might need it.

<source lang="php">
function __construct()
{
parent::__construct();

global $mainframe, $option;

$filter_order = $mainframe->getUserStateFromRequest( $option.'filter_order', 'filter_order', 'default_column_name', 'cmd' );
$filter_order_Dir = $mainframe->getUserStateFromRequest( $option.'filter_order_Dir', 'filter_order_Dir', 'asc', 'word' );

$this->setState('filter_order', $filter_order);
$this->setState('filter_order_Dir', $filter_order_Dir);
}
</source>

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the table. Most often this is the [[JModel/getData|getData()]] method, but might not be; check in the view to see which method is actually being used.

The model could pull data in from anywhere; it doesn't have to be a database, but in the vast majority of cases the model will be using the Joomla database API to submit SQL queries to a database. Assuming that to be the case, you need to adjust the query so that the sort parameters are taken into account.

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
function _buildContentOrderBy()
{
global $mainframe, $option;

$orderby = '';
$filter_order = $this->getState('filter_order');
$filter_order_Dir = $this->getState('filter_order_Dir');

/* Error handling is never a bad thing*/
if(!empty($filter_order) && !empty($filter_order_Dir) ){
$orderby = ' ORDER BY '.$filter_order.' '.$filter_order_Dir;
}

return $orderby;
}
</source>

==Step 2: The View==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
function display($tpl = null)
{

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

/* Call the state object */
$state =& $this->get( 'state' );

/* Get the values from the state object that were inserted in the model's construct function */
$lists['order_Dir'] = $state->get( 'filter_order_Dir' );
$lists['order'] = $state->get( 'filter_order' );

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

parent::display($tpl);
}

</source>

==Step 3: The Template==
Now you need to add some elements to the component layout file. The table must be included in a form. This might already be the case as, for example, you might already have implemented pagination or filtering on the table. But if the table is not yet in a form then now is the time to wrap it in <form> and </form> tags. The reason that a form is required is that the sortable columns rely on a bit of JavaScript that will submit the form with sort parameters added. Naturally, this will involve a page load, so if you would prefer an [[AJAX]]-based solution, then this procedure is not for you.

The form tags will look something like this:

<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". You may need to adjust the action URL in some cases.

You also need to add a couple of hidden fields to the form. They can be placed anywhere between the <form> and </form> tags, but generally they are placed just before the closing tag, like this:
<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->lists['order']; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->lists['order_Dir']; ?>" />
</form>
</source>

Now look at the table itself. You might have a table with static headings already, looking vaguely like this:
<source lang="php">
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</source>
You need to replace the static column names with calls to the Joomla [[JHTML]] static class, so that your code will look something like this:
<source lang="php">
<tr>
<th><?php echo JHTML::_( 'grid.sort', 'Name', 'DbNameColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
<th><?php echo JHTML::_( 'grid.sort', 'Description', 'DbDescriptionColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
</tr>
</source>
You will definitely need to adapt this code to your specific requirements. The arguments to the [[JHTML]] call are as follows:
# Must be 'grid.sort' so that [[JHTML]] will insert the correct behaviour for a sortable column.
# This is the name of the column that your visitors will actually see. You need to change this for your particular table columns.
# This is the name of the corresponding database field (column) that is to be sorted on. This will be passed to the model, most likely so it can be added to an "ORDER BY" clause in the SQL query statement.
# Must be exactly as shown here. It is the current order direction (ascending or descending) and comes from the view (see later).
# Must be exactly as shown here. It is the name of the column that the table is currently sorted on and comes from the view (see later).

In short, you need to amend the second and third arguments to each [[JHTML]] call appropriately.

Finally, if your sortable table is going to be in the front-end of your site, then you need to add a little snippet of JavaScript to the layout. Alternatively, you can add it to the view code (using [[JDocument/addScriptDeclaration|JDocument->addScriptDeclaration]]) if you would rather keep your JavaScript code in the HTML <head> section.
<source lang="javascript">
<script language="javascript" type="text/javascript">
function tableOrdering( order, dir, task )
{
var form = document.adminForm;

form.filter_order.value = order;
form.filter_order_Dir.value = dir;
document.adminForm.submit( task );
}
</script>
</source>
You don't need to add this code if your sortable table is in the Administrator as this code is loaded for you automatically anyway.

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form. In the next step you will see how the model picks up those field values and amends the database query appropriately.

==Step 4: Styling the result==
Finally. you might want to apply a bit of CSS styling to make the output a bit more attractive.

Selecting the sortable columns can only be done via their context, so you will probably need to add a CSS class to the <nowiki><table></nowiki>, the <nowiki><tr></nowiki> or to the <nowiki><th></nowiki> tags. This is what the output might look like with a class added to the <tr> tag:
<source lang="html4strict">
<tr class="sortable">
<th><a href="javascript:tableOrdering('DbName','asc','');" title="Click to sort by this column">Training provider</a></th>
<th><a href="javascript:tableOrdering('DbDescription','asc','');" title="Click to sort by this column">Location</a></th>
</tr>
</source>
To add a bit of space between the column name and the ascending/descending indicator image (a common requirement), you could then apply CSS like this:
<source lang="css">
tr.sortable th img {
margin-left: 5px;
}
</source>

==See also==
* [[JHTMLGrid]]
* [[JModel/getData|JModel->getData]]
* [[JApplication/getUserStateFromRequest|JApplication->getUserStateFromRequest]]
* [[Using JPagination in your component]]
* [[Developing a Model-View-Controller Component - Part 1]]

[[Category:Component Development]]
[[Category:Tutorials]]

J1.5:Adding sortable columns to a table in a component

2011-05-23T23:50:36Z

Nicholasjohn16: /* Step 2: The view */

Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator? It's not particularly hard to do, but there are several steps required and details you need to be aware of so everything fits together properly. There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.

This procedure assumes that your component is structured according to the [[Model-View-Controller]] (MVC) design pattern. The general idea behind the procedure will still be applicable to non-MVC components if you apply a bit of imagination!

==Step 1: The model==

The first thing is to add the filter_order and filter_order_Dir request into the __construct() function. If you've used JPagination, this step will already be familiar to you. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the filter order direction if you wish Adding this information to the State object here insures it's accessible to all of the code that might need it.

<source lang="php">
function __construct()
{
parent::__construct();

global $mainframe, $option;

$filter_order = $mainframe->getUserStateFromRequest( $option.'filter_order', 'filter_order', 'default_column_name', 'cmd' );
$filter_order_Dir = $mainframe->getUserStateFromRequest( $option.'filter_order_Dir', 'filter_order_Dir', 'asc', 'word' );

$this->setState('filter_order', $filter_order);
$this->setState('filter_order_Dir', $filter_order_Dir);
}
</source>

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the table. Most often this is the [[JModel/getData|getData()]] method, but might not be; check in the view to see which method is actually being used.

The model could pull data in from anywhere; it doesn't have to be a database, but in the vast majority of cases the model will be using the Joomla database API to submit SQL queries to a database. Assuming that to be the case, you need to adjust the query so that the sort parameters are taken into account.

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
function _buildContentOrderBy()
{
global $mainframe, $option;

$orderby = '';
$filter_order = $this->getState('filter_order');
$filter_order_Dir = $this->getState('filter_order_Dir');

/* Error handling is never a bad thing*/
if(!empty($filter_order) && !empty($filter_order_Dir) ){
$orderby = ' ORDER BY '.$filter_order.' '.$filter_order_Dir;
}

return $orderby;
}
</source>

==Step 2: The View==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
function display($tpl = null)
{

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

/* Call the state object */
$state =& $this->get( 'state' );

/* Get the values from the state object that were inserted in the model's construct function */
$lists['order_Dir'] = $state->get( 'filter_order_Dir' );
$lists['order'] = $state->get( 'filter_order' );

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

parent::display($tpl);
}

</source>

==Step 3: The Template==
Now you need to add some elements to the component layout file. The table must be included in a form. This might already be the case as, for example, you might already have implemented pagination or filtering on the table. But if the table is not yet in a form then now is the time to wrap it in <form> and </form> tags. The reason that a form is required is that the sortable columns rely on a bit of JavaScript that will submit the form with sort parameters added. Naturally, this will involve a page load, so if you would prefer an [[AJAX]]-based solution, then this procedure is not for you.

The form tags will look something like this:

<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". You may need to adjust the action URL in some cases.

You also need to add a couple of hidden fields to the form. They can be placed anywhere between the <form> and </form> tags, but generally they are placed just before the closing tag, like this:
<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->lists['order']; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->lists['order_Dir']; ?>" />
</form>
</source>

Now look at the table itself. You might have a table with static headings already, looking vaguely like this:
<source lang="php">
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</source>
You need to replace the static column names with calls to the Joomla [[JHTML]] static class, so that your code will look something like this:
<source lang="php">
<tr>
<th><?php echo JHTML::_( 'grid.sort', 'Name', 'DbNameColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
<th><?php echo JHTML::_( 'grid.sort', 'Description', 'DbDescriptionColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
</tr>
</source>
You will definitely need to adapt this code to your specific requirements. The arguments to the [[JHTML]] call are as follows:
# Must be 'grid.sort' so that [[JHTML]] will insert the correct behaviour for a sortable column.
# This is the name of the column that your visitors will actually see. You need to change this for your particular table columns.
# This is the name of the corresponding database field (column) that is to be sorted on. This will be passed to the model, most likely so it can be added to an "ORDER BY" clause in the SQL query statement.
# Must be exactly as shown here. It is the current order direction (ascending or descending) and comes from the view (see later).
# Must be exactly as shown here. It is the name of the column that the table is currently sorted on and comes from the view (see later).

In short, you need to amend the second and third arguments to each [[JHTML]] call appropriately.

Finally, if your sortable table is going to be in the front-end of your site, then you need to add a little snippet of JavaScript to the layout. Alternatively, you can add it to the view code (using [[JDocument/addScriptDeclaration|JDocument->addScriptDeclaration]]) if you would rather keep your JavaScript code in the HTML <head> section.
<source lang="javascript">
<script language="javascript" type="text/javascript">
function tableOrdering( order, dir, task )
{
var form = document.adminForm;

form.filter_order.value = order;
form.filter_order_Dir.value = dir;
document.adminForm.submit( task );
}
</script>
</source>
You don't need to add this code if your sortable table is in the Administrator as this code is loaded for you automatically anyway.

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form. In the next step you will see how the model picks up those field values and amends the database query appropriately.

==Step 4: Styling the result==
Finally. you might want to apply a bit of CSS styling to make the output a bit more attractive.

Selecting the sortable columns can only be done via their context, so you will probably need to add a CSS class to the <nowiki><table></nowiki>, the <nowiki><tr></nowiki> or to the <nowiki><th></nowiki> tags. This is what the output might look like with a class added to the <tr> tag:
<source lang="html4strict">
<tr class="sortable">
<th><a href="javascript:tableOrdering('DbName','asc','');" title="Click to sort by this column">Training provider</a></th>
<th><a href="javascript:tableOrdering('DbDescription','asc','');" title="Click to sort by this column">Location</a></th>
</tr>
</source>
To add a bit of space between the column name and the ascending/descending indicator image (a common requirement), you could then apply CSS like this:
<source lang="css">
tr.sortable th img {
margin-left: 5px;
}
</source>

==See also==
* [[JHTMLGrid]]
* [[JModel/getData|JModel->getData]]
* [[JApplication/getUserStateFromRequest|JApplication->getUserStateFromRequest]]
* [[Using JPagination in your component]]
* [[Developing a Model-View-Controller Component - Part 1]]

[[Category:Component Development]]
[[Category:Tutorials]]

J1.5:Adding sortable columns to a table in a component

2011-05-23T23:50:17Z

Nicholasjohn16: /* Step 2: The View */

Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator? It's not particularly hard to do, but there are several steps required and details you need to be aware of so everything fits together properly. There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.

This procedure assumes that your component is structured according to the [[Model-View-Controller]] (MVC) design pattern. The general idea behind the procedure will still be applicable to non-MVC components if you apply a bit of imagination!

==Step 1: The model==

The first thing is to add the filter_order and filter_order_Dir request into the __construct() function. If you've used JPagination, this step will already be familiar to you. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the filter order direction if you wish Adding this information to the State object here insures it's accessible to all of the code that might need it.

<source lang="php">
function __construct()
{
parent::__construct();

global $mainframe, $option;

$filter_order = $mainframe->getUserStateFromRequest( $option.'filter_order', 'filter_order', 'default_column_name', 'cmd' );
$filter_order_Dir = $mainframe->getUserStateFromRequest( $option.'filter_order_Dir', 'filter_order_Dir', 'asc', 'word' );

$this->setState('filter_order', $filter_order);
$this->setState('filter_order_Dir', $filter_order_Dir);
}
</source>

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the table. Most often this is the [[JModel/getData|getData()]] method, but might not be; check in the view to see which method is actually being used.

The model could pull data in from anywhere; it doesn't have to be a database, but in the vast majority of cases the model will be using the Joomla database API to submit SQL queries to a database. Assuming that to be the case, you need to adjust the query so that the sort parameters are taken into account.

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
function _buildContentOrderBy()
{
global $mainframe, $option;

$orderby = '';
$filter_order = $this->getState('filter_order');
$filter_order_Dir = $this->getState('filter_order_Dir');

/* Error handling is never a bad thing*/
if(!empty($filter_order) && !empty($filter_order_Dir) ){
$orderby = ' ORDER BY '.$filter_order.' '.$filter_order_Dir;
}

return $orderby;
}
</source>

==Step 2: The view==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
function display($tpl = null)
{

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

/* Call the state object */
$state =& $this->get( 'state' );

/* Get the values from the state object that were inserted in the model's construct function */
$lists['order_Dir'] = $state->get( 'filter_order_Dir' );
$lists['order'] = $state->get( 'filter_order' );

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

parent::display($tpl);
}

</source>

==Step 3: The Template==
Now you need to add some elements to the component layout file. The table must be included in a form. This might already be the case as, for example, you might already have implemented pagination or filtering on the table. But if the table is not yet in a form then now is the time to wrap it in <form> and </form> tags. The reason that a form is required is that the sortable columns rely on a bit of JavaScript that will submit the form with sort parameters added. Naturally, this will involve a page load, so if you would prefer an [[AJAX]]-based solution, then this procedure is not for you.

The form tags will look something like this:

<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". You may need to adjust the action URL in some cases.

You also need to add a couple of hidden fields to the form. They can be placed anywhere between the <form> and </form> tags, but generally they are placed just before the closing tag, like this:
<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->lists['order']; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->lists['order_Dir']; ?>" />
</form>
</source>

Now look at the table itself. You might have a table with static headings already, looking vaguely like this:
<source lang="php">
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</source>
You need to replace the static column names with calls to the Joomla [[JHTML]] static class, so that your code will look something like this:
<source lang="php">
<tr>
<th><?php echo JHTML::_( 'grid.sort', 'Name', 'DbNameColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
<th><?php echo JHTML::_( 'grid.sort', 'Description', 'DbDescriptionColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
</tr>
</source>
You will definitely need to adapt this code to your specific requirements. The arguments to the [[JHTML]] call are as follows:
# Must be 'grid.sort' so that [[JHTML]] will insert the correct behaviour for a sortable column.
# This is the name of the column that your visitors will actually see. You need to change this for your particular table columns.
# This is the name of the corresponding database field (column) that is to be sorted on. This will be passed to the model, most likely so it can be added to an "ORDER BY" clause in the SQL query statement.
# Must be exactly as shown here. It is the current order direction (ascending or descending) and comes from the view (see later).
# Must be exactly as shown here. It is the name of the column that the table is currently sorted on and comes from the view (see later).

In short, you need to amend the second and third arguments to each [[JHTML]] call appropriately.

Finally, if your sortable table is going to be in the front-end of your site, then you need to add a little snippet of JavaScript to the layout. Alternatively, you can add it to the view code (using [[JDocument/addScriptDeclaration|JDocument->addScriptDeclaration]]) if you would rather keep your JavaScript code in the HTML <head> section.
<source lang="javascript">
<script language="javascript" type="text/javascript">
function tableOrdering( order, dir, task )
{
var form = document.adminForm;

form.filter_order.value = order;
form.filter_order_Dir.value = dir;
document.adminForm.submit( task );
}
</script>
</source>
You don't need to add this code if your sortable table is in the Administrator as this code is loaded for you automatically anyway.

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form. In the next step you will see how the model picks up those field values and amends the database query appropriately.

==Step 4: Styling the result==
Finally. you might want to apply a bit of CSS styling to make the output a bit more attractive.

Selecting the sortable columns can only be done via their context, so you will probably need to add a CSS class to the <nowiki><table></nowiki>, the <nowiki><tr></nowiki> or to the <nowiki><th></nowiki> tags. This is what the output might look like with a class added to the <tr> tag:
<source lang="html4strict">
<tr class="sortable">
<th><a href="javascript:tableOrdering('DbName','asc','');" title="Click to sort by this column">Training provider</a></th>
<th><a href="javascript:tableOrdering('DbDescription','asc','');" title="Click to sort by this column">Location</a></th>
</tr>
</source>
To add a bit of space between the column name and the ascending/descending indicator image (a common requirement), you could then apply CSS like this:
<source lang="css">
tr.sortable th img {
margin-left: 5px;
}
</source>

==See also==
* [[JHTMLGrid]]
* [[JModel/getData|JModel->getData]]
* [[JApplication/getUserStateFromRequest|JApplication->getUserStateFromRequest]]
* [[Using JPagination in your component]]
* [[Developing a Model-View-Controller Component - Part 1]]

[[Category:Component Development]]
[[Category:Tutorials]]

J1.5:Adding sortable columns to a table in a component

2011-05-23T23:49:52Z

Nicholasjohn16: /* Step 3: The component layout file */

Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator? It's not particularly hard to do, but there are several steps required and details you need to be aware of so everything fits together properly. There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.

This procedure assumes that your component is structured according to the [[Model-View-Controller]] (MVC) design pattern. The general idea behind the procedure will still be applicable to non-MVC components if you apply a bit of imagination!

==Step 1: The model==

The first thing is to add the filter_order and filter_order_Dir request into the __construct() function. If you've used JPagination, this step will already be familiar to you. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the filter order direction if you wish Adding this information to the State object here insures it's accessible to all of the code that might need it.

<source lang="php">
function __construct()
{
parent::__construct();

global $mainframe, $option;

$filter_order = $mainframe->getUserStateFromRequest( $option.'filter_order', 'filter_order', 'default_column_name', 'cmd' );
$filter_order_Dir = $mainframe->getUserStateFromRequest( $option.'filter_order_Dir', 'filter_order_Dir', 'asc', 'word' );

$this->setState('filter_order', $filter_order);
$this->setState('filter_order_Dir', $filter_order_Dir);
}
</source>

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the table. Most often this is the [[JModel/getData|getData()]] method, but might not be; check in the view to see which method is actually being used.

The model could pull data in from anywhere; it doesn't have to be a database, but in the vast majority of cases the model will be using the Joomla database API to submit SQL queries to a database. Assuming that to be the case, you need to adjust the query so that the sort parameters are taken into account.

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
function _buildContentOrderBy()
{
global $mainframe, $option;

$orderby = '';
$filter_order = $this->getState('filter_order');
$filter_order_Dir = $this->getState('filter_order_Dir');

/* Error handling is never a bad thing*/
if(!empty($filter_order) && !empty($filter_order_Dir) ){
$orderby = ' ORDER BY '.$filter_order.' '.$filter_order_Dir;
}

return $orderby;
}
</source>

==Step 2: The view==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
function display($tpl = null)
{

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

/* Call the state object */
$state =& $this->get( 'state' );

/* Get the values from the state object that were inserted in the model's construct function */
$lists['order_Dir'] = $state->get( 'filter_order_Dir' );
$lists['order'] = $state->get( 'filter_order' );

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

parent::display($tpl);
}

</source>

==Step 3: The Template==
Now you need to add some elements to the component layout file. The table must be included in a form. This might already be the case as, for example, you might already have implemented pagination or filtering on the table. But if the table is not yet in a form then now is the time to wrap it in <form> and </form> tags. The reason that a form is required is that the sortable columns rely on a bit of JavaScript that will submit the form with sort parameters added. Naturally, this will involve a page load, so if you would prefer an [[AJAX]]-based solution, then this procedure is not for you.

The form tags will look something like this:

<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". You may need to adjust the action URL in some cases.

You also need to add a couple of hidden fields to the form. They can be placed anywhere between the <form> and </form> tags, but generally they are placed just before the closing tag, like this:
<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->lists['order']; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->lists['order_Dir']; ?>" />
</form>
</source>

Now look at the table itself. You might have a table with static headings already, looking vaguely like this:
<source lang="php">
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</source>
You need to replace the static column names with calls to the Joomla [[JHTML]] static class, so that your code will look something like this:
<source lang="php">
<tr>
<th><?php echo JHTML::_( 'grid.sort', 'Name', 'DbNameColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
<th><?php echo JHTML::_( 'grid.sort', 'Description', 'DbDescriptionColumn', $this->lists['order_Dir'], $this->lists['order']); ?></th>
</tr>
</source>
You will definitely need to adapt this code to your specific requirements. The arguments to the [[JHTML]] call are as follows:
# Must be 'grid.sort' so that [[JHTML]] will insert the correct behaviour for a sortable column.
# This is the name of the column that your visitors will actually see. You need to change this for your particular table columns.
# This is the name of the corresponding database field (column) that is to be sorted on. This will be passed to the model, most likely so it can be added to an "ORDER BY" clause in the SQL query statement.
# Must be exactly as shown here. It is the current order direction (ascending or descending) and comes from the view (see later).
# Must be exactly as shown here. It is the name of the column that the table is currently sorted on and comes from the view (see later).

In short, you need to amend the second and third arguments to each [[JHTML]] call appropriately.

Finally, if your sortable table is going to be in the front-end of your site, then you need to add a little snippet of JavaScript to the layout. Alternatively, you can add it to the view code (using [[JDocument/addScriptDeclaration|JDocument->addScriptDeclaration]]) if you would rather keep your JavaScript code in the HTML <head> section.
<source lang="javascript">
<script language="javascript" type="text/javascript">
function tableOrdering( order, dir, task )
{
var form = document.adminForm;

form.filter_order.value = order;
form.filter_order_Dir.value = dir;
document.adminForm.submit( task );
}
</script>
</source>
You don't need to add this code if your sortable table is in the Administrator as this code is loaded for you automatically anyway.

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form. In the next step you will see how the model picks up those field values and amends the database query appropriately.

==Step 4: Styling the result==
Finally. you might want to apply a bit of CSS styling to make the output a bit more attractive.

Selecting the sortable columns can only be done via their context, so you will probably need to add a CSS class to the <nowiki><table></nowiki>, the <nowiki><tr></nowiki> or to the <nowiki><th></nowiki> tags. This is what the output might look like with a class added to the <tr> tag:
<source lang="html4strict">
<tr class="sortable">
<th><a href="javascript:tableOrdering('DbName','asc','');" title="Click to sort by this column">Training provider</a></th>
<th><a href="javascript:tableOrdering('DbDescription','asc','');" title="Click to sort by this column">Location</a></th>
</tr>
</source>
To add a bit of space between the column name and the ascending/descending indicator image (a common requirement), you could then apply CSS like this:
<source lang="css">
tr.sortable th img {
margin-left: 5px;
}
</source>

==See also==
* [[JHTMLGrid]]
* [[JModel/getData|JModel->getData]]
* [[JApplication/getUserStateFromRequest|JApplication->getUserStateFromRequest]]
* [[Using JPagination in your component]]
* [[Developing a Model-View-Controller Component - Part 1]]

[[Category:Component Development]]
[[Category:Tutorials]]

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

2011-05-21T22:03:15Z

Nicholasjohn16: /* The Hellos Template */

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

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

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

== Creating the Basic Framework ==

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

Here is the listing for hello.php:

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

// No direct access

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

// Require the base controller

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

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

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

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

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

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

==== The Hellos Model ====

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

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

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

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

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

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

return $query;
}</source>

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

Here is the getData() method:

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

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

The completed model looks like:

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

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

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

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

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

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

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

This file is saved as models/hellos.php.

==== The Hellos View ====

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

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

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

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

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

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

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

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

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

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

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

==== The Hellos Template ====

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

Here is our template:

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

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

</form></source>

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

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

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

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

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

== Conclusion ==

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

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

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

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

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

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

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

== Contributors ==
* staalanden
* jamesconroyuk

== Download ==

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

[[Category:Tutorials]]
[[Category:Component Development]]

J1.5:Developing a MVC Component/Introduction

2011-05-16T05:04:59Z

Nicholasjohn16: /* Creating the Entry Point */ Missing a colon in JRequest::getWord()

== Introduction ==
A software framework is the base of an application that can be used by a developer. The framework in Joomla! 1.5 unleashes a great deal of power for them. The Joomla! code has been designed for extensibility. This tutorial will guide you through the process of developing a component using the framework.

The scope of this project will be to develop a simple Hello World! component. In future tutorials, this simple framework will be built upon to show the full power and versatility of the MVC design pattern in Joomla!

== Requirements ==
You need Joomla! 1.5 or greater for this tutorial.

== Introduction to Model-View-Controller ==
[[image:MVC basics.png|frameless|right]]While the idea behind a component may seem extremely simple, code can quickly become very complex as additional features are added or the interface is customized.

Model-View-Controller (herein referred to as MVC) is a software design pattern that can be used to organize code in such a way that the business logic and data presentation are separate. The premise behind this approach is that if the business logic is grouped into one section, then the interface and user interaction that surrounds the data can be revised and customized without having to reprogram the business logic. MVC was originally developed to map the traditional input, processing, output roles into a logical GUI architecture.

These three main roles are the basis for the Joomla MVC. They are described here in brief, but for a more thorough explanation, please refer to the links provided at the end of this tutorial.

=== Model ===
The model is the part of the component that encapsulates the application's data. It will often provide routines to manage and manipulate this data in a meaningful way in addition to routines that retrieve the data from the model. In our case, the model will contain methods to add, remove and update information about the greetings in the database. It will also contain methods to retrieve the list of greetings from the database. In general, the underlying data access technique should be encapsulated in the model. In this way, if an application is to be moved from a system that utilizes a flat file to store its information to a system that uses a database, the model is the only element that needs to be changed, not the view or the controller.

=== View ===
The view is the part of the component that is used to render the data from the model in a manner that is suitable for interaction. For a web-based application, the view would generally be an HTML page that is returned to the data. The view pulls data from the model (which is passed to it from the controller) and feeds the data into a template which is populated and presented to the user. The view does not cause the data to be modified in any way, it only displays data retrieved from the model.

=== Controller ===
The controller is responsible for responding to user actions. In the case of a web application, a user action is (generally) a page request. The controller will determine what request is being made by the user and respond appropriately by triggering the model to manipulate the data appropriately and passing the model into the view. The controller does not display the data in the model, it only triggers methods in the model which modify the data, and then pass the model into the view which displays the data.

=== MVC connection ===
[[image:MVC joomla.png|frameless|right]]The simplified picture on the right depicts the basic components being used within Joomla. Besides the Model, the View and the Controller, an Entry Point has been added that is depicted as a small circle. Attached to the viewer (view) a Template has been added. With these five components you should be able to understand this tutorial about making a basic Joomla! MVC component.

Part 1 of the tutorial only focuses on the Controller and the View (with the use of the Template); these are marked with the blue colour in the picture. Part 2 adds and Part 3 extends the model functionality for the data manipulation abstraction; marked with the green colour in the picture.

Keep in mind that this simplified picture only applies for the site section (i.e the front-end). An identical picture is applicable for the admin section (i.e. the back-end). The administrative section is taken care of in Parts 4 through 6 of this component development tutorial. Both the site and the admin section are maintained and configured in an XML based installation file (typically termed a manifest file).

== Joomla! MVC Implementation ==
In Joomla!, the MVC pattern is implemented using three classes: [http://api.joomla.org/Joomla-Framework/Application/JModel.html JModel], [http://api.joomla.org/Joomla-Framework/Application/JView.html JView] and [http://api.joomla.org/Joomla-Framework/Application/JController.html JController]. For more detailed information about these classes, please refer to the API reference documentation (WIP).

For learning purposes and debugging, adding a run-time debugger to your Joomla! site might be a good extension especially during development of your (tutorial) component. A good example is the community project [http://extensions.joomla.org/extensions/miscellaneous/development/1509/details J!Dump] that has the advantage of being a pop-up which leaves the view output unchanged. The J!Dump system allows you to view not only your development properties but also the methods.

== Creating a Component ==
For our basic component, we only require five files:

* site/hello.php - this is the entry point to our component
* site/controller.php - this file contains our base controller
* site/views/hello/view.html.php - this file retrieves the necessary data and pushes it into the template
* site/views/hello/tmpl/default.php - this is the template for our output
* hello.xml - this is an XML (manifest) file that tells Joomla! how to install our component.

Remember that the filename for the entry point must have the same name of the component. For example, if you call your component "Very Intricate Name Component", at install time (see below in the hello.xml section) Joomla! will create the folder com_veryintricatenamecomponent and the entry point php file must be named veryintricatenamecomponent.php otherwise it will not work. Be aware that use of some special characters, notibly the underscore '_', may have special meaning in Joomla and should be avoided in component names or files.

The site directory here is for the parts of the component which are installed in the front end site.

=== Naming conventions ===

Main article: [[Naming conventions]]

At this point it is important to say that some words are reserved for using in component or its class names, and violating some of that will produce a hard for debugging error. One of them is "view" (in any character case) for view class (subclass of JView) and controller class (subclass of JController), because view class need to have first part of name the same as controller class name, and component name (although violating of last one won't produce an error, it's just a useful convention).

All filenames and foldernames for models, views and controllers must be lower-case in order to operate well on Unix/Linux-systems.

=== Creating the Entry Point ===
{{review}}
Joomla! is always accessed through a single point of entry: index.php for the Site Application or administrator/index.php for the Administrator Application. The application will then load the required component, based on the value of 'option' in the URL or in the POST data. For our component, the URL would be:

<source lang="php">index.php?option=com_hello&view=hello</source>

This will load our main file, which can be seen as the single point of entry for our component: components/com_hello/hello.php.

The code for this file is fairly typical across components.

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

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

// Require the base controller

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

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

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

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

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

The first statement is a security check.

JPATH_COMPONENT is the absolute path to the current component, in our case components/com_hello. If you specifically need either the Site component or the Administrator component, you can use JPATH_COMPONENT_SITE or JPATH_COMPONENT_ADMINISTRATOR.

DS is the directory separator of your system: either '/' or '\'. This is automatically set by the framework so the developer doesn't have to worry about developing different versions for different server OSs. The 'DS' constant should always be used when referring to files on the local server.

After loading the base controller, we check if a specific controller is needed. In this component, the base controller is the only controller, but we will leave this conditional check "in place" for future use.

JRequest::getWord() finds a word variable in the URL or the POST data. So if our URL is index.php?option=com_hello&controller=controller_name, then we can retrieve our controller name in our component using: echo JRequest::getWord('controller');

Now we have our base controller 'HelloController' in com_hello/controller.php, and, if needed, additional controllers like 'HelloControllerController1' in com_hello/controllers/controller1.php. Using this standard naming scheme will make things easy later on: '{Componentname}{Controller}{Controllername}'

After the controller is created, we instruct the controller to execute the task, as defined in the URL: index.php?option=com_hello&task=sometask. If no task is set, the default task 'display' will be assumed. When display is used, the 'view' variable will decide what will be displayed. Other common tasks are save, edit, new...

The controller might decide to redirect the page, usually after a task like 'save' has been completed. This last statement takes care of the actual redirection.

The main entry point (hello.php) essentially passes control to the controller, which handles performing the task that was specified in the request.

Note that we don't use a closing php tag in this file: ?>. The reason for this is that we will not have any unwanted whitespace in the output code. This is default practice since Joomla! 1.5, and will be used for all php-only files.

=== Creating the Controller ===
Our component only has one task - greet the world. Therefore, the controller will be very simple. No data manipulation is required. All that needs to be done is the appropriate view loaded. We will have only one method in our controller: display(). Most of the required functionality is built into the JController class, so all that we need to do is invoke the JController::display() method.

The code for the base controller site/controller.php is:
<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
* @license GNU/GPL
*/

// No direct access

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

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

/**
* Hello World Component Controller
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HelloController extends JController
{
/**
* Method to display the view
*
* @access public
*/
function display()
{
parent::display();
}

}</source>

The JController constructor will always register a display() task and unless otherwise specified (using the registerDefaultTask() method), it will set it as the default task.

This barebones display() method isn't really even necessary since all it does is invoke the parent constructor. However, it is a good visual clue to indicate what is happening in the controller.

The JController::display() method will determine the name of the view and layout from the request and load that view and set the layout. When you create a menu item for your component, the menu manager will allow the administrator to select the view that they would like the menu link to display and to specify the layout. A view usually refers to a view of a certain set of data (i.e. a list of cars, a list of events, a single car, a single event). A layout is a way that that view is organized.

In our component, we will have a single view called hello, and a single layout (default).

=== Creating the View ===
The task of the view is very simple: It retrieves the data to be displayed and pushes it into the template. Data is pushed into the template using the JView::assignRef method.
<small>(Note: The key (the first argument) passed to the assignRef method cannot be preceded by an underscore i.e. $this->assignRef('_greeting',$greeting). Doing so will cause the assignRef method to return false and your variable will not be pushed into the template.)</small>

The code for the view at site/views/hello/view.html.php:

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

// no direct access

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

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

/**
* HTML View class for the HelloWorld Component
*
* @package HelloWorld
*/

class HelloViewHello extends JView
{
function display($tpl = null)
{
$greeting = "Hello World!";
$this->assignRef( 'greeting', $greeting );

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

==== Creating the Template ====

Joomla! templates/layouts are regular PHP files that are used to layout the data from the view in a particular manner. The variables assigned by the JView::assignRef method can be accessed from the template using $this->{propertyname} (see the template code below for an example).

Our template is very simple: we only want to display the greeting that was passed in from the view - this file is:<br>site/views/hello/tmpl/default.php:

<source lang="php"><?php

// No direct access

defined('_JEXEC') or die('Restricted access'); ?>
<h1><?php echo $this->greeting; ?></h1></source>

=== Wrapping It All Up - Creating the hello.xml File ===
It is possible to install a component manually by copying the files using an FTP client and modifying the database tables. It is more efficient to create a package file that will allow the Joomla! Installer to do this for you. This package file contains a variety of information:

* basic descriptive details about your component (i.e. name), and optionally, a description, copyright and license information.
* a list of files that need to be copied.
* optionally, a PHP file that performs additional install and uninstall operations.
* optionally, an SQL file which contains database queries that should be executed upon install/uninstall

The format of the XML file at hello.xml is as follows:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>1.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
</files>

</administration>
</install></source>

{{notice|
Put this xml file, also called manifest, in the root of your package (because the installer will take its path as the root path for all other files).{{1}}Don't include itself under <files>...}}

You may have noticed the manifest source above mentioned files we have not discussed. These are the index.html files and the admin files. An index.html file is placed in each directory to prevent prying users from getting a directory listing. If there is no index.html file, some web servers will list the directory contents. This is often undesirable. These files have the simple line:

<source lang="php"><html><body bgcolor="#FFFFFF"></body></html></source>

It will simply display a blank page.

The hello.php file in the admin folder is the entry point for the our component's admin section. Since our component has no administrator needs (yet), this file will have the same content as the index.html files for now.

If you've followed along, you can visit URL index.php?option=com_hello to see your work.

== 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 ==
* mjaz
* staalanden
* dannystaple
* Stilgar

== Download ==
The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8108/29433/com_hello1_01.zip com_hello1_01]

[[Category:Tutorials]]
[[Category:Component Development]]