Joomla! Documentation - User contributions [en]

Using Joomla Ajax Interface

2014-05-16T13:19:41Z

Jonasfh: Format is required in 3.3 as far as I can see

<noinclude>{{version/tutor|3.2}}</noinclude>
==What is The Joomla Ajax Interface (com_ajax)==
A slim, extensible component to act as an entry point for HTTP requests for stand alone modules and plugins, thus allowing for the potential of Ajax functionality in them. Com_ajax is generally used when you are not the developer of the component that the module or plugin is interacting with.

'''NOTE''': If you are a component developer, you do not need to use com_ajax to implement Ajax functionality in it. You can do so directly in your component.

Examples of use cases include, but are not limited to:
*A module that retrieves data from an external API
*A module that interacts with a component that you did not develop
*A plugin that implement API like functionality to allow consumption of data from your site

==Anatomy of an Ajax Request==

===Required===

*<code>option=com_ajax</code>
*<code>[module|plugin]=name</code>
*<code>format=[json|debug|raw]</code>

===Optional===
*<code>method=[custom fragment]</code> defaults to <code>get</code> if omitted.

===Overview===
All requests begin with <code>?option=com_ajax</code>, which calls this extension, and must indicate the type of extension to call, and the data format to be returned.

Additional variables and values used by your extension may also be included in the URL.

For example, a request to <code>?option=com_ajax&module=session</code> would call <code>mod_session</code> with results returned in the default format. In contrast,<code>?option=com_ajax&plugin=session&format=json</code> would trigger the <code>onAjaxSession</code> plugin group with results returned in JSON.

==Module Support==

===Summary===

Module support is accomplished by calling a method in the module's <code>helper.php</code> file.

===Details===

Module requests must include the <code>module</code> variable in the URL, paired with the name of the module (i.e. <code>module=session</code> for <code>mod_session</code>).

This value is also used for:

*The name of the directory to check for the helper file, e.g. <code>/modules/mod_session/helper.php</code>

*The class name to call, e.g. <code>modSessionHelper</code>

Optionally, the <code>method</code> variable may be included to override the default method prefix of <code>get</code>.

:'''NOTE''': All methods must end in <code>Ajax</code>. For example:
:<code>method=mySuperAwesomeMethodToTrigger</code> will call <code>mySuperAwesomeMethodToTriggerAjax</code>

The [https://github.com/Joomla-Ajax-Interface/Ajax-Session-Module Ajax Session Module] is an example module that demonstrates this functionality.

==Plugin Response==

===Summary===

Plugin support is accomplished by triggering the <code>onAjax[Name]</code> plugin event.

===Details===

Plugin requests must include the <code>plugin</code> variable in the URL, paired with the name of the plugin event, e.g. <code>plugin=session</code> for <code>onAjaxSession</code>.

This value is also used for:

*The plugin class name following the <code>plgAjax[Name]</code> convention.
*The plugin function name following the <code>onAjax[Name]</code> convention.

The [https://github.com/Joomla-Ajax-Interface/Ajax-Latest-Articles Ajax Latest Articles plugin] is an example plugin that demonstrates this functionality.

==Response Format==

<code>format=[json|debug]</code> is an optional argument for the results format:

*<code>json</code> for JSON format
*<code>debug</code> for human-readable output of the results.

[[Category:AJAX]]
[[Category:JavaScript]]
[[Category:Development]]

Using Joomla Ajax Interface

2014-05-16T13:17:36Z

Jonasfh:

<noinclude>{{version/tutor|3.2}}</noinclude>
==What is The Joomla Ajax Interface (com_ajax)==
A slim, extensible component to act as an entry point for HTTP requests for stand alone modules and plugins, thus allowing for the potential of Ajax functionality in them. Com_ajax is generally used when you are not the developer of the component that the module or plugin is interacting with.

'''NOTE''': If you are a component developer, you do not need to use com_ajax to implement Ajax functionality in it. You can do so directly in your component.

Examples of use cases include, but are not limited to:
*A module that retrieves data from an external API
*A module that interacts with a component that you did not develop
*A plugin that implement API like functionality to allow consumption of data from your site

==Anatomy of an Ajax Request==

===Required===

*<code>option=com_ajax</code>
*<code>[module|plugin]=name</code>
*<code>format=[json|debug]</code> defaults to raw if omitted.

===Optional===
*<code>method=[custom fragment]</code> defaults to <code>get</code> if omitted.

===Overview===
All requests begin with <code>?option=com_ajax</code>, which calls this extension, and must indicate the type of extension to call, and the data format to be returned.

Additional variables and values used by your extension may also be included in the URL.

For example, a request to <code>?option=com_ajax&module=session</code> would call <code>mod_session</code> with results returned in the default format. In contrast,<code>?option=com_ajax&plugin=session&format=json</code> would trigger the <code>onAjaxSession</code> plugin group with results returned in JSON.

==Module Support==

===Summary===

Module support is accomplished by calling a method in the module's <code>helper.php</code> file.

===Details===

Module requests must include the <code>module</code> variable in the URL, paired with the name of the module (i.e. <code>module=session</code> for <code>mod_session</code>).

This value is also used for:

*The name of the directory to check for the helper file, e.g. <code>/modules/mod_session/helper.php</code>

*The class name to call, e.g. <code>modSessionHelper</code>

Optionally, the <code>method</code> variable may be included to override the default method prefix of <code>get</code>.

:'''NOTE''': All methods must end in <code>Ajax</code>. For example:
:<code>method=mySuperAwesomeMethodToTrigger</code> will call <code>mySuperAwesomeMethodToTriggerAjax</code>

The [https://github.com/Joomla-Ajax-Interface/Ajax-Session-Module Ajax Session Module] is an example module that demonstrates this functionality.

==Plugin Response==

===Summary===

Plugin support is accomplished by triggering the <code>onAjax[Name]</code> plugin event.

===Details===

Plugin requests must include the <code>plugin</code> variable in the URL, paired with the name of the plugin event, e.g. <code>plugin=session</code> for <code>onAjaxSession</code>.

This value is also used for:

*The plugin class name following the <code>plgAjax[Name]</code> convention.
*The plugin function name following the <code>onAjax[Name]</code> convention.

The [https://github.com/Joomla-Ajax-Interface/Ajax-Latest-Articles Ajax Latest Articles plugin] is an example plugin that demonstrates this functionality.

==Response Format==

<code>format=[json|debug]</code> is an optional argument for the results format:

*<code>json</code> for JSON format
*<code>debug</code> for human-readable output of the results.

[[Category:AJAX]]
[[Category:JavaScript]]
[[Category:Development]]

Constants

2014-03-20T12:47:38Z

Jonasfh:

These constants are defined for use in Joomla and [[extensions|extensions]]:-

{| class="wikitable"
|-
|JPATH_ADMINISTRATOR
|The path to the administrator folder.
|-
|JPATH_BASE
|The path to the installed Joomla! site, or JPATH_ROOT/administrator if executed from the backend.
|-
|JPATH_CACHE
|The path to the cache folder.
|-
|JPATH_COMPONENT
|The path to the current component being executed.
|-
|JPATH_COMPONENT_ADMINISTRATOR
|The path to the administration folder of the current component being executed.
|-
|JPATH_COMPONENT_SITE
|The path to the site folder of the current component being executed.
|-
|JPATH_CONFIGURATION
|The path to folder containing the configuration.php file.
|-
|JPATH_INSTALLATION
|The path to the installation folder.
|-
|JPATH_LIBRARIES
|The path to the libraries folder.
|-
|JPATH_PLUGINS
|The path to the plugins folder.
|-
|JPATH_ROOT
|The path to the installed Joomla! site.
|-
|JPATH_SITE
|The path to the installed Joomla! site.
|-
|JPATH_THEMES
|The path to the templates folder.
|-
|JPATH_XMLRPC
|The path to the XML-RPC Web service folder.(1.5 only)
|}

These constants are defined in <code>_path_/includes/defines.php</code> except JPATH_BASE which is defined in <code>_path_/index.php</code>.

Note: These paths are the absolute paths of these locations within the file system, NOT the path you'd use in a URL.

For URL paths, try using [[JURI/base|JURI::base()]].

== Difference between JPATH_SITE, JPATH_ROOT, and JPATH_BASE ==
''JPATH_SITE'' is meant to represent the root path of the JSite application, just as ''JPATH_ADMINISTRATOR'' is mean to represent the root path of the JAdministrator application.

''JPATH_BASE'' is the root path for the current requested application.... so if you are in the administrator application:
:JPATH_BASE == JPATH_ADMINISTRATOR

If you are in the site application:
:JPATH_BASE == JPATH_SITE

If you are in the installation application:
:JPATH_BASE == JPATH_INSTALLATION.

JPATH_ROOT is the root path for the Joomla install and does not depend upon any application.

== Consideration ==

Whilst using JPATH_COMPONENT and JPATH_COMPONENT_ADMINISTRATOR is highly useful in some cases, it has one big disadvantage: it immediately breaks all attempts to reuse the model from another component. That's something to keep in mind.

<noinclude>[[Category:Development]]</noinclude>
[[Category:References]][[Category:Module Development]]
[[Category:Plugin Development]]
[[Category:Component Development]]

Retrieving request data using JInput

2013-10-02T13:24:19Z

Jonasfh:

Archived:Developing a MVC Component/Filter input from users

2012-12-21T13:06:13Z

Jonasfh:

Fields in the xmlfiles can have filter-options to reduce the risk of injecting erroneous or malicious data in the forms in your component. From what I have found, the following filters are available by default, defined on line 162 in [http://api.joomla.org/__filesource/fsource_Joomla-Platform_Filter_librariesjoomlafilterinput.php.html filterinput.php]

INT / INTEGER: Forces Integer value
UINT: Forces absolute Integer value
FLOAT / DOUBLE: Forces floating point value
BOOL / BOOLEAN: Forces the value to be true or false
WORD: Allows only a-z (not case sensitive) and underscores
ALNUM: Allow a-z and numbers
CMD: allows ALNUM plus the characters _ (underscore) . (dot) - (dash)
BASE64: Allows only a base64-encoded string (ALNUM and the characters + / = )
STRING: Removes HTML
HTML: Allows basic HTML
ARRAY: Forces value to be an array
PATH: Forces value to be a file path
USERNAME: Only characters allowed in a Joomla username
RAW: Allow any content

There are probably more available by default, please edit this doc...

Archived:Developing a MVC Component/Filter input from users

2012-12-21T13:05:43Z

Jonasfh:

{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Filter_input_from_users}}
Fields in the xmlfiles can have filter-options to reduce the risk of injecting erroneous or malicious data in the forms in your component. From what I have found, the following filters are available by default, defined on line 162 in [http://api.joomla.org/__filesource/fsource_Joomla-Platform_Filter_librariesjoomlafilterinput.php.html filterinput.php]

INT / INTEGER: Forces Integer value
UINT: Forces absolute Integer value
FLOAT / DOUBLE: Forces floating point value
BOOL / BOOLEAN: Forces the value to be true or false
WORD: Allows only a-z (not case sensitive) and underscores
ALNUM: Allow a-z and numbers
CMD: allows ALNUM plus the characters _ (underscore) . (dot) - (dash)
BASE64: Allows only a base64-encoded string (ALNUM and the characters + / = )
STRING: Removes HTML
HTML: Allows basic HTML
ARRAY: Forces value to be an array
PATH: Forces value to be a file path
USERNAME: Only characters allowed in a Joomla username
RAW: Allow any content

There are probably more available by default, please edit this doc...

Archived:Developing a MVC Component/Filter input from users

2012-12-21T13:03:11Z

Jonasfh:

Archived:Developing a MVC Component/Filter input from users

2012-12-21T13:02:41Z

Jonasfh:

Fields in the xmlfiles can have filter-options to reduce the risk of injecting erroneous or malicious data in the forms in your component. From what I have found, the following filters are available by default, defined on line 162 in [ http://api.joomla.org/__filesource/fsource_Joomla-Platform_Filter_librariesjoomlafilterinput.php.html filterinput.php]

INT / INTEGER: Forces Integer value
UINT: Forces absolute Integer value
FLOAT / DOUBLE: Forces floating point value
BOOL / BOOLEAN: Forces the value to be true or false
WORD: Allows only a-z (not case sensitive) and underscores
ALNUM: Allow a-z and numbers
CMD: allows ALNUM plus the characters _ (underscore) . (dot) - (dash)
BASE64: Allows only a base64-encoded string (ALNUM and the characters + / = )
STRING: Removes HTML
HTML: Allows basic HTML
ARRAY: Forces value to be an array
PATH: Forces value to be a file path
USERNAME: Only characters allowed in a Joomla username
RAW: Allow any content

There are probably more available by default, please edit this doc...

Archived:Developing a MVC Component/Filter input from users

2012-12-21T13:00:43Z

Jonasfh: Filter options for text in joomla, to be used for f.ex. input fields in the config xml files for components, modules, plugins etc

Fields in the xmlfiles can have filter-options to reduce the risk of injecting erroneous or malicious data in the forms in your component. From what I have found, the following filters are available by default, defined on line 162 in [http://api.joomla.org/__filesource/fsource_Joomla-Platform_Filter_librariesjoomlafilterinput.php.html]

INT / INTEGER: Forces Integer value
UINT: Forces absolute Integer value
FLOAT / DOUBLE: Forces floating point value
BOOL / BOOLEAN: Forces the value to be true or false
WORD: Allows only a-z (not case sensitive) and underscores
ALNUM: Allow a-z and numbers
CMD: allows ALNUM plus the characters _ (underscore) . (dot) - (dash)
BASE64: Allows only a base64-encoded string (ALNUM and the characters + / = )
STRING: Removes HTML
HTML: Allows basic HTML
ARRAY: Forces value to be an array
PATH: Forces value to be a file path
USERNAME: Only characters allowed in a Joomla username
RAW: Allow any content

There are probably more available by default, please edit this doc...

How to debug your code

2011-08-25T11:24:25Z

Jonasfh:

'''The Easy Way:'''
The simplest way to see what is going on inside your code is to temporarily add echo statements for variables to show their values on the screen. For example, say you want to know what the value of some variables are when $i is "5". You could use code like this:

<source lang="PHP">for ( $i = 0; $i < 10; $i++ ) {
if ( $i == 5 ) {
echo '$i=' . $i;
// other echo statements
}
}</source>

This works for simple situations. However, if you are planning on doing a lot of Joomla! development, it is worth the effort to install and learn an integrated development environment (IDE) that includes a real PHP debugger.

'''Using an IDE:'''
Many Joomla! developers use the Eclipse IDE. This is free and includes a debugger. Instructions for installing it are available at [[Setting_up_your_workstation_for_Joomla!_development]].

'''Using the PHP Expert editor:'''
Another option is the PHP Expert editor with an installed extension for debugging. Add the following lines to the php.ini file:

extension=php_dbg.dll
[Debugger]
debugger.enabled=on
debugger.profiler_enabled=off

It is best to set profiler_enable to "off". Then you need set options in the menu Run/Options menu to use HTTP-server and the directory to where your script is located.

If all options are correct you may run your script in debug mode by clicking on the Debug button (F8).

'''J!Dump:'''
An often handy extension that can be found in the JED is the J!Dump extension that will allow you to dump variable, stack traces, and system information into a popup window at run time. This extension works similarly to the php command `var_dump` but formats the output in a much more readable fashion.

'''JDEBUG'''
To check if the website is in debug-mode, you test the JDEBUG - variable:
<source lang="PHP">
if(JDEBUG){
//whatever debugging code you want to run
}
</source>

[[Category:Development]]

How to debug your code

2011-08-25T11:23:36Z

Jonasfh:

'''The Easy Way:'''
The simplest way to see what is going on inside your code is to temporarily add echo statements for variables to show their values on the screen. For example, say you want to know what the value of some variables are when $i is "5". You could use code like this:

<source lang="PHP">for ( $i = 0; $i < 10; $i++ ) {
if ( $i == 5 ) {
echo '$i=' . $i;
// other echo statements
}
}</source>

This works for simple situations. However, if you are planning on doing a lot of Joomla! development, it is worth the effort to install and learn an integrated development environment (IDE) that includes a real PHP debugger.

'''Using an IDE:'''
Many Joomla! developers use the Eclipse IDE. This is free and includes a debugger. Instructions for installing it are available at [[Setting_up_your_workstation_for_Joomla!_development]].

'''Using the PHP Expert editor:'''
Another option is the PHP Expert editor with an installed extension for debugging. Add the following lines to the php.ini file:

extension=php_dbg.dll
[Debugger]
debugger.enabled=on
debugger.profiler_enabled=off

It is best to set profiler_enable to "off". Then you need set options in the menu Run/Options menu to use HTTP-server and the directory to where your script is located.

If all options are correct you may run your script in debug mode by clicking on the Debug button (F8).

'''J!Dump:'''
An often handy extension that can be found in the JED is the J!Dump extension that will allow you to dump variable, stack traces, and system information into a popup window at run time. This extension works similarly to the php command `var_dump` but formats the output in a much more readable fashion.

'''JDEBUG'''
To check if the website is beeing debugged, you test the JDEBUG - variable:
<source lang="PHP">
if(JDEBUG){
//whatever debugging code you want to run
}
</source>

[[Category:Development]]

How to debug your code

2011-08-25T11:22:59Z

Jonasfh:

'''The Easy Way:'''
The simplest way to see what is going on inside your code is to temporarily add echo statements for variables to show their values on the screen. For example, say you want to know what the value of some variables are when $i is "5". You could use code like this:

<source lang="PHP">for ( $i = 0; $i < 10; $i++ ) {
if ( $i == 5 ) {
echo '$i=' . $i;
// other echo statements
}
}</source>

This works for simple situations. However, if you are planning on doing a lot of Joomla! development, it is worth the effort to install and learn an integrated development environment (IDE) that includes a real PHP debugger.

'''Using an IDE:'''
Many Joomla! developers use the Eclipse IDE. This is free and includes a debugger. Instructions for installing it are available at [[Setting_up_your_workstation_for_Joomla!_development]].

'''Using the PHP Expert editor:'''
Another option is the PHP Expert editor with an installed extension for debugging. Add the following lines to the php.ini file:

extension=php_dbg.dll
[Debugger]
debugger.enabled=on
debugger.profiler_enabled=off

It is best to set profiler_enable to "off". Then you need set options in the menu Run/Options menu to use HTTP-server and the directory to where your script is located.

If all options are correct you may run your script in debug mode by clicking on the Debug button (F8).

'''J!Dump:'''
An often handy extension that can be found in the JED is the J!Dump extension that will allow you to dump variable, stack traces, and system information into a popup window at run time. This extension works similarly to the php command `var_dump` but formats the output in a much more readable fashion.

'''JDEBUG'''
To check if the website is beeing debugged, you test the JDEBUG - variable:
if(JDEBUG){
//whatever debugging code you want to run
}

[[Category:Development]]

J1.5:Plugin/Events/System

2010-08-09T15:09:35Z

Jonasfh: /* Overview */

[[Category:Development]]
[[Category:Plugins]]
===Overview===
In a standard installation of Joomla! 1.5 we have several predefined events which, when triggered, call functions in the associated plugins. For more information on plugins, check [[Tutorial:Plugins|Tutorial:Plugins]], [[Tutorial:Creating_a_Plugin_for_Joomla_1.5|Tutorial:Creating a Plugin for Joomla 1.5]], [[How_to_create_a_content_plugin|How to create a content plugin]] etc.

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Called in files'''

*index.php
*administrator/index.php

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

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

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

'''Return Value'''

Array of stdClass objects with members as described above.

'''Used in files'''

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

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

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

'''Parameters'''

None.

'''Return Value'''

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

'''Used in files'''

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

===onGetWebServices===

'''Description'''

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

'''Parameters'''

None.

'''Return Value'''

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

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

'''Used in files'''

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

===Example===

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

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

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

jimport( 'joomla.plugin.plugin' );

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

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

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

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

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

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

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

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

J1.5:Plugin/Events/System

2010-08-09T15:08:51Z

Jonasfh: /* Overview */

[[Category:Development]]
[[Category:Plugins]]
===Overview===
In a standard installation of Joomla! 1.5 we have several predefined events which, when triggered, call functions in the associated plugins. For more information on plugins, check [Tutorial:Plugins[Tutorial:Plugins]], [Tutorial:Creating_a_Plugin_for_Joomla_1.5[Tutorial:Creating a Plugin for Joomla 1.5]], [[How_to_create_a_content_plugin|How to create a content plugin]] etc.

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Called in files'''

*index.php
*administrator/index.php

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

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

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

'''Return Value'''

Array of stdClass objects with members as described above.

'''Used in files'''

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

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

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

'''Parameters'''

None.

'''Return Value'''

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

'''Used in files'''

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

===onGetWebServices===

'''Description'''

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

'''Parameters'''

None.

'''Return Value'''

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

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

'''Used in files'''

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

===Example===

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

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

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

jimport( 'joomla.plugin.plugin' );

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

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

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

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

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

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

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

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

J1.5:Plugin/Events/System

2010-08-09T15:05:01Z

Jonasfh: /* Overview */

[[Category:Development]]
[[Category:Plugins]]
===Overview===
In a standard installation of Joomla! 1.5 we have several predefined events which, when triggered, call functions in the associated plugins. For more information on plugins, check [[How_to_create_a_content_plugin|How to create a content plugin]].

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Called in files'''

*index.php
*administrator/index.php

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

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

None.

'''Return Value'''

None.

'''Used in files'''

* index.php
* administrator/index.php

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

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

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

'''Parameters'''

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

'''Return Value'''

Array of stdClass objects with members as described above.

'''Used in files'''

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

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

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

'''Parameters'''

None.

'''Return Value'''

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

'''Used in files'''

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

===onGetWebServices===

'''Description'''

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

'''Parameters'''

None.

'''Return Value'''

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

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

'''Used in files'''

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

===Example===

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

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

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

jimport( 'joomla.plugin.plugin' );

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

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

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

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

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

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

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

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

Display error messages and notices

2009-10-24T19:57:46Z

Jonasfh:

Errors, warnings and notices can be displayed from any component, module, plugin or template using the method outlined below (took me some time to figure this out, might help someone else):
<source lang="php">
//Get a handle to the Joomla!-application object
$app =& JFactory::getApplication();
//add a message to the message queue
$app->enqueueMessage(JText::_('Random error occured'), 'error');
</source>

The second argument to the enqueueMessage()-function is the type of message. Default is 'message', but 'error' gives a different style message. Try other types as well, to see how that works. The api for the JApplication-object can be found at:
[http://api.joomla.org/Joomla-Framework/Application/JApplication.html JApplication API]
The error message will now be displayed if the message-tag is present in your template. The message-field is added with the following statement in your template:
<source lang="php">
<jdoc:include type="message" />
</source>

Display error messages and notices

2009-10-24T19:51:29Z

Jonasfh:

Errors, warnings and notices can be displayed from any component, module, plugin or template using the method outlined below (took me some time to figure this out, might help someone else):
<source lang="php">
//Get a handle to the Joomla!-application object
$app =& JFactory::getApplication();
//add a message to the message queue
$app->enqueueMessage(JText::_('Random error occured'), 'error');
</source>

The second argument to the enqueueMessage()-function is the type of message. Default is 'message', but both error, and I believe also 'warning' will work. The api for the JApplication-object can be found at:
[http://api.joomla.org/Joomla-Framework/Application/JApplication.html JApplication API]
The error message will now be displayed if the message-tag is present in your template. The message-field is added with the following statement in your template:
<source lang="php">
<jdoc:include type="message" />
</source>

Display error messages and notices

2009-10-24T19:49:59Z

Jonasfh:

Errors, warnings and notices can be displayed from any component, module, plugin or template using the method outlined below (took me some time to figure this out, might help someone else):

//Get a handle to the Joomla!-application object
$app =& JFactory::getApplication();
//add a message to the message queue
$app->enqueueMessage(JText::_('Random error occured'), 'error');

The second argument to the enqueueMessage()-function is the type of message. Default is 'message', but both error, and I believe also 'warning' will work. The api for the JApplication-object can be found at:
[[http://api.joomla.org/Joomla-Framework/Application/JApplication.html JApplication API]]
The error message will now be displayed if the message-tag is present in your template. The message-field is added with the following statement in your template:

<jdoc:include type="message" />

Display error messages and notices

2009-10-24T19:49:30Z

Jonasfh: New page: Errors, warnings and notices can be displayed from any component, module, plugin or template using the method outlined below (took me some time to figure this out, might help someone else)...

Errors, warnings and notices can be displayed from any component, module, plugin or template using the method outlined below (took me some time to figure this out, might help someone else):

//Get a handle to the Joomla!-application object
$app =& JFactory::getApplication();
//add a message to the message queue
$app->enqueueMessage(JText::_('Random error occured'), 'error');

The second argument to the enqueueMessage()-function is the type of message. Default is 'message', but both error, and I believe also 'warning' will work. The api for the JApplication-object can be found at:
[[http://api.joomla.org/Joomla-Framework/Application/JApplication.html]]
The error message will now be displayed if the message-tag is present in your template. The message-field is added with the following statement in your template:

<jdoc:include type="message" />

Portal:Developers

2009-10-24T19:36:57Z

Jonasfh:

{{Developer profile}}

A complete contents list of all pages of interest to developers can be found in the [[:Category:Development|development category]].

== Reference Material ==

* [[Framework|Joomla Framework]].
* [http://api.joomla.org API documentation] automatically generated using phpDocumentor.

== Articles and Tutorials ==

=== General ===
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development.
* [[Setting up your workstation for extension development]] A guide to Joomla Extension development
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development
* [[Do not use die to debug]]
* [[How to debug your code]]
* [[Tutorial:Adapting Joomla 1.0 extensions to Joomla 1.5]]
* [[Version 1.6 Developer Notes]]
* [[Tutorial:Joomla Beginning Developer Course]]

=== Components ===
* Developing a Model-View-Controller (MVC) Component
** [[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]]
* [[File Structure and Naming Conventions]]
* [[Component parameters]]
* [[Components:xml installfile]]. An example component XML installation file.
* [[How to use the JPane classes in a component]]
* [[How to use the editor in a component]]
* [[Supporting plugins in your component]]
* [[Tutorial:Adding Javascript moo.fx to your component WIP]]
* [[Creating a toolbar for your component]]
* [[Adding view layout configuration parameters]]
* [[How to implement XML-RPC in a component]]
* [[Using JPagination in your component]]
* [[Adding sortable columns to a table in a component]]
* [[Using multiple models in an MVC component]]
* [[Ajax using MooTools]]

=== Modules ===
* [[Tutorial:Creating a Hello World Module for Joomla_1.5]]
* [[How to create a module]]

=== Plugins ===
* [[Plugin Developer Overview]]
* [[Tutorial:Plugins]]
* [http://developer.joomla.org/tutorials/184-how-to-create-a-joomla-plugin.html How to create a Joomla! Plugin]
* [[How to create a content plugin]]
* [[How to create a search plugin]]
* [[Supporting plugins in your component]]
* [[Tutorial:Creating an Authentication Plugin for Joomla 1.5]]
* [[Tutorial:Using plugins in your own extension]]

=== Templates ===
* [[Understanding Output Overrides]]
* [http://developer.joomla.org/tutorials/165-understanding-output-overrides-in-joomla.html Understanding Output Overrides in Joomla! 1.5]
* [[Creating custom template parameter types]]
* [[How are templates executed?]]
* [[How to determine if the user is viewing the front page]]
* [[Tutorial:Template parameters]]

===Parameters===
* [[Standard parameter types]]
* [[Custom parameter types]]
* [[Component parameters]]
* [[Creating custom template parameter types]]
See also: [[:Category:Parameters]]

=== Security ===
* [[How to add CSRF anti-spoofing to forms]]
* [http://developer.joomla.org/tutorials/181-preventing-sql-injections.html Preventing SQL Injections]
* [[Tutorial:How_to_make_your_Joomla_addon_more_secure_WIP]]

=== Database ===
* [[How to use the database classes in your script]]
* [[How to use the JTable class]]
* [[How to connect to an external database]]

=== Localisation ===
* [http://community.joomla.org/magazine/article/508-developer-localization-advancements-in-joomla-15.html Localization Advancements in Joomla! 1.5]
* [[Adding multi-language support]]
* [[Adding Joomfish functionality to custom components]]

=== Miscellaneous ===
* [[How to use the filesystem package]]
* [[How to use the editor in a component]]
* [[Adding AJAX to your component]].
* [[How to send email from components]]
* [[How to use the JToolBar class in the frontend]]
* [[Routing]]
* [[Joomla Routes and SEF]]
* [[API Execution Order]]
* [[Accessing the current user object]]
* [[Adding JavaScript and CSS to the page]]
* [[Constants]] used in the Joomla [[Framework]].
* [[Form validation]]
* [[How to create a custom button]]
* [[How to create a stand-alone application using the Joomla! Framework]]
* [[How to use user state variables]]
* [[Adding template overridable images in your extension]]
* [[Retrieving data from GET and POST requests]]
* [[Using caching to speed up your code]]
* [[Using a custom image in the menu bar title]]
* [[Using the installer API to support package installation]]
* [[Tutorial:How to add tooltips to your Joomla! website]]
* [[Xml-rpc|XML-RPC]]
* [[How to add breadcrumbs]]
* [[Creating a file uploader in your component]].
* [[Display error messages and notices]].

== Contributing to Joomla Development ==
The development of Joomla itself is carried out by the [[Development Working Group]] and third party developers.

* [[Participating in the community]]: a brief description of how people can get involved.
* [[Developer Email lists]]: a list of email lists for developers, including third party developers.
* [[Coding style and standards]] (To be reviewed).
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development.
* [http://docs.joomla.org/Setting_up_your_workstation_for_Joomla!_development_--_Part_2#Check_Out_Joomla.21_Source_Code How to check out SVN Code]
* [[Patch submission guidelines]].
* [[Filing bugs and issues]].
* [[How to release a distribution tarball]].

== Contributing to Joomla Developer Documentation ==
The development of Joomla developer documentation is carried out primarily by the [[Documentation Working Group]]. There are currently two sub-projects of interest to developers:
* [[Joomla! 1.5 Template Tutorials Project]]
* [[API Reference Project]]

When creating a new page, ensure you place the following marker at the bottom of the page so it is included in the category list:

<pre><nowiki>[[Category:Development]]
</nowiki></pre>

If you locate other articles you think are relevant to developers, please add this marker to those pages.

=== Suggested topics ===
This is a short list of articles that might be written to support developers. Please feel free to add further topic ideas.

* [[Adding configuration objects to modules and plugins]].
* [[Storing data in the session between page loads]].
* [[Suppressing output of extra HTML]].
* [[How to use the filter package]].
*: Describe how and when to use the Filter package and explain what needs to be filtered for various situations (for queries, for URLs, etc)
* [[How to use the registry package]]
* [[How to use JSimpleXML]].
*: How to load and store XML files and how to work with them
* [[How to create component feeds]] (RSS/ATOM)
* [[How to create PDF views]]
* [[How to generate paths for client side and server side]]
* [[How to access information from the request]]
*: This focuses on using the JBrowser class to retrieve information about the features available in the user's browser.
* [[How to create an editor plugin]]
* [[What can be done with a user plugin]]
* [[How to work with parameters]]
* [[How to cloak email addresses]]
* [[Using the caching system in your component]].

==Joomla Security Guide==
Developers should also be aware of security issues.
{{Security Guide}}
[[Category:Development]]

J1.5 talk:Finding and installing extensions

2008-12-18T14:40:11Z

Jonasfh:

I see that in Joomla 1.5 the function where you could see if the nessesary directories where writable, is removed. I always get into trouble when trying to install components/modules/plugins because of permission problems. In addition the errors from Joomla seem pretty random depending on where there is a permission problem. The current information in this guide is quite poor (see [[Installing_an_extension#Installation]] ) Could someone here please say which directories commonly need to be writable for a successful installation? this would certainly be very helpful...

Jonas:))

J1.5 talk:Finding and installing extensions

2008-12-18T14:37:01Z

Jonasfh: Regarding permissions problems when installing modules etc...

I see that in Joomla 1.5 the function where you could see if the nessesary directories where writable, is removed. I always get into trouble when trying to install components/modules/plugins because of permission problems. In addition the errors from Joomla seem pretty random depending on where there is a permission problem. Could someone here please say which directories commonly need to be writable for a successful installation? this would certainly be very helpful...

Jonas:))