J1.5:Plugin/Events/System

2011-09-15T23:10:44Z

Mtlj: Minor typos

{{RightTOC}}

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

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

=== Parameters ===

None.

=== Return Value ===

None.

=== Called in files ===

*<tt>index.php</tt>
*<tt>administrator/index.php</tt>

== onAfterRoute ==
=== Description ===

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

None.

=== Return Value ===

None.

=== Used in files ===

* <tt>index.php</tt>
* <tt>administrator/index.php</tt>

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

* <tt>index.php</tt>
* <tt>administrator/index.php</tt>

==onBeforeRender==
=== Description ===
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 into the JResponse buffer.

=== Parameters ===

None.

=== Return Value ===

None.

=== Used in files ===

* <tt>include/application.php</tt>
* <tt>administrator/include/application.php</tt>

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

* <tt>include/application.php</tt>
* <tt>administrator/include/application.php</tt>

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

=== Parameters ===

None.

===Return Value===

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

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

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

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

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

* <tt>plugins/xmlrpc/blogger.php</tt>
* <tt>plugins/xmlrpc/joomla.php</tt>
* <tt>xmlrpc/index.php</tt>

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

<source lang="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()
{
}
}</source>

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

<source lang="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></source>
<noinclude>[[Category:Plugin Development]][[Category:Specifications]]</noinclude>

Adding JavaScript

2011-09-02T15:54:42Z

Mtlj: typo correction

{{cookiejar}}
===Adding Javascript===
----
This chunk should describe in detail how to add Javascript to the head of
a template using the Joomla! 1.5 API calls. It should be aimed at
people who have only minimal knowledge of PHP, HTML and Javascript.
[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Add the following code to have the Javascript library /media/system/js/sample.js included in your template.

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScript( '/media/system/js/sample.js' );
?>
</source>

==Explanation==
Ultimately you are trying to have the resulting HTML page have a Javascript included in the head element (i.e. <head> ... </head>):

For example:
<source lang="php">
<script type="text/javascript" src="/media/system/js/sample.js"></script>
</source>
Ensure that the Javascript you want to include is in the directory, from the above example:
<nowiki>/media/system/js/sample.js</nowiki>

Load your page into a browser and verify that the <script> tag is in the <head> area and able to load the Javascript. Again, using the example:
<nowiki>http://www.example.com/media/system/js/sample.js</nowiki>

When successful the script is integrated into your page. Now you can use Javascript in your HTML.

Do not directly add the <script> to your template's index.php. The code will insert the <script> line where your index.php has the following line:
<source lang="php">
<jdoc:include type="head" />
</source>
Add this PHP code to your page, in the head, or next to the Javascript code you will use, depending on your preference.

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScript( '/media/system/js/sample.js' );
?>
</source>
Reload and view the page. Ensure that the sample.js is included in the <head> section.

== Adding Javascript Files Using JHTML ==
You may also use the [http://api.joomla.org/Joomla-Framework/HTML/JHTML.html JHTML] [http://api.joomla.org/Joomla-Framework/HTML/JHTML.html#script script] method to add a Javascript file to the head of your document.

<source lang="php">
<?php
$filename = 'filename.js';
// Add the path parameter if the path is different than 'media/system/js/'
$path = 'path/to/file/';
JHTML::script($filename, $path);
?>
</source>
There is a third Boolean argument that can be passed to the script method. Set this to true if you also want MooTools loaded.
<source lang="php">
<?php
$filename = 'filename.js';
// Add the path parameter if the path is different than 'media/system/js/'
$path = 'path/to/file/';
// MooTools will load if it is not already loaded
JHTML::script($filename, $path, true);
?>
</source>
'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

== References ==
<references/>

Joomla! Documentation - User contributions [en]

J1.5:Plugin/Events/System

Adding JavaScript