Joomla! Documentation - User contributions [en]

Archived:Upgrading a Joomla 1.5 template to Joomla 2.5

2011-01-18T23:51:15Z

Probie715: corrected typographical errors

{{Underconstruction}}
{{RightTOC}}
== Template parameters ==
In both Joomla! 1.5 and 1.6 template parameters are defined in templateDetails.xml.

Whereas in 1.5 parameters are defined as part of the <code><params></code> section, and each parameter is defined as a <code><param></code>, in 1.6 template parameters are contained in the <code><config></code> section and treated as a <code><field></code> nested within the <code><fieldset></code> and <code><fields></code> tags, as illustrated below.

<pre>
<config>
<fields name="params">
<fieldset name="basic">
<field name="" type=" default="" label="" description="">
<option value="1">On</option>
<option value="0">Off</option>
</field>
<field name="" type="" default="" label="e" description="" />
</fieldset>
</fields>
</config>
</pre>

<code><fieldset name="basic"></code> wraps the parameters in a slider and using name="basic" labels that slider as "Basic Options" and name="advanced" labels it as "Advanced Options".

The name="" type=" default="" label="" description="" attributes still apply.

== Objects and Methods ==
=== Sitename ===

* <code><?php echo $mainframe->getCfg('sitename');?></code> is now <code>$app->getCfg('sitename');</code> Where <code>$app = JFactory::getApplication();</code>

=== Error Codes ===
* <code>$this->error->code</code> is replaced by <code>$this->error->getCode();</code>
* <code>$this->error->message</code> is replaced by </code>$this->error->getMessage();</code>

[[Category:Joomla! 1.6]]

Publishers

2010-07-14T20:44:17Z

Probie715: fix gramatics

{{review}}

To understand more about what a publisher can do, we need to clarify about the Access Control Levels (ACL). In other words ACL's govern the permissions that are associated with the individual User levels. There are seven (7) User Groups/levels within Joomla. Four (4) only have access to the Site Front-end: Registered, Author, Editor, and Publisher. There are also three (3) levels with access to the Administrator Back-end: Manager, Administrator, and Super Administrator. In addition to the registered User Groups listed above there is a Public (unregistered) or Guest, level.

So a publisher is a User level with access only to the Site Front-end functions, but with permission to publish content on the Site.

Register globals

2010-06-06T12:00:35Z

Probie715: typographical edit

{{review}}

== What is it? ==

<tt>register_globals</tt> is a PHP environment setting that has been the subject of controversy for sometime. Older versions of PHP often have this variable set to on and that setting is known to leave a site vulnerable to hacking. Further information is available at [http://us.php.net/register_globals the PHP website]. Current Joomla! releases do not require this setting to be on, and best practices dictate that it should be changed to off. (Joomla! 1.0.x releases also have a related emulator for this setting, which was implemented for backward compatibility with older components and extensions. ''It is generally preferred not to enable this capability''.) If you have a component that requires this setting, you should look for an update, or find an alternative component.

== Can I change it? ==
Yes, maybe. Depending on how much control you have over your server, there are several approaches to addressing this setting.

If you have complete control of your server, then you probably want to make sure that your main PHP configuration file (which is typically found in /usr/local/lib/php.ini) has the directive ''register_globals'' set to 0(zero).

If you're in a shared web environment, most likely your hosting provider will not let you modify the global php.ini file. You have a couple of options in this case.

== Where do I change it? ==
Possibly the easiest thing to do is to ask your hosting provider to make this change for your domain. (Often this is accomplished by logging a technical support request.) But not all providers will make this change for you. So you may not be so lucky. The good news is that there are likely other options available to you, and here are some of them.

'''Local php configuration file:'''
If you have access to your web site's root directory, you should be able to include your own copy of a php.ini file. Your copy only needs to include the settings that you want to alter from the global settings.

'''Change to .htaccess:'''
Another option is to introduce the preferred setting by making an entry in the .htaccess file at the root directory of your web site. In this case, you should add the following line to .htaccess
: '''Important''': This method is only suitable for the Apache PHP ''module'' and will not work if PHP runs in CGI-mode.
php_flag register_globals off

'''Joomla's Global Register Emulator:'''
In the case where you have an extension that absolutely needs to have register_globals on, Joomla! 1.0.x provides an alternative approach that does not require a change to your global settings. The ''globals.php'' file in your site's root directory has an entry that lets Joomla! emulate a change to the register_globals site setting. You will find a line that looks as such:

define( 'RG_EMULATION', 0 );

You can change the zero to a one, if you want Joomla to emulate ''register_globals = on''.
[[Category:Landing Pages]]

Coding style and standards

2010-05-05T21:40:55Z

Probie715: Corrected a few typos

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

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
{
// 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 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 ($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/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 ===

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

Cache

2010-04-26T01:34:21Z

Probie715: corrected typographical errors

{{review}}
Joomla has different ways of caching "things". Here is an overview for administrators and developers, what, where and when..

=Cache partly broken=
{{notice| All cache storages except filecache are broken in Joomla 1.5. Though they are all redirected to the filecache since a certain 1.5 version, there still seem to be some problems with this workaround. (See [[Talk:Cache]])}}
=For Administrators=
A Joomla administrator can use these caches and options:
==Page Caching==
*'''Configuration''': Built-in Plugin (Extensions -> Plugin Manager -> System - Cache)
*'''Caches''': each whole page of your site
*'''Based on''': URL
*'''More info''':
**Optional browser caching: Also caches on your visitors' browser/computer
**Only caches pages for guest visitors (not for logged in visitors)

==View Caching==
*'''Configuration''': Global Config->Cache
*'''Caches''': each view of a component
*'''Based on''': URL, view, parameters, ...
*'''More info''': Component developers have to include this in their code to work. Mostly this is not done. The Joomla main content component uses this, but only for guest visitors of your site though this is not obligated for every component.
==Module Caching==
*'''Configuration''': Global Config->Cache
*'''Caches''': each module (individually customized via each module's Advanced Parameters)
*'''Based on''': ?
*'''More info''': You must disable it on some modules to avoid problems
==Further Caching==
If you want to check out other cache systems and possibilities, you might want to check out the third-party extensions around caching.
==Caching engines or storages==
*'''Configuration''': Global Config->Cache
Here you can choose which system you want your site to use for all caching. Current options are: APC, Eaccelorator, File, Memcache, XCache.

APC, for example, also caches your php opcode.

=For Developers=
The class '''[[JCache]]''' allows a lot of different sorts and levels of caching. The following sub-classes are made specifically, but you can add your own, or use the main one in many different ways.

Don't forget that the first level of cache encountered, will override any deeper caching. I suppose that too many levels is also counterproductive (''to be verified though'').
*'''[[JCacheView]]''' caches and returns the output of a given view (in MVC). A cache id is automatically generated from the URI, specific view and its specific method, or you can give your own.
This can automatically be done via the base controller's display function. For example in the controller of your component:
<source lang="php">class DeliciousController extends JController {
function display() {
parent::display(true); //true asks for caching.
}
}</source>
*'''[[JCachePage]]''' caches and returns the body of the page.
*'''[[JCacheCallback]]''' caches and returns the output and results of functions or methods.
If you want to cache queries, this is a good class for it, as illustrated here: [[Using caching to speed up your code]]
*'''[[JCacheOutput]]''' caches and returns output.
This is rather meant for caching a specific part of php code. It acts like an output buffer, but cached.

=References=
* [http://forum.joomla.org/viewtopic.php?f=428&t=326990&start=0 Better performance with joomla System Cache plugin (Joomla Forum)]
* [[JCache]]

<noinclude>[[Category:Development]] [[Category:Cache]] [[Category:Manual]]</noinclude>

J1.5:Creating a simple module

2010-04-26T01:30:22Z

Probie715: corrected typographical errors

{{review}}
== Basic Hello World Module ==

A Joomla! 1.5 Module is in its most basic form two files: an XML configuration file and a PHP controller file. The XML configuration file contains general information about the module (as will be displayed in the Module Manager in the Joomla! administration interface), as well as module parameters which may be supplied to fine tune the appearance / functionality of the module. The PHP file provides the controlling logic for the module. A very simple "Hello World" module might looking something like this.

'''/modules/mod_hello_world/mod_hello_world.xml:'''

'''!!! Note:''' it is very important, that XML file name matches module name. Otherwise, installer will install the module, but Joomla wouldn't show parameters and additional info stored in XML.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">

<name>Hello World - Hello</name>


<author>Ambitionality Software LLC</author>


<creationDate>2008-06-23</creationDate>


<copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright>


<license>GPL 2.0</license>


<authorEmail>info@ambitionality.com</authorEmail>


<authorUrl>www.ambitionality.com</authorUrl>


<version>1.0.0</version>


<description>Provides a basic "Hello World" notice</description>


<files>

<filename module="mod_hello_world">mod_hello_world.php</filename>
<filename>index.html</filename>
</files>


<params />
</install>
</source>

Basically, this XML file just lines out basic information about the module such as the owner, version, etc. for identification by the Joomla! installer and then provides optional parameters which may be set in the Module Manager and accessed from within the module's logic to fine tune its behavior. Additionally, this file tells the installer which files should be copied and installed. Notice that we DO NOT include a reference in the files section for the XML file.

'''/modules/mod_hello_world/mod_hello_world.php:'''

<source lang="php">
<?php
//don't allow other scripts to grab and execute our file
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
?>
<p>
Hello World
</p>
</source>

What happens when this module is loaded is that Joomla! includes (via the PHP include directive) the mod_hello_world.php file and stores the output into an output buffer which is then rendered onto the page output. This file would simply produce <p>Hello World</p> to the final page.

'''/modules/mod_hello_world/index.html:'''

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

This really just helps to ensure that a default page is displayed if direct access to the directory is attempted without listing all of the other files in the directory. It's not necessary, but is good practice.

To package this module for distribution and installation, simply zip the files together, e.g.,

<source lang="text">
% cd mod_hello_world
% zip mod_hello_world.zip mod_hello_world.php mod_hello_world.xml index.html
</source>

The resulting mod_hello_world.zip file may be uploaded and installed through the standard Joomla! 1.5 Extension Manager.

== Real Joomla! 1.5 Style Module Implementation ==

Now that was easy...too easy. In fact, that was pretty much the simplest form of a module possible. In reality a module will probably be doing something much more substantial. Let's assume that our modules are going to be more complex - we need to take advantage of the MVC (Model View Controller) design pattern and consider using the following file layout for a "Hello World 2" module instead:

<source lang="text">
/modules/mod_hello_world2/index.html
/modules/mod_hello_world2/mod_hello_world2.php
/modules/mod_hello_world2/mod_hello_world2.xml
/modules/mod_hello_world2/helper.php
/modules/mod_hello_world2/en-GB.mod_hello_world2.ini
/modules/mod_hello_world2/tmpl/index.html
/modules/mod_hello_world2/tmpl/default.php
</source>

The differences to note here are that there are three additional files beyond what the "Hello World" module had, namely helper.php, tmpl/default.php, and the en-GB.mod_hello_world2.ini file. The purpose in adding the first two files is two-fold. Firstly, we separate the module's logic into the helper.php file to ensure that all of the thinking and data access is performed here and separate out the module's presentation / template into the tmpl/default.php file (the (X)HTML). I argue that this is just good programming - separating logic from presentation. There is a second advantage to this, however, which is that it will allow the HTML / presentation to be overridden easily by any Joomla! 1.5 template for optimal integration into any site. (Overriding module and component presentation in templates is beyond the scope of this article, however it should be addressed as it's really useful).

Let's take a look at what these files might look like and discuss what's going on.

'''/modules/mod_hello_world2/mod_hello_world2.php:'''

<source lang="php">
<?php
//no direct access
defined('_JEXEC') or die('Direct Access to this location is not allowed.');

// include the helper file
require_once(dirname(__FILE__).DS.'helper.php');

// get a parameter from the module's configuration
$userCount = $params->get('usercount');

// get the items to display from the helper
$items = ModHelloWorld2Helper::getItems($userCount);

// include the template for display
require(JModuleHelper::getLayoutPath('mod_hello_world2'));
?>
</source>

The important differences to note are that (1) we include a helper file which will be the work-horse of our logic and data access and (2) once we have our data, we just load a template which will use our data and render it as it sees fit.

'''/modules/mod_hello_world2/mod_hello_world2.xml'''

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">

<name>Hello World 2 - Hello</name>


<author>Ambitionality Software LLC</author>


<creationDate>2008-06-23</creationDate>


<copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright>


<license>GPL 2.0</license>


<authorEmail>info@ambitionality.com</authorEmail>


<authorUrl>www.ambitionality.com</authorUrl>


<version>1.0.0</version>


<description>Provides a random listing of registered users</description>


<files>

<filename module="mod_hello_world2">mod_hello_world2.php</filename>
<filename>index.html</filename>
<filename>helper.php</filename>
<filename>tmpl/default.php</filename>
<filename>tmpl/index.html</filename>
</files>

<languages>

<language tag="en-GB">en-GB.mod_hello_world2.ini</language>
</languages>


<params>

<param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />


<param name="@spacer" type="spacer" default="" label="" description="" />


<param name="usercount" type="text" default="5" label="LABEL USER COUNT" description="DESC USER COUNT" />
</params>
</install>
</source>

The main differences to note here are that we have added a language file reference (we could have added more) and we added some parameters.

'''/modules/mod_hello_world2/helper.php:'''

<source lang="php">
<?php
defined('_JEXEC') or die('Direct Access to this location is not allowed.');

class ModHelloWorld2Helper
{
/**
* Returns a list of post items
*/
public function getItems($userCount)
{
// get a reference to the database
$db = &JFactory::getDBO();

// get a list of $userCount randomly ordered users
$query = 'SELECT a.name FROM `#__users` AS a ORDER BY rand() LIMIT ' . $userCount . '';

$db->setQuery($query);
$items = ($items = $db->loadObjectList())?$items:array();

return $items;
} //end getItems

} //end ModHelloWorld2Helper
?>
</source>

This helper class (note that it is named for the module name so that it doesn't collide with other class names) simply retrieves a list of all users in the database and randomly selects a subset of those based upon the number supplied as $userCount.

'''/modules/mod_hello_world2/tmpl/default.php:'''

<source lang="php">
<?php defined('_JEXEC') or die('Restricted access'); // no direct access ?>
<?php echo JText::_('RANDOM USERS'); ?>
<ul>
<?php foreach ($items as $item) { ?>
<li>
<?php echo JText::sprintf('USER LABEL', $item->name); ?>
</li>
<?php } ?>
</ul>
</source>

Here we simply create an unordered HTML list and then iterate through the items returned by our helper (in mod_hello_world2.php), printing out a message with each user's name.

'''/modules/mod_hello_world2/en-GB.mod_hello_world2.ini:'''

<source lang="text">
LABEL USER COUNT=User Count
DESC USER COUNT=The number of users to display
RANDOM USERS=Random Users for Hello World2
USER LABEL=%s is a randomly selected user
</source>

Here we simply identify strings which appear in the module configuration file and the module template which appear in JText::_ or JText::sprintf statements. This allows someone to easily write a new language file without editing any of the HTML or code for the module.

Now all we have to do is zip up these files, as in:

<source lang="text">
% pwd
/somesite/modules/mod_hello_world2
% zip -r ../mod_hello_world2.zip *
% ls ..
mod_hello_world2.zip
</source>

The resulting mod_hello_world2.zip file is ready for installation and distribution. When the ZIP file is installed, the en-GB.mod_hello_world2.ini file is copied to /language/en-GB/en-GB.mod_hello_world2.ini and is loaded each time the module is loaded. All of the other files are copied to the /modules/mod_hello_world2 subfolder of the Joomla! installation.
<noinclude>[[Category:Development]]</noinclude>

Unable to connect to the database

2010-04-26T01:25:36Z

Probie715: Corrected misspelling in page title

<startFeed />

{{review}}
== Unable to Connect to the Database: Could Not Connect to MySQL ==
If during or after installation, you received "'''Unable to connect to the database'''" error, verify that you have entered your MySQL database details correctly. The installation script will not allow you to continue unless the details are correct.

If the failure occurs after moving your site to another host, check the following items of your ''configuration.php'' file. The normal database settings are the following:
<pre>
var $dbtype = 'mysql';
var $host = 'localhost';
var $user = 'user_with_database_access';
var $db = 'the_actual_database_name';
var $dbprefix = 'table_prefix_';
</pre>

== The Most Common Reasons ==
# Sometimes you will see this message if MySQL has stopped running on your server. Your server administrator may temporarily turn MySQL off to run maintenance utilities. In such circumstances, your site will likely return shortly.
# Your database user has been deleted. If this is the case, you will need to recreate your database user with the same username and password that existed when you first installed Joomla. Use your domain control panel to administer this or contact your server administrator.
# Your database username or password has changed.

[[Category:FAQ]]
[[Category:Administration FAQ]]
[[Category:Getting Started FAQ]]
[[Category:Version 1.5 FAQ]]
<endFeed />