Joomla! Documentation - User contributions [en]

J1.5:Component parameters

2009-07-15T09:33:20Z

Darkick: /* Storing the parameters and their values. */

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The url parameter specifies a parameter which is added to the URL of the menu item. To enable this functionality, you must create a new class which extends JElement and put it in the administrator/components/com_COMPONENT_NAME directory. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template (not to be confused with the site Template, which is different!) directory and with the same name as the template, i.e. <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/TEMPLATE_NAME.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types.

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> tag will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( &$row->params );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

<noinclude>[[Category:Development]][[Category:Components]][[Category:Parameters]]</noinclude>

Coding style and standards

2009-07-14T09:30:51Z

Darkick: /* Function Definitions */ Removed spaces in definition of the fooFunction

{{review}}
{{RightTOC}}
remark: The following information has been copied from the old WIKI archive has not yet been reviewed.
See: http://dev.joomla.org/component/option,com_jd-wiki/Itemid,/id,standards:coding/

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.

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

== 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 judgement 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
{
// Use one true brace in control structures
// when the block is longer than one line
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 the "one true brace" 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 here: http://www.phpdoc.org/

See also [[Adding phpDocumentor 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 - commented code 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 whitespace 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 string must using 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 ($debug) {
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
/**
* @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/utitilies/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 sectino of code.

Files included from third party sources must leave DocBlocks intact.

Layout files do not need full DocBlocks. However, they do require and Id tag and direct access block as follows:

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

== 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 tradationally uppercase acryonyms (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 uppercased 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 uppsercase 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 ===

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 a "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 ''[Folder]Plugin[Element]''.

<source lang="php">
class ContentPluginPagebreak 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 granual control in order to render individual parts or repetitive items of the data.

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

=== Templates ===

=== Template Layout Overrides ===