Joomla! Documentation - User contributions [en]

Coding style and standards

2012-04-21T23:44:28Z

Kissaki: /* Language Keys */

{{RightTOC}}

<div style="background-color: #ffc; border: 2px solid orange; padding: 0.5em;">

==New Coding Standards Apply as of December 2011==
''As of December 2011, this document has been replaced by newer [http://developer.joomla.org/coding-standards.html coding standards on the Joomla Developer Network]. Please use that document for the current versions of Joomla and the Joomla Platform. The older document is kept here for historical reference.''
</div>

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask. There is [[Joomla_CodeSniffer|a tool available]] to help your code conform to the standards.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
*:Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition) {
case 1:
doAction1();
break;
case 2:
doAction2();
break;
default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow this convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found on http://www.phpdoc.org/. There is a [[/Comments|standard for inline documentation comments]].

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - '''code''' that has been "commented out" is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

'''NOTE: This part has to be rewritten for 1.6 (JM)'''

Except for the most common of words, such as "Yes", "No", "Show", "Hide" '''all language keys should be namespaced''' to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays.

Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

''TODO: Link to page with "common" strings that can be used for typical actions in components, such as "Save"''

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

As a further example: ''Toolbar'' and ''Linkbar text'' should be prefixed ''Toolbar'' and ''Linkbar'' respectively.

The '''language keys''' should be written '''as naturally as possible''' with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by '''common sense''', but must be '''consistent'''. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each '''phrase''' must be represented by a '''single language key''', using '''sprintf as appropriate''' to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If '''more than one dynamic string''' is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via ''%[number]$[printf_type]'' as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[Creating a content plugin|the relevant tutorial]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

[[Category:Development]]

Coding style and standards

2012-04-21T23:44:00Z

Kissaki: /* Language Keys */

{{RightTOC}}

<div style="background-color: #ffc; border: 2px solid orange; padding: 0.5em;">

==New Coding Standards Apply as of December 2011==
''As of December 2011, this document has been replaced by newer [http://developer.joomla.org/coding-standards.html coding standards on the Joomla Developer Network]. Please use that document for the current versions of Joomla and the Joomla Platform. The older document is kept here for historical reference.''
</div>

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask. There is [[Joomla_CodeSniffer|a tool available]] to help your code conform to the standards.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
*:Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition) {
case 1:
doAction1();
break;
case 2:
doAction2();
break;
default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow this convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found on http://www.phpdoc.org/. There is a [[/Comments|standard for inline documentation comments]].

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - '''code''' that has been "commented out" is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

'''NOTE: This part has to be rewritten for 1.6 (JM)'''

Except for the most common of words, such as "Yes", "No", "Show", "Hide" '''all language keys should be namespaced''' to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays.

Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

''TODO: Link to page with "common" strings that can be used for typical actions in components, such as "Save"''

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

As a further example: ''Toolbar'' and ''Linkbar text'' should be prefixed ''Toolbar'' and ''Linkbar'' respectively.

The '''language keys''' should be written '''as naturally as possible''' with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by '''common sense''', but must be '''consistent'''. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each '''phrase''' must be represented by a '''single language key''', using '''sprintf as appropriate''' to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If more than one dynamic string is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via ''%[number]$[printf_type]'' as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[Creating a content plugin|the relevant tutorial]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

[[Category:Development]]

Coding style and standards

2012-04-21T23:40:08Z

Kissaki: /* Language Keys */

{{RightTOC}}

<div style="background-color: #ffc; border: 2px solid orange; padding: 0.5em;">

==New Coding Standards Apply as of December 2011==
''As of December 2011, this document has been replaced by newer [http://developer.joomla.org/coding-standards.html coding standards on the Joomla Developer Network]. Please use that document for the current versions of Joomla and the Joomla Platform. The older document is kept here for historical reference.''
</div>

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask. There is [[Joomla_CodeSniffer|a tool available]] to help your code conform to the standards.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
*:Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition) {
case 1:
doAction1();
break;
case 2:
doAction2();
break;
default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow this convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found on http://www.phpdoc.org/. There is a [[/Comments|standard for inline documentation comments]].

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - '''code''' that has been "commented out" is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

'''NOTE: This part has to be rewritten for 1.6 (JM)'''

Except for the most common of words, such as "Yes", "No", "Show", "Hide" '''all language keys should be namespaced''' to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays.

Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

''TODO: Link to page with "common" strings that can be used for typical actions in components, such as "Save"''

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

As a further example: ''Toolbar'' and ''Linkbar text'' should be prefixed ''Toolbar'' and ''Linkbar'' respectively.

The '''language keys''' should be written '''as naturally as possible''' with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by '''common sense''', but must be '''consistent'''. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each '''phrase''' must be represented by a '''single language key''', using '''sprintf as appropriate''' to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If more than one dynamic string is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via %[number]$[printf_type] as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[Creating a content plugin|the relevant tutorial]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

[[Category:Development]]

Coding style and standards

2012-04-21T23:18:55Z

Kissaki: /* Language Keys */

{{RightTOC}}

<div style="background-color: #ffc; border: 2px solid orange; padding: 0.5em;">

==New Coding Standards Apply as of December 2011==
''As of December 2011, this document has been replaced by newer [http://developer.joomla.org/coding-standards.html coding standards on the Joomla Developer Network]. Please use that document for the current versions of Joomla and the Joomla Platform. The older document is kept here for historical reference.''
</div>

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask. There is [[Joomla_CodeSniffer|a tool available]] to help your code conform to the standards.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
*:Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition) {
case 1:
doAction1();
break;
case 2:
doAction2();
break;
default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow this convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found on http://www.phpdoc.org/. There is a [[/Comments|standard for inline documentation comments]].

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - '''code''' that has been "commented out" is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

NOTE: This part has to be rewritten for 1.6 (JM)

Except for the most common of words, such as "Yes", "No", "Show", "Hide" all language keys should be namespaced to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays. Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

TODO: Link to page with "common" strings that can be used for typical actions in components, such as "Save"

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

Toolbar and Linkbar text should be prefixed Toolbar and Linkbar respectively.

The language keys should be written as naturally as possible with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by common sense, but must be consistent. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each phrase must be represented by a single language key, using sprintf as appropriate to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If more than one dynamic string is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via %[number]$[printf_type] as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[Creating a content plugin|the relevant tutorial]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

[[Category:Development]]

API17:Platform

2011-06-04T22:45:30Z

Kissaki: display references

{{Framework}}
{{Description:Platform}}

The following Platform classes are present in version 11.1.
For other versions see [[Platform]]
{| class="wikitable sortable"
|Class name
|Subpackage
|-
|[[ApplicationException/11.1|ApplicationException]]
|[[Subpackage Application/11.1|Application]]
|-
|[[DatabaseException/11.1|DatabaseException]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JAccess/11.1|JAccess]]
|[[Subpackage Access/11.1|Access]]
|-
|[[JAdapter/11.1|JAdapter]]
|[[Subpackage Base/11.1|Base]]
|-
|[[JAdapterInstance/11.1|JAdapterInstance]]
|[[Subpackage Base/11.1|Base]]
|-
|[[JApplication/11.1|JApplication]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JApplicationHelper/11.1|JApplicationHelper]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JArchive/11.1|JArchive]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JArchiveBzip2/11.1|JArchiveBzip2]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JArchiveGzip/11.1|JArchiveGzip]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JArchiveTar/11.1|JArchiveTar]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JArchiveZip/11.1|JArchiveZip]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JArrayHelper/11.1|JArrayHelper]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JAuthentication/11.1|JAuthentication]]
|[[Subpackage User/11.1|User]]
|-
|[[JAuthenticationResponse/11.1|JAuthenticationResponse]]
|[[Subpackage User/11.1|User]]
|-
|[[JBrowser/11.1|JBrowser]]
|[[Subpackage Environment/11.1|Environment]]
|-
|[[JBuffer/11.1|JBuffer]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JButton/11.1|JButton]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JButtonConfirm/11.1|JButtonConfirm]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JButtonCustom/11.1|JButtonCustom]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JButtonHelp/11.1|JButtonHelp]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JButtonLink/11.1|JButtonLink]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JButtonPopup/11.1|JButtonPopup]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JButtonSeparator/11.1|JButtonSeparator]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JButtonStandard/11.1|JButtonStandard]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JCache/11.1|JCache]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheController/11.1|JCacheController]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheControllerCallback/11.1|JCacheControllerCallback]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheControllerOutput/11.1|JCacheControllerOutput]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheControllerPage/11.1|JCacheControllerPage]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheControllerView/11.1|JCacheControllerView]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorage/11.1|JCacheStorage]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageApc/11.1|JCacheStorageApc]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageCachelite/11.1|JCacheStorageCachelite]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageEaccelerator/11.1|JCacheStorageEaccelerator]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageFile/11.1|JCacheStorageFile]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageHelper/11.1|JCacheStorageHelper]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageMemcache/11.1|JCacheStorageMemcache]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageWincache/11.1|JCacheStorageWincache]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCacheStorageXcache/11.1|JCacheStorageXcache]]
|[[Subpackage Cache/11.1|Cache]]
|-
|[[JCategories/11.1|JCategories]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JCategoryNode/11.1|JCategoryNode]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JCli/11.1|JCli]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JClientHelper/11.1|JClientHelper]]
|[[Subpackage Client/11.1|Client]]
|-
|[[JComponentHelper/11.1|JComponentHelper]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JController/11.1|JController]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JControllerAdmin/11.1|JControllerAdmin]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JControllerForm/11.1|JControllerForm]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JDaemon/11.1|JDaemon]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JDatabase/11.1|JDatabase]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseExporterMySQL/11.1|JDatabaseExporterMySQL]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseExporterMySQLi/11.1|JDatabaseExporterMySQLi]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseImporterMySQL/11.1|JDatabaseImporterMySQL]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseImporterMySQLi/11.1|JDatabaseImporterMySQLi]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseMySQL/11.1|JDatabaseMySQL]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseMySQLi/11.1|JDatabaseMySQLi]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQuery/11.1|JDatabaseQuery]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQueryElement/11.1|JDatabaseQueryElement]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQueryElementMySQL/11.1|JDatabaseQueryElementMySQL]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQueryElementMySQLi/11.1|JDatabaseQueryElementMySQLi]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQueryElementSQLAzure/11.1|JDatabaseQueryElementSQLAzure]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQueryElementSQLSrv/11.1|JDatabaseQueryElementSQLSrv]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQueryMySQL/11.1|JDatabaseQueryMySQL]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQueryMySQLi/11.1|JDatabaseQueryMySQLi]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQuerySQLAzure/11.1|JDatabaseQuerySQLAzure]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseQuerySQLSrv/11.1|JDatabaseQuerySQLSrv]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseSQLAzure/11.1|JDatabaseSQLAzure]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDatabaseSQLSrv/11.1|JDatabaseSQLSrv]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JDate/11.1|JDate]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JDispatcher/11.1|JDispatcher]]
|[[Subpackage Event/11.1|Event]]
|-
|[[JDocument/11.1|JDocument]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentError/11.1|JDocumentError]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentFeed/11.1|JDocumentFeed]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentHTML/11.1|JDocumentHTML]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentJSON/11.1|JDocumentJSON]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRAW/11.1|JDocumentRAW]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRenderer/11.1|JDocumentRenderer]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRendererAtom/11.1|JDocumentRendererAtom]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRendererComponent/11.1|JDocumentRendererComponent]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRendererHead/11.1|JDocumentRendererHead]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRendererMessage/11.1|JDocumentRendererMessage]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRendererModule/11.1|JDocumentRendererModule]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRendererModules/11.1|JDocumentRendererModules]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentRendererRSS/11.1|JDocumentRendererRSS]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JDocumentXML/11.1|JDocumentXML]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JEditor/11.1|JEditor]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElement/11.1|JElement]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementCalendar/11.1|JElementCalendar]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementCategory/11.1|JElementCategory]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementComponentLayouts/11.1|JElementComponentLayouts]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementContentLanguages/11.1|JElementContentLanguages]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementEditors/11.1|JElementEditors]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementFilelist/11.1|JElementFilelist]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementFolderlist/11.1|JElementFolderlist]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementHelpsites/11.1|JElementHelpsites]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementHidden/11.1|JElementHidden]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementImageList/11.1|JElementImageList]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementLanguages/11.1|JElementLanguages]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementList/11.1|JElementList]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementMenu/11.1|JElementMenu]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementMenuItem/11.1|JElementMenuItem]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementModuleLayouts/11.1|JElementModuleLayouts]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementPassword/11.1|JElementPassword]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementRadio/11.1|JElementRadio]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementSpacer/11.1|JElementSpacer]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementSQL/11.1|JElementSQL]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementTemplateStyle/11.1|JElementTemplateStyle]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementText/11.1|JElementText]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementTextarea/11.1|JElementTextarea]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementTimezones/11.1|JElementTimezones]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JElementUserGroup/11.1|JElementUserGroup]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JError/11.1|JError]]
|[[Subpackage Error/11.1|Error]]
|-
|[[JEvent/11.1|JEvent]]
|[[Subpackage Event/11.1|Event]]
|-
|[[JException/11.1|JException]]
|[[Subpackage Error/11.1|Error]]
|-
|[[JExtension/11.1|JExtension]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JFactory/11.1|JFactory]]
|
|-
|[[JFeedEnclosure/11.1|JFeedEnclosure]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JFeedImage/11.1|JFeedImage]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JFeedItem/11.1|JFeedItem]]
|[[Subpackage Document/11.1|Document]]
|-
|[[JFile/11.1|JFile]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JFilesystemHelper/11.1|JFilesystemHelper]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JFilterInput/11.1|JFilterInput]]
|[[Subpackage Filter/11.1|Filter]]
|-
|[[JFilterOutput/11.1|JFilterOutput]]
|[[Subpackage Filter/11.1|Filter]]
|-
|[[JFolder/11.1|JFolder]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JForm/11.1|JForm]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormField/11.1|JFormField]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldAccessLevel/11.1|JFormFieldAccessLevel]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldCacheHandler/11.1|JFormFieldCacheHandler]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldCalendar/11.1|JFormFieldCalendar]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldCategory/11.1|JFormFieldCategory]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldCheckbox/11.1|JFormFieldCheckbox]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldCheckboxes/11.1|JFormFieldCheckboxes]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldCombo/11.1|JFormFieldCombo]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldComponentLayout/11.1|JFormFieldComponentLayout]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldContentLanguage/11.1|JFormFieldContentLanguage]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldEditor/11.1|JFormFieldEditor]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldEditors/11.1|JFormFieldEditors]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldEMail/11.1|JFormFieldEMail]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldFile/11.1|JFormFieldFile]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldFileList/11.1|JFormFieldFileList]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldFolderList/11.1|JFormFieldFolderList]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldGroupedList/11.1|JFormFieldGroupedList]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldHelpsite/11.1|JFormFieldHelpsite]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldHidden/11.1|JFormFieldHidden]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldImageList/11.1|JFormFieldImageList]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldInteger/11.1|JFormFieldInteger]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldLanguage/11.1|JFormFieldLanguage]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldList/11.1|JFormFieldList]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldMedia/11.1|JFormFieldMedia]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldMenu/11.1|JFormFieldMenu]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldMenuItem/11.1|JFormFieldMenuItem]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldModuleLayout/11.1|JFormFieldModuleLayout]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldPassword/11.1|JFormFieldPassword]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldRadio/11.1|JFormFieldRadio]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldRules/11.1|JFormFieldRules]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldSessionHandler/11.1|JFormFieldSessionHandler]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldSpacer/11.1|JFormFieldSpacer]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldSQL/11.1|JFormFieldSQL]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldTel/11.1|JFormFieldTel]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldTemplateStyle/11.1|JFormFieldTemplateStyle]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldText/11.1|JFormFieldText]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldTextarea/11.1|JFormFieldTextarea]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldTimezone/11.1|JFormFieldTimezone]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldUrl/11.1|JFormFieldUrl]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldUser/11.1|JFormFieldUser]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormFieldUsergroup/11.1|JFormFieldUsergroup]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormHelper/11.1|JFormHelper]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormRule/11.1|JFormRule]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormRuleBoolean/11.1|JFormRuleBoolean]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormRuleEmail/11.1|JFormRuleEmail]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormRuleEquals/11.1|JFormRuleEquals]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormRuleRules/11.1|JFormRuleRules]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormRuleTel/11.1|JFormRuleTel]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFormRuleUsername/11.1|JFormRuleUsername]]
|[[Subpackage Form/11.1|Form]]
|-
|[[JFTP/11.1|JFTP]]
|[[Subpackage Client/11.1|Client]]
|-
|[[JHelp/11.1|JHelp]]
|[[Subpackage Language/11.1|Language]]
|-
|[[JHtml/11.1|JHtml]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlAccess/11.1|JHtmlAccess]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlBehavior/11.1|JHtmlBehavior]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlCategory/11.1|JHtmlCategory]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlContent/11.1|JHtmlContent]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlContentLanguage/11.1|JHtmlContentLanguage]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlEmail/11.1|JHtmlEmail]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlForm/11.1|JHtmlForm]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlGrid/11.1|JHtmlGrid]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlImage/11.1|JHtmlImage]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlJGrid/11.1|JHtmlJGrid]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlList/11.1|JHtmlList]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlMenu/11.1|JHtmlMenu]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlNumber/11.1|JHtmlNumber]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlRules/11.1|JHtmlRules]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlSelect/11.1|JHtmlSelect]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlSliders/11.1|JHtmlSliders]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlString/11.1|JHtmlString]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlTabs/11.1|JHtmlTabs]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHtmlTel/11.1|JHtmlTel]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JHttp/11.1|JHttp]]
|[[Subpackage Client/11.1|Client]]
|-
|[[JHttpResponse/11.1|JHttpResponse]]
|[[Subpackage Client/11.1|Client]]
|-
|[[JInput/11.1|JInput]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JInputCLI/11.1|JInputCLI]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JInputCookie/11.1|JInputCookie]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JInputFiles/11.1|JInputFiles]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JInstaller/11.1|JInstaller]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerComponent/11.1|JInstallerComponent]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerFile/11.1|JInstallerFile]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerHelper/11.1|JInstallerHelper]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerLanguage/11.1|JInstallerLanguage]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerLibrary/11.1|JInstallerLibrary]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerModule/11.1|JInstallerModule]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerPackage/11.1|JInstallerPackage]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerPlugin/11.1|JInstallerPlugin]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JInstallerTemplate/11.1|JInstallerTemplate]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JLanguage/11.1|JLanguage]]
|[[Subpackage Language/11.1|Language]]
|-
|[[JLanguageHelper/11.1|JLanguageHelper]]
|[[Subpackage Language/11.1|Language]]
|-
|[[JLanguageTransliterate/11.1|JLanguageTransliterate]]
|[[Subpackage Language/11.1|Language]]
|-
|[[JLDAP/11.1|JLDAP]]
|[[Subpackage Client/11.1|Client]]
|-
|[[JLibraryManifest/11.1|JLibraryManifest]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JLog/11.1|JLog]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLogEntry/11.1|JLogEntry]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLogger/11.1|JLogger]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLoggerDatabase/11.1|JLoggerDatabase]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLoggerEcho/11.1|JLoggerEcho]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLoggerFormattedText/11.1|JLoggerFormattedText]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLoggerMessageQueue/11.1|JLoggerMessageQueue]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLoggerSysLog/11.1|JLoggerSysLog]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JLoggerW3C/11.1|JLoggerW3C]]
|[[Subpackage Log/11.1|Log]]
|-
|[[JMail/11.1|JMail]]
|[[Subpackage Mail/11.1|Mail]]
|-
|[[JMailHelper/11.1|JMailHelper]]
|[[Subpackage Mail/11.1|Mail]]
|-
|[[JMenu/11.1|JMenu]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JModel/11.1|JModel]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JModelAdmin/11.1|JModelAdmin]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JModelForm/11.1|JModelForm]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JModelItem/11.1|JModelItem]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JModelList/11.1|JModelList]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JModuleHelper/11.1|JModuleHelper]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JNode/11.1|JNode]]
|[[Subpackage Base/11.1|Base]]
|-
|[[JObject/11.1|JObject]]
|[[Subpackage Base/11.1|Base]]
|-
|[[JObservable/11.1|JObservable]]
|[[Subpackage Base/11.1|Base]]
|-
|[[JObserver/11.1|JObserver]]
|[[Subpackage Base/11.1|Base]]
|-
|[[JPackageManifest/11.1|JPackageManifest]]
|[[Subpackage Installer/11.1|Installer]]
|-
|[[JPagination/11.1|JPagination]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JPaginationObject/11.1|JPaginationObject]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JPane/11.1|JPane]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JPaneSliders/11.1|JPaneSliders]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JPaneTabs/11.1|JPaneTabs]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JParameter/11.1|JParameter]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JPath/11.1|JPath]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JPathway/11.1|JPathway]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JPlugin/11.1|JPlugin]]
|[[Subpackage Plugin/11.1|Plugin]]
|-
|[[JPluginHelper/11.1|JPluginHelper]]
|[[Subpackage Plugin/11.1|Plugin]]
|-
|[[JProfiler/11.1|JProfiler]]
|[[Subpackage Error/11.1|Error]]
|-
|[[JRegistry/11.1|JRegistry]]
|[[Subpackage Registry/11.1|Registry]]
|-
|[[JRegistryFormat/11.1|JRegistryFormat]]
|[[Subpackage Registry/11.1|Registry]]
|-
|[[JRegistryFormatIni/11.1|JRegistryFormatIni]]
|[[Subpackage Registry/11.1|Registry]]
|-
|[[JRegistryFormatJson/11.1|JRegistryFormatJson]]
|[[Subpackage Registry/11.1|Registry]]
|-
|[[JRegistryFormatPhp/11.1|JRegistryFormatPhp]]
|[[Subpackage Registry/11.1|Registry]]
|-
|[[JRegistryFormatXml/11.1|JRegistryFormatXml]]
|[[Subpackage Registry/11.1|Registry]]
|-
|[[JRequest/11.1|JRequest]]
|[[Subpackage Environment/11.1|Environment]]
|-
|[[JResponse/11.1|JResponse]]
|[[Subpackage Environment/11.1|Environment]]
|-
|[[JRoute/11.1|JRoute]]
|
|-
|[[JRouter/11.1|JRouter]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JRule/11.1|JRule]]
|[[Subpackage Access/11.1|Access]]
|-
|[[JRules/11.1|JRules]]
|[[Subpackage Access/11.1|Access]]
|-
|[[JSession/11.1|JSession]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorage/11.1|JSessionStorage]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorageApc/11.1|JSessionStorageApc]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorageDatabase/11.1|JSessionStorageDatabase]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorageEaccelerator/11.1|JSessionStorageEaccelerator]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorageMemcache/11.1|JSessionStorageMemcache]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorageNone/11.1|JSessionStorageNone]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorageWincache/11.1|JSessionStorageWincache]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSessionStorageXcache/11.1|JSessionStorageXcache]]
|[[Subpackage Session/11.1|Session]]
|-
|[[JSimpleCrypt/11.1|JSimpleCrypt]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JSimpleXML/11.1|JSimpleXML]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JSimpleXMLElement/11.1|JSimpleXMLElement]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JStream/11.1|JStream]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JStreamString/11.1|JStreamString]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JString/11.1|JString]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JStringController/11.1|JStringController]]
|[[Subpackage Filesystem/11.1|Filesystem]]
|-
|[[JTable/11.1|JTable]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableAsset/11.1|JTableAsset]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableCategory/11.1|JTableCategory]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableContent/11.1|JTableContent]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableExtension/11.1|JTableExtension]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableLanguage/11.1|JTableLanguage]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableMenu/11.1|JTableMenu]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableMenuType/11.1|JTableMenuType]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableModule/11.1|JTableModule]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableNested/11.1|JTableNested]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableSession/11.1|JTableSession]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableUpdate/11.1|JTableUpdate]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableUser/11.1|JTableUser]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableUsergroup/11.1|JTableUsergroup]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JTableViewlevel/11.1|JTableViewlevel]]
|[[Subpackage Database/11.1|Database]]
|-
|[[JText/11.1|JText]]
|
|-
|[[JToolBar/11.1|JToolBar]]
|[[Subpackage Html/11.1|Html]]
|-
|[[JTree/11.1|JTree]]
|[[Subpackage Base/11.1|Base]]
|-
|[[JUpdate/11.1|JUpdate]]
|[[Subpackage Updater/11.1|Updater]]
|-
|[[JUpdateAdapter/11.1|JUpdateAdapter]]
|[[Subpackage Updater/11.1|Updater]]
|-
|[[JUpdater/11.1|JUpdater]]
|[[Subpackage Updater/11.1|Updater]]
|-
|[[JUpdaterCollection/11.1|JUpdaterCollection]]
|[[Subpackage Updater/11.1|Updater]]
|-
|[[JUpdaterExtension/11.1|JUpdaterExtension]]
|[[Subpackage Updater/11.1|Updater]]
|-
|[[JURI/11.1|JURI]]
|[[Subpackage Environment/11.1|Environment]]
|-
|[[JUser/11.1|JUser]]
|[[Subpackage User/11.1|User]]
|-
|[[JUserHelper/11.1|JUserHelper]]
|[[Subpackage User/11.1|User]]
|-
|[[JUtility/11.1|JUtility]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[JView/11.1|JView]]
|[[Subpackage Application/11.1|Application]]
|-
|[[JXMLElement/11.1|JXMLElement]]
|[[Subpackage Utilities/11.1|Utilities]]
|-
|[[LogException/11.1|LogException]]
|[[Subpackage Log/11.1|Log]]
|-
|}
<noinclude>== References ==
<references/>
[[Category:Platform 11.1]][[Category:Subpackages 11.1]]</noinclude>

Archived:Developing a MVC Component/Adding a variable request in the menu type

2011-03-25T16:15:17Z

Kissaki: /* Adding a variable request in the menu type */

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a variable request in the menu type ==
For the moment, the displayed message is always ''Hello World!''. Joomla!1.6 gives the possibility to add parameters to menu types. In our case, this is done in the ''site/views/helloworld/tmpl/default.xml'' file:

<span id="site/views/helloworld/tmpl/default.xml">
''site/views/helloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="request">
<fieldset name="request">
<field
name="id"
type="list"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
default="1"
>
<option value="1">Hello World!</option>
<option value="2">Good bye World!</option>
</field>
</fieldset>
</fields>
</metadata>
</source>
</span>

Two important things to note:
* the ''request'' group of fields indicates mandatory fields
* <span style="text-decoration:line-through;">the ''array'' parameter that indicates that these parameters will be added in the request URL</span> [??]

The model has to be modified in order to switch between the two different messages (which is chosen by the user with the field defined above):

<span id="site/models/helloworld.php">
''site/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var string msg
*/
protected $msg;

/**
* Get the message
* @return string The message to be displayed to the user
*/
public function getMsg()
{
if (!isset($this->msg))
{
$id = JRequest::getInt('id');
switch ($id)
{
case 2:
$this->msg = 'Good bye World!';
break;
default:
case 1:
$this->msg = 'Hello World!';
break;
}
}
return $this->msg;
}
}
</source>
</span>

Also modify your ''helloworld.xml'' file to indicate the new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</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>0.0.5</version>

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

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

You can test this variable request by putting ''index.php?option=com_helloworld&id=1'' or ''index.php?option=com_helloworld&id=2'' in your browser address.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_04#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58229/com_helloworld-1.6-part05.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 04|Prev: Adding a model to the site part]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 06|Next: Using the database]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding a variable request in the menu type

2011-03-25T16:13:34Z

Kissaki: /* Adding a variable request in the menu type */

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a variable request in the menu type ==
For the moment, the displayed message is always ''Hello World!''. Joomla!1.6 gives the possibility to add parameters to menu types. In our case, this is done in the ''site/views/helloworld/tmpl/default.xml'' file:

<span id="site/views/helloworld/tmpl/default.xml">
''site/views/helloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="request">
<fieldset name="request">
<field
name="id"
type="list"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
default="1"
>
<option value="1">Hello World!</option>
<option value="2">Good bye World!</option>
</field>
</fieldset>
</fields>
</metadata>
</source>
</span>

Two important things to note:
* the ''request'' group of fields indicates mandatory fields
* <span style="text-decoration:line-through;">the ''array'' parameter that indicates that these parameters will be added in the request URL</span> [??]

The model has to be modified in order to switch between the two different messages (which are selected in the field defined above):

<span id="site/models/helloworld.php">
''site/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var string msg
*/
protected $msg;

/**
* Get the message
* @return string The message to be displayed to the user
*/
public function getMsg()
{
if (!isset($this->msg))
{
$id = JRequest::getInt('id');
switch ($id)
{
case 2:
$this->msg = 'Good bye World!';
break;
default:
case 1:
$this->msg = 'Hello World!';
break;
}
}
return $this->msg;
}
}
</source>
</span>

Also modify your ''helloworld.xml'' file to indicate the new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</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>0.0.5</version>

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

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

You can test this variable request by putting ''index.php?option=com_helloworld&id=1'' or ''index.php?option=com_helloworld&id=2'' in your browser address.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_04#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58229/com_helloworld-1.6-part05.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 04|Prev: Adding a model to the site part]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 06|Next: Using the database]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding a variable request in the menu type

2011-03-25T16:11:43Z

Kissaki: /* Adding a variable request in the menu type */

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a variable request in the menu type ==
For the moment, the displayed message is always ''Hello World!''. Joomla!1.6 gives the possibility to add parameters to menu types. In our case, this is done in the ''site/views/helloworld/tmpl/default.xml'' file:

<span id="site/views/helloworld/tmpl/default.xml">
''site/views/helloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="request">
<fieldset name="request">
<field
name="id"
type="list"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
default="1"
>
<option value="1">Hello World!</option>
<option value="2">Good bye World!</option>
</field>
</fieldset>
</fields>
</metadata>
</source>
</span>

Two important things to note:
* the ''request'' group of fields indicates mandatory fields
* <span style="text-decoration:line-through;">the ''array'' parameter that indicates that these parameters will be added in the request URL</span> [??]

The model has to be modified in order to choose between the two different messages:

<span id="site/models/helloworld.php">
''site/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var string msg
*/
protected $msg;

/**
* Get the message
* @return string The message to be displayed to the user
*/
public function getMsg()
{
if (!isset($this->msg))
{
$id = JRequest::getInt('id');
switch ($id)
{
case 2:
$this->msg = 'Good bye World!';
break;
default:
case 1:
$this->msg = 'Hello World!';
break;
}
}
return $this->msg;
}
}
</source>
</span>

Also modify your ''helloworld.xml'' file to indicate the new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</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>0.0.5</version>

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

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

You can test this variable request by putting ''index.php?option=com_helloworld&id=1'' or ''index.php?option=com_helloworld&id=2'' in your browser address.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_04#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58229/com_helloworld-1.6-part05.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 04|Prev: Adding a model to the site part]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 06|Next: Using the database]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding a variable request in the menu type

2011-03-25T16:11:22Z

Kissaki: /* Adding a variable request in the menu type */ – PLEASE FIX! I can not find a array anywhere, so this does not seem to fit or belong here!

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a variable request in the menu type ==
For the moment, the displayed message is always ''Hello World!''. Joomla!1.6 gives the possibility to add parameters to menu types. In our case, this is done in the ''site/views/helloworld/tmpl/default.xml'' file:

<span id="site/views/helloworld/tmpl/default.xml">
''site/views/helloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="request">
<fieldset name="request">
<field
name="id"
type="list"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
default="1"
>
<option value="1">Hello World!</option>
<option value="2">Good bye World!</option>
</field>
</fieldset>
</fields>
</metadata>
</source>
</span>

Two important things to note:
* the ''request'' group of fields indicates mandatory fields
<span style="text-decoration:line-through;">* the ''array'' parameter that indicates that these parameters will be added in the request URL</span> [??]

The model has to be modified in order to choose between the two different messages:

<span id="site/models/helloworld.php">
''site/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var string msg
*/
protected $msg;

/**
* Get the message
* @return string The message to be displayed to the user
*/
public function getMsg()
{
if (!isset($this->msg))
{
$id = JRequest::getInt('id');
switch ($id)
{
case 2:
$this->msg = 'Good bye World!';
break;
default:
case 1:
$this->msg = 'Hello World!';
break;
}
}
return $this->msg;
}
}
</source>
</span>

Also modify your ''helloworld.xml'' file to indicate the new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</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>0.0.5</version>

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

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

You can test this variable request by putting ''index.php?option=com_helloworld&id=1'' or ''index.php?option=com_helloworld&id=2'' in your browser address.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_04#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58229/com_helloworld-1.6-part05.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 04|Prev: Adding a model to the site part]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 06|Next: Using the database]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Version 1.6 Developer Notes

2011-03-25T15:32:53Z

Kissaki: /* Changes to XML-RPC support */ fix

{{incomplete}}
{{RightTOC}}
[[Category:Development]]

Compilation of developer notes on changes in 1.6.

== Schema ==

* Added ACL tables (todo - list them)
* Removed jos_groups table
* Removed [[Tables/plugins|jos_plugins]] table in favour of [[Tables/extensions|jos_extensions]]
* Added update tables
** jos_updates
** jos_update_sites
** jos_update_sites_extensions
** jos_update_categories

== Framework ==

=== JAuthorization ===

Remove <code>JAuthorization::_mos_add_acl</code>.

Added <code>JAuthorization::getUserAccessLevels( $section [, $action = 'view'] )</code>.

=== JDatabase ===

JDatabase::setQuery casts the sql variable to a string. This allows you to pass an object that implements the __toString magic method.

=== JFile ===

Both JFile::write and JFTP::write now use a reference for its second argument. Code like ''JFile::write($filename,'string');'' will fail, however ''$data = 'string'; JFile::write($filename, $data);'' will work for both 1.5 and 1.6

=== JModel ===

JModel::getState will now take an optional second argument to set the default.
$value = $model->getState( 'foo', 'bar' );

JModel has an addition contruction option and internal variable <code>__state_set</code>. This is used to lazy-load model initialisation.

=== New API ===

Added <code>JTableTree</code> as an abstract class for tree-based tables.

Made JObject abstract. It can no longer be directly instantiated. Use JStdClass instead.

Added <code>JDocumentXML</code> to allow easy generation of valid XML files.

=== Changes to XML-RPC support ===
On april the 9th. Louis Landry explained his intended changes to the way Joomla will handle XML-RPC in version 1.6. You can view his detailed explanation [http://docs.joomla.org/Xml-rpc here].

== Components ==

=== Join for access level ===

Before:
<pre>LEFT JOIN #__groups AS g ON g.id = c.access</pre>

After:
<pre>LEFT JOIN #__core_acl_axo_groups AS g ON g.value = a.access</pre>

=== Administrator:Users ===

== Legacy Mode ==

Only available in legacy mode (to be dropped in future versions):

* <code>global $mainframe</code> - Use <code>$app = &JFactory::getApplication()</code> instead.
* JTemplate (patTemplate completely deprecated)
* Multiple client language install packs (e.g. where site and administrator language files are in the same installation file), use packages with two language install packages

== Files/Features Dropped ==

* Support for constants as language strings with JLanguage
* Polls component

==Templates==

Mapping of positions in Milky Way 1.5 to new positions.

*user3->position-1
*breadcrumb->position-2
*right->position-3,position-4
*left->position-7
*user1->position-9
*user2->position-10
*footer->position-5,position-8,position-11
*user4->position-12
*syndicate->position-14

== TODO ==

== Migration issues ==

Please use [[Version_1.6._Migration_Notes]] to track migration issues that are not schema changes.

J2.5:Supporting SEF URLs in your component

2011-03-24T13:59:27Z

Kissaki: /* The Component Router */

{{incomplete}}
{{RightTOC}}
[[Category:Development]]

== Routing Overview ==

Joomla! 1.5 is capable of creating and parsing URLs in any format, including human readable URL's. Another improvement is that this still works even if Joomla! runs a server other than Apache with the mod_rewrite module.

A good example of this is the "Welcome to Joomla" article. The first link shown was generated without mod_rewrite, and the second link was generated with mod_rewrite:

* <code><nowiki>http://www.example.com/index.php/the-news/1-latest-news/1-welcome-to-joomla</nowiki></code>
* <code><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></code>

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the title is the text you want to have in the url). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport( 'joomla.filter.output' );
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the JFilterOutput::stringURLSafe() method.

=== The Slug ===

Continuing with the same example, the "slug" - "1-welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

After this step the slug is used instead of the id.

== Routing URL's ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute</code> has three parameters and its prototype is:

<source lang="php">JRoute::_( $url, $xhtml = true, $ssl=null );</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_( 'index.php?view=article&id='.$row->slug );</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the router.php in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the router.php. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (view=categories), the second is a single category (view=category) and the third is a single article (view=article).

The file router.php should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your installation XML in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute( &$query )
{
$segments = array();
if(isset($query['view']))
{
$segments[] = $query['view'];
unset( $query['view'] );
}
if(isset($query['id']))
{
$segments[] = $query['id'];
unset( $query['id'] );
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <code>/components/com_magic/...</code> would use a prefix <code>magic</code> (all lower case).

The next function in the <code>router.php</code> parses the URL:

<source lang="php">
function [componentname]ParseRoute( $segments )
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first, the catid is second and the id is third in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <code>router.php</code> is a very simple way to generate sef URL's but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<code><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></code>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <code><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></code>
* When viewing a category: <code><nowiki>http://www.example.com/[menualias]/[category]</nowiki></code>
* When viewing the categories overview: <code><nowiki>http://www.example.com/[menualias]</nowiki></code>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_( 'index.php?view=article&catid='.$row->catslug .'&id='.$row->slug );
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_( 'index.php?view=category&id='.$row->catslug );
</source>

The corresponding <code>router.php</code>:

<source lang="php">

function [''Componentname'']BuildRoute(&$query)
{
$segments = array();
if(isset( $query['catid'] ))
{
$segments[] = $query['catid'];
unset( $query['catid'] );
};
if( isset($query['id']) )
{
$segments[] = $query['id'];
unset( $query['id'] );
};
unset( $query['view'] );
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [''Componentname'']ParseRoute($segments)
{
$vars = array();
$menu =& JMenu::getInstance();
$item =& $menu->getActive();
// Count segments
$count = count( $segments );
//Handle View and Identifier
switch( $item->query['view'] )
{
case 'categories':
if($count == 1) {
$vars['view'] = 'category';
}
if($count == 2) {
$vars['view'] = 'article';
}
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count( $segments );
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article .
* The menu item is a link to the categories view and the $segments array has one item ($id). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the $segments array is the identifier for an article .

The result of all this code is nice and human readable component URL's.

== Application Route Parsing ==

The [[API Execution Order]] outlines that the route (URL) is parsed immediately after initialisation is complete. Since fancy URL's are not treated (yet) in the Administrator, we will follow the route parsing process in detail when <code>JSite::route</code> in the <code>index.php</code> file.

* Call to <code>JApplication::route</code>
** Clone the URI
** Call to <code>JApplication::getRouter</code>
*** Call to <code>JRouter::getInstance</code> passing the type ("site")
** Call to <code>JRouterSite::parse</code> passing the URI
*** Strip the suffix if applicable (added to $vars['format'])
*** Re-set the route (URI)
*** Call to <code>JRouter::parse</code> passing the URI
**** Call to <code>JRouterSite::_processParseRules</code> passing the URI (this will call custom route rules)
***** Call to <code>JRouter::_processParseRules</code> passing the URI
****** Call any custom routing rules (probably added via a system plugin using the <code>onAfterInitialise</code> event trigger) passing the URI
****** Returns an array of vars
***** If SEF mode, replace <code>start</code> variable with </code>limitstart</code>
**** If raw mode, call to <code>JRouterSite::_parseRawRoute</code> passing the URI
**** If SEF mode, call to <code>JRouterSite::_parseSefRoute</code> passing the URI
***** If the route (the URI path) is empty, load it from the default menu item; set the active menu item as the default
***** If first part is <code>/component/com_content</code>, set the <code>option</code> as the second segement. Null the <code>Itemid</code>.
***** Else, loop through menu alias values and take off segments that match as the menu tree is traversed. Set <code>option</code> and <code>Itemid</code> based on the last menu item found.
***** If the <code>Itemid</code> is set in the URL, set the active menu item based on this value.
***** Push the vars collected so far (eg, <code>option</code>, <code>Itemid</code>, etc) into the router object (<code>$this</code>).
***** If the route and <code>option</code> is set, load the component router;
***** Else, get the active menu item and get the route vars from it

== Application Route Building ==

TODO

== Custom Router Rules ==

TODO

== Additional References ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

Archived:Developing a MVC Component/Adding a variable request in the menu type

2011-03-10T18:07:04Z

Kissaki: /* Adding a variable request in the menu type */

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a variable request in the menu type ==
For the moment, the displayed message is always ''Hello World!''. Joomla!1.6 gives the possibility to add parameters to menu types. In our case, this is done in the ''site/views/helloworld/tmpl/default.xml'' file:

<span id="site/views/helloworld/tmpl/default.xml">
''site/views/helloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="request">
<fieldset name="request">
<field
name="id"
type="list"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
default="1"
>
<option value="1">Hello World!</option>
<option value="2">Good bye World!</option>
</field>
</fieldset>
</fields>
</metadata>
</source>
</span>

Two important things to note:
* the ''request'' group of fields indicates mandatory fields
* the ''array'' parameter that indicates that these parameters will be added in the request URL

The model has to be modified in order to choose between the two different messages:

<span id="site/models/helloworld.php">
''site/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var string msg
*/
protected $msg;

/**
* Get the message
* @return string The message to be displayed to the user
*/
public function getMsg()
{
if (!isset($this->msg))
{
$id = JRequest::getInt('id');
switch ($id)
{
case 2:
$this->msg = 'Good bye World!';
break;
default:
case 1:
$this->msg = 'Hello World!';
break;
}
}
return $this->msg;
}
}
</source>
</span>

Also modify your ''helloworld.xml'' file to indicate the new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</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>0.0.5</version>

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

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

You can test this variable request by putting ''index.php?option=com_helloworld&id=1'' or ''index.php?option=com_helloworld&id=2'' in your browser address.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_04#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58229/com_helloworld-1.6-part05.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 04|Prev: Adding a model to the site part]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 06|Next: Using the database]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding a variable request in the menu type

2011-03-10T18:04:31Z

Kissaki: /* Adding a variable request in the menu type */

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a variable request in the menu type ==
For the moment, the displayed message is always ''Hello World!''. Joomla!1.6 gives the possibility to add parameters to menu types. In our case, this is done in the ''site/views/helloworld/tmpl/default.xml'' file:

<span id="site/views/helloworld/tmpl/default.xml">
''site/views/helloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="request">
<fieldset name="request">
<field
name="id"
type="list"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
default="1"
>
<option value="1">Hello World!</option>
<option value="2">Good bye World!</option>
</field>
</fieldset>
</fields>
</metadata>
</source>
</span>

Note two important information:
* the ''request'' group of fields indicates mandatory fields
* the ''array'' parameter that indicates that these parameters will be added in the request URL

The model has to be modified in order to choose between the two different messages:

<span id="site/models/helloworld.php">
''site/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var string msg
*/
protected $msg;

/**
* Get the message
* @return string The message to be displayed to the user
*/
public function getMsg()
{
if (!isset($this->msg))
{
$id = JRequest::getInt('id');
switch ($id)
{
case 2:
$this->msg = 'Good bye World!';
break;
default:
case 1:
$this->msg = 'Hello World!';
break;
}
}
return $this->msg;
}
}
</source>
</span>

Also modify your ''helloworld.xml'' file to indicate the new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</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>0.0.5</version>

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

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

You can test this variable request by putting ''index.php?option=com_helloworld&id=1'' or ''index.php?option=com_helloworld&id=2'' in your browser address.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_04#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58229/com_helloworld-1.6-part05.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 04|Prev: Adding a model to the site part]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 06|Next: Using the database]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding a view to the site part

2011-03-10T17:30:36Z

Kissaki: /* Setting the view */

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

In the Joomla!1.6 framework, third party components authors divide their code into three main parts:
* ''models'' They manage the data
* ''controllers'' They perform tasks, set and get the states of the models and ask the views to display
* ''views'' They display the content according to the type (''error'', ''feed'', ''html'', ''json'', ''raw'', ''xml'') and the layout chosen by the controllers

== Setting the controller ==
In the core code of Joomla, there is a class able to manage controllers: ''JController''. This class has to be extended to be used in our component. In the file ''site/helloworld.php'' (entry point of our ''Hello World'' component), put these lines

<span id="site/helloworld.php">
''site/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by HelloWorld
$controller = JController::getInstance('HelloWorld');

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

// Redirect if set by the controller
$controller->redirect();</source>
</span>
The ''getInstance'' static method of the ''JController'' class will create a controller. In the code above, it will create a controller named ''HelloWorldController'' using the ''controller.php'' file (it's a default behavior)

With your favorite file manager and editor, create a ''site/controller.php'' file containing

<span id="site/controller.php">
''site/controller.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla controller library
jimport('joomla.application.component.controller');

/**
* Hello World Component Controller
*/
class HelloWorldController extends JController
{
}
</source>
</span>

When no task is given in the request variables, the default task will be executed. It's the ''display'' task by default. The ''JController'' class has such a task. In our example, it will display a view named ''HelloWorld''.

== Setting the view ==
With your favorite file manager and editor, create a file ''site/views/helloworld/view.html.php'' able to display the default view and containing

<span id="site/views/helloworld/view.html.php">
''site/views/helloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the HelloWorld Component
*/
class HelloWorldViewHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
// Assign data to the view
$this->msg = 'Hello World';

// Display the view
parent::display($tpl);
}
}
</source>
</span>

The ''display'' method of the ''JView'' class is called with the ''display'' task of the JController class. In our case, this method will display data using the ''tmpl/default.php'' file. With your favorite file manager and editor, create a file ''site/views/helloworld/tmpl/default.php'' able to display the default view and containing

<span id="site/views/helloworld/tmpl/default.php">
''site/views/helloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');
?>
<h1><?php echo $this->msg; ?></h1>
</source>

This template file will be included by the JView class. Therefore, here, $this refers to the HelloWorldViewHelloWorld class.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[#site/helloworld.php|site/helloworld.php]]''
* ''[[#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58226/com_helloworld-1.6-part02.zip archive] and install it using the extension manager of Joomla!1.6. You can test this basic component by putting ''index.php?option=com_helloworld'' in your browser address.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</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>0.0.2</version>

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

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

'''Result:'''
You will see by default the message contained in the variable ''$this->msg'' in the ''view.html.php'' file.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 01|Prev: Developing a Basic Component]] [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 03|Next: Adding a menu type to the site part]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Joomla 1.6 version history

2011-02-11T17:37:46Z

Kissaki: 1.6 has been released …

{{RightTOC}}

== Joomla! 1.6.0 ==
* Onward
* 10 January 2011
* [http://www.joomla.org/announcements/general-news/5348-joomlar-16-has-arrived.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5696 Package and MD5s]

== Joomla! 1.6 Release Candidate 1 ==
* 14 December 2010
* [http://www.joomla.org/announcements/release-news/5328-joomla-16-rc1-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5560 Package and MD5s]

== Joomla! 1.6 Beta 15 ==
* 29 November 2010
* [http://www.joomla.org/announcements/release-news/5324-joomla-16-beta15-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5539 Package and MD5s]

== Joomla! 1.6 Beta 14 ==
* 15 November 2010
* [http://www.joomla.org/announcements/release-news/5320-joomla-16-beta14-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5523 Package and MD5s]

== Joomla! 1.6 Beta 13 ==
* 1 November 2010
* [http://www.joomla.org/announcements/release-news/5315-joomla-16-beta13-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5496 Package and MD5s]

== Joomla! 1.6 Beta 12 ==
* 18 October 2010
* [http://www.joomla.org/announcements/release-news/5304-joomla-16-beta12-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5480 Package and MD5s]

== Joomla! 1.6 Beta 11 ==
* 4 October 2010
* [http://www.joomla.org/announcements/release-news/5296-joomla-16-beta11-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5448 Package and MD5s]

== Joomla! 1.6 Beta 10 ==
* 20 September 2010
* [http://www.joomla.org/announcements/release-news/5295-joomla-16-beta10-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5426 Package and MD5s]

== Joomla! 1.6 Beta 9 ==
* 7 September 2010
* [http://www.joomla.org/announcements/release-news/5294-joomla-16-beta9-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5398 Package and MD5s]

== Joomla! 1.6 Beta 8 ==
* 23 August 2010
* [http://www.joomla.org/announcements/release-news/5292-joomla-16-beta8-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5378 Package and MD5s]

== Joomla! 1.6 Beta 7 ==
* 9 August 2010
* [http://www.joomla.org/announcements/release-news/5291-joomla-16-beta7-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5364 Package and MD5s]

== Joomla! 1.6 Beta 6 ==
* 26 July 2010
* [http://www.joomla.org/announcements/release-news/5285-joomla-16-beta6-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5346 Package and MD5s]

== Joomla! 1.6 Beta 5 ==
* 12 July 2010
* [http://www.joomla.org/announcements/release-news/5282-joomla-16-beta5-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5314 Package and MD5s]

== Joomla! 1.6 Beta 4 ==
* 28 June 2010
* [http://www.joomla.org/announcements/release-news/5280-joomla-16-beta4-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5300 Package and MD5s]

== Joomla! 1.6 Beta 3 ==
* 14 June 2010
* [http://www.joomla.org/announcements/release-news/5279-joomla-16-beta3-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5276 Package and MD5s]

== Joomla! 1.6 Beta 2 ==
* 31 May 2010
* [http://www.joomla.org/announcements/release-news/5278-joomla-16-beta2-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5249 Package and MD5s]

== Joomla! 1.6 Beta 1 ==
* 18 May 2010
* [http://www.joomla.org/announcements/release-news/5275-joomla-16-beta-now-available.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=5224 Package and MD5s]

== Joomla! 1.6 Alpha 2 ==
* 24 October 2009
* [http://community.joomla.org/blogs/community/1061-joomla-16-alpha-2-released.html Release Notes]
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=3585 Package and MD5s]

== Joomla! 1.6 Alpha ==
* 22 April 2009
* Release Notes
* [http://joomlacode.org/gf/project/joomla/frs/?action=FrsReleaseBrowse&frs_package_id=3585 Package and MD5s]

== Joomla! 1.6.x Change Log ==
For any Joomla! 1.6 release, use [http://joomlacode.org/gf/project/joomla/scmsvn/?action=browse&path=%2Fdevelopment%2Ftrunk%2Finstallation%2FCHANGELOG&view=markup this Change Log]

== To locate the MD5 Hash ==
# Click the link for '''Packages and MD5s''' above for the version desired.
# Click the word '''Files''' in the blue bar to expand the list of patch packages available.
# Locate the row that matches your current installation version.
# On that row, select the patch package (zip, tar.gz and tar.bz2) that is most convenient for you.
# Verify the download using the MD5 hash listed in the right column on the same line as the package you selected.

[[Category:Joomla! 1.6]]

J2.5:What's new in Joomla 2.5

2010-09-18T19:48:12Z

Kissaki: /* Banners list */

Lots of things.

...and:
* '''New Access Control System''' - Allows site administrators control over who can view and manage content.
* '''Unlimited Depth Organizational Model''' - Gives site administrators and content creators user-defined category levels that allow for the creation of a category tree with as many or as few levels for organizing articles and other content as needed.
* '''One-Click Extension Updates''' - Allows users to keep sites secure and controlled by simplifying the process of updating extensions.
* '''Semantic XHTML Layouts''' - Provides a better baseline for content presentation.

...and:

==Administrators==
===Introduction===
*Consistent UI
*Consistent Features
*Richer sample data
*IE 7+, Firefox 3.x, Safari 4.x
*PHP 5.2.4+
*MySQL 5.0.4 (allows for wide varchars)

===Administrator===
*Menu Changes
*Submenu consistency

====Toolbar Features====
*Save
*Save & Close
*Save & New
*Save as Copy
*Expired session will return to the page you were on then you got logged out (can be hit and miss)
*Most search filters allow you to search for a record id via [ id:123 ]
*"Parameters" are now referred to as "Options"
*Template Styles
*Integrated Trash Management
*Consistent archive support for most content
*Extension Installer Improvements

===Module Enhancements===
*Publish up and down
*Add option to display on all pages "except" selected
*Expanded Category System
*404 Page Redirection
*Better Menu Management
*Alternative layouts for content, modules and menus (taken from the home template)

===New Templates===
*Atomic
*Beez2
*(Administrator) Bluestork (replaces Khephri)
*(Administrator) Hathor
*Legacy layer in Milkyway
*Backend supports layout overrides
*New Modules
*New Plugins
*Content Languages
*User Login Permissions
*Activate selected users from the user list now (and filter)
*Administrator registration approval
*Polls component removed
*New codemirror editor

===SEO Improvements===
*Meta decription and keywords for categories
*Articles can change the page title and page header separately

===Global Configuration===
*Add site name to titles
*Default Access Level
*Set Metadata Language (buggy)
*Unicode Aliases
*Cookie domain and path
*User Setting moved to User Manager -> Options
*Media Settings moved to Media Manager -> Options
*Debug Modules - allows you to enabled to disable the tp=1 feature
*Server Timezone now a location, not an integer offset
*New Global Permissions tab

===User Manager===
*Can activate a user from the list now
*User can be assigned to multiple groups
*Manage user groups
*Manager content access levels

===Media Manager===
*Flash uploader fixed

===Menu Manager===
====Menus List====
*Rebuild button to press when you brick the menu
*Clicking the menu name brings up the menu items list rather than going into Edit Menu. To edit the menu, click on the check box next to the name and click on the Edit icon in the toolbar.

====Items List====
*Menus support the language filter
*Default now called Home
*Home is now clickable in the menu item list
*A separate home can be set for different languages

=====New batch operations=====
*Set access level
*Copy or move to another part of this or another menu

====Edit Item====
*Improved "Type" selector with human readable view and layout names
*Note field added
*New window target
*New Language assignment
*New Template style
*Ability to add & edit Module assignments from this page

=====New options for the menu links and pages themselves=====
*Link title attribute
*Link CSS style
*Menu image is changed to a modal selector
*CSS class for page heading
*Page meta description
*Page meta keywords
*Robots options

===Articles Manager===
*Frontpage is now referred to as Featured
*Article manager uses submenu to quickly skip between articles , categories and featured
*Sections and categories are now merged.

====Articles List====
*''"Missing move and copy; filter by author"''
*New column to show language
*Filtering by language available

====Article Edit====
*Created by user now selected by modal popup
*New ability to set the page title from the article
*Define create, delete, edit and publishing permissions

====Archived Articles====
*In 1.5, Archived Articles had to first be changed to Published or Unpublished before update.
*In 1.6, an Article with an Archived Status *can* be changed without changing the State first.

===Categories===
====Category List====
*Nested view
*Filtering on language

====Edit Category====
*New note field
*Section replaced with ability to assign a parent category
*Ability to assign content language

=====New Options (not previously available in 1.5)=====
*Assign alternate layout
*Define create, delete, edit and publishing permissions
*Meta description
*Meta keywords
*Alternative page title
*Meta author
*Meta robots

===Banners===
====Banners list====
* Missing copy toolbar button
*New archive toolbar button
*New columns to show meta keywords, purchase type and language
*New filtering by client and language

====Edit Banner====
*New type toggle for Image or Custom (dynamically changes the available form fields)
*New alt text field for image
*New language field

=====New Options=====
*Ability to set the created date
*Ability to set start and finish publishing times
*Ability to set the purchase type
*Ability to track impressions
*Ability to track clicks
*Use own prefix ?
*Tags renamed to meta
*Contacts
*Messaging
*Newsfeeds
*Search
*Weblinks
*Redirect

===Extensions Manager===
====Discover====
*Module mgr
*Plugin Mgr
*Template Mgr
*Language mgr

===Misc===
*Auto create linked contact when creating new user ??

==Access Controls==
*Introduction
*User Groups
*Access Levels
*Permission Layers
*How Permissions are Inherited
*How to debrick your site

==Developers==
===Introduction===
*PHP 5.2.4+
*MySQL 5.0.4 (allows for wide varchars)
*IE7+, Firefox 3+, Safari 4+
*Focus on code consistency
*Focus on code reduction

Usage of PHP Native Functions where possible, for example:
*[[JXMLElement]] extends the native [http://php.net/manual/en/book.simplexml.php SimpleXML] class
*[[JDate]] extends the [http://www.php.net/manual/en/class.datetime.php DateTime] class
*Native INI parser to load languages

===Removed features===
*ADODB compatibility methods in database classes
*DOMIT (unsupported XML library)
*Legacy mode (includes global $mainframe, etc)
*JTemplate (based on patTemplate)
*patTemplate (templating engine)
*PDF support
*PEAR libraries (due to license incompatibilities)
*phpgacl
*PHP 4.0 and 5.0 compatibility files
*XStandard Editor

===Deprecated Features===
*JController::_acoSection
*JController::_acoSectionValue
*JController::authorize()
*JController::setAccessControl()
*JDatabase::stderr()
*JDate::offest
*JDate::setOffset()
*JDate::toFormat() - use JDate::format() instead
*JException::toString()
*JFactory::getXMLParser()
*JHtmlGird::access()
*JHtmlImage::administrator - use JHtml::image instead
*JHtmlImage::site - use JHtml::image instead
*JHtmlList::accesslevel()
*JHtmlList::specificordering() - use JHtml::_('list.ordering')
*JHtmlList::category()
*JHtmlSelect::optgroup() - see JHtmlSelect::groupedList()
*JLanguage::_parseLanguageFiles - renamed to parseLanguageFiles
*JLanguage::_parseXMLLanguageFile - renamed to parseXMLLanguageFile
*JLanguage::_parseXMLLanguageFiles - renamed to parseXMLLanguageFiles
*JObject::toString - replaced with magic method
*JRegistry::getNameSpaces()
*JRegistry::getValue()
*JRegistry::makeNameSpace()
*JRegistry::setValue()
*JPane - See JHtmlSliders
*JParameter - replaced by JForm
*JSimpleXML, JSimpleXMLElement - Use JXMLElement instead, based on the native SimpleXMLElement
*JTable::canDelete() - models or controllers should be doing the access checks
*JTable::toXML()
*JToolbarHelper customX(), addNewX(), editListX(), editHtmlX(), editCssX(), deleteListX()
*JUser::authorize() - Use JUser::authorise()
*JUtility::dump()
*JUtility::array_unshift_ref() - Not needed in PHP 5
*JUtility::getHash() - Use JApplication::getHash()
*JUtility::getToken() - Use JFactory::getSession()->getFormToken()
*JUtility::isWinOS() - Use JApplication::isWinOS()
*JUtility::return_bytes() - See InstallerModelWarnings::return_bytes()
*JUtility::sendMail() - Use JFactory::getMailer()->sendMail()
*JUtility::sendAdminMail() - Use JFactory::getMailer()->sendMail()
*JXMLElement::data() - Provided for backward compatibility
*JXMLElement::getAttribute() - Provided for backward compatibility

===Database===
*JTable now automatically looks up the fields from the database schema
*New JDatabaseQuery - A chained CRUD query builder
*New JDatabase::getNextRow
*New JDatabase::getNextObject
*JDatabase::loadAssocList - Now takes a second argument to just return the value of a column
*JDatabase::setQuery - Added chaining support

====Important Schema Changes====
*New jos_extensions table to list all extensions
*Components table information moved and split between jos_extensions and jos_menu (special menu called _adminmenu)

The old phpgacl (jos_core_acl*) and jos_groups tables have been reworked into:
*jos_assets
*jos_user_usergroup_map
*jos_usergroups
*jos_viewlevels
*Archived state changed from a value of -1 to +2

===Improved MVC===
====Models====
*JModelList
*JModelForm
*JModelAdmin
*Format handling (eg JSON)
*Sub-controller handling

====Controllers====
*JControllerForm
*JControllerAdmin
*JController::setMessage takes second arg to set the message type
*JController can set the default view
*Added chaining support to several JController methods

====Views====
*Semantic core output
*Milkyway legacy layouts
*The old component parameters are not automatically added to the menu anymore. You need to explicitly put them in the layout XML files.
*The menu manager will now detect additional layouts for a given view in the default template.

===Form API===
====Event manipulation====
*onContentPrepareForm
*onContentPrepareFormData

===Translation and Language Support===
*Support for unicode slugs, eg, SEF URL's with Greek characters
*3-letter languages now supported, xxx-XX
*All existing language keys have been refactored

====INI files must validate====
*Upper case key with no spaces, alphanumeric characters and underscores
*Quoted values
*Double quotes within literal strings must use _QQ_ in the form KEY="<a href="_QQ_"index.php"_QQ_">Click</a>"

====Javascript translation layer====
*See the flash uploader script for an example
Local extension language files

====Language file API====
*Pluralisation support
*Transliteration support for ASCII or Unicode slugs
*Ignore Search Words
*Minimum search word length
*Custom language overrides
*System language file to support administrator menu and installation (.sys.ini)

====Language switcher====
*Language Filter plugin enables language switching
*Sets the automatic filtering via JFactory::getApplication()->setLanguageFilter(true)
*A frontend component with language support would test JFactory::getApplication()->getLanguageFilter(), which returns the selected language code from the Languages Module
*The language field can be a language code for a single language, or "*" to be displayed for all languages
*Community extension for language maintenance com_localise

===Extension management===
====New installation types====
=====Libraries=====
*Must include an XML manifest where type="library"
*Can only be installed into a sub-folder of /libraries/
*Can extend parts of an existing library, eg /libraries/joomla/database/database/oracle.php

=====Packages multi-installer=====
*Must include an XML manifest where type="package"
*A package is a zip of zip's

New install script can be provided with 5 methods:
=====preflight=====
*Runs before anything is run and while the extracted files are in the uploaded temp folder

======Could allow for:======
*secondary extraction of custom zip's
*version checks to be performed
*halting the installer on an error

=====install / update=====
*Runs after the database scripts are executed
*If the extension is new, the install method is run
*If the extension exists then update method is run if method="upgrade", otherwise assumes that the extension is not meant to be upgradable

=====postflight=====
*Runs after the extension is registered in the database
*Is not run for the uninstall process (nothing left to do obviously)

====Discover====
*Does not do any file copying, only works with what it finds
*Performs preflight, install and postflight
*Developer of installer has two language files??

====Update site====
*Can publish an XML manifest on your site that can include individual extensions and extension sets.

====XML Manifest Changes====
*<install> is deprecated - use <extension>
*New <update> tag. Takes a <schemas> tag which can define <schemapath>
*<params> and <param> tags are deprecated, use <fields>, <fieldsets> and <field> instead

====File changes====
*Installation manifest must be the same name as the extension, eg com_foobar/foobar.xml This helps with discovery (otherwise the function has to go through all the files in the extension folder
*Plugins are now in folders like modules and components
*See SVN/tests/_data/installer_packages/ for complete examples of all extensions and manifests.
*The method="upgrade" will compare individual files in the original and incoming manifests and will remove files as appropriate. However, it will not remove differences in the <folder> tags.
*Future support for rollback

===Events===
====New Events====
*onBeforeRender
*onContentBeforeDelete
*onContentAfterDelete
*onContentChangeState
*onContentPrepareForm
*onContentPrepareFormData
*onExtensionBeforeInstall
*onExtensionBeforeUpdate
*onExtensionBeforeUninstall
*onExtensionAfterInstall
*onExtensionAfterUpdate
*onExtensionAfterUninstall

====Renamed Events====
*onContentAfterSave
*onContentAfterTitle
*onContentAfterDisplay
*onContentBeforeDisplay
*onContentBeforeSave
*onContentSearch
*onContentSearchAreas
*onUserAuthenticate
*onUserAfterDelete
*onUserAfterSave
*onUserBeforeDelete
*onUserBeforeSave
*onUserLogin
*onUserLogout
*All content events (except for search and search areas) now pass a 'context' as the first argument to alert the plugin as to what type of content is being passed. The plugin event may or may not heed this context.

===Categories===
*Component can provide custom options for its own categories via optional category.xml
*Supported via JTableNested

===Access Controls===
*A thing that can be controlled by permissions is registered in the assets table
*JTable handles this transparently via asset_id field
*For view permissions, support is as simple as adding
:::$user = JFactory::getUser();
:::$groups = implode(',', $user->authorisedLevels());
:::$query->where('a.access IN (' . $groups . ')');

For action permissions, same format as in 1.5:
$user->authorise($actionName, $assetName)
*OpenID library moved to plugin folder
*Geshi library moved to plugin folder
*JRegistry notes defaults to JSON (new format), dynamically converting existing data in INI format
*New JStream
*New JApplicationHelper::getComponentName
*Core icons moved to /media/
*Backward incompatible change to JEditor::display
*Added chaining support to JMail
*JFilterInput can no longer be called statically
*JHtml::image now supports relative paths
*All system images are overridable in the default template
*New JHtmlString
*Added wincache session handler for IIS
*New JFilterOutput::stripImages
*JPath::check takes second arg for separator (to pass to JPath::clean)
*Expanded configuration support through config.xml (multiple tabs)

====Core actions====
*core.login.site
*core.login.admin
*core.admin
*core.manage
*core.create
*core.edit
*core.edit.state
*core.delete
*Miscellaneous changes

===Debug Plugin===
*More tools for assisting with translation

===Mootools 1.2/1.3===
*Need to use document.id instead of $

==Cache changes ==
===API changes relevant to 3rd party developers===
====Component view cache====

Component view cache now takes an array of url parameters and their types to create Cacheid. This is a replacement for a previous unsafe way which took the whole URL for this and so opened the doors for DOS attacks via random url parameters added to request URL's.

Com_contact example:

<pre>
$safeurlparams = array(
'id'=>'INT',
'catid'=>'INT', 'limit'=>'INT',
'limitstart'=>'INT',
'filter_order'=>'CMD',
'filter_order_Dir'=>'CMD'
);

parent::display($cachable,$safeurlparams);
</pre>

Old cacheid created from URL was retained for backwards compatibility and takes effect if there are no $safeurlparams.

====Module cache====
This has been completly reconceptualized. Module cache now has 5 different modes of operation, 3 of them are to be set from module XML file, while 2 are meant to be used from within the module itself. Default is backwards compatible oldstatic mode that requires no changes to a module.

Modes to be set in XML:
*'''static''' - one cache file for all pages with the same module parameters
*'''oldstatic''' - 1.5. definition of module caching, one cache file for all pages with the same module id and user aid. Default for backwards compatibility
*'''itemid''' - changes on itemid change

In addition to cache field that was required in 1.5 there is now another hidden field called cachemode that sets any of the above modes.

<pre>
<field name="cachemode" type="hidden" label="" default="static">
<option value="static"></option>
</pre>

Modes to be called from inside the module:
*'''safeuri''' - id is created from $cacheparams->modeparams array, the same as in component view cache
*'''id''' - module sets own cache id's

To use this modes one must rename cache field in xml to owncache field and call JModuleHelper::ModuleCache from within the module's main php file. This is actually a shortcut to cache callback to avoid code duplication in every module.

An example that uses safeuri mode and replaces uncached
$list = modRelatedItemsHelper::getList($params) :

<pre>
$cacheparams = new stdClass;
$cacheparams->cachemode = 'safeuri';
$cacheparams->class = 'modRelatedItemsHelper';
$cacheparams->method = 'getList';
$cacheparams->methodparams = $params;
$cacheparams->modeparams = array('id'=>'int','Itemid'=>'int');
$list = JModuleHelper::ModuleCache ($module, $params, $cacheparams);
</pre>

====Functional changes====
'''Cache administration (Clean cache, Purge cache) now works with all drivers''', not only with file cache.
'''New standalone garbage collect script''' that is to be called from crontab has been added. It can be found in libraries/joomla/utilities/garbagecron.php . For safety reasons it is recommended that it is renamed to something unique.

====CMS and framework level functional changes====
'''Caching is implemented in all components and modules''' that can potentially gain from cache.
Caching has also been added to some most expensive and frequent framework calls JComponentHelper::_load(), JModuleHelper::_load(),JMenuSite::load();

====Cache library changes====
Cache library has been completely refactored.
*Cache '''handlers have been renamed to controllers''' to better reflect their role and avoid confusion with cache storage handlers (referred to as drivers in following text).
*'''New JCacheController''' parent class has been added and inheritance has been changed to prevent bugs occurring from controller's and storage handler's get method clashes.

====JCache====
*'''getAll()''' method was added to JCache, JCacheStorage and all drivers, and it returns all cached items (this was previously possible only with file driver and hardcoded in administration)
*New '''lock and unlock''' methods were added to JCache, JCacheStorage and drivers. They enable cache item locking and unlocking to prevent errors on parallel accesses and double saves. This functionally was also implemented in controllers.
*Workarounds are now consolidated in new '''JCache getWorkarounds and setWorkarounds''' methods, are now used by all controllers and their use has been made optional.
*New makeId() method in JCache that creates cache id from registered url parameters set by components and system plugins

====JCacheController====
New parent class to Controllers that also functions as an intermediate to JCache. There is no JObject inheritance as otherwise magic __call doesn't work.
Change was needed to prevent bugs occurring from controller's and storage handler's get method clashes. They could be renamed but this would break backwards compatibility.

====JCacheStorage====
*_getCacheId method was moved from drivers to their parent JCacheStorage and all drives now use the same method by default
*CacheItem was moved from cache admin to framework JCacheStorageHelper, it is used by getAll
*There are new cachelite and wincache drivers. All other drivers have been fixed with missing functions (gc, clean) added, their code cleaned and tested they should be now working properly.
*Replaced separate _expire files in filecache driver with timestamps (this should amount to cca. 40% speed gain). The same in all drivers that had this.
*Numerous bugfixes on all levels, most important is proper use of options defaulting to configuration parameters settings and correctly passing from level to level.

====Other framework level changes====
*Safe url parameters registration added to JControler view method.
*New ModuleCache method in JModuleHelper that performs the above described module cache (in 5 modes) for both, modules and module renderer.
*JFactory::getFeedParser has been changed to use Joomla caching instead of simplepie's.

==Performance==
===Eliminate the usage of JTable for general browsing on the frontend===
*Session drops the usage of JTable
*Item views use a dedicated question, not JTable->load

==Known Issues==
*Still Mootools 1.2. Will be upgrading to 1.3 during the beta process.
*Scaling issues to address

==Notes==
===Releases===
*Alpha 1: 22 June 2009
*Alpha 2: 25 October 2009
*Beta 1: 18 May 2010
*Beta 2: 31 May 2010
*Beta 3: 14 June 2010
*Beta 4: 28 June 2010
*Beta 5: 12 July 2010
*Beta 6: 26 July 2010
*Beta 7: 09 August 2010

[[Category:Joomla! 1.6]]

J2.5:What's new in Joomla 2.5

2010-09-18T19:44:00Z

Kissaki: /* Articles Manager */

Lots of things.

...and:
* '''New Access Control System''' - Allows site administrators control over who can view and manage content.
* '''Unlimited Depth Organizational Model''' - Gives site administrators and content creators user-defined category levels that allow for the creation of a category tree with as many or as few levels for organizing articles and other content as needed.
* '''One-Click Extension Updates''' - Allows users to keep sites secure and controlled by simplifying the process of updating extensions.
* '''Semantic XHTML Layouts''' - Provides a better baseline for content presentation.

...and:

==Administrators==
===Introduction===
*Consistent UI
*Consistent Features
*Richer sample data
*IE 7+, Firefox 3.x, Safari 4.x
*PHP 5.2.4+
*MySQL 5.0.4 (allows for wide varchars)

===Administrator===
*Menu Changes
*Submenu consistency

====Toolbar Features====
*Save
*Save & Close
*Save & New
*Save as Copy
*Expired session will return to the page you were on then you got logged out (can be hit and miss)
*Most search filters allow you to search for a record id via [ id:123 ]
*"Parameters" are now referred to as "Options"
*Template Styles
*Integrated Trash Management
*Consistent archive support for most content
*Extension Installer Improvements

===Module Enhancements===
*Publish up and down
*Add option to display on all pages "except" selected
*Expanded Category System
*404 Page Redirection
*Better Menu Management
*Alternative layouts for content, modules and menus (taken from the home template)

===New Templates===
*Atomic
*Beez2
*(Administrator) Bluestork (replaces Khephri)
*(Administrator) Hathor
*Legacy layer in Milkyway
*Backend supports layout overrides
*New Modules
*New Plugins
*Content Languages
*User Login Permissions
*Activate selected users from the user list now (and filter)
*Administrator registration approval
*Polls component removed
*New codemirror editor

===SEO Improvements===
*Meta decription and keywords for categories
*Articles can change the page title and page header separately

===Global Configuration===
*Add site name to titles
*Default Access Level
*Set Metadata Language (buggy)
*Unicode Aliases
*Cookie domain and path
*User Setting moved to User Manager -> Options
*Media Settings moved to Media Manager -> Options
*Debug Modules - allows you to enabled to disable the tp=1 feature
*Server Timezone now a location, not an integer offset
*New Global Permissions tab

===User Manager===
*Can activate a user from the list now
*User can be assigned to multiple groups
*Manage user groups
*Manager content access levels

===Media Manager===
*Flash uploader fixed

===Menu Manager===
====Menus List====
*Rebuild button to press when you brick the menu
*Clicking the menu name brings up the menu items list rather than going into Edit Menu. To edit the menu, click on the check box next to the name and click on the Edit icon in the toolbar.

====Items List====
*Menus support the language filter
*Default now called Home
*Home is now clickable in the menu item list
*A separate home can be set for different languages

=====New batch operations=====
*Set access level
*Copy or move to another part of this or another menu

====Edit Item====
*Improved "Type" selector with human readable view and layout names
*Note field added
*New window target
*New Language assignment
*New Template style
*Ability to add & edit Module assignments from this page

=====New options for the menu links and pages themselves=====
*Link title attribute
*Link CSS style
*Menu image is changed to a modal selector
*CSS class for page heading
*Page meta description
*Page meta keywords
*Robots options

===Articles Manager===
*Frontpage is now referred to as Featured
*Article manager uses submenu to quickly skip between articles , categories and featured
*Sections and categories are now merged.

====Articles List====
*''"Missing move and copy; filter by author"''
*New column to show language
*Filtering by language available

====Article Edit====
*Created by user now selected by modal popup
*New ability to set the page title from the article
*Define create, delete, edit and publishing permissions

====Archived Articles====
*In 1.5, Archived Articles had to first be changed to Published or Unpublished before update.
*In 1.6, an Article with an Archived Status *can* be changed without changing the State first.

===Categories===
====Category List====
*Nested view
*Filtering on language

====Edit Category====
*New note field
*Section replaced with ability to assign a parent category
*Ability to assign content language

=====New Options (not previously available in 1.5)=====
*Assign alternate layout
*Define create, delete, edit and publishing permissions
*Meta description
*Meta keywords
*Alternative page title
*Meta author
*Meta robots

===Banners===
====Banners list====
*** Missing copy toolbar button
*New archive toolbar button
*New columns to show meta keywords, purchase type and language
*New filtering by client and language

====Edit Banner====
*New type toggle for Image or Custom (dynamically changes the available form fields)
*New alt text field for image
*New language field

=====New Options=====
*Ability to set the created date
*Ability to set start and finish publishing times
*Ability to set the purchase type
*Ability to track impressions
*Ability to track clicks
*Use own prefix ?
*Tags renamed to meta
*Contacts
*Messaging
*Newsfeeds
*Search
*Weblinks
*Redirect

===Extensions Manager===
====Discover====
*Module mgr
*Plugin Mgr
*Template Mgr
*Language mgr

===Misc===
*Auto create linked contact when creating new user ??

==Access Controls==
*Introduction
*User Groups
*Access Levels
*Permission Layers
*How Permissions are Inherited
*How to debrick your site

==Developers==
===Introduction===
*PHP 5.2.4+
*MySQL 5.0.4 (allows for wide varchars)
*IE7+, Firefox 3+, Safari 4+
*Focus on code consistency
*Focus on code reduction

Usage of PHP Native Functions where possible, for example:
*[[JXMLElement]] extends the native [http://php.net/manual/en/book.simplexml.php SimpleXML] class
*[[JDate]] extends the [http://www.php.net/manual/en/class.datetime.php DateTime] class
*Native INI parser to load languages

===Removed features===
*ADODB compatibility methods in database classes
*DOMIT (unsupported XML library)
*Legacy mode (includes global $mainframe, etc)
*JTemplate (based on patTemplate)
*patTemplate (templating engine)
*PDF support
*PEAR libraries (due to license incompatibilities)
*phpgacl
*PHP 4.0 and 5.0 compatibility files
*XStandard Editor

===Deprecated Features===
*JController::_acoSection
*JController::_acoSectionValue
*JController::authorize()
*JController::setAccessControl()
*JDatabase::stderr()
*JDate::offest
*JDate::setOffset()
*JDate::toFormat() - use JDate::format() instead
*JException::toString()
*JFactory::getXMLParser()
*JHtmlGird::access()
*JHtmlImage::administrator - use JHtml::image instead
*JHtmlImage::site - use JHtml::image instead
*JHtmlList::accesslevel()
*JHtmlList::specificordering() - use JHtml::_('list.ordering')
*JHtmlList::category()
*JHtmlSelect::optgroup() - see JHtmlSelect::groupedList()
*JLanguage::_parseLanguageFiles - renamed to parseLanguageFiles
*JLanguage::_parseXMLLanguageFile - renamed to parseXMLLanguageFile
*JLanguage::_parseXMLLanguageFiles - renamed to parseXMLLanguageFiles
*JObject::toString - replaced with magic method
*JRegistry::getNameSpaces()
*JRegistry::getValue()
*JRegistry::makeNameSpace()
*JRegistry::setValue()
*JPane - See JHtmlSliders
*JParameter - replaced by JForm
*JSimpleXML, JSimpleXMLElement - Use JXMLElement instead, based on the native SimpleXMLElement
*JTable::canDelete() - models or controllers should be doing the access checks
*JTable::toXML()
*JToolbarHelper customX(), addNewX(), editListX(), editHtmlX(), editCssX(), deleteListX()
*JUser::authorize() - Use JUser::authorise()
*JUtility::dump()
*JUtility::array_unshift_ref() - Not needed in PHP 5
*JUtility::getHash() - Use JApplication::getHash()
*JUtility::getToken() - Use JFactory::getSession()->getFormToken()
*JUtility::isWinOS() - Use JApplication::isWinOS()
*JUtility::return_bytes() - See InstallerModelWarnings::return_bytes()
*JUtility::sendMail() - Use JFactory::getMailer()->sendMail()
*JUtility::sendAdminMail() - Use JFactory::getMailer()->sendMail()
*JXMLElement::data() - Provided for backward compatibility
*JXMLElement::getAttribute() - Provided for backward compatibility

===Database===
*JTable now automatically looks up the fields from the database schema
*New JDatabaseQuery - A chained CRUD query builder
*New JDatabase::getNextRow
*New JDatabase::getNextObject
*JDatabase::loadAssocList - Now takes a second argument to just return the value of a column
*JDatabase::setQuery - Added chaining support

====Important Schema Changes====
*New jos_extensions table to list all extensions
*Components table information moved and split between jos_extensions and jos_menu (special menu called _adminmenu)

The old phpgacl (jos_core_acl*) and jos_groups tables have been reworked into:
*jos_assets
*jos_user_usergroup_map
*jos_usergroups
*jos_viewlevels
*Archived state changed from a value of -1 to +2

===Improved MVC===
====Models====
*JModelList
*JModelForm
*JModelAdmin
*Format handling (eg JSON)
*Sub-controller handling

====Controllers====
*JControllerForm
*JControllerAdmin
*JController::setMessage takes second arg to set the message type
*JController can set the default view
*Added chaining support to several JController methods

====Views====
*Semantic core output
*Milkyway legacy layouts
*The old component parameters are not automatically added to the menu anymore. You need to explicitly put them in the layout XML files.
*The menu manager will now detect additional layouts for a given view in the default template.

===Form API===
====Event manipulation====
*onContentPrepareForm
*onContentPrepareFormData

===Translation and Language Support===
*Support for unicode slugs, eg, SEF URL's with Greek characters
*3-letter languages now supported, xxx-XX
*All existing language keys have been refactored

====INI files must validate====
*Upper case key with no spaces, alphanumeric characters and underscores
*Quoted values
*Double quotes within literal strings must use _QQ_ in the form KEY="<a href="_QQ_"index.php"_QQ_">Click</a>"

====Javascript translation layer====
*See the flash uploader script for an example
Local extension language files

====Language file API====
*Pluralisation support
*Transliteration support for ASCII or Unicode slugs
*Ignore Search Words
*Minimum search word length
*Custom language overrides
*System language file to support administrator menu and installation (.sys.ini)

====Language switcher====
*Language Filter plugin enables language switching
*Sets the automatic filtering via JFactory::getApplication()->setLanguageFilter(true)
*A frontend component with language support would test JFactory::getApplication()->getLanguageFilter(), which returns the selected language code from the Languages Module
*The language field can be a language code for a single language, or "*" to be displayed for all languages
*Community extension for language maintenance com_localise

===Extension management===
====New installation types====
=====Libraries=====
*Must include an XML manifest where type="library"
*Can only be installed into a sub-folder of /libraries/
*Can extend parts of an existing library, eg /libraries/joomla/database/database/oracle.php

=====Packages multi-installer=====
*Must include an XML manifest where type="package"
*A package is a zip of zip's

New install script can be provided with 5 methods:
=====preflight=====
*Runs before anything is run and while the extracted files are in the uploaded temp folder

======Could allow for:======
*secondary extraction of custom zip's
*version checks to be performed
*halting the installer on an error

=====install / update=====
*Runs after the database scripts are executed
*If the extension is new, the install method is run
*If the extension exists then update method is run if method="upgrade", otherwise assumes that the extension is not meant to be upgradable

=====postflight=====
*Runs after the extension is registered in the database
*Is not run for the uninstall process (nothing left to do obviously)

====Discover====
*Does not do any file copying, only works with what it finds
*Performs preflight, install and postflight
*Developer of installer has two language files??

====Update site====
*Can publish an XML manifest on your site that can include individual extensions and extension sets.

====XML Manifest Changes====
*<install> is deprecated - use <extension>
*New <update> tag. Takes a <schemas> tag which can define <schemapath>
*<params> and <param> tags are deprecated, use <fields>, <fieldsets> and <field> instead

====File changes====
*Installation manifest must be the same name as the extension, eg com_foobar/foobar.xml This helps with discovery (otherwise the function has to go through all the files in the extension folder
*Plugins are now in folders like modules and components
*See SVN/tests/_data/installer_packages/ for complete examples of all extensions and manifests.
*The method="upgrade" will compare individual files in the original and incoming manifests and will remove files as appropriate. However, it will not remove differences in the <folder> tags.
*Future support for rollback

===Events===
====New Events====
*onBeforeRender
*onContentBeforeDelete
*onContentAfterDelete
*onContentChangeState
*onContentPrepareForm
*onContentPrepareFormData
*onExtensionBeforeInstall
*onExtensionBeforeUpdate
*onExtensionBeforeUninstall
*onExtensionAfterInstall
*onExtensionAfterUpdate
*onExtensionAfterUninstall

====Renamed Events====
*onContentAfterSave
*onContentAfterTitle
*onContentAfterDisplay
*onContentBeforeDisplay
*onContentBeforeSave
*onContentSearch
*onContentSearchAreas
*onUserAuthenticate
*onUserAfterDelete
*onUserAfterSave
*onUserBeforeDelete
*onUserBeforeSave
*onUserLogin
*onUserLogout
*All content events (except for search and search areas) now pass a 'context' as the first argument to alert the plugin as to what type of content is being passed. The plugin event may or may not heed this context.

===Categories===
*Component can provide custom options for its own categories via optional category.xml
*Supported via JTableNested

===Access Controls===
*A thing that can be controlled by permissions is registered in the assets table
*JTable handles this transparently via asset_id field
*For view permissions, support is as simple as adding
:::$user = JFactory::getUser();
:::$groups = implode(',', $user->authorisedLevels());
:::$query->where('a.access IN (' . $groups . ')');

For action permissions, same format as in 1.5:
$user->authorise($actionName, $assetName)
*OpenID library moved to plugin folder
*Geshi library moved to plugin folder
*JRegistry notes defaults to JSON (new format), dynamically converting existing data in INI format
*New JStream
*New JApplicationHelper::getComponentName
*Core icons moved to /media/
*Backward incompatible change to JEditor::display
*Added chaining support to JMail
*JFilterInput can no longer be called statically
*JHtml::image now supports relative paths
*All system images are overridable in the default template
*New JHtmlString
*Added wincache session handler for IIS
*New JFilterOutput::stripImages
*JPath::check takes second arg for separator (to pass to JPath::clean)
*Expanded configuration support through config.xml (multiple tabs)

====Core actions====
*core.login.site
*core.login.admin
*core.admin
*core.manage
*core.create
*core.edit
*core.edit.state
*core.delete
*Miscellaneous changes

===Debug Plugin===
*More tools for assisting with translation

===Mootools 1.2/1.3===
*Need to use document.id instead of $

==Cache changes ==
===API changes relevant to 3rd party developers===
====Component view cache====

Component view cache now takes an array of url parameters and their types to create Cacheid. This is a replacement for a previous unsafe way which took the whole URL for this and so opened the doors for DOS attacks via random url parameters added to request URL's.

Com_contact example:

<pre>
$safeurlparams = array(
'id'=>'INT',
'catid'=>'INT', 'limit'=>'INT',
'limitstart'=>'INT',
'filter_order'=>'CMD',
'filter_order_Dir'=>'CMD'
);

parent::display($cachable,$safeurlparams);
</pre>

Old cacheid created from URL was retained for backwards compatibility and takes effect if there are no $safeurlparams.

====Module cache====
This has been completly reconceptualized. Module cache now has 5 different modes of operation, 3 of them are to be set from module XML file, while 2 are meant to be used from within the module itself. Default is backwards compatible oldstatic mode that requires no changes to a module.

Modes to be set in XML:
*'''static''' - one cache file for all pages with the same module parameters
*'''oldstatic''' - 1.5. definition of module caching, one cache file for all pages with the same module id and user aid. Default for backwards compatibility
*'''itemid''' - changes on itemid change

In addition to cache field that was required in 1.5 there is now another hidden field called cachemode that sets any of the above modes.

<pre>
<field name="cachemode" type="hidden" label="" default="static">
<option value="static"></option>
</pre>

Modes to be called from inside the module:
*'''safeuri''' - id is created from $cacheparams->modeparams array, the same as in component view cache
*'''id''' - module sets own cache id's

To use this modes one must rename cache field in xml to owncache field and call JModuleHelper::ModuleCache from within the module's main php file. This is actually a shortcut to cache callback to avoid code duplication in every module.

An example that uses safeuri mode and replaces uncached
$list = modRelatedItemsHelper::getList($params) :

<pre>
$cacheparams = new stdClass;
$cacheparams->cachemode = 'safeuri';
$cacheparams->class = 'modRelatedItemsHelper';
$cacheparams->method = 'getList';
$cacheparams->methodparams = $params;
$cacheparams->modeparams = array('id'=>'int','Itemid'=>'int');
$list = JModuleHelper::ModuleCache ($module, $params, $cacheparams);
</pre>

====Functional changes====
'''Cache administration (Clean cache, Purge cache) now works with all drivers''', not only with file cache.
'''New standalone garbage collect script''' that is to be called from crontab has been added. It can be found in libraries/joomla/utilities/garbagecron.php . For safety reasons it is recommended that it is renamed to something unique.

====CMS and framework level functional changes====
'''Caching is implemented in all components and modules''' that can potentially gain from cache.
Caching has also been added to some most expensive and frequent framework calls JComponentHelper::_load(), JModuleHelper::_load(),JMenuSite::load();

====Cache library changes====
Cache library has been completely refactored.
*Cache '''handlers have been renamed to controllers''' to better reflect their role and avoid confusion with cache storage handlers (referred to as drivers in following text).
*'''New JCacheController''' parent class has been added and inheritance has been changed to prevent bugs occurring from controller's and storage handler's get method clashes.

====JCache====
*'''getAll()''' method was added to JCache, JCacheStorage and all drivers, and it returns all cached items (this was previously possible only with file driver and hardcoded in administration)
*New '''lock and unlock''' methods were added to JCache, JCacheStorage and drivers. They enable cache item locking and unlocking to prevent errors on parallel accesses and double saves. This functionally was also implemented in controllers.
*Workarounds are now consolidated in new '''JCache getWorkarounds and setWorkarounds''' methods, are now used by all controllers and their use has been made optional.
*New makeId() method in JCache that creates cache id from registered url parameters set by components and system plugins

====JCacheController====
New parent class to Controllers that also functions as an intermediate to JCache. There is no JObject inheritance as otherwise magic __call doesn't work.
Change was needed to prevent bugs occurring from controller's and storage handler's get method clashes. They could be renamed but this would break backwards compatibility.

====JCacheStorage====
*_getCacheId method was moved from drivers to their parent JCacheStorage and all drives now use the same method by default
*CacheItem was moved from cache admin to framework JCacheStorageHelper, it is used by getAll
*There are new cachelite and wincache drivers. All other drivers have been fixed with missing functions (gc, clean) added, their code cleaned and tested they should be now working properly.
*Replaced separate _expire files in filecache driver with timestamps (this should amount to cca. 40% speed gain). The same in all drivers that had this.
*Numerous bugfixes on all levels, most important is proper use of options defaulting to configuration parameters settings and correctly passing from level to level.

====Other framework level changes====
*Safe url parameters registration added to JControler view method.
*New ModuleCache method in JModuleHelper that performs the above described module cache (in 5 modes) for both, modules and module renderer.
*JFactory::getFeedParser has been changed to use Joomla caching instead of simplepie's.

==Performance==
===Eliminate the usage of JTable for general browsing on the frontend===
*Session drops the usage of JTable
*Item views use a dedicated question, not JTable->load

==Known Issues==
*Still Mootools 1.2. Will be upgrading to 1.3 during the beta process.
*Scaling issues to address

==Notes==
===Releases===
*Alpha 1: 22 June 2009
*Alpha 2: 25 October 2009
*Beta 1: 18 May 2010
*Beta 2: 31 May 2010
*Beta 3: 14 June 2010
*Beta 4: 28 June 2010
*Beta 5: 12 July 2010
*Beta 6: 26 July 2010
*Beta 7: 09 August 2010

[[Category:Joomla! 1.6]]

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

2010-09-12T15:27:34Z

Kissaki: /* The Hello Controller */ when the heck did the component change its name from hello to hellos???

== 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 code for the controller at admin/controllers/hello.php:
<source lang="php">
<?php
/**
* Hello Controller for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

/**
* Hello Hello Controller
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosControllerHello extends HellosController
{
/**
* constructor (registers additional tasks to methods)
* @return void
*/
function __construct()
{
parent::__construct();

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

/**
* display the edit form
* @return void
*/
function edit()
{
JRequest::setVar( 'view', 'hello' );
JRequest::setVar( 'layout', 'form' );
JRequest::setVar('hidemainmenu', 1);

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

==== 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 code for the view at admin/views/hello/view.html.php:
<source lang="php">
<?php
/**
* Hello View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

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

/**
* Hello View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHello extends JView
{
/**
* 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 __construct( &$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 [http://docs.joomla.org/API15:JTable/bind 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 [http://docs.joomla.org/API15:JTable/check 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 [http://docs.joomla.org/API15:JTable/store 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/Adding Backend Actions

2010-09-12T15:24:45Z

Kissaki: /* The Hello Controller */ csty

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

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

The code for the controller at admin/controllers/hello.php:
<source lang="php">
<?php
/**
* Hello Controller for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

/**
* Hello Hello Controller
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosControllerHello extends HellosController
{
/**
* constructor (registers additional tasks to methods)
* @return void
*/
function __construct()
{
parent::__construct();

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

/**
* display the edit form
* @return void
*/
function edit()
{
JRequest::setVar( 'view', 'hello' );
JRequest::setVar( 'layout', 'form' );
JRequest::setVar('hidemainmenu', 1);

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

==== 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 code for the view at admin/views/hello/view.html.php:
<source lang="php">
<?php
/**
* Hello View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

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

/**
* Hello View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHello extends JView
{
/**
* 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 __construct( &$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 [http://docs.joomla.org/API15:JTable/bind 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 [http://docs.joomla.org/API15:JTable/check 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 [http://docs.joomla.org/API15:JTable/store 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/Adding Backend Actions

2010-09-12T15:24:16Z

Kissaki: /* The Hello Controller */ csty

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

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

The code for the controller at admin/controllers/hello.php:
<source lang="php">
<?php
/**
* Hello Controller for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

/**
* Hello Hello Controller
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosControllerHello extends HellosController
{
/**
* constructor (registers additional tasks to methods)
* @return void
*/
function __construct()
{
parent::__construct();

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

/**
* display the edit form
* @return void
*/
function edit()
{
JRequest::setVar( 'view', 'hello' );
JRequest::setVar( 'layout', 'form' );
JRequest::setVar('hidemainmenu', 1);

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

==== 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 code for the view at admin/views/hello/view.html.php:
<source lang="php">
<?php
/**
* Hello View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

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

/**
* Hello View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHello extends JView
{
/**
* 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 __construct( &$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 [http://docs.joomla.org/API15:JTable/bind 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 [http://docs.joomla.org/API15:JTable/check 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 [http://docs.joomla.org/API15:JTable/store 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/Adding Backend Actions

2010-09-12T15:19:16Z

Kissaki: /* The Hello Controller */ fix

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

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

The code for the controller at admin/controllers/hello.php:
<source lang="php">
<?php
/**
* Hello Controller for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

/**
* Hello Hello Controller
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosControllerHello extends HellosController
{
/**
* constructor (registers additional tasks to methods)
* @return void
*/
function __construct()
{
parent::__construct();

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

/**
* display the edit form
* @return void
*/
function edit()
{
JRequest::setVar( 'view', 'hello' );
JRequest::setVar( 'layout', 'form' );
JRequest::setVar('hidemainmenu', 1);

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

==== 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 code for the view at admin/views/hello/view.html.php:
<source lang="php">
<?php
/**
* Hello View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

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

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

/**
* Hello View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHello extends JView
{
/**
* 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 __construct( &$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 [http://docs.joomla.org/API15:JTable/bind 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 [http://docs.joomla.org/API15:JTable/check 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 [http://docs.joomla.org/API15:JTable/store 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/Basic Backend Framework

2010-09-12T14:17:19Z

Kissaki: /* The Hellos View */

== 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:Development]]

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

2010-09-11T18:19:12Z

Kissaki: /* Posting Form Data to the Joomla! Engine */ remove rather non-fitting sentence

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

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

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

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

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

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

<menu>Hello World!</menu>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Conclusion ==

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

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

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

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

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

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

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

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]

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

2010-09-11T14:00:17Z

Kissaki: /* Views */ indent

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

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

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

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

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

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

<menu>Hello World!</menu>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Conclusion ==

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

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

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

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

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

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

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

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]