J1.5

Difference between revisions of "Plugin/Events/System"

From Joomla! Documentation

< J1.5:Plugin/Events
 
(21 intermediate revisions by 13 users not shown)
Line 1: Line 1:
[[Category:Development]]
+
{{RightTOC}}
[[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, look [[plugins:create_plugin|here]].
 
  
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.
+
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 [[Plugin]], [[Creating a Plugin for Joomla 1.5]], [[How to create a content plugin]] etc.
  
=== onAfterInitialise ===
+
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 [[Plugin]] for a complete list over available core events.
'''Description'''
 
  
This event is triggered after the framework has loaded and the applicaiton initialise method has been called.
+
== onAfterInitialise ==
 +
=== Description ===
  
'''Parameters'''
+
This event is triggered after the framework has loaded and the application initialise method has been called.
 +
 
 +
=== Parameters ===
  
 
None.
 
None.
  
'''Return Value'''
+
=== Return Value ===
  
 
None.
 
None.
  
'''Called in files'''
+
=== Called in files ===
  
*index.php
+
*<tt>index.php</tt>
*administrator/index.php
+
*<tt>administrator/index.php</tt>
  
===onAfterRoute===
+
== onAfterRoute ==
'''Description'''
+
=== Description ===
  
This event is triggered after the framework has loaded and initialised and the router has route the client request.
+
This event is triggered after the framework has loaded and initialised and the router has routed 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.
+
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 that will 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.
+
When this event triggers, the router has parsed the route and pushed the request parameters into JRequest to be retrieved by the application.
  
'''Parameters'''
+
=== Parameters ===
  
 
None.
 
None.
  
'''Return Value'''
+
=== Return Value ===
  
 
None.
 
None.
  
'''Used in files'''
+
=== Used in files ===
  
* index.php
+
* <tt>index.php</tt>
* administrator/index.php
+
* <tt>administrator/index.php</tt>
  
===onAfterDispatch===
+
==onAfterDispatch==
'''Description'''
+
=== Description ===
 
This event is triggered after the framework has dispatched the application.
 
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.
+
Dispatching is the process of pulling the option from the request object and mapping them to a component. If the component does 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.
 
When this event is triggered the output of the component is available in the document buffer.
  
'''Parameters'''
+
=== Parameters ===
 +
 
 +
None.
 +
 
 +
=== Return Value ===
 +
 
 +
None.
 +
 
 +
=== Used in files ===
 +
 
 +
* <tt>index.php</tt>
 +
* <tt>administrator/index.php</tt>
 +
 
 +
==onBeforeRender==
 +
=== Description ===
 +
'''This event is not in available in Joomla 1.5. It's available in Joomla 1.6 and above.'''
 +
 
 +
This event is triggered immediately before 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 JResponse buffer.
 +
 
 +
=== Parameters ===
  
 
None.
 
None.
  
'''Return Value'''
+
=== Return Value ===
  
 
None.
 
None.
  
'''Used in files'''
+
=== Used in files ===
  
* index.php
+
* <tt>includes/application.php</tt>
* administrator/index.php
+
* <tt>administrator/includes/application.php</tt>
  
===onAfterRender===
+
==onAfterRender==
'''Description'''
+
=== Description ===
 
This event is triggered after the framework has rendered the application.
 
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.
+
Rendering is the process of pushing the document buffers into the template placeholders, retrieving data from the document and pushing it into the JResponse buffer.
  
 
When this event is triggered the output of the application is available in the response buffer.
 
When this event is triggered the output of the application is available in the response buffer.
  
'''Parameters'''
+
=== Parameters ===
  
 
None.
 
None.
  
'''Return Value'''
+
=== Return Value ===
  
 
None.
 
None.
  
'''Used in files'''
+
=== Used in files ===
 +
 
 +
* <tt>includes/application.php</tt>
 +
* <tt>administrator/includes/application.php</tt>
 +
 
 +
==onBeforeCompileHead==
 +
=== Description ===
 +
This event is triggered before the framework creates the Head section of the Document.
 +
 
 +
=== Parameters ===
  
* index.php
+
None.
* administrator/index.php
 
  
===onSearch===
+
===Return Value===
'''Description'''
+
 
 +
None.
 +
 
 +
===Used in files===
 +
 
 +
* <tt>libraries/joomla/document/html/renderer/head.php</tt>
 +
 
 +
==onSearch==
 +
===Description===
  
 
This event is triggered by a variety of search related operations. It is a request for a
 
This event is triggered by a variety of search related operations. It is a request for a
Line 101: Line 137:
 
* browsernav
 
* browsernav
  
'''Parameters'''
+
===Parameters===
  
 
* The target search string.
 
* The target search string.
Line 108: Line 144:
 
* An array if restricted to areas, null if search all.
 
* An array if restricted to areas, null if search all.
  
'''Return Value'''
+
===Return Value===
  
 
Array of stdClass objects with members as described above.
 
Array of stdClass objects with members as described above.
  
'''Used in files'''
+
===Used in files===
  
* administrator/components/com_statistics/admin.statistics.php
+
* <tt>administrator/components/com_statistics/admin.statistics.php</tt>
* components/com_search/search.php
+
* <tt>components/com_search/search.php</tt>
* plugins/search/categories.php
+
* <tt>plugins/search/categories.php</tt>
* plugins/search/contacts.php
+
* <tt>plugins/search/contacts.php</tt>
* plugins/search/content.php
+
* <tt>plugins/search/content.php</tt>
* plugins/search/newsfeeds.php
+
* <tt>plugins/search/newsfeeds.php</tt>
* plugins/search/sections.php
+
* <tt>plugins/search/sections.php</tt>
* plugins/search/weblinks.php
+
* <tt>plugins/search/weblinks.php</tt>
* plugins/xmlrpc/joomla.php
+
* <tt>plugins/xmlrpc/joomla.php</tt>
  
===onSearchAreas===
+
==onSearchAreas==
'''Description'''
+
===Description===
  
 
This appears to be a request for plugins to identify which "areas" they provide
 
This appears to be a request for plugins to identify which "areas" they provide
 
search facilities for.
 
search facilities for.
  
'''Parameters'''
+
===Parameters===
  
 
None.
 
None.
  
'''Return Value'''
+
===Return Value===
  
 
An associative array of area names, indexed by the area identifier. For example, array( 'categories' => 'Categories' ).
 
An associative array of area names, indexed by the area identifier. For example, array( 'categories' => 'Categories' ).
  
'''Used in files'''
+
===Used in files===
  
* components/com_search/search.php
+
* <tt>components/com_search/search.php</tt>
* plugins/search/categories.php
+
* <tt>plugins/search/categories.php</tt>
* plugins/search/contacts.php
+
* <tt>plugins/search/contacts.php</tt>
* plugins/search/content.php
+
* <tt>plugins/search/content.php</tt>
* plugins/search/newsfeeds.php
+
* <tt>plugins/search/newsfeeds.php</tt>
* plugins/search/sections.php
+
* <tt>plugins/search/sections.php</tt>
* plugins/search/weblinks.php
+
* <tt>plugins/search/weblinks.php</tt>
  
===onGetWebServices===
+
==onGetWebServices==
  
'''Description'''
+
===Description===
  
 
This is an introspection request for plugins that provide web services.
 
This is an introspection request for plugins that provide web services.
  
'''Parameters'''
+
===Parameters===
  
 
None.
 
None.
  
'''Return Value'''
+
===Return Value===
  
 
An array of associative arrays. The outer array is indexed by the service method name and
 
An array of associative arrays. The outer array is indexed by the service method name and
Line 167: Line 203:
 
* ['signature'] An array identifying the types of the method's parameters. See the global variables $xmlrpc* for more information.
 
* ['signature'] An array identifying the types of the method's parameters. See the global variables $xmlrpc* for more information.
  
'''Used in files'''
+
===Used in files===
  
* plugins/xmlrpc/blogger.php
+
* <tt>plugins/xmlrpc/blogger.php</tt>
* plugins/xmlrpc/joomla.php
+
* <tt>plugins/xmlrpc/joomla.php</tt>
* xmlrpc/index.php
+
* <tt>xmlrpc/index.php</tt>
  
===Example===
+
==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.
 
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>.
+
The following class would be located in the file <tt>/plugins/system/example/example.php</tt>.
  
<pre><?php
+
<source lang="php"><?php
 
// no direct access
 
// no direct access
 
defined( '_JEXEC' ) or die( 'Restricted access' );
 
defined( '_JEXEC' ) or die( 'Restricted access' );
Line 190: Line 226:
 
class plgSystemExample extends JPlugin
 
class plgSystemExample extends JPlugin
 
{
 
{
/**
+
/**
* Constructor
+
* Constructor.
*
+
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
+
* @access protected
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
+
* @param object $subject The object to observe
* This causes problems with cross-referencing necessary for the observer design pattern.
+
* @param array  $config  An array that holds the plugin configuration
*
+
* @since 1.0
* @access protected
+
*/
* @param object $subject The object to observe
+
public function __construct( &$subject, $config )
* @param array  $config  An array that holds the plugin configuration
+
{
* @since 1.0
+
parent::__construct( $subject, $config );
*/
 
function plgSystemCache( &$subject, $config )
 
{
 
parent::__construct( $subject, $config );
 
  
// Do some extra initialisation in this constructor if required
+
// Do some extra initialisation in this constructor if required
}
+
}
  
/**
+
/**
* Do something onAfterInitialise  
+
* Do something onAfterInitialise
*/
+
*/
function onAfterInitialise()
+
function onAfterInitialise()
{
+
{
}
+
}
  
/**
+
/**
* Do something onAfterRoute  
+
* Do something onAfterRoute
*/
+
*/
function onAfterRoute()
+
function onAfterRoute()
{
+
{
}
+
}
  
/**
+
/**
* Do something onAfterDispatch  
+
* Do something onAfterDispatch
*/
+
*/
function onAfterDispatch()
+
function onAfterDispatch()
{
+
{
}
+
}
  
/**
+
/**
* Do something onAfterRender  
+
* Do something onAfterRender
*/
+
*/
function onAfterRender()
+
function onAfterRender()
{
+
{
}
+
}
}</pre>
+
}</source>
  
The following XML document would be located in the file <code>/plugins/system/example.xml</code>.
+
The following XML document would be located in the file <tt>/plugins/system/example/example.xml</tt>.
  
<pre><?xml version="1.0" encoding="utf-8"?>
+
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
 
<install version="1.5" type="plugin" group="system">
 
<install version="1.5" type="plugin" group="system">
<name>System - Example</name>
+
<name>System - Example</name>
<author>Author</author>
+
<author>Author</author>
<creationDate>Month 2008</creationDate>
+
<creationDate>Month 2008</creationDate>
<copyright>Copyright (C) 2008 Holder. All rights reserved.</copyright>
+
<copyright>Copyright (C) 2008 Holder. All rights reserved.</copyright>
<license>GNU General Public License</license>
+
<license>GNU General Public License</license>
<authorEmail>email</authorEmail>
+
<authorEmail>email</authorEmail>
<authorUrl>url</authorUrl>
+
<authorUrl>url</authorUrl>
<version>1.0.1</version>
+
<version>1.0.1</version>
<description>An example system plugin</description>
+
<description>An example system plugin</description>
<files>
+
<files>
<filename plugin="example">example.php</filename>
+
<filename plugin="example">example.php</filename>
</files>
+
</files>
<params>
+
<params>
  <param name="example"
+
  <param name="example"
  type="text"
+
  type="text"
  default=""
+
  default=""
  label="Example"
+
  label="Example"
  description="An example text parameter" />
+
  description="An example text parameter" />
</params>
+
</params>
</install></pre>
+
</install></source>
 +
<noinclude>[[Category:Plugin Development]][[Category:Specifications]]</noinclude>

Latest revision as of 04:04, 11 November 2013

The "J1.5" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

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 Plugin, Creating a Plugin for Joomla 1.5, 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 Plugin for a complete list over available core events.

onAfterInitialise[edit]

Description[edit]

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

Parameters[edit]

None.

Return Value[edit]

None.

Called in files[edit]

  • index.php
  • administrator/index.php

onAfterRoute[edit]

Description[edit]

This event is triggered after the framework has loaded and initialised and the router has routed 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 that will 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 to be retrieved by the application.

Parameters[edit]

None.

Return Value[edit]

None.

Used in files[edit]

  • index.php
  • administrator/index.php

onAfterDispatch[edit]

Description[edit]

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 does 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[edit]

None.

Return Value[edit]

None.

Used in files[edit]

  • index.php
  • administrator/index.php

onBeforeRender[edit]

Description[edit]

This event is not in available in Joomla 1.5. It's available in Joomla 1.6 and above.

This event is triggered immediately before 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 JResponse buffer.

Parameters[edit]

None.

Return Value[edit]

None.

Used in files[edit]

  • includes/application.php
  • administrator/includes/application.php

onAfterRender[edit]

Description[edit]

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 JResponse buffer.

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

Parameters[edit]

None.

Return Value[edit]

None.

Used in files[edit]

  • includes/application.php
  • administrator/includes/application.php

onBeforeCompileHead[edit]

Description[edit]

This event is triggered before the framework creates the Head section of the Document.

Parameters[edit]

None.

Return Value[edit]

None.

Used in files[edit]

  • libraries/joomla/document/html/renderer/head.php

onSearch[edit]

Description[edit]

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[edit]

  • 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[edit]

Array of stdClass objects with members as described above.

Used in files[edit]

  • 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[edit]

Description[edit]

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

Parameters[edit]

None.

Return Value[edit]

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

Used in files[edit]

  • 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[edit]

Description[edit]

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

Parameters[edit]

None.

Return Value[edit]

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[edit]

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

Example[edit]

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 /plugins/system/example/example.php.

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

jimport( 'joomla.plugin.plugin' );

/**
 * Example system plugin
 */
class plgSystemExample extends JPlugin
{
/**
* Constructor.
*
* @access protected
* @param object $subject The object to observe
* @param array   $config  An array that holds the plugin configuration
* @since 1.0
*/
public function __construct( &$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()
{
}
}

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

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