Mastering Joomla! 1.5 Extension and Framework Development

Mastering Joomla! 1.5 Extension and Framework Development

By : James Kennard

Buy this Book

Mastering Joomla! 1.5 Extension and Framework Development

By: James Kennard

Buy this Book

Overview of this book

Joomla! is the world's hottest open-source content management system, and the winner of the 2006 Open Source CMS Prize. Out of the box, Joomla! does a great job of managing the content needed to make your website sing. But for many people, the true power of Joomla! lies in its application framework that makes it possible for thousands of developers around the world to create powerful add-ons and extensions. Many companies or organizations have requirements that go beyond what is available in the basic Joomla! package or in a freely available extension. Thankfully, Joomla! offers a powerful application framework that makes it easy for developers to create sophisticated add-ons that extend the power of Joomla! into virtually unlimited directions. If you use PHP programming to extend or customize Joomla!, this book is essential reading. If you feel that you've mastered the basics of creating Joomla! extensions, then this book will take you to the next level. Packed with expert advice on all aspects of development with Joomla!, you will learn about best-practice design and coding for Joomla! components, modules, plugins and other extensions. You will also learn about customizing the page output, using JavaScript effects, making use of Web Services from within Joomla! and ensuring that your code is secure and error-free. A unique and comprehensive reference to the main areas of interest within the Joomla! framework is also included in the book. <a href="http://www.packtpub.com/article/joomla-one-point-five-extension-framework-table-of-contents"> </a>

Mastering Joomla! 1.5 Extension and Framework Development

Credits

About the Author

About the Reviewers

Preface

Free Chapter

Introduction to Joomla!

Overview

History

Requirements

Extension Types and Their Uses

Extension Manager

JED and JoomlaCode.org

Development Tools

Summary

Getting Started

The Application and Document

Request to Response

Directory Structure

Libraries

A Quick Lesson in Classes

Working with the Request

The Factory

The Session

Predefined Constants

Summary

The Database

The Core Database

Extending the Database

Querying the Database

JTable

Summary

Component Design

Setting up a Sandbox

The Structure

The MVC

Rendering Other Document Types

Dealing with Component Configuration

Elements and Parameters

Help Files

Routing

Packaging

Summary

Module Design

Setting Up a Sandbox

First Steps

Module Settings (Parameters)

Helpers

Layouts (Templates)

Translating

Packaging

Summary

Plugin Design

Setting Up a Sandbox

Events

Listeners

Plugin Groups

Using Plugins as Libraries (in Lieu of Library Extensions)

Translating Plugins

Dealing with Plugin Settings (Parameters)

Packaging

Summary

Extension Design

Supporting Classes

Helpers

Using and Building getInstance() Methods

Assets

Summary

Rendering Output

The joomla.html Library

Component Backend

Itemized Data

Summary

Customizing the Page

Application Message Queue

Redirects

Using Menu Item Parameters

Modifying the Document

Translating

Using JavaScript Effects

Summary

APIs and Web Services

XML

AJAX

LDAP

File Transfer Protocol

Web Services

Building a Web Service (XML-RPC Plugin)

Summary

Error Handling and Security

Errors, Warnings, and Notices

Dealing with CGI Request Data

Access Control

Attacks

Summary

Utilities and Useful Classes

Dates

File System

Arrays

Trees

Log Files

Summary

Appendix

Classes

Customer Reviews

5 star

4 star

3 star

2 star

1 star

Classes

This section details a number of the core classes. Additional documentation can be found at the official API site: http://api.joomla.org.

Note

This reference uses standard UML notation:

methodOrFunctionName(paramsList) : returnType

The following example describes a method called someMethod with two parameters, anArray and xyz, which returns a string. The parameters are of type array and Boolean respectively. The array type includes associative arrays; more information about array parameters and return types is given in the description of each method. The ampersand denotes that anArray will be passed by reference:

someMethod( &anArray : array, xyz : boolean ) : string

The next example returns a reference (denoted by the ampersand before the method name) to an instance of a JObject class. Methods and functions that return a reference must use the =& assignment operator to prevent copying of the returned value.

The returned object can be a subclass of JObject. The string parameter message is optional, and if it is not specified, it will contain the default value foobar:

&anotherMethod( message : string='foobar' ) : JObject

This last example doesn’t return a value; this is signified by the return type void. The someParameter parameter is of type mixed. A mixed type means that the value can be any type:

andAnotherMethod( someParameter : mixed ) : void

Note

It is important to remember that all method and property names that begin with an underscore are to be treated as private/protected. There is one exception to this. Methods that are named solely with an underscore, _(), are not to be considered private. This method name is used when a class has a method that we use frequently, for example JText::_('translate some text').

JObject

JObject is a common base class. It provides constructor compatibility between PHP 4 and 5, and provides some common methods. For information about using JObject as a parent class, refer to Chapter 2.

Properties

_errors : array

Object error history

Constructors

JObject( ) : JObject

This constructor removes the need for subclasses to use the className() style constructor. Subclasses need only define the __construct() constructor, which, if PHP 5 is not being used, is called by this method. Although this constructor does not define any parameters, this does not restrict the subclasses. Multiple parameters can still be used, all of which will be passed to the highest level __construct() method.

__construct( ) : JObject

This constructor is designed to be overridden in subclasses. Overriding methods should always call parent::__construct().

Methods

get( property : string, default : mixed=null ) : mixed

Accessor; gets the value of the requested property. If the property is not set, then the optional default value will be returned. This method will not return a reference; in subclasses it can be beneficial to add specific methods where a reference to a property is more suitable. Private properties, identified by an underscore at the start of the name, can be returned using this method.
Parameters	property	Name of the property to return
	[default]	The default value to return if the property has not been initialized
Returns	Value of property

getError( i : int=null, toString : boolean=true ) : mixed

Returns an error that occurred during the execution of one of the object’s methods. The error can be an object or a string. See JError for more information about errors.
Parameters	[i]	Error number; by default the last error is retrieved
	[toString]	Return a string even if the error is an object
Returns	Error object or string associated with the object

getErrors( ) : array

Returns a copy of the `_error` property.
Returns	Array of errors associated with the object

getPublicProperties( assoc : boolean=false ) : array

Gets the names of all the public properties of the object; this includes run-time properties, not just class properties. Names of private properties will not be returned; private properties are identified by an underscore at the start of the name. If assoc is `true`, gets an associative array including the property values.
Parameters	[assoc]	Get associative array with values; default is `false`
Returns	Array of public property names or associative array of object property values

set( property : string, value : mixed=null ) : void

Mutator; sets the value of the property in the object.
Parameters	property	Name of the property
	[value]	Value of the property

setError( error : mixed ) : void

Adds an error to the object’s error history.
Parameters	[error]	String or error object

toString( ) : string

Gets a string representation of the object. This method gets the name of the class.
Returns	String representation of the object

JUser

extends JObject
Handles a site user. If the user is not logged in, `id` and `gid` will be zero and `usergroup` will be null. For more information about dealing with users refer to Chapter 7.

Properties

_errorMsg : string	Log of errors, separated by new lines
_params : JParameter	Parameters from `#__users.params` field. Metadata available from `administrator/components/com_users/user.xml`.
activation : string	Activation string, used to verify account registration
aid : int	Access group ID
block : int	Access blocked. 0=not blocked, 1=blocked.
clearPW : string	Clear text password, only present when changing password
email : string	Email address
gid : int	Group ID, relates to the legacy `#__groups` table
id: int	User ID, relates to the `#__users.id` field
lastvisitDate : string	Date on which the user last visited the site
name : string	User’s name, their actual name/nickname, not username
params : string	INI parameter string, used when updating and creating users
password : string	MD5-hashed password
registerDate : string	Date on which the account was registered
sendEmail : int	Receive system emails. 0=no, 1=yes.
username : string	Username
usertype : string	User group that the user is a member of (ARO group). If the user is not logged in this will be null.

Constructors

__construct( identifier : int=0 ) : JUser

Builds a new JUser object and loads the user’s details from the database.
Parameters	[identifier]	User’s ID

Methods

authorize( acoSection : string, aco : string, axoSection : string=null, axo : string=null ) : boolean

Determines if the user is authorized to perform an action. Acts as a pass-through for JAuthorization. This is only for GACL authorization.
Parameters	acoSection	ACO Section (the term ‘section’ does not relate to content sections)
	aco	ACO value
	[axoSection]	AXO Section (the term ‘section’ does not relate to content sections)
	[axo]	AXO value
Returns	`true` if authorized

bind( &array : array ) : boolean

Binds an associative array to the object. There are two ways to use this: updating an existing user and creating a new user. Create is assumed if the object property id is empty (zero is considered empty).

When updating an existing user, array can contain any of the public properties associated with a JUser object. If user parameters are going to be bound they must be passed in a key named params and be in INI string format. The values are then bound to the object.

When creating a new user the username property must already be set. If password is omitted from array a random password will be generated.

Parameters

array

Associative array with which to bind

Returns

true on success

defParam( key : string, value : mixed) : mixed

If the user’s parameter is not defined, this defines the parameter and sets the value.
Parameters	key	Name of the parameter
	value	Value of the parameter
Returns	Previous value of the user’s parameter

delete( ) : boolean

Removes user from the Joomla! database.
Returns	`true` on success

getError( ) : string

Gets the object’s error log.
Returns	Error log

static &getInstance( id : mixed=0 ) : JUser

Gets a reference to a global instance of a JUser object. If the object does not exist, it will be created. `id` can be a string or an integer. If it is a string it will be assumed that it is a username, and if it is an integer it will be assumed that it is a user’s ID. To get a reference to the current user object, use `JFactory::getUser()`.
Parameters	[id]	User’s ID or username
Returns	Reference to a JUser object

getParam( key : string, default : mixed=null) : mixed

Gets a user’s parameter from the `_params` property. If the parameter does not exist, the value of `default` will be returned.
Parameters	key	Name of the parameter
	[default]	Default value
Returns	Value of the parameter, or default value if the parameter does not exist

&getParameters( ) : JParameter

Gets a refernce to the user’s parameters (`_params` property).
Returns	Reference to the user’s parameters

&getTable( ) : JTableUser

Gets a reference to a new JTableUser object loaded with the current user’s details.
Returns	Reference to a new JTableUser object

load( id : int ) : boolean

Loads a user based on their ID. On failure, a warning will be raised.
Parameters	id	User ID
Returns	`true` on success

save( updateOnly : boolean=false ) : boolean

Saves the user to the database. If updateOnly is true, then the creation of a new user will not be permitted. If this is the case, and an attempt is made to save a new user, the method will still return true.

Before saving the user a number of sanity checks are made, including data validation and authorization verification. If any of these fail then the method will return false.

Parameters

[updateOnly]

Only save if it is an existing user

Returns

true on success

setLastVisit( timestamp : string ) : boolean

Updates the user’s database record last visit date; note that this does not update the `lastvisitDate` property of the object.
Parameters	timestamp	Timestamp for the last visit
Returns	`true` on success

setParam( key : string, value : mixed ) : mixed

Sets the value of a user’s parameter.
Parameters	key	Name of the parameter
	value	Value of the parameter
Returns	Previous value of the parameter

setParameters( data : string, path : string=null ) : void

Loads an INI parameter string. `path`, if specified, is the path to an XML file defining the parameters; if not specified, the default user XML file is used.
Parameters	data	INI parameter string
	[path]	XML parameter definition file path

_bind( from : mixed, ignore : string=” ) : boolean

Used by the `bind()` and `load()` methods to bind data to the object. `from` must be an object or associative array. `ignore` defines a list of key/property names that should not be bound to the object.
Parameters	from	Object or associative array to bind
	[ignore]	Properties and keys to ignore
Returns	`true` on success

_setError( msg : string ) : void

Appends `msg` to the object’s error log.
Parameters	msg	Error message

JModel

abstract, extends JObject

Base class for model classes that use the MVC implementation. For more information about JModel refer to Chapter 4.

Properties

_db : JDatabase	Reference to the database connection
_name: string	Model name
_state : JObject	State of the object

Constructors

__construct( config : array=array() ) : JModel

Builds a new JModel object. `config`, an associative array, can contain the keys `'name'` and `'table_path'.'name'` is transposed to the model name; if `'name'` is not specified the name will be extracted from the name of the class. This will only work if the name of the class is in the format `optionalPrefixModelSomeName`. `'table_path'` will be added to the JTable include paths. If `table_path` is not specified, but `JPATH_COMPONENT_ADMINISTRATOR` is defined, then the path `JPATH_COMPONENT_ADMINISTRATOR.DS.'tables'` will be added.
Parameters	[config]	Associative array of configuration options

Methods

static addIncludePath( path : string=” ) : array

Adds a new path to the array of paths used to find JModel classes.
Parameters	[path]	Path to add
Returns	Paths to search for JModel subclasses

static addTablePath( path : mixed=” ) : void

Adds a new path to the array of paths used to find JTable classes. `path` can be a string, or an array of strings. Pass through method for `JTable::addIncludePath()`.
Parameters	[path]	Path or array of paths to add

&getDBO( ) : JDatabase

Gets a reference to a database connection.
Returns	Reference to a database connection

static &getInstance( type : string, prefix : string=” ) : JModel

Gets a reference to a new instance of a JModel subclass object. If the class cannot be found, returns `false`.
Parameters	type	Name of the JTable
	[prefix]	Prefix of the class name, normally `Model`
Returns	Reference to a new instance of a JModel-derived object

getName( ) : string

Gets the model name.
Returns	Model name

getState( property : string=null ) : mixed

Gets a model state property. If `property` is not specified, a complete copy of the model’s state object is returned.
Parameters	[property]	Name of state property
Returns	State property or a complete copy of the model’s state object

&getTable( name : string=”, prefix : string=‘Table’ ) : JTable

Gets an instance of a JTable subclass object. If `name` is not specified, then the model name will be used. The parameters are concatenated to create the class name, in the form `$prefix.$name`. If the class is not present, the paths defined in JTable will be searched for a file named `$prefix.$name.'.php'` where the class should reside.
Parameters	[name]	Name of the JTable
	[prefix]	Class prefix
Returns	Reference to a new instance of a JTable subclass object

setDBO( &db : JDatabase ) : void

Sets the reference to the database connection.
Parameters	Database connection

setState( property : string, value : mixed=null ) : mixed

Sets a user state property.
Parameters	property	Name of state property
	[value]	Value of state property
Returns	Previous value of state property

_createFileName( type : string, parts : array=array() ) : string

Gets the name of the file that a class should be located in. `parts` must include the key `name`. `type` should always be `'table'`.
Parameters	type	The type of resources; only accepts `'table'`
	[parts]	Associative array of name parts
Returns	Name of the file that a class should be located in

&_createTable( name : string, prefix : string=‘Table’ ) : mixed

Used by `getTable()` to create a new instance of a JTable subclass object. Returns null or an error on failure.
Parameters	name	Name of JTable
	[prefix]	Class prefix, normally `Table` or `JTable`
Returns	Reference to a new instance of a JTable subclass object

&_getList( query : string, limitstart : int =0, limit : int=0 ) : array

Executes a query and gets a reference to an array of resultant objects.
Parameters	query	Query to execute
	[limitstart]	Start record
	[limit]	Maximum number of records
Returns	Reference to an array of objects as a result of the query

_getListCount( query : string ) : int

Gets the number of results obtained from `query`. Should be used cautiously; causes the query to be executed. If possible, consider using `$db->getNumRows()` directly after `&_getList()`; this prevents the `query` being executed twice.
Parameters	[query]	Query to count number of results from
Returns	Number of results

JView

abstract, extends JObject

Base class for view classes that use the MVC implementation. For more information about JModel refer to Chapter 4.

Properties

_basePath : string	Path to view base
_defaultModel : string	Name of the default model
_escape : array	Array of names of functions used to escape output. Can also contain arrays with two elements, a class name and method name. For more information see http://php.net/manual/function.call-user-func.php.
_layout : string	Template layout, normally `default`
_layoutExt : string	Template extension, normally `php`
_models : array	Array of models
_name: string	Name of view
_output : string	Output from the template
_path : array	Associative array of arrays of paths for resources
_template : string	Path to template

Constructors

__construct( config : array=array() ) : JView

Builds a new JView object. `config` is an associative array that might contain the keys `name`, `base_path`, `template_path`, `helper_path`, and `layout`. `name` will be transposed to the view name, unless the view name has already been defined. `template_path` adds a path to the template paths. `layout` is the name of the template layout (template filename prefix), normally HTML.
Parameters	[config]	Associative array of options.

Methods

addEscape( ) : void

If provided with parameters, the parameters will be used as the function and methods to use with the escape() method. Parameters must be strings or arrays with two elements, a class and method name.

addHelperPath( path : mixed ) : void

Adds paths to search for template files. `path` can be a string or an array of strings.
Parameters	path	A path or array of paths

addTemplatePath( path : mixed ) : void

Adds paths to search for template files. `path` can be a string or an array of strings.
Parameters	path	A path or array of paths

assign( arg0 : mixed, arg1 : mixed=null ) : boolean

Dynamically adds properties to the object. If `arg0` is an object/array, each of the properties/keys will be added to the object. If `arg0` is a string, it will be used as the name of the property, and `arg1` will be assigned to the value. Properties will be ignored if they start with an underscore.
Parameters	arg0	Object/Array to add or a property name
	[arg1]	Value if `arg0` is a string
Returns	`true` on success

assignRef( key : string, &val : mixed ) : boolean

Dynamically adds the property, identified by `key`, to the object with a reference to `val`. If `key` starts with an underscore it will be rejected.
Parameters	key	Name of the property to add
	val	Value to add a reference to
Returns	`true` on success

display( tpl : string=null ) : mixed

Calls the `loadTemplate()` method and gets the rendered result. If an error occurs a JException object will be returned. If `tpl` is specified, then it will be used as a suffix to the layout with an underscore separator.
Parameters	[tpl]	The template suffix
Returns	Rendered template on success. Error on failure.

escape( value : mixed ) : mixed

Performs escape functions on `value`. This method can be used dynamically, by calling it with extra parameters; extra parameters will be treated as the escape functions. For more information see http://php.net/manual/function.call-user-func.php.
Parameters	value	Value to escape
Returns	Escaped value

&get( method : string, model : string=null ) : mixed

Gets the result of a get method, from a registered model. If the model is not defined then the default model will be used. The method is identified as `'get'.$method`. If the specified model does not exist then the request will passed to the parent (JObject) class `JObject::get($method, $model)`.
Parameters	method	Method or property to return
	[model]	Model to run the method on, or default value
Returns	`get` accessor result. `false` on failure (can be ambiguous depending upon the method being called, or the property being returned).

getLayout( ) : string

Gets the view layout.
Returns	View layout

&getModel( name : string=null ) : JModel

Gets a JModel subclass object from the view. `name` is the name of the JModel class. If `name` is not provided, the default model is retrieved. JView supports a one-to-many relationship with JModels, but only one object per class.
Parameters	[name]	Name of model class
Returns	Reference to a registered model

getName( ) : string

Gets the name of the view.
Returns	View name

loadHelper( hlp : string=null ) : string

Searches known helper paths for the specified helper.
Parameters	[tpl]	Template suffix
Returns	Rendered template

loadTemplate( tpl : string=null ) : string

Loads and renders a template. The rendered result is returned and stored in the object output buffer. If `tpl` is specified, it is appended to the layout name with an underscore separator, for example if `tpl` was `'item'` and the template layout was `'default'`, the template name would be `'default_item'`.
Parameters	[tpl]	Template suffix
Returns	Rendered template

setEscape( ) : void

Resets the escape callback functions and methods to use with the escape() method. If provided with parameters, the parameters will be used as the function and methods to use with the escape() method. Parameters must be strings or arrays with two elements, a class and method name. For more information see http://php.net/manual/function.call-user-func.php.

setLayout( layout : string ) : string

Sets the view layout, normally `default`.
Parameters	layout	View layout
Returns	Previous layout

setLayoutExt( value : string ) : string

Sets the layout extension to use.
Parameters	Value	JModel to associate
Returns	Previous value

&setModel( &model : JModel, default : boolean=false ) : JModel

Registers a JModel subclass object with the view. If `default` is `true`, the registered model will become the default model. JView supports a one-to-many relationship with JModels, but only one object per model class.
Parameters	model	JModel to associate
	[default]	Set as the default model
Returns	Reference to the newly registered model (`returns $model`)

_addPath( type : string, path : mixed ) : void

Adds paths to search for subclass files, normally templates. `type` is the type of path. To add a template path `type` would need to be `'template'`. `path` can be a string or an array of strings.
Parameters	type	Type of path
	path	A path or array of paths

_createFileName ( type : string, parts : array ) : string

Gets a filename based on `type` and `parts`. `type` can be `'template'`. `parts` must contain the key `'name'`.
Parameters	type	Type of filename
	parts	Filename parts
Returns	Name of a file

_setPath( type : string, path : mixed ) : void

Adds paths to search for files, normally templates. `type` is the type of path. To add a template path `type` would need to be `'template'`. `path` can be a string or an array of strings. Using this method will prepend `JPATH_COMPONENT.DS.'views'.DS.'nameOfView'.DS.'tmpl'` to template paths.
Parameters	type	Type of path
	path	A path or array of paths

JController

abstract, extends JObject

Base class for controller classes that use the MVC implementation. For more information about JModel refer to Chapter 4.

Properties

_acoSection : string	ACO Section (relates to GACL)
_acoSectionValue : string	ACO Section Value (relates to GACL)
_basePath : string	Path to controller base
_doTask : string	Task method that is being executed
_message : string	Message to include in redirect
_messageType : string	Type of message to include in redirect
_methods : array	Class method names
_name: string	Name of the controller
_path : array	Directories in which to search for views and models
_redirect : string	Redirect URI
_task : string	Current or last task to be executed
_taskMap : array	Task-to-method map

Constructors

__construct( config : array=array() ) : JController

Builds a new JController object. `config`, an associative array, can contain the keys `name`, base_path, `default_task`, `model_path`, and `view_path`. `name` becomes the controller name, unless the controller name is already defined by the subclass. `default_task` is the task that will be executed by default (this is not the same as the method). `model_path` and `view_path` are the paths in which to search for JModel and JView subclasses (`JPATH_COMPONENT` is prepended to the paths).
Parameters	[config]	An associative array of configuration options

Methods

addModelPath( path : mixed ) : void

Adds paths to search for JModel subclass files. `path` can be a string or an array of strings.
Parameters	path	Path or array of paths to JModel subclass files

addViewPath( path : mixed ) : void

Adds paths to search for JView subclass files. `path` can be a string or an array of strings.
Parameters	path	Paths to JView subclass files

authorize( task : string ) : boolean

If the object ACO Section is not defined authorization is automatically granted. If the object ACO Section has been defined, it determines if the current user has the rights to complete the specified task. If the ACO section value is not specified, `task` is used as the ACO section value.
Parameters	task	The task to execute
Returns	Returns `true` on authorized, false on not authorized

display( cachable : boolean=false ) : void

Attempts to display. Uses JRequest (`view` and `layout`) to determine the view name and which template layout to use. If `view` is not known then the controller name is used. `layout` determines which template to use, normally `default`. If `cachable` is `true` then the global cache object is used to get and populate the display cache.
Parameters	[cachable]	Use cached response

execute( task : string ) : mixed

Executes the method mapped to `task`. If a mapped method for `task` does not exist, it attempts to execute the default `task`. If a mapped method for the default `task` does not exist, a 404 error is raised. When a mapped method is found, access rights are checked using the `authorize()` method. If access is denied, a 403 error is raised.
Parameters	task	The task to execute
Returns	Result of the executed method. Returns error if no mapped method exists.

&getModel( name : string, prefix : string=” ) : JModel

Gets a new instance of a JModel subclass object. If `prefix` is not specified, the name of the controller concatenated with the word `'Model'` is used. `name` is the model class name suffix. If the class does not exist, Joomla! will attempt to load it from the model paths. If the file where the class is expected to reside is found but the class is missing, an error will be thrown.
Parameters	name	Name of model (normally the entity name)
	[prefix]	Class prefix
Returns	A new instance of a JModel subclass object; `null` on failure

getName( ) : string

Gets the name of the controller.
Returns	Controller name

getTask( ) : string

Gets the current task or the last task that was executed.
Returns	Current task or the last task that was executed

getTasks( ) : array

Gets the different task methods that are available for this controller.
Returns	Array of task methods

&getView( name : string=”, type : string=”, prefix : string=”, config : array=array() ) : JView

Gets a JView subclass object. If `name` is not specified, the controller name is used. If `prefix` is not specified, the prefix will be `$controllerName.'View'`. `type` is the view layout, normally HTML. This method is normally called only specifying `name`. $view = $SomeController->getView('Item'); This would attempt to instantiate the class SomeViewItem.
Parameters	[name]	View name
	[type]	View type; relates to the document type
	[prefix]	View prefix, default is `View`
	[config]	Configuration array to pass to the view
Returns	JView subclass object

redirect( ) : boolean

If a redirect has been set, it redirects the browser and closes the application.
Returns	Returns false on failure

registerDefaultTask( method : string ) : void

Registers the default task method. The default task is the task that is executed when an attempt is made to execute a task that is not mapped to a method.
Parameters	method	Default task method

registerTask( task : string, method : string ) : void

Registers a task, with a method.
Parameters	task	Task name
	method	Method name

setAccessControl( section : string, value : string=null ) : void

Sets the object authorization ACO and ACO value. This is used by the authorize method.
Parameters	section	ACO section
	[value]	ACO value

setMessage( text : string ) : void

Sets the object redirect message. This is only used if the redirect method is called.
Parameters	text	Redirect message

setRedirect( url : string, msg : string=null, type : string=‘message’ ) : void

Sets the object redirect options. This is only used if the redirect method is called.
Parameters	url	Redirect URI
	[msg]	Redirect message
	[type]	Message type

_addPath( type : string, path : mixed ) : void

Adds paths to search for JModel or JView subclass files. `type` can be `'view'` or `'model'`. `path` can be a string or an array of strings.
Parameters	type	Type of path
	path	Path or array of paths

_createFileName ( type : string, parts : array=array() ) : string

Gets a filename based on `type` and `parts`. `type` can be `'view'` or `'model'`. `parts` must contain the key `'name'` and if `type` is `'view'` it can optionally contain the key `'type'`, which relates to the layout.
Parameters	type	Type of filename
	[parts]	Filename parts
Returns	Name of a file

&_createModel( name : string, prefix : string=” ) : JModel

Builds a new JModel subclass object. `name` is the class name suffix, normally the entity name. `prefix` is the class name prefix, normally `$controllerName.'View'`.
Parameters	name	Model name (normally the entity name)
	[prefix]	Model class name prefix
Returns	A new JModel subclass object

&_createView( name : string, prefix : string=”, type : string=”, config : array=array() ) : JView

Builds a new JView subclass object. `name` is the class name suffix, normally the entity name. `prefix` is the class name prefix, normally `$controllerName.'View'`. `type` is the layout, normally HTML.
Parameters	name	View name, normally the entity name
	[prefix]	View class name prefix
	[type]	View output type
	[config]	Configuration array to pass to the view
Returns	A new JView subclass object

_setPath( type : string, path : mixed ) : void

Adds paths to search for JModel or JView subclass files. `type` can be `view` or `model`. `path` can be a string or an array of strings. Using this method will prepend `JPATH_COMPONENT. DS.$type` to each path.
Parameters	type	Type of path
	path	Path or array of paths

JTable

abstract, extends JObject

Class that handles individual database tables. JTable uses a buffering mechanism, which allows it to handle records on an individual basis. For more information about JTable refer to Chapter 3.

Properties

_tbl: string	Table name
_tbl_key : array	Primary key
_errorNum : int	Error Number
_db : JDatabase	Database connection

Constructors

__construct( table : string, key : string, &db : JDatabase ) : JTable

Builds a new JTable object.
Parameters	table	Table name
	key	Primary Key
	db	Database connection

Methods

static addIncludePath( path : mixed=” ) : array

Adds paths to search for JTable subclasses. `path` can be a string or an array of strings.
Parameters	[paths]	Path or array of paths to add
Returns	Array of paths

bind( from : mixed, ignore : mixed=array() ) : boolean

Binds a subject (normally a record) to the object. For all the public object properties, this finds a corresponding key or property in `from`, and binds them to the object.
Parameters	from	Bind subject, object or associative array
	[ignore]	Fields to ignore, string or array
Returns	`true` on success

canDelete( oid : string=null, joins : array=null ) : boolean

Determines if there are any records linked to the buffered record or, if `oid` is specified, the record identified by `oid`. `joins` identifies linked tables. `joins` is an optional two-dimensional array; the inner arrays are associative, and must contain the keys `name`, `idfield`, and `joinfield`. `name` is the linked table name, `idfield` is the linked table’s primary key, and `joinfield` is the foreign key in the linked table.
Parameters	[oid]	Record ID
	[joins]	Associative array of table join constraints
Returns	`true` if there are no dependent records

check( ) : boolean

This method is used to validate the contents of the record buffer. This should be overridden in subclasses.
Returns	`true` on success

checkin( oid : string=null ) : boolean

Checks-in the buffered record or, if `oid` is specified, checks-in the record identified by `oid`. This sets the record’s `checked_out` field to zero and `checked_out_time` to a null date-time.
Parameters	[oid]	Record ID
Returns	`true` on success

checkout( who : id, oid : string=null ) : boolean

Checks out the buffered record or, if `oid` is specified, checks out the record identified by `oid`. This sets the record’s `checked_out` field to `who` and `checked_out_time` to the current date-time.
Parameters	who	User’s ID
	[oid]	Record ID
Returns	`true` on success

delete( oid : string=null ) : boolean

Deletes the buffered record or, if `oid` is specified, deletes the record identified by `oid`.
Parameters	[oid]	Record ID
Returns	`true` on success

&getDBO( ) : JDatabase

Gets the database connection object.
Returns	Database connection object

getErrorNum( ) : int

Gets the object error number. `0` (zero) means no error.
Returns	Error number

static &getInstance( type : string, prefix : string=‘JTable’ ) : mixed

Gets a new JTable subclass object. `type` is the name of the file the class resides in and the class name suffix, normally the entity name. `prefix` is the class name prefix. Core JTable subclasses use the prefix `'JTable'`; third-party JTable classes tend to use the prefix `'Table'`.
Parameters	type	Class name suffix and file name
	[prefix]	Class name prefix
Returns	New JTable subclass object

getKeyName( ) : string

Gets the name of the primary key field.
Returns	Name of the primary key

getNextOrder( where : string=” ) : int

Gets the next place available in the current ordering. Using `reorder()` before using this method will ensure there are no gaps in the ordering.
Parameters	[where]	`WHERE` clause
Returns	Next place available in the current ordering

getTableName( ) : string

Gets the name of the table.
Returns	Name of the table

hit( oid : string=null, log : boolean=false ) : void

Increases the hit counter of the buffered record or, if `oid` is specified, the record identified by `oid`.
Parameters	[oid]	Record ID
	[log]	Has no effect

[static] isCheckedOut( with : int=0, against : int=null ) : boolean

Determines if the buffered record is checked out by any user other than the current user. If used statically (both `with` and `against` must be specified) compares `with` to `against`.
Parameters	[with]	Current user’s ID
	[against]	Record’s `checked_out` value (checked-out user’s ID)
Returns	`true` if the record is checked out by any user other than the current user

load( oid : string=null ) : boolean

Resets the record buffer and loads a single record into the buffer. `oid` is the value of the record’s primary key.
Parameters	[oid]	Record ID
Returns	`true` on success

move( dirn : int, where : string=” ) : void

Moves a record up or down the ordering (table must have an ordering field). -1 = move up, 1 = move down.
Parameters	dirn	Direction to move
	[where]	`WHERE` clause

publish( cid : array=null, publish : int=1, user_id : int=0 ) : boolean

Sets the publish value of records identified by `cid`, an array of record IDs (this only works when the table’s primary key is numeric). Although `cid` is optional, if it is not specified the method will fail. If the table has a `checked_out` field, any records that are checked out by other users will not be affected.
Parameters	[cid]	Array of record IDs
	[publish]	Publish value, `1` or `0`
	[user_id]	Current user’s ID
Returns	`true` on success

reorder( where : string=” ) : boolean

Removes gaps in ordering.
Parameters	[where]	`WHERE` clause
Returns	`true` on success

reset( ) : void

Resets the object to the initial class option values.

save( source : mixed, order_filter : string=” ) : boolean

Binds `source` to the object; `source` must be an object or an associative array. Checks the buffer, stores the buffer, checks-in the record, and if `order_filter` is specified uses it to determine which field must be common during the execution of the `reorder()` method.
Parameters	source	Record to save
	[order_filter]	Name of field by which records are ordered
Returns	`true` on success

setDBO( &db : JDatabase ) : void

Sets the JDatabase connection object.
Parameters	db	Database connection object

store( updateNulls : boolean=false ) : boolean

Saves the record buffer to the database. If the record buffer primary key property is set, an `UPDATE` will be executed, otherwise an `INSERT` will be executed.
Parameters	[updateNulls]	Update null values
Returns	`true` on success

setErrorNum( value : int ) : void

Sets the object error number. `0` (zero) means no error.
Parameters	value	Error number

toXML( mapKeysToText : boolean=false ) : string

Gets an XML representation of the buffered record.
Parameters	[mapKeysToText]	Maps foreign keys to text
Returns	XML string

JError

static

Error handler. For more information about JError refer to Chapter 11.

Methods

static customErrorPage( &error : JException ) : void

Gets the global instance of JDocumentError and passes it the error, then renders the page. This removes any previous output, and terminates the script.
Parameters	error	JException error object
Return	`$error`

static &getError( unset : boolean=false ) : mixed

Gets the last error in the global error stack, or false if there are no errors. If `unset` is `true`, then the error will be removed from the stack.
Parameters	[unset]	Remove last error from the global error stack
Returns	First error in the global error stack, or false if there are no errors

static getErrorHandling( level : int ) : array

Gets a copy of the associative array used to determine the handling of the specified error level. The array contains the key `mode` and, optionally, the key `options`. If an unknown level is passed, then null will be returned.
Parameters	level	Error level
Return	Associative array used to determine error handling mechanism of `level`

static &getErrors( ) : array

Gets a reference to the global error stack.
Returns	Reference to the global error stack

static &handleCallback( &error : JException, options : array ) : mixed

Calls a method in another class, passes `error` to it, and returns the result. `options` must have two string elements, the class name and method name to be called. This is essentially a pass-through method for the PHP `call_user_func()` function.
Parameters	error	JException error object
	options	`array('classname', 'methodname')`
Return	Result of the executed method

static &handleDie( &error : JException, options : array ) : JException

Terminates the script and outputs the JException message to screen in HTML. If `$_SERVER['HTTP_HOST']` is not set, the message will either be echoed in plain text, or if `STDERR` is defined, written to `STDERR`.
Parameters	error	JException error object
	options	Array of options (ignored)
Return	`$error`

static &handleEcho( &error : JException, options : array ) : JException

Outputs JException message to screen in HTML. If `$_SERVER['HTTP_HOST']` is not set, the message will either be echoed in plain text, or if `STDERR` is defined, written to `STDERR`.
Parameters	error	JException error object
	options	Array of options (ignored)
Return	`$error`

static &handleIgnore( &error : JException, options : array ) : JException

Handle ignore error. No actions taken, returns `error`.
Parameters	error	JException error object
	options	Array of options (ignored)
Return	`$error`

static &handleLog( &error : JException, options : array ) : JException

Adds a log entry to the error log. A new error log is created every day in the format `Y-m-d.error.log`. The entry includes the date, time, level, code, and message.
Parameters	error	JException error object
	options	Array of options (passed to JLog)
Return	`$error`

static &handleMessage( &error : JException, options : array ) : JException

Adds the JExcpetion message to the application message queue.
Parameters	error	JException error object
	options	Array of options (ignored)
Return	`$error`

static &handleTrigger( &error : JException, options : array ) : JException

Triggers a PHP user-level error, warning, or notice.
Parameters	error	JException error object
	options	Array of options (ignored)
Return	`error`

static &handleVerbose( &error : JException, options : array ) : JException

Outputs JException message, info, and backtrace to screen in HTML. If `$_SERVER['HTTP_HOST']` is not set, the message will either be echoed in plain text, or if `STDERR` is defined, written to `STDERR`.
Parameters	error	JException error object
	options	Array of options (ignored)
Return	`$error`
Return	`$error`

static isError( &object : mixed ) : boolean

Checks if `object` is an error (is of class JException or Exception).
Parameters	object	Object to check
Returns	`true` if object is an error

static &raise( level : int, code : string, msg : string, info : mixed=null, backtrace : boolean=false ) : mixed

Raises a new error of `level` and executes the associated error handling mechanisms. `level` relates to the PHP error levels, `E_NOTICE`, `E_WARNING`, and `E_ERROR`. Error handling levels and mechanisms can be altered.
Parameters	level	Error level
	code	Error code
	msg	Error message
	[info]	Additional error information
	[backtrace]	Include `debug_backtrace()` information
Returns	Depends on error handling mechanism; normally a JException object

static &raiseError( code : string, msg : string, info : mixed=null) : mixed

Raises a new error (`E_ERROR`) and executes the associated error handling mechanisms (by default `JError::handleCallback()`, which in turn calls, `JError::customErrorPage()`).
Parameters	code	Error code
	msg	Error message
	[info]	Additional information
Return	Depends on error handling mechanism; normally a JException object

static &raiseNotice( code : string, msg : string, info : mixed=null) : mixed

Raises a new notice (`E_NOTICE`) and executes the associated error handling mechanisms (by default this is `JError::handleMessage`). Normally this method will display a notice message on the resultant page
Parameters	code	Error code
	msg	Error message
	[info]	Additional information
Return	Depends on error handling mechanism; normally a JException object

static &raiseWarning( code : string, msg : string, info : mixed=null) : mixed

Raises a new warning (`E_WARNING`) and executes the associated error handling mechanisms (by default `JError::handleMessage()`). Normally this method will display a warning message on the resultant page.
Parameters	code	Error code
	msg	Error message
	[info]	Additional information
Return	Depends on error handling mechanism; normally a JException object

static registerErrorLevel( level : int, name : string, handler : string=‘ignore’ ) : boolean

Defines a new error level. If the level already exists it will be rejected. `name` describes to the error type. `handler` defines the mode to use when an error of the new level is encountered (`ignore`, `echo`, `verbose`, `die`, `messages`, or `log`). To use `callback`, use `JError::setErrorHandling()` after registering the new level.
Parameters	level	New error level
	name	Name
	[handler]	Handler (mode)
Return	`true` on success

static setErrorHandling( level : int, mode : string, options : array=‘null’ ) : mixed

Sets the error handling mechanism for `level`. Only levels that have already been defined can be modified. `mode` specifies what will occur when an error of the specified level is encountered (`ignore`, `echo`, `verbose`, `die`, `messages`, `log`, or `callback`). `options`, if set, is passed to the handler method. For example, if `mode` was `'message'`, then the `JError::handleMessage()` method would be called with two parameters—the JException object and `options`. If `'mode'` is `callback`, the options array must be specified, and it must contain two string elements, a class name and a method to execute. `callback` is special, because it is the only mode in which a method outside of the JError class can be used to handle an error.
Parameters	level	Error level
	mode	Error handler
	[options]	Options to pass to the handler method
Return	`true` on success; error on failure

static translateErrorLevel( level : int ) : mixed

Gets the name of the error level. If the error level is not defined, false will be returned.
Parameters	level	Error level
Return	Name of error level; `false` if error level is not defined

JDocument

abstract, extends JObject

Encapsulates and caches a response during the execution of an application. This enables us to make modifications to any part of the document irrespective of where we are in the output process. For more information about the document please refer to Chapter 2.

Properties

_buffer : string	Document rendered content buffer
_charset : string	Character encoding; default encoding is UTF-8
_engine : object	Rendering engine, used by core subclass JDocumentPDF
_generator : string	Generator metadata
_lineEnd : string	EOL character/string
_mdate : string	Document modified date
_metaTags : array	Metadata tags
_mime : string	MIME type
_namespace : string	Namespace, not used by core JDocument subclasses
_profile : string	Document profile, not used by core JDocument subclasses
_script : array	Embedded scripts
_scripts : array	URIs to linked scripts
_style : array	Embedded styles
_styleSheets : array	URIs to linked Cascading Style Sheets
_tab : string	Tab character/string
_type : string	Document type
description : string	Document description
direction : string	Text direction (`ltr` or `rtl`); default is left-to-right
language : string	Language setting, default is `en` (English)
link : string	Base URI of the document
title : string	Document title

Constructors

__construct( options : array=array() ) : JDocument

Builds a new JDocument. Subclasses call `parent::_construct($options)`.`options` can contain the keys, `lineend`, `charset`, `language`, `direction`, `tab`, and `link`.
Parameters	[options]	Associative array of configuration options

Methods

addLink( url : string ) : void

Sets base URI of the document.
Parameters	url	Base URI

addScript( url : string, type : string=‘text/javascript’ ) : void

Adds a link to a script to the document.
Parameters	url	Script URI
	[type]	MIME type

addScriptDeclaration( content : string, type : string=‘text/javascript’) : void

Embeds a script in the document.
Parameters	content	Script
	[type]	MIME type

addStyleSheet( url : string, type : string=‘text/css’, media : string=null, attribs : array=array() ) : void

Links a stylesheet to the document. `media` is the link tag’s media attribute. Common media types include `screen`, `handheld`, `print`, and `aural.attribs` is an associative array of link tag attributes.
Parameters	url	Script URI
	[type]	MIME type
	[media]	Link tag media attribute type
	[attribs]	Associative array of tag attributes

addStyleDeclaration( content : string, type : string=‘text/css’ ) : void

Embeds styles in the document.
Parameters	content	Style content
	[type]	MIME type

getBuffer( ) : string

Gets the buffered contents of the document.
Returns	Document contents

getCharset() : string

Gets the character set encoding.
Returns	Character set encoding

getDescription( ) : string

Gets the document description.
Returns	Document description

getDirection( ) : string

Gets the text direction of the document, `ltr` (left-to-right) or `rtl` (right-to-left).
Returns	Text direction

getGenerator( ) : string

Gets the document generator.
Returns	Document generator

getHeadData( ) : array

Gets an associative array of header data. Must be implemented in child classes.
Returns	Associative array of header data

static &getInstance ( type : string=‘html’, attributes : array=array() ) : JDocument

Gets a global instance of a JDocument subclass object, based on `type` (error, feed, HTML, PDF, or RAW) and `attributes`. Use `JFactory::getDocument()` to get the application document.
Parameters	[type]	JDocument type
	[attributes]	Associative array of options
Returns	Global instance of a JDocument subclass object

getLanguage( ) : string

Gets the language of the document.
Returns	Document language

getLink( ) : string

Gets the document base URI.
Returns	Document base URI

getMetaData( name : string, http_equiv : boolean=false ) : string

Gets the document metadata. If the metadata is http-equiv (equivalent to an HTTP header) then specify `http_equiv` as `true`.
Parameters	name	Metadata name
	[http_equiv]	Get HTTP header equivalent metadata
Returns	Metadata

getModifiedDate( ) : string

Gets the document modified date.
Returns	Document modified date

getTitle( ) : string

Gets the document title.
Returns	Document title

getType( ) : string

Gets the document type.
Returns	String representation of document type

&loadRenderer( type : string ) : JDocumentRenderer

Gets a new instance of a JDocumentRenderer subclass object. `type` can be `Atom`, `RSS`, `Component`, `Head`, `Message`, `Module`, or `Modules`. If you define your own JDocumentRenderer class, you must include the class, before using this method.
Parameters	type	Renderer type
Returns	Instance of a JDocumentRenderer-derived object

render( cache : boolean=false, params : array=array() ) : string

Gets the rendered document. This method varies depending upon the subclass.
Parameters	cache	Cache document
	params	Associative array of options
Returns	Rendered document

setBuffer( content : string ) : void

Sets the buffered contents of the document.
Parameters	content	Document contents

setCharset( type : string=‘utf-8’ ) : void

Sets the character set encoding. This does not convert content to the new character set.
Parameters	[type]	Character set

setDescription( description : string ) : void

Sets the document description.
Parameters	description	Document description

setDirection( dir : string=‘ltr’ ) : void

Sets the text direction of the document, `ltr` (left-to-right) or `rtl` (right-to-left).
Parameters	[dir]	Text direction

setGenerator( generator : string ) : void

Sets the document generator; default is `Joomla! 1.5 - Open Source Content Management`.
Parameters	generator	Generator name

setLanguage( lang : string=‘en’ ) : void

Sets the language of the document.
Parameters	[lang]	Language

setLineEnd( style : string ) : void

Sets the document EOL character string. `style` can be `win`, `unix`, `mac`, or a custom EOL character string.
Parameters	style	System type or EOL string

setMetaData( name : string, content : string, http_equiv : boolean=false ) : void

Sets metadata. If the metadata is http-equiv (equivalent to an HTTP header) then specify `http_equiv` as `true`.
Parameters	name	Metadata name
	content	Metadata content
	[http_equiv]	Header equivalent

setMimeEncoding( type : string=‘text/html’ ) : void

Sets the document MIME encoding.
Parameters	[type]	MIME encoding

setModifiedDate( date : string ) : void

Sets the document modified date.
Parameters	date	Modified date

setTab( string : string ) : void

Sets the document indentation string, e.g `"\t"`.
Parameters	string	Indentation string

setTitle( title : string ) : void

Sets the document title.
Parameters	[title]	Document title

setType( type : string ) : void

Sets the document type.
Parameters	type	JDocument type

_getLineEnd( ) : string

Gets the EOL character/string.
Returns	EOL character string

_getTab( ) : string

Gets the indentation character string.
Returns	Indentation character string

JApplication

abstract, extends JObject

Base application class. The frontend and backend application classes both extend this class. This class encapsulates the process from request to response. For more information about the application refer to Chapter 2.

Properties

_clientId : int	Client type; 0 = site, 1 = admin, 2 = installation
_router : JRouter	Application router
_messageQueue : array	Queued messages

Constructors

__construct( clientId : int=0 ) : JApplication

Builds a new JApplication object with the specified `clientId`. Subclasses generally do not require the `clientId` parameter.
Parameters	[clientId]	0 = site, 1 = admin, 2 = installation

Methods

addCustomHeadTag( html : string ) : void

Deprecated; use of this method is no longer advised.

Adds a custom HTML tag to the head if the document type is HTML. Instead use:

$document =& JFactory::getDocument();
if($document->getType() == 'html')
{
    $document->addCustomTag('<!—a custom tag-->');
}

Parameters

HTML

HTML to add to the head

addMetaTag( name : string, content : string, prepend : string=”, append : string=” ) : void

Deprecated; use of this method is no longer advised. Adds metadata to the document. Instead use: $document =& JFactory::getDocument(); $document->setMetadata('metaName', 'metaValue');
Parameters	name	Metadata name
	content	Metadata value
	[prepend]	Deprecated, no effect
	[append]	Deprecated, no effect

appendMetaTag( name : string, content : string ) : void

Deprecated; use of this method is no longer advised.

Adds metadata to the document. Instead use:

$document=& JFactory::getDocument();
$document->setMetadata('metaName', 'metaValue');

Parameters

name

Metadata name

content

Metadata value

appendPathway( name : string, link : string=null ) : boolean

Deprecated and created during the development of Joomla! 1.5. Appends an item to the pathway. Instead use JPathWay: $pathway = mainframe->getPathWay(); $pathway->addItem($name, $link);
Parameters	name	Item name
	[link]	Item link
Returns	`true` on success

close( code : int=0 ) : void

Closes the application gracefully.
Parameters	[code]	`exit()` code

dispatch( component :string ) : void

Dispatches the request and executes the relevant component, storing the rendered result in the global JDocument object.
Parameters	[component]	Component being invoked

enqueueMessage( msg : string=”, msgType : string=‘message’ ) : void

Adds a new message to the application message queue. Clears the session message queue.
Parameters	msg	Message
	[msgType]	Type of message

getBasePath( client : int=0, addTrailingSlash : boolean=true ) : string

Deprecated; use of this method is no longer advised.

Gets the base path to application entry point, not including the file name. Instead use:

$basePath = JURI::base();

Parameters

[client]

Deprecated, no effect

[addTrailingSlash]

Deprecated, no effect

Returns

Path to application entry point, not including the file name

getBlogCategoryCount( ) : int

Deprecated; use of this method is no longer advised.

Counts the number of menu items that are blog categories (content_blog_category). Instead use:

$menus = &JMenu::getInstance();
$count = count($menus->getItems('type',
 'content_blog_category'));

Returns

Number of menu items that are blog categories

getBlogSectionCount( ) : int

Deprecated; use of this method is no longer advised.

Counts the number of menu items that are blog sections (content_blog_section). Instead use:

$menus = &JMenu::getInstance();
$count = count($menus->getItems('type',
 'content_blog_section'));

Returns

Number of menu items that are blog sections

getCfg( varname : string ) : mixed

Gets a configuration value.
Parameters	varname	Name of config value
Returns	Configuration value

getClientId( ) : int

Gets the client id. 0 = site, 1 = administrator, 2 = installer.
Returns	Client ID

getContentItemLinkCount( ) : int

Deprecated; use of this method is no longer advised.

Counts the number of menu items that are content item links (content_item_link). Instead use:

$menus = &JMenu::getInstance();
$count = count($menus->getItems('type',
 'content_item_link'));

Returns

Number of menu items that are content item links

getCustomPathway( ) : array

Deprecated and created during the development of Joomla! 1.5.

Instead use JPathWay:

$pathway = mainframe->getPathWay();
$customPathway = $pathway->getPathWayNames();

Returns

Array of breadcrumbs

getGlobalBlogSectionCount( ) : int

Deprecated; use of this method is no longer advised.

Counts the number of menu items that are blog sections (content_blog_section). Instead use:

$menus = &JMenu::getInstance();
$count = count($menus->getItems('type',
 'content_blog_section'));

Returns

Number of menu items that are blog sections

getHead( ) : string

Deprecated; use of this method is no longer advised.

Gets the document head. Instead use:

$document =& JFactory::getDocument();
$head = $document->get('head');

Returns

Document head

getItemId( id : int ) : int

Deprecated; use of this method is no longer advised.

Gets the menu ItemId for the specified content item. Instead use:

ContentHelper::getItemid($id, $categoryId,
 $sectionId);

Parameters

Content item ID

Returns

Menu ItemId for the specified content item

getMessageQueue( ) : array

Gets a copy of the application message queue. If no application messages exist and there are session messages, the session message queue will be moved to the application message queue.
Returns	Array of application messages

getPageTitle( ) : string

Deprecated; use of this method is no longer advised.

Gets the title of the document. Instead use:

$document=& JFactory::getDocument();
$title = $document->getTitle();

Returns

Menu ItemId for the specified content item

getPath( varname : string, user_option : string=null ) : string

Deprecated; use of this method is no longer advised. Determines path to a resource. `varname` (resource type) can be `front`, `html`, `front_html`, `toolbar`, `toolbar_html`, `toolbar_default`, `toolbar_front`, `admin`, `admin_html`, `admin_functions`, `class`, `helper`, `com_xml`, `mod0_xml`, `mod1_xml`, `plg_xml`, or `menu_xml`. `user_option` refers to a user-related option, for example `com_content`. Instead use: $path = JApplicationHelper::getPath($varname, $user_option);
Parameters	varname	User_option type
	[user_option]	User option
Returns	Path

&getRouter( ) : JRouter

Gets the application router object.
Returns	Application router object

getStaticContentCount( ) : int

Deprecated; use of this method is no longer advised.

Counts the number of menu items that are static content (content_typed). Instead use:

$menus = &JMenu::getInstance();
$count = count($menus->getItems('type',
 'content_typed'));

Returns

Number of menu items that are static content

getTemplate( ) : string

Gets the name of the application template.
Returns	Application template name

getUser( ) : JUser

Deprecated; use of this method is no longer advised.

Gets the current user object. Instead use:

$user =& JFactory::getUser();

Returns

User object

getUserState( key : string ) : mixed

Gets a value from the user session registry.
Parameters	key	Name of the user session registry value
Returns	Value from the user session registry

getUserStateFromRequest( key : string, request : string, default : mixed=null, type : string=‘none’ ) : string

Gets a value from the user session registry, updating with a request value if a request value exists.
Parameters	key	Name of the session registry value
	request	Name of the request value
	[default]	Default value
	[type]	Name of the hash from which the request value should be retrieved
Returns	Up-to-date value from the user session registry

initialise( options : array=array() ) : void

Initializes the application. Prepares application language, defines date formats, and builds the application router.
Parameters	[options]	Associative array of options

isAdmin( ) : boolean

Checks if application is administrator (client ID is 1).
Returns	`true` if application is backend

isSite( ) : boolean

Checks if application is frontend (client ID is 0).
Returns	`true` if application is frontend

loadConfiguration( file : string ) : void

Loads the application configuration and sets the database debug mode.
Parameters	file	Path to configuration file

loadSession( name : string ) : void

Loads the session. Creates a new session, if the session does not already exist.
Parameters	name	Session name

login( credentials : array, options : array=array() ) : mixed

Checks Joomla! credentials. `credentials` must include the keys `username` and `password`. If the login fails a warning will be raised. If any `onLoginUser` event handlers return false, login will be unsuccessful.
Parameters	credentials	Associative array of user credentials
	[options]	Options to pass to the authentication plugins
Returns	`true` on success

logout( ) : boolean

If a user is logged-in, logs them out
Returns	`true` on success

prependMetaTag( name : string, content : string ) : void

Deprecated; use of this method is no longer advised.

Adds metadata to the document. Instead use:

$document=& JFactory::getDocument();
$document->setMetadata('metaName', 'metaValue');

Parameters

name

Metadata name

content

Metadata value

registerEvent( event : string, handler : string ) : void

Registers an event handler with the global event dispatcher. `handler` must be the name of a function or the name of a class that has a method of the same name as `event`.
Parameters	event	Name of event
	handler	Function or class name

render( ) : void

Renders the response and adds it to the static JResponse body.

redirect( url : string, msg : string=”, msgType : string=‘message’ ) : void

Redirects to the specified `url` and, if specified, enqueues `msg`, ready to be served in the next request. This method closes the application. If the headers have not been sent an HTTP 301 (Moved Permanently) response will be made, otherwise a JavaScript redirect will be used.
Parameters	url	Redirect URI
	[msg]	Optional message to enqueue
	[msgType]	Type of message

route( ) : void

Route the applictaion. Chooses the route through the application to take, based on the request URI.

setPageTitle( title : string=null ) : void

Deprecated; use of this method is no longer advised.

Sets the title of the document. Instead use:

$document =& JFactory::getDocument();
$document->setTitle($title);

Parameters

[title]

Document title

setUserState( key : string, value : mixed ) : mixed

Sets a value in the user session registry.
Parameters	key	Name of the user session registry value
	value	Key value
Returns	Value from the user session registry

triggerEvent( event : string, args : array=null ) : array

Triggers an event. This will notify any registered event handlers associated with the event that the event has occurred. `args` is exploded and each element is passed as individual argument to the handler.
Parameters	event	Event to trigger
	[args]	Array of arguments to pass to the handlers
Returns	Array of the resultant returns from the event handlers

&_createConfiguration( file : string ) : JConfig

Loads the global configuration. The configuration file must define the class JConfig.
Parameters	file	Path to configuration file
Returns	JConfig configuration object

&_createRouter( ) : JRouter

Gets the application router. If the application router does not exist, it is created.
Returns	Application router

&_createSession( name : string ) : JTableSession

If a session does not exist, creates a session and adds it to the `#__session` table. If a session already exists, updates the session expiry time.
Parameters	name	Session name
Returns	Session JTable object

JURI

extends JObject

Handles URIs

Properties

_fragment : string	URI fragment (internal document location)
_host : string	Host
_pass : string	URI Password (not the Joomla! user’s password)
_path : string	Path
_port : int	Port number
_query : string	GET query
_scheme : string	URI scheme (e.g. `http`)
_uri : string	URI
_user : string	URI Username (not the Joomla! user’s username)
_vars : array	GET query, associative array

Constructors

__construct( uri : string=null ) : JURI

Builds a new JURI object. If `uri` is specified, it will be parsed.
Parameters	[uri]	URI to parse

Methods

static base( ) : string

Gets the base URI for the entry point, not including the filename.
Returns	Base URI

current( ) : string

Gets the URI of the current location including the scheme, host, port, and path.
Returns	Current URI

delVar( name : string ) : void

Deletes a value from the URI query.
Parameters	name	Name of query value

getFragment( ) : string

Gets the URI fragment identifier (denoted by a hash, #).
Returns	URI fragment identifier

getHost( ) : string

Gets the URI host name. This does not include the path to the resource.
Returns	Host name or IP address

static &getInstance( uri : string=‘SERVER’ ) : JURI

Gets a global instance of a JURI object. If `uri` is not specified, `uri` will be constructed based on the current request.
Parameters	[uri]	URI object to get
Returns	Global instance of a JURI object

getPass( ) : string

Gets the URI password. This is part of the scheme authorization; it is not the same as Joomla! authorization.
Returns	Scheme password

getPath( ) : string

Gets the URI path. This does not include the host name.
Returns	URI path

getPort( ) : int

Gets the URI port. If it is the default port for the scheme, this may not return anything.
Returns	Port number

getQuery( toArray : boolean=false ) : mixed

Gets the URI query. If `toArray` is false, it will return a string, otherwise it will return an associative array.
Parameters	[toArray]	Get in array format
Returns	URI query string

getScheme( ) : string

Gets the URI scheme, normally `http` or `https`.
Returns	URI scheme

getUser( ) : string

Gets the URI username. This is part of HTTP authorization; it is not the same as Joomla! authorization, or Joomla! user’s username.
Returns	Scheme username

getVar( name : string=null, default : mixed=null ) : string

Gets a value from the URI query. Returns `default` if not set.
Parameters	[name]	Name of query value
	[default]	Default value
Returns	Value from the URI query

isSSL( ) : boolean

Determines if the URI scheme is `https`.
Returns	`true` if scheme is `https`

parse( uri : string ) : boolean

Attempts to parse a URI, the results of which are stored in the object.
Parameters	uri	URI to parse
Returns	`true` on success

setFragment( anchor : string ) : void

Sets the URI fragment identifier.
Parameters	anchor	Fragment identifier

setHost( host : string ) : void

Sets the URI host name. This does not include the path to the resource.
Parameters	host	Host name or IP address

setPass( pass : string ) : void

Sets the URI password. This is part of the scheme authorization; it is not the same as Joomla! authorization.
Parameters	pass	Scheme password

setPath( path : string ) : void

Sets the URI path.
Parameters	path	URI path

setPort( port : int ) : void

Sets the URI port.
Parameters	port	Port number

setQuery( query : mixed ) : void

Sets the URI query. This can be done using a query string or an associative array.
Parameters	query	Query string or associative array

setScheme( scheme : string ) : string

Sets the URI scheme, normally `http` or `https`.
Parameters	scheme	Scheme to set to

setUser( user : string ) : void

Sets the URI username. This is part of the scheme authorization; it is not the same as Joomla! authorization.
Parameters	user	Scheme username

setVar( name : string, value : string ) : string

Sets a value in the URI query. Returns the previous value.
Parameters	name	Name of query value
	value	New value
Returns	Previous value

toString( parts : array=array(’scheme’, ‘user’, ‘pass’, ‘host’, ‘port’, ‘path’, ‘query’, ‘fragment’) ) : string

Returns the URI in string format, including the defined parts. The default value for `parts` includes all of the possible parts of the URI. Order of elements in `parts` is not important.
Parameters	[parts]	Parts to include in the URI
Returns	String representation of the JURI object

_buildQuery( params : array, akey : string=null ) : string

Builds a URI query from the `params` associative array. `akey` is used internally as part of a callback routine for array query values.
Parameters	path	Path to clean
	[akey]	Array name
Returns	Cleaned path

_cleanPath( path : string ) : string

Cleans the passed URI. Removes any unnecessary clutter from the path.
Parameters	path	URI to clean
Returns	Cleaned path

JLanguage

extends JObject

Handles languages and translation.

Properties

_debug : boolean	Debug mode
_default : string	Default language (en-GB)
_lang : string	Language name
_metadata : array	Language metadata
_orphans : array	Strings that failed translation (only maintained during debug)
_paths : array	Array of loaded language file paths
_strings : array	Associative array of translations
_used : array	Array of used strings (only maintained during debug)

Constructors

__construct( lang : string=null ) : JLanguage

Builds a new JLanguage object. Loads the specified language; if `lang` is not specified the default language, `en-GB`, will be loaded.
Parameters	[lang]	Language to load

Methods

exists( lang : string, basePath : string=JPATH_BASE ) : boolean

Checks if a language exists in the default language folder. `basePath` is one level above where the languages reside.
Parameters	lang	Language to look for
	[basePath]	Basis for building language path
Returns	`true` if the language exists

get( property : string, default : mixed=null ) : mixed

Gets metadata about the language. Common properties include `name` and `tag`.
Parameters	property	Property to retrieve
	[default]	Default if the property is not set
Returns	Value of the property

getBackwardLang( ) : string

Gets the backward-compatible language name. Used for legacy support.
Returns	Backward-compatible language name

getDebug( ) : boolean

Checks if the language object is in debug mode.
Returns	`true` if the language object is in debug mode

getDefault( ) : string

Gets the default language.
Returns	Default language

&getInstance( lang : string ) : JLanguage

Gets a global instance of JLanguage. If an instance for the specified `lang` does not exist, it will be created.
Parameters	lang	Language to load
Returns	A global instance of JLanguage

getKnownLanguages( basePath : string=JPATH_BASE ) : array

Gets a two-dimensional associative array of all the known languages. The array contains keys named the same as the languages, which contain associative arrays of the corresponding language metadata.
Parameters	[basePath]	Path on which to look for the languages folder
Returns	Two-dimensional associative array languages and metadata

getLanguagePath( basePath : string=JPATH_BASE, language : string=null ) : string

Gets the path to a language. If `language` is not specified, the path will point to all languages.
Parameters	[basePath]	Basis for building language path
	[language]	Language name
Returns	Path to a language, or all languages

getLocale( ) : array

Gets an array of the language locales, for example `en-GB`, `en`, `english`.
Returns	Array of the different language locales

getMetaData( lang : string ) : array

Returns an associative array containing the metadata about the specified language.
Parameters	lang	Language to get metadata for
Returns	Associative array of metadata; returns null on failure

getName( ) : string

Gets the name of the language.
Returns	Language Name

getOrphans( ) : array

Gets the orphan strings. This is an array of strings that could not be translated. This information is only collated if the language object is in debug mode.
Returns	Array of orphan (not translated) strings

getPaths( extension : string=null ) : array

Gets an array of loaded language file paths. If `extension` is defined, only information about language files that are specific to that extension will be returned.
Parameters	[extension]	Name of the extension
Returns	Array of loaded language file paths

getPdfFontName( ) : string

Gets the PDF font name.
Returns	PDF font name

getTag( ) : string

Gets the language tag, for example `en-GB`.
Returns	Language tag

getUsed( ) : array

Gets an array of strings that were successfully translated.
Returns	Array of successfully translated strings

getWinCP( ) : string

Gets the Windows Code Page name.
Returns	Windows Code Page name

hasKey( key : string ) : boolean

Checks if a translation exists.
Parameters	key	Translation to look for
Returns	`true` if translation exists

isRTL( ) : boolean

Checks if the language is written right-to-left.
Returns	`true` if Language is written right-to-left

load( extension : string=‘joomla’, basePath : string=JPATH_BASE ) : boolean

Loads a language file. `extension` is used to identify the extension for which we are loading the language file, this determines where the file is located. `basePath` is one level above where the languages reside. If a language fails to load, normally because the file does not exist, or is inaccessible, the equivalent default language will be loaded. Note that the new translations are merged with previously loaded translations.
Parameters	[extension]	Name of the extension
	[basePath]	Basis for building language path
Returns	`true` on success

setDebug( debug : boolean ) : boolean

Turns debug on or off.
Parameters	debug	Turn debug on or off
Returns	Previous debug value

setDefault( lang : string ) : string

Sets the default language.
Parameters	lang	Default language
Returns	Previous default language value

setLanguage( lang : string ) : string

Sets the language and loads the metadata. This does not load the translations; use the `load()` method to load the translations.
Parameters	lang	Language identifier
Returns	Returns previous language

_( string : string, jsSafe : boolean=false ) : string

Attempts to translate `string`. `jsSafe`, if `true`, will add slashes to the translated string. If a translation cannot be found the original string will be returned. If debug is enabled, translated strings will be encapsulated by bullet characters, strings translated from a constant will be encapsulated in double exclamation marks, and strings that are not translated will be encapsulated in double question marks.
Parameters	string	String to translate
	[jsSafe]	Add slashes to translated string
Returns	Translated string

_load( filename : string, extension : string=‘unknown’ ) : mixed

Loads a language file and returns an associative array of translations.
Parameters	filename	Language path and filename to load
	[extension]	Name of the extension
Returns	Associative array of translations; `false` on failure

_getCallerInfo( ) : array

Gets back-trace information that can be used to determine where a method call originated.
Returns	Back-trace information

_parseLanguageFiles( dir : string=null ) : array

Gets a two-dimensional associative array of all the languages in the path specified by `dir`. The returned associative array contains keys named the same as the languages, which contain associative arrays of the corresponding metadata.
Parameters	[dir]	Path to look for languages in
Returns	Two-dimensional associative array of languages and metadata

_parseXMLLanguageFile( path : string ) : array

Parses an individual XML language information file and returns an array of metadata.
Parameters	path	Path to XML language information file
Returns	Associative array of metadata

_parseXMLLanguageFiles( dir : string=null ) : array

Gets a two-dimensional associative array of all the XML language information files in `dir`. The array contains keys named the same as the languages, which contain arrays of metadata. Normally there will only be one XML language information file per language.
Parameters	[dir]	Path to XML language information files
Returns	Two-dimensional associative array of languages and metadata

JLanguageHelper

static

Performs language functions that are not specific to an individual language

Methods

static detectLanguage( ) : string

Attempts to detect the language using the HTTP headers. If unable to detect, assumes `en-GB`.
Returns	Detected language

static createLanguageList( actualLanguage : string, basePath : string=JPATH_BASE, caching : boolean=true ) : array

Gets an array of language options. Each element is an associative array with three keys, `name`, `value`, and `selected`. This can be used to build a selection list of languages.
Parameters	actualLanguage	Current language
	[basePath]	Path in which to find known languages
	[caching]	Use cached response
Returns	Two-dimensional array of language options

JText

static

Translates strings to the correct language using the JLanguage class.

Methods

static printf( string : string ) : int

Works like the PHP `printf()` function, except that `string` is translated. This method accepts a variable number of parameters. The additional arguments will not be translated. The result is outputted, and the method returns the length of the outputted string. If no additional parameters are specified, a null string will be returned. Refer to the PHP manual for more information: http://php.net/manual/function.printf.php.
Parameters	string	String to translate
	(extra arguments)	Multiple arguments to insert into `string`
Returns	Length of translated string

static sprintf( string : string ) : string

Works like the PHP `sprintf()` function, except that `string` is translated. This method accepts a variable number of parameters. The additional parameters will not be translated. If no additional parameters are specified, a null string will be returned. Refer to the PHP manual for more information: http://php.net/manual/function.sprintf.php.
Parameters	string	String to translate
	(extra arguments)	Multiple arguments to insert into `string`
Returns	Translated string

static _( string : string, jsSafe : boolean=false ) : string

Attempts to translate `string`. `jsSafe`, if `true`, will add slashes to the translated string. See the JLanguage `_()` method for more information.
Parameters	string	String to translate
	[jsSafe]	Add slashes
Returns	Translated string

JElement

abstract, extends JObject

This class is used to aid integration of extensions into Joomla!. A core use of this class enables the selection of bespoke parameters options when creating new menu items. The class is used in conjunction with an XML definition of an element, and used extensively by the JParameter class. For more information about JElement refer to the Parameters (Core JElements) section in this Appendix.

Properties

_name : string	Element name
_parent : object	Parent object that created the instance

Constructors

__construct( parent : object=null ) : JElement

Builds a new JElement object and sets the parent object.
Parameters	[parent]	Parent object

Methods

fetchElement( name : string, value : string, &xmlElement : JSimpleXMLElement, control_name : string ) : string

Gets the rendered element. This method must be overridden in subclasses. For example, the output could be: <input type="text" name="controlName[name]" id="controlNamename" value="value" class="text_area" size="20" />
Parameters	name	Name and ID suffix
	value	Value
	xmlElement	JSimpleXMLElement element definition
	control_name	Name and ID prefix
Returns	Rendered element

fetchTooltip( label : string, description : string, &xmlElement : JSimpleXMLElement, control_name : string=”, name : string=” ) : string

Gets a tooltip, encapsulated in HTML label tags.
Parameters	label	Content and title
	description	Title suffix
	xmlElement	JSimpleXMLElement element definition
	[control_name]	ID prefix
	[name]	ID suffix
Returns	HTML tooltip

getName( ) : string

Gets the name of the element.
Returns	Element name

render( &xmlElement : JSimpleXMLElement, value : string, control_name : string=‘params’ ) : array

Gets an array containing the rendered parts and attributes of the element. The array contains six items in order, tooltip `[0]`, rendered input element `[1]`, description `[2]`, label `[3]`, value `[4]`, and name `[5]`.
Parameters	xmlElement	JSimpleXMLElement element definition
	value	Element value
	[control_name]	Name of the control
Returns	An array containing rendered parts and attributes of the element

JParameter

extends JRegistry

Handles INI string parameters. This class is used in conjunction with JElement subclasses and XML files that define the nature of parameters. INI strings are used in database tables for values that do not have a specific field. An instance of the class can be used to handle multiple INI strings (with different XML definitions), using groups to separate each one. When dealing with one INI string, omitting the group will always use the default group, '_default'. For more information about JParameter refer to the Parameters (Core JElements) section in this Appendix.

Properties

_elementPath : array	Array of paths in which to find JElement subclasses (not restricted to groups)
_elements : array	Associative array of JElement objects (not restricted to groups)
_raw : string	INI string
_xml : array	Associative array of JSimpleXMLElement objects that define parameters (one object per group)

Constructors

__construct( data : string, path : string=” ) : JParameter

Builds a new JParameter object and loads `data` and, if specified, the XML file.
Parameters	data	INI string
	[path]	Path to XML file

Methods

addElemenrPath( path : mixed ) : void

Adds a path, or array of paths, to search for JElement subclass files.
Parameters	path	Path or array of paths

bind( data : mixed, group : string=’ _default’ ) : boolean

Binds data with parameters in the specified group. `data` can be an associative array, an object, or an INI string.
Parameters	data	Data to bind
	[group]	Parameter group
Returns	`true` on success

def( key : string, value : string=”, group : string= ‘_default’ ) : string

If the parameter is not defined, sets the value of the parameter in the specified group.
Parameters	key	Parameter to get
	[value]	Value if not defined
	[group]	Parameter group
Returns	Up-to-date value of the parameter

get( key : string, default : string=”, group : string=‘_default’ ) : string

Gets the value of a parameter in the specified group. Returns the default value if the parameter is not set.
Parameters	key	Parameter to retrieve
	[default]	Default value to return
	[group]	Parameter group
Returns	Value of the parameter

getGroups( ) : mixed

Gets an associative array of the group names and the number of parameters in each, defined by the corresponding JSimpleXMLElement object. Groups that do not have a JSimpleXMLElement object will not be included.
Returns	Associative array of group names and number of parameters in each. Returns `false` if no XML has been successfully loaded.

getNumParams( group : string=’ _default’ ) : mixed

Gets the number of parameters defined by the associated JSimpleXMLElement object, in the specified `group`.
Parameters	[group]	Parameter group
Returns	Number of parameters; `false` if no JSimpleXMLElement object exists

getParam( &node : JSimpleXMLElement, control_name : string=‘params’, group : string=’ _default’ ) : mixed

Gets an array of parameter details from a group. The array contains six items in order: tooltip `[0]`, HTML rendered string `[1]`, description `[2]`, label `[3]`, value `[4]`, and name `[5]`.
Parameters	Node	JSimpleXMLElement parameter to render
	[control_name]	Input names
	[group]	Parameter group
Returns	Array of parameter details from a group

getParams( name : string=‘params’, group : string=’ _default’ ) : mixed

Gets a two-dimensional array of all the parameters in a group. The inner arrays contain six items in order: tooltip `[0]`, HTML rendered string `[1]`, description `[2]`, label `[3]`, value `[4]`, and name `[5]`.
Parameters	[name]	Input names and ID prefix
	[group]	Parameter group
Returns	Two-dimensional array of all the parameters in a group; `false` on failure

&loadElement( type : string, new : boolean=false ) : mixed

Gets an instance of a JElement subclass object based on `type`. If an instance of the specified type does not exist, it will be created. If `new` is `true`, a new instance will be created even if there is an existing instance. JElements subclass objects are not restricted to groups.
Parameters	path	Path to XML file
	[new]	Force create new instance
Returns	Instance of a JElement object; `false` on failure

loadSetupFile( path : string ) : boolean

Builds a JSimpleXMLElement object from an XML file. The XML file can include the group name; if it does not, the group `'_default'` will be assumed.
Parameters	path	Path to XML file
Returns	`true` on success

render( name : string=‘params’, group : string=’ _default’ ) : mixed

Renders a group within the parameters and returns an HTML string.
Parameters	[name]	Input names and ID prefix
	[group]	Parameter group
Returns	HTML rendered string; `false` on failure

renderToArray( name : string=‘params’, group : string=’ _default’ ) : mixed

Renders a group within the parameters and returns an array of HTML strings.
Parameters	[name]	Input names and ID prefix
	[group]	Parameter group
Returns	Array of HTML rendered parameters; `false` on failure

set( key : string, value : string=”, group : string=‘_default’ ) : string

Sets the value of a parameter in the specified group.
Parameters	key	Parameter to set
	[value]	New value
	[group]	Parameter group
Returns	Previous value of the parameter

setXML( &xml : JSimpleXMLElement ) : void

Sets an XML definition; the group is extracted from the group attribute of the object.
Parameters	[xml]	JSimpleXMLElement object to add

JCache

abstract, extends JObject

Handles caching. Several subclasses exist for caching different items; subclasses are sometimes referred to as JCache types. JCache uses JCacheStorage subclass objects to store and retrieve cache data.

Properties

_handler : JCacheStorage	Storage handler
_options : array	Cache handling options

Constructors

__construct( options : array ) : JCache

Builds a new JCache object. The `options` associative array can contain the keys `language`, `cachebase`, `defaultgroup`, `caching`, and `storage` .`language` is used to create separate caches for different languages. `cachebase` is used as the path to the base cache folder. `defaultgroup` is the group name used when no group is specified in other methods. `caching` is a Boolean value; if `true` caching is enabled. Cached data is identified by an ID and a group. The way the cache is stored differs, depending on the chosen storage handler. `storage` is a string that defines the default storage handler type.
Parameters	options	Associative array of options

Methods

clean( group : string=null, mode : string=‘group’ ) : boolean

Removes all cached items in `group`. If `mode` is `'group'`, removes all cached data in `group`, if mode is `'notgroup'`, removes all cached data in other groups.
Parameters	[group]	Selected group
	[mode]	Cleaning mode
Returns	`true` on success

gc( ) : boolean

Removes any redundant cached data (data that has expired).
Returns	`true` on success

get( id : string, group : string=null ) : mixed

Gets cached data. Cached data is identified by an ID and a group. Returns `false` if no cached data is available.
Parameters	id	Cached data ID
	[group]	Cached data group
Returns	Cached data; `false` if no cached data is found

static &getInstance( type : string=‘output’, options : array=array() ) : JCache

Gets a new instance of a JCache subclass object based on `type`. `options` is passed to the constructor.
Parameters	[type]	JRegistry instance identifier
	[options]	Options to pass to the constructor
Returns	A new instance of a JCache derived object

static getStores( ) : array

Gets an array of storage handler names that will operate correctly in the current environment.
Returns	Array of storage handler names

remove( id : string, group : string=null ) : boolean

Removes cached data, identified by `id` and `group`.
Parameters	id	Cached data ID
	[group]	Cached data group
Returns	`true` if the data is removed

setCacheValidation( ) : void

Deprecated; this method no longer performs any action, and there is no replacement function or method.

setCaching( enabled : boolean ) : void

Enables and disables caching.
Parameters	enabled	Turn caching on or off

setLifeTime( lt : int ) : void

Sets the maximum lifetime of cached items in seconds.
Parameters	lt	Lifetime of cached items in seconds

store( data : string, id : string, group : string=null ) : boolean

Adds data to the cache, identified by `id` and `group`.
Parameters	data	Data to chache
	id	Cached data ID
	[group]	Cached data group
Returns	`true` if the item is stored

&_getStorageHandler( ) : JCacheStorage

Gets the cache storage handler. If the handler does not exist it will be created.
Returns	Cache storage object

JMail

extends PHPMailer

Sends emails.

Constructors

JMail( ) : JMail

Builds a new JMail object.

Methods

addAtachment( attachment : mixed ) : void

Adds one attachment if `attachment` is a string (filename). Adds multiple attachments if `attachment` is an array (filenames).
Parameters	attachment	Attachment file path or array of attachment file paths

addBCC( bcc : mixed ) : void

Adds one blind carbon copy recipient if `bcc` is a string. Adds multiple blind carbon copy recipients if `bcc` is an array.
Parameters	bcc	Email address string or array of email addresses

addCC( cc : mixed ) : void

Adds one carbon copy recipient if `cc` is a string. Adds multiple carbon copy recipients if `cc` is an array.
Parameters	cc	Email address string or array of email addresses

addRecipient( recipient : mixed ) : void

Adds one recipient if `recipient` is a string. Adds multiple recipients if `recipient` is an array.
Parameters	recipient	Email address string or array of email addresses

addReplyTo( replyto : array ) : void

Sets the reply-to email address and name. `replyto` can be an array of two elements `array('email@address', 'name')` or an array of arrays in this format.
Parameters	from	Email address array

static &getInstance( id : string=‘Joomla’ ) : JMail

Gets a reference to a global instance of a JMail object. If the object does not exist it will be created. `id` identifies the JMail object to return.
Parameters	[id]	JMail ID
Returns	Reference to a global JMail object

&Send( ) : mixed

Sends the email.
Returns	`true` on success, error on failure

setBody( content : string ) : void

Sets the email body.
Parameters	content	Email body

setSender( from : mixed ) : void

Sets the sender’s email address and name. `from` can either be an array of two elements—`array('email@address', 'name')`—or a string consisting of one email address
Parameters	from	Email address string or array of email address and email name

setSubject( subject : string ) : void

Sets the email subject line.
Parameters	subject	Email subject line

useSendmail( sendmail : string=null ) : boolean

If `sendmail` is specified, sets the object to use the sendmail path. If `sendmail` is not specified, sets the object to use the PHP `mail()` function.
Parameters	[sendmail]	Path to sendmail
Returns	`true` if sendmail is enabled

useSMTP( auth : boolean=null, host : string=null, user : string=null, pass : string=null ) : boolean

If all parameters are specified, sets the object to use SMTP. If any of the parameters are not specified, sets the object to use the PHP `mail()` function.
Parameters	[auth]	Use SMTP authorization
	[host]	SMTP host
	[user]	Username
	[pass]	Password
Returns	`true` if SMTP is enabled

JMailHelper

static

Performs mail functions that are not specific to an individual JMail object.

Methods

static cleanAddress( address : string ) : mixed

Determines if an email address is clean. An unclean email address may include spaces, semicolons, and commas.
Parameters	address	Address to clean
Returns	Email address or `false` if the address is deemed to be unclean

static cleanBody( body : string ) : string

Cleans a multi-line string for use in an email body. Removes unsafe characters and potentially confusing MIME header strings.
Parameters	body	String to clean
Returns	Cleaned string

static cleanLine( value : string ) : string

Cleans a line for use in an email. Removes unsafe characters.
Parameters	value	String to clean
Returns	Cleaned string

static cleanSubject( subject : string ) : string

Cleans an email subject line. Removes unsafe characters and potentially confusing MIME header strings.
Parameters	subject	String to clean
Returns	Cleaned string

static cleanText( value : string) : string

Cleans a multi-line string for use in an email. Removes unsafe characters and potentially confusing MIME header strings.
Parameters	value	String to clean
Returns	Cleaned string

static isEmailAddress( email : string ) : boolean

Checks if `email` is a valid email address.
Parameters	email	Email to validate
Returns	`true` if `email` is in a valid format

JFactory

static

Joomla! static factory class for accessing global objects and building new objects.

Methods

static &getACL( ) : JAuthorization

Gets the global authorization object. If the authorization object does not exist it will be created.
Returns	Global authorization object

static &getCache( group : string=”, handler : string=‘callback’, storage : string=null ) : JCache

Gets the global cache object. If the cache object does not exist it will be created. `group` is the group to which the cache belongs. `handler` is the handler to use; this can be `callback`, `output`, `page`, or `view`. `storage` is the storage mechanism to use; this can be `apc`, `eaccelerator`, `file`, `memcache`, or `xcache`. In most instances, it will not be necessary to define `handler` or `storage`.
Parameters	[group]	Cache group
	[handler]	Handler type
	[storage]	Storage type
Returns	Global cache object

static &getConfig( file : string=null, type : string=‘PHP’ ) : JRegistry

Gets the global configuration object. If the object does not exist, it will be created. `file` is the path, including the name, of the configuration file. `type` is the format of configuration file; this currently has no effect. The parameters need only be specified the first time this method is run.
Parameters	file	Path and name of the configuration file
	[type]	Type of configuration file
Returns	Global configuration object

static &getDBO( ) : JDatabase

Gets the global database object. If the database object does not exist it will be created.
Returns	Global database object

static &getDocument( ) : JDocument

Gets the global document object. If the document object does not exist it will be created.
Returns	Global document object

static &getEditor( editor : string=null ) : JEditor

Gets a new instance of the specified editor. If `editor` is not specified, the default editor will be used.
Parameters	[editor]	Type of editor
Returns	A new editor object

static &getLanguage( ) : JLanguage

Gets the global language object. If the language object does not exist it will be created.
Returns	Global language object

static &getMailer( ) : JMail

Gets the global mail object loaded with the site mail settings. If the mail object does not exist it will be created.
Returns	Global mail object

static &getSession( options : array=array() ) : JSession

Gets the global session object. If the session does not exist it will be created. The `options` associative array is the options to pass on to the session storage handler; this only needs to be specified the first time the method is executed.
Parameters	[options]	Options to pass to the session storage handler
Returns	Global session object

static &getTemaplate( ) : JTemplate

Gets the global template object. If the template object does not exist it will be created.
Returns	Global template object

static &getURI( uri : string=‘SERVER’ ) : JURI

Gets a global instance of the specified JURI object. If `uri` is not specified, the requested URI will be used.
Parameters	[uri]	URI
Returns	A global JURI object.

static &getUser( ) : JUser

Gets the current user object.
Returns	Global user object

static &getXMLParser( type : string=‘DOM’, options : array=array() ) : object

Creates a new XML Parser object. Supported types are `RSS`, `Atom`, `Simple`, and `DOM`; if an unrecognized type is provided, a `DOM` XML parser will be created. The `options` associative array can contain the key `rssUrl` if the type is `Atom` or `RSS`. The `options` associative array can contain the key `lite` if the type is `DOM`. The XML parser classes include SimplePie, JSimpleXML, DOMIT_Document, and DOMIT_Lite_Document.
Parameters	[type]	Type of Parser
	[options]	Parser options
Returns	A new XML parser object

static &_createACL( ) : JAuthorization

Creates the global authorization object.
Returns	New global authorization object

static &_createConfig( file : string, type : string=‘PHP’ ) : JRegistry

Creates the global configuration object. `file` is the path to the configuration file. `type` is the format of the configuration file.
Parameters	file	Path to the configuration file
	[type]	Type of configuration file
Returns	New global configuration object

static &_createDBO( ) : JDatabase

Creates the database object.
Returns	New global database object

static &_createDocument( ) : JDocument

Creates the global document object. The document type is determined by the value of the `format` request. If no format is included, HTML is assumed.
Returns	New global document object

static &_createLanguage( ) : JLanguage

Creates the language object.
Returns	New global language object

static &_createMailer( ) : JMail

Creates the global mail object.
Returns	New global mail object

static &_createSession( options : array=array() ) : JSession

Creates the global session object. If the session has expired, it will be restarted.
Parameters	[options]	Session storage handler options
Returns	New global session object

static &_createTemplate( ) : JTemplate

Creates the template object.
Returns	New global template object

JRegistry

extends JObject

Handles configuration details in a hierarchy using namespaces.

Properties

_defaultNameSpace : string	Namespace to use by default
_registry : array	Registry data

Constructors

__construct( namespace : string=‘default’ ) : JRegistry

Builds a new JRegistry object and adds the namespace, setting it as the default.
Parameters	[namespace]	Default namespace

Methods

static &getInstance( id : string, namespace : string=‘default’ ) : JRegistry

Gets a global instance of JRegistry, identified by `id`. If the instance does not exist it will be created.
Parameters	id	JRegistry instance ID
	[namespace]	Default namespace, only used if the instance does not exist
Returns	A global instance of JRegistry

getNameSpaces( ) : array

Gets the names of all the namespaces in the registry.
Returns	Array of namespace names

getValue( regpath : string, default : mixed=null ) : mixed

Gets a value from the registry. `regpath` can include multiple levels separated by periods. If the path includes no periods, the value will be retrieved from the default namespace. If the value is not set, the default value will be returned.
Parameters	regpath	Path to value
	[default]	Default value
Returns	Value of the item identified by `regpath`

loadArray( array : array, namespace : string=null ) : boolean

Loads an associative array into the registry namespace. The `array` keys must not contain periods. If the namespace is not specified, the default namespace will be used.
Parameters	array	Associative array to load
	[namespace]	The namespace to load the array into
Returns	`true`

loadFile( file : string, format : string=‘INI’, namespace : string=null ) : boolean

Loads a configuration file into the registry namespace. The file parameter keys must not contain periods. Possible formats are `INI`, `PHP`, and `XML`. If the namespace is not specified, the default namespace will be used.
Parameters	file	File path
	[format]	File format
	[namespace]	Namespace to load the file into
Returns	`true`

loadINI( data : string, namespace : string=null ) : boolean

Loads an INI string into the registry namespace. The INI parameter keys must not contain periods. If the namespace is not specified, the default namespace will be used.
Parameters	data	INI string
	[namespace]	The namespace to load the INI into
Returns	`true`

loadObject( &object : object, namespace : string=null ) : boolean

Loads public properties of an object into the registry namespace. If the namespace is not specified, the default namespace will be used.
Parameters	object	Object to load
	[namespace]	The namespace to load the object into
Returns	`true`

loadXML( data : string, namespace : string=null ) : boolean

Loads an XML string into the registry namespace. The XML parameter keys must not contain periods. If the namespace is not specified, the default namespace will be used.
Parameters	data	XML string
	[namespace]	Namespace to load the XML into
Returns	`true`

makeNameSpace( namespace : string ) : boolean

Creates a new namespace in the registry. If the namespace already exists, it will be overwritten.
Parameters	namespace	Namespace to create
Returns	`true`

merge( &source : JRegistry ) : boolean

Merges the registry data with `source` registry data. The source values take precedence over existing values.
Parameters	source	JRegistry to merge from
Returns	`true` on success

setValue( regpath : string, value : mixed ) : mixed

Sets a value in the registry. The `regpath` can include multiple levels separated by periods. If the path includes no periods, the value will be set in the default namespace. If the `regpath` does not exist, it will be created.
Parameters	regpath	Path to value
	value	Value
Returns	Previous value

toArray( namespace : string=null ) : array

Gets an associative array representation of the registry namespace. If `namespace` is not specified, the default namespace will be used.
Parameters	namespace	The namespace to get
Returns	Array representation of the registry

toObject( namespace : string=null ) : array

Gets an object (stdClass) representation of the registry namespace. If `namespace` is not specified, the default namespace will be used.
Parameters	[namespace]	The namespace to load the array into
Returns	Object representation of the registry

toString( format : string=‘INI’, namespace : string=null, params : mixed) : string

Gets a string representation of the registry namespace in the specified format. Possible formats are `INI`, `PHP`, and `XML`. If the namespace is not specified, the default namespace will be used. `params` is passed to the format handler `objectToString()` method; use of `params` depends upon `format`. Some format handlers are restricted to a maximum depth.
Parameters	[format]	Registry format handler name
	[namespace]	The namespace to get
	[params]	Options to pass to the format handler
Returns	String representation of the registry

JSession

extends JObject

Handles a user session and stores session data in namespaces. For more information about sessions refer to Chapter 7.

Properties

_expire : int	Length of inactive time before session expires.
_security : array	Security session validation options. Can include the keys `fix_browser` and `fix_adress` (note that `fix_adress` is not a typo).
_state : string	State of the session (`active`, `expired`, `destroyed`, or `error`)
_store : JSessionStorage	Session storage handler

Constructors

__construct( store : string=‘none’, options : array=array() ) : JSession

Builds a new JSession object. `store` is the storage handler type, normally `database`.
Parameters	[store]	Storage handler type
	[options]	Options to pass to the storage handler

Methods

clear( name : string, namespace : string=‘default’ ) : mixed

Removes a value from the session.
Parameters	name	Name of value to remove
	[namespace]	Namespace to remove the value from
Returns	Cleared value

close( ) : void

Closes the session gracefully.

destroy( ) : boolean

Resets the session removing any existing session data. This does not remove the session cookie or session `id`. Equivalent to the PHP `session_destroy()` function.
Returns	`true`

fork( ) : boolean

Creates a new session, and copies the exiting session data to the new session.
Returns	`true`

&get( name : string, default : mixed=‘null’, namespace : string=‘default’ ) : mixed

Gets a value from the session. If the value is not set, `default` is returned.
Parameters	name	Name of the value to retrieve
	[default]	Default value
	[namespace]	Namespace to retrieve the value from
Returns	Value from the session

getExpire( ) : int

Gets the number of inactive minutes to wait before the session expires.
Returns	Session lifetime in minutes

getId( ) : string

Gets the ID of the session. Returns null if the session has been destroyed.
Returns	Session ID

static &getInstance( handler : string, options : array ) : JSession

Gets the global instance of JSession. If it doesn’t already exist it will be created.
Parameters	handler	Storage handler type
	options	Options to pass to the storage handler
Returns	Global session object

getName( ) : string

Gets the name of the session. Returns null if the session has been destroyed.
Returns	Session name

getState( ) : string

Gets the state of the session (`active`, `expired`, `destroyed`, or `error`).
Returns	State of the session

getStores( ) : array

Gets the names of session storage handlers that work in the current environment.
Returns	Array of session storage handler names

getToken( forceNew : boolean=false ) : string

Gets the session token. The token is a random alphanumeric string that can be used to increase security of requests.
Parameters	[forceNew]	Create a new token
Returns	Token string

has( name : string, namespace : string=‘default’ ) : boolean

Checks if a value is set in the session.
Parameters	name	Name of value to check
	[namespace]	Namespace to check the value in
Returns	`true` if the value is set in the session

hasToken( tCheck : string, forceExpire : boolean=true ) : boolean

Compares the session token with `tCheck`. If the tokens do not match and `forceExpire` is `true`, the session will be expired.
Parameters	tCheck	Token to check session against
	forceExpire	Expire session if invalid token
Returns	`true` if tokens match

isNew( ) : boolean

Dtermines if the session was created during this request.
Returns	`true` if the session was created during this request

restart( ) : boolean

Restarts the session. This will remove any existing session data.
Returns	`true`

set( name : string, value : mixed, namespace : string=‘default’ ) : mixed

Sets a value in the session.
Parameters	name	Name of value to set
	value	Value
	[namespace]	Namespace to set the value in
Returns	Previous value

_createId( ) : string

Creates a new session ID.
Returns	A new session ID

_createToken( ) : string

Creates a new token.
Returns	New token string

_setCounter( ) : boolean

Increments the session counter. Must only be invoked once per request.
Returns	`true`

_setOptions( &options : array ) : boolean

Sets session options. The `options` associative array can include the keys `name`, `id`, `expire`, and `security`.
Parameters	options	Session options
Returns	`true`

_setTimers( ) : boolean

Sets the session timers. Includes the session start time, the last request time, and the current request time.
Returns	`true`

_start( ) : boolean

Starts the session. Continues a previous session or creates a new session. Equivalent to the PHP `session_start()` function.
Returns	`true`

_validate( restart : boolean=false ) : boolean

Validates the session. If the session has exceeded the maximum expiry time, the session state will be changed to `expired`. Checks the client address and client browser match the security array, if they are defined in the security array.
Parameters	[restart]	Restart the session if the session state is not active
Returns	`true` if the session is valid

JRoute

static, extends JObject

Handles internal URIs.

Methods

static _( url : string, xhtml : boolean=true, ssl : int=0 ) : string

Converts a URI into a Search Engine-Friendly (SEF) URI. This method should be used for all internal URIs. No processing will be performed if we are in the administrative area. `xhtml` determines if ampersands should be encoded as HTML special character `&`.
Parameters	url	URI to convert
	xhtml	Make URI XHTML standard
	ssl	URI is SSL
Returns	Converted URI

JMenu

extends JObject

Handles menus and menu items.

Properties

_active : int	ID of the current menu item
_default : int	ID of the default homepage menu item
_items : array	Array of menu items (stdClass objects)

Constructors

__construct( ) : JMenu

Builds a new JMenu object and loads all of the published menu items for every menu.

Methods

authorize( id : int, accessid : int=0 ) : boolean

Checks the user group has rights to view the menu item.
Parameters	id	Menu item ID
	[accessed]	Legacy group ID
Returns	`true` if authorized to view the menu item

&getActive( ) : boolean

Gets the current menu item. Gets the default menu item if the current item is not set.
Returns	Active menu item; returns null on failure

&getDefault( ) : object

Gets the default menu item (homepage).
Returns	Default menu item object

static &getInstance( ) : JMenu

Gets the global instance of JMenu, creating it if it does not exist.
Returns	Global instance of JMenu

&getItem( id : int ) : object

Gets a menu item based on `id`. If the menu item does not exist, returns null.
Parameters	id	Menu item ID
Returns	Menu item object

getItems( attribute : string, value : string, firstonly : boolean=false) : mixed

Gets an active menu item or an array of menu items. Returned active menu item attributes must match the specified `attribute` and `value`. If `firstonly` is `true`, only gets the first matching menu item.
Parameters	attribute	Attribute to check
	value	Value to check attribute against
	[firstonly]	Only get the first matching menu item
Returns	A menu item or an array of menu items

getMenu( ) : JParameter

Gets a copy of all the menu items.
Returns	Array of menu items

&getParams( id : int ) : JParameter

Gets the parameters of the specified menu item. If the menu item does not exist, or is not published, returns an empty JParameter object.
Parameters	id	Menu item ID
Returns	JParameter object populated with the parameters from the specified menu item

&setActive( id : int ) : boolean

Sets the active menu item.
Parameters	id	Menu item ID
Returns	`true` on success

setDefault( id : int ) : boolean

Sets the default menu item (homepage).
Returns	`true` on success

_load( ) : mixed

Loads published menu items from the `#__menu` table and returns them as an array of stdClass objects in published order. This method uses caching; if changes are made to the `#__menu` table records after this method has been called once, the changes will not be reflected if the method is used a second time.
Returns	Array of published menu items; `false` on failure

JPathway

extends JObject

Handles breadcrumbs. This class is used to model the breadcrumb trail, which is used in most templates as a way of describing a user’s current position within a Joomla! site. For more information about the breadcrumb trail refer to Chapter 9.

Properties

_count : int	Number of breadcrumbs
_pathway : array	Array of breadcrumbs

Methods

addItem( name : string, link : string=” ) : boolean

Adds a breadcrumb to the end of the trail.
Parameters	name	Name of breadcrumb
	[link]	Breadcrumb URI
Returns	`true` on success

getPathWay( ) : array

Gets an array of the breadcrumbs. Breadcrumbs are represented as stdClass objects with two properties, `name` and `link`.
Returns	Array of breadcrumbs in order of display

getPathWayNames( ) : array

Gets an array of breadcrumb names.
Returns	Array of breadcrumb names in order

setItemName( id : int, name : string ) : boolean

Sets the name of a breadcrumb. `id` refers to the breadcrumb number; breadcrumbs are numbered from zero.
Parameters	id	Breadcrumb number
	name	Breadcrumb name
Returns	`true` on success

_makeItem( name : string, link : string ) : object

Builds a new menu item and returns it.
Parameters	name	Name of new breadcrumb
	link	Breadcrumb URI
Returns	New breadcrumb object (stdClass)

JDatabase

abstract, extends JObject

Handles a database connection. There are two core subclasses (sometimes called drivers or adapters), JDatabaseMySQL and JDatabaseMySQLi. Additional subclasses, enabling support of other database servers, are intended to be added later. For more information about JDatabase refer to Chapter 3.

Properties

_cursor : mixed	Result of last `mysql_query()` call
_debug : int	Debug mode; 0 = disabled, 1 = enabled
_errorMsg : string	Error message from last query
_errorNum : int	Error number from last query
_hasQuoted : boolean	There are specific fieldnames to be quoted
_limit : int	Maximum number of records to return from a query
_log : array	Query history (only maintained if debug is enabled)
_nameQuote : string	Named SQL element quotes (tables, fields, databases)
_nullDate : string	Null date string
_offset : int	Record offset
_quoted : array	Array of values that should be quoted
_resource : mixed	Database resource
_sql : string	Current query
_table_prefix : string	Database table prefix, normally `'jos_'`
_ticker : int	Number of queries executed (only maintained if debug is enabled)
_utf : boolean	Supports UTF-8
name : string	Database driver name

Constructors

__construct( options: array ) : JDatabase

Builds a new JDatabase object and prepares the internal properties. Subclasses also connect to the specified database. `options` normally includes the keys: `host`, `user`, `password`, `database`, `prefix`, and `select`.
Parameters	options	Database options

Destructors

__destruct( ) : boolean

Runs when the object is destroyed. Ensures the database connection is closed cleanly.
Returns	`true` on success

Methods

addQuoted( quoted : mixed ) : void

Adds a new value that should always be encapsulated in quotes. `quoted` can be a string or an array of strings.
Parameters	quoted	String or array of values to quote

BeginTrans( ) : void

Emulates ADOdb functionality.

This method must be overridden in subclasses. If you intend to use this, please ensure the database driver supports it.

CommitTrans( ) : string

Emulates ADOdb functionality.

This method must be overridden in subclasses. If you intend to use this, please ensure the database driver supports it.

connected( ) : boolean

Determines if the database connection is alive.
Returns	`true` if currently connected to the database

debug( debug : int ) : void

Sets debug mode; `0` = disabled, `1` = enabled.
Parameters	debug	Debug mode

ErrorMsg( ) : string

Emulates ADOdb functionality .

Gets the error message from the last query. If no error was encountered, the error message will be an empty string.

Returns

Error message from the last query

ErrorNo( ) : int

Emulates ADOdb functionality.

Error number from the last query. If no error was encountered, the error number will be zero.

Returns

Error number from the last query

Execute( query : string ) : mixed

Emulates ADOdb functionality.

Executes query. If the query is a SELECT query, the results will be returned in a JRecordSet object. If the query is not a SELECT query, an empty JRecordSet will be returned on success. If the query fails, false will be returned.

Parameters

query

Query to execute.

Returns

JRecordSet object; false on failure

explain( ) : string

Explains the current query.
Returns	XHTML string describing the active query.

GenID( foo1 : string=null, foo2 : int=null ) : mixed

Emulates ADOdb functionality. Gets a sequence ID for databases that are sequence aware (sequences are used with databases that allow multiple connections, to reduce the chance of errors). If you are creating an application that relies on sequences, ensure that the JDatabase subclass object supports `GenID()` fully. Subclasses must implement this method to enable `GenID()` support. JDatabaseMySQL and JDatabaseMySQLi do not support `GenID()`; using `GenID()` with these databases will always return `0`.
Parameters	foo1	Sequence name
	foo2	Start ID
Returns	Sequence ID; normally an integer, but sometimes a string

getAffectedRows( ) : int

Gets the total number of records that were affected by the last query.
Returns	Number of records that were affected by the last query

GetCol( query : string ) : array

Emulates ADOdb functionality.

Executes query and returns an array of the first column from the resultant records.

Parameters

query

Query to execute

Returns

Array of first column from records

getCollation( ) : string

Gets the database collation. This method is not infallible for MySQL databases; MySQL allows the collation to be set at four different levels, server, database, table, and column. This method returns the collation used by `#__content.fulltext`; it is possible that the collation may differ elsewhere in the database. This method only works if the database supports UTF-8.
Returns	Collation name

static getConnectors( ) : array

Gets an array of the names of database drivers supported in the current environment.
Returns	Array of available driver names

getEscaped( text : string ) : string

Escapes a string for use as a value in a query.
Parameters	text	String to escape
Returns	Escaped string

getErrorMsg( escaped : boolean=false ) : string

Gets the error message from the last query. If no error was encountered returns an empty string.
Parameters	[escaped]	Escape the message with slashes
Returns	Error message from the last query

getErrorNum( ) : int

Gets the error number from the last query. If no error was encountered, returns `0` (zero).
Returns	Error number from the last query

static &getInstance( options : array=array() ) : JDatabase

Gets a global instance of JDatabase, creating it if it does not already exist. An instance exists for every different set of `options`. The options array normally contains the keys defined in the constructor options array and the key `driver`. `driver` determines the subclass that is instantiated, available core drivers are `MySQL` and `MySQLi`.
Parameters	options	Database options
Returns	A global instance of JDatabase

getNullDate( ) : string

Gets a null date string specific to the current database driver.
Returns	Null date-time string

getNumRows( cur : resource=null ) : mixed

Gets the number of records that were returned in the last query. If `cur` is specified, it will determine the number of rows that were returned for the corresponding query. This only works if the query was a `SELECT`, `SHOW`, `DESCRIBE`, or `EXPLAIN` query.
Parameters	[cur]	Database resource
Returns	Number of records that were returned in the last query; `false` on failure

GetOne( query : string ) : string

Emulates ADOdb functionality.

Executes query and returns the value in the first field in the first record.

Parameters

query

Query to execute

Returns

Value in the first field in the first record of the results

getPrefix( ) : string

Gets the database table prefix, normally `jos_`.
Returns	Database table prefix

getQuery( ) : mixed

Gets the active query.
Returns	Active query

GetRow( query : string ) : array

Emulates ADOdb functionality.

Executes query and gets the first record as an array.

Parameters

query

Query to execute

Returns

First record as an array

getTableCreate( tables : array ) : array

Gets an associative array of table creation queries for the tables named in `tables`.
Parameters	tables	Array of table names
Returns	Associative array of table creation queries

getTableFields( tables : array ) : array

Gets an associative array of table fields and types. For example, a table called jos_test with two fields might return this:

Array
(
    [jos_test] => Array
        (
            [id] => int
            [name] => varchar
        )
)

Parameters

tables

Array of table names

Returns

Associative array of tables and table fields

getTableList( ) : array

Gets the names of the tables in the database.
Returns	Array of table names

getUTFSupport( ) : boolean

Determines if the database supports UTF-8.
Returns	`true` if the database supports UTF-8

getVersion( ) : string

Gets the database server version.
Returns	Database server version

hasUTF( ) : boolean

Determines if the database supports UTF-8. You should use `getUTFSupport()` in preference to this method, which returns a cached value of `hasUTF()`.
Returns	`true` if the database supports UTF-8

insertid( ) : int

If the last query was an `INSERT` query on a table with an auto-increment primary key, this method gets the ID inserted as a result of the last query. If it was not an `INSERT` query, zero will be returned.
Returns	Inserted ID from the last query

insertObject( table : string, &object : object, keyName : string=null ) : boolean

Treats `object` as a new record and attempts to insert it into the specified table. If `keyName` (primary key fieldname) is specified, the object will be updated with the record primary key value; this is for use with tables with auto-increment primary keys only.
Parameters	table	Table name
	object	Record object
	[keyName]	Primary key
Returns	`true` on success

isQuoted( fieldname : string ) : boolean

Determines if `fieldname` is amongst the fieldnames to be encapsulated in quotes. If no values have been specified to be quoted, returns `true`.
Parameters	fieldname	Fieldname to check
Returns	`true` if the fieldname should be encapsulated in quotes

loadAssoc( ) : array

Executes the current query and gets the first record as an associative array.
Returns	First record from query as an associative array

loadAssocList( key : string=” ) : array

Executes the current query and gets a two-dimensional array of records. Each inner array represents a record as an associative array. If `key` is specified (primary key fieldname) the returned array will be associative, using the record primary key as array key.
Parameters	[key]	Primary key
Returns	Two-dimensional array of records

loadObject( ) : object

Executes the current query and returns the first record as an object (stdClass).
Returns	First record from query as an object

loadObjectList( key : string=” ) : array

Executes the current query and returns an array of record objects. Each object represents a record. If `key` is specified (primary key fieldname) the returned array will be associative, using the record primary key as array key.
Parameters	[key]	Primary key
Returns	Array or associative array of record objects

loadResult( ) : string

Executes the current query and gets the value in the first field of the first record.
Returns	Value in the first field of the first record

loadResultArray( numinarray : int= 0 ) : array

Executes the current query and gets an array of the specified column/field number from the resultant records.
Parameters	[numinarray]	Column/Field number
Returns	Array of column from records

loadRow( ) : array

Executes the current query and returns the first record as an array.
Returns	First record from query as an array

loadRowList( key : int=” ) : array

Executes the current query and returns a two-dimensional array of records. Each inner array represents a record as an array. If `key` is specified (primary key field number), the returned array will be associative, using the record primary key as array key.
Parameters	[key]	Primary key
Returns	Two-dimensional array of records

nameQuote( s : string ) : string

Encapsulates a string in quotes. This is for strings that are named SQL elements (tables, fields, databases), not values.
Parameters	s	String to encapsulate
Returns	Quote encapsulated string

PageExecute( sql : string, nrows : int, page : int, inputarr : boolean=false, sec2cache : int=0 ) : JRecordSet

Emulates ADOdb functionality. Executes query and returns the results in a JRecordSet object. `nrows` and `page` are used to determine the offset and limit.
Parameters	sql	Query to execute
	nrows	Number of records per page
	page	Results page (pagination)
	[inputarr]	Ignored; emulation purposes only
	[secs2cache]	Ignored; emulation purposes only
Returns	JRecordSet object

query( ) : mixed

Executes the current query. If the query is successful and is a `SELECT`, `SHOW`, `DESCRIBE`, or `EXPLAIN` query, a resource will be returned. If the query is successful, and is not one of the above query types, `true` will be returned. If the query fails, `false` will be returned.
Returns	Database resource or `true` on success; `false` on failure

queryBatch( abort_on_error : boolean=true, p_transaction_safe : boolean=false ) : mixed

Executes a batch of queries. If `abort_on_error` is `true` the batch process will stop if an error occurs. If `p_transaction_safe` is `true` then all the queries will only be applied if they are all successful.
Parameters	[abort_on_error]	Stop batch process on error
	[p_transaction_safe]	Perform as transaction
Returns	`true` on success; `false` or the failed resource on failure

Quote( text : string ) : string

Emulates ADOdb functionality.

Encapsulates text in quotes and escapes text. Use this to make query values safe.

Parameters

text

String to encapsulate in quotes and escape

Returns

Quoted string

replacePrefix( sql : string, prefix : string=‘#__’ ) : string

Substitutes occurrences of `prefix` in `sql` with the database table prefix.
Parameters	sql	Query
	prefix	Database table prefix to replace
Returns	Query with correct table prefixes

RollbackTrans( ) : string

Emulates ADOdb functionality.

This method must be overridden in subclasses. If you intend to use this, please ensure the database driver supports it.

stderr( showSQL : boolean=false ) : string

Gets an error report of the last error. If `showSQL` is `true`, the SQL is included in the report.
Parameters	[showSQL]	Display query
Returns	Error report

SelectLimit( query : string, count : int, offset : int=0 ) : JRecordSet

Emulates ADOdb functionality. Executes query and returns the results in a JRecordSet object. `offset` and `limit` are used for pagination; in MySQL databases, this relates directly to the `LIMIT` clause.
Parameters	query	Query to execute
	count	Maximum number of records
	[offset]	Start record
Returns	JRecordSet object

setUTF( ) : void

Prepares the database connection for UTF-8 strings.

setQuery( sql : string, offset : int=0, limit : int=0, prefix : string=‘#__’ ) : void

Sets the next query to execute. `offset` and `limit` are used for pagination; in MySQL this relates directly to the `LIMIT` clause. If you use `offset` or `limit`, then your SQL must not contain a `LIMIT` clause. `prefix` is the string that is replaced in the SQL by the database table prefix; it would be unusual to change this from the default `#__`.
Parameters	sql	Query
	[offset]	Start record
	[limit]	Maximum number of records
	[prefix]	Table prefix to substitue

static test( ) : boolean

Determines if the driver (subclass) is compatible with the current environment.
Returns	`true` of the driver is compatible with the current environment

updateObject( table : string, &object : object, keyName : string, updateNulls : boolean=true ) : boolean

Treats `object` as an updated record and attempts to update the specified table from the record. If `updateNulls` is `true`, object properties that are null will still be used to update the record in the table.
Parameters	table	Table name
	object	Record object
	keyName	Primary key
	[updateNulls]	Update values even if they are null
Returns	`true` on success

Parameters (Core JElements)

We can use the XML tag param to define different parameters. Every param tag must include the following attributes:

Attribute	Description
description	Description of the parameter
label	Human-readable name of the input; this will always be translated by JText
name	Name of the input
type	Type of parameter; this relates to JElement subclasses
default	The default value (this does not work for all elements)

This is an example of a param tag:

<param name="title" type="text" default="My Title" label="Title"
description="Title of page" size="30" />

When we define the type we are informing Joomla! which JElement subclass to use to render the parameter. There are a number of core JElement subclasses available to us, each of which has its own set of attributes that modify the rendered output.

The following tables describe the parameter types from the core that we can use. Any attributes that are optional are encapsulated in square braces. Remember that when we use the param tag we also need to include the attributes defined in the previous table.

category
Displays a drop-down selection box of published categories. The first option in the selection box is always `– Select Category -`; this option has a value of `0`.
Parameters	class	CSS Style
	[section]	Section ID or component name if using component-specific categories. If not specified, all content categories are displayed.

editors

Displays a drop-down selection box of all the published editors. The first option in the selection box is always – Select Editor -; this option has a value of 0.

filelist
Displays a drop-down selection box of files in a specified directory. Can optionally include the options `– Do not use –` and `– Use default –`; these options have the values `-1` and `null` respectively.
Parameters	[directory]	Directory where the files are located, relative to the root of Joomla!
	[exclude]	RE file exclusion, applied after filter
	[filter]	RE filter to apply to file names
	[hide_default]	Hide the ‘use default’ option; Boolean
	[hide_none]	Hide the ‘do not use’ option; Boolean
	[stripExt]	Remove extensions from the file list; Boolean

folderlist
Displays a drop-down selection box of folders in a specified directory. Can optionally include the options `– Do not use –` and `– Use default –`; these options have the values `-1` and `null` respectively.
Parameters	[directory]	Directory where the folders are located, relative to the root of Joomla!
	[exclude]	RE folder exclusion, applied after filter
	[filter]	RE filter to apply to folder names
	[hide_default]	Hide the ‘use default’ option; Boolean
	[hide_none]	Hide the ‘do not use’ option; Boolean
	[stripExt]	Remove extensions from the folder list; Boolean

helpsites

Displays a drop-down selection box of the different Joomla! help sites. The help sites are defined in the core administrator/help/helpsites-15.xml file.

hidden
A hidden field. We cannot define a value here; this type is used in conjunction with an INI string in which the value will be defined.
Parameters	[class]	CSS Style

imagelist
Displays a drop-down selection box of image files in a specified directory. Can optionally include the options `– Do not use –` and `– Use default –`; these options have the values `-1` and `null` respectively.
Parameters	[directory]	Directory where the folders are located, relative to the root of Joomla!
	[exclude]	RE file exclusion, applied after filter
	[hide_default]	Hide the ‘use default’ option; Boolean
	[hide_none]	Hide the ‘do not use’ option; Boolean
	[stripExt]	Remove extensions from the file list; Boolean

languages
Displays a drop-down selection box of known languages from a specific client.
Parameters	client	`JPATH_` suffix where a language folder is located. Normally `BASE` or `ADMINISTRATOR`.

list
Displays a drop-down selection box of specified options. Options are defined by sub-tags called `option`. Each `option` tag includes a value attribute and the encapsulated content is the name.
Parameters	[class]	CSS Style

menu

Displays a drop-down selection box of the different menus. The first option is always – Select Menu – with a value of null.

menuitem
Displays a drop-down selection box of the different menu items grouped by menu. The first option is always `– Select Item –` with a value of `null`.
Parameters	[state]	Published state of the menu items

password
Displays a password text box.
Parameters	[class]	CSS Style.
	[size]	Character width of the password box; this is not the same as the maximum number of characters.

radio

Displays a selection of radio buttons. Options are defined by sub-tags called option. Each option tag includes a value attribute and the encapsulated content is the name. The first option is selected by default. We normally use radio buttons for show and hide options:

<param name="show" type="radio" label="Hide/Show" 
description="Hide
                                                  
             or Show">
    <option value="0">Hide</option>
    <option value="1">Show</option>
</param>

Parameters

[class]

CSS Style

section

Displays a drop-down selection box of published sections. The first option in the selection box is always – Select Section -; this option has a value of 0.

spacer

Adds a horizontal rule.

sql
Displays a drop-down selection box of items. The items are determined by executing the query attribute against the database. The query must return two fields, one called `id` and one called `value`. Use the AS alias clause in your SQL to set names of returned fields.
Parameters	query	Query to execute

text
Displays a text box.
Parameters	[class]	CSS Style
	[size]	Character width of the text box; this is not the same as the maximum number of characters

textarea
Displays a text box.
Parameters	[class]	CSS Style
	cols	Number of columns
	rows	Number of rows

timezones

Displays a drop-down selection box of different time zones. Values are identified as plus or minus hours from UTC (Universal Time Code); UTC is the same as GMT (Greenwich Mean Time), and Z (Zulu Time).

Configuration

The site settings are located in the config namespace within the registry. Most of these settings originate from the configuration.php file. This table details the values we expect to be present in the config namespace:

Name	Description
absolute_path	Full path to the Joomla! installation, for example `/www/joomla`
cache_handler	Mechanism with which to handle caching; Joomla! supports APC, EAccelerator, Memcache, and File
cachetime	Cache life expectancy in seconds
caching	Caching enabled; `1` = enabled, `0` = disabled
db	Database name
dbprefix	Database table prefix
dbtype	Database driver
debug	Site debug status; `1` = enabled, `0` = disabled
debug_db	Database debug status; `1` = enabled, `0` = disabled
debug_lang	Language debug status; `1` = enabled, `0` = disabled
editor	Default editor
error_reporting	Error reporting level; `-1` = system default, `0` = none, `7` = simple, `2047` = maximum
feed_limit	Number of content feed items to display
feed_summary	Display full text in feeds; `1` = true, `0` = false
fromname	Mail email address alias, see mailfrom
ftp_enable	FTP access enabled; `1` = true, `0` = false
ftp_host	FTP host, normally `127.0.0.1`
ftp_pass	FTP account password
ftp_port	FTP port, normally 21
ftp_root	FTP path to Joomla! installation
ftp_user	FTP account username
gzip	GZIP compression enabled; `1` = true, `0` = false
helpurl	Joomla! help site
host	Host name
lang	Default language name
lang_administrator	Default backend language tag
lang_site	Default frontend language tag
language	Default language tag
lifetime	Session lifetime in minutes
list_limit	Default length of lists (pagination) in the backend
live_site	URI to the site
log_path	Path to the site LOG files
mailer	Email sending mechanism; Joomla! supports: PHP mail, sendmail, and SMTP
mailfrom	Default email sender address
memcache_settings	Settings for Memcache (serialized PHP data); Memcache is a PHP caching system
MetaAuthor	Global option to show the author’s meta tag when viewing a content item; `1` = true, `0` = false
MetaDesc	Site metadata-description-tag content
MetaKeys	Site metadata keys tag content
MetaTitle	Display the site metadata title tag; `1` = show, `0` = hide
offline	Site offline; `1` = true, `0` = false
offline_message	This site is down for maintenance. Please check back again soon.
offset	Time zone hours offset from UTC (also known as GMT and Z)
password	Database account password
secret	Secret site word (random alphanumeric string)
sef	SEF enabled; `1` = true, `0` = false
sef_rewrite	Apache SEF mod_rewrite enabled; `1` = true, `0` = false
sendmail	`/usr/sbin/sendmail`
session_handler	Session storage handling mechanism; Joomla! supports: APC, database EAccelerator, and Memcache
sitename	Name of the Joomla! installation
smtpauth	SMTP requires authorization; `1` = true, `0` = false
smtphost	SMTP host, normally localhost
smtppass	SMTP account password
smtpuser	SMTP account username
tmp_path	Temporary directory; used for archive extraction
user	Database account username
xmlrpc_server	XMLRPC support; `1` = enabled, `0` = disabled

Mastering Joomla! 1.5 Extension and Framework Development

By : James Kennard

Mastering Joomla! 1.5 Extension and Framework Development

By: James Kennard

Overview of this book

Related Content you might be interested in

Current Title:

Mastering Joomla! 1.5 Extension and Framework Development

Classes

Note

Note

JObject

Properties

Constructors

Methods

JUser

Properties

Constructors

Methods

JModel

Properties

Constructors

Methods

JView

Properties

Constructors

Methods

JController

Properties

Constructors

Methods

JTable

Properties

Constructors

Methods

JError

Methods

JDocument

Properties

Constructors

Methods

JApplication

Properties

Constructors

Methods

JURI

Properties

Constructors

Methods

JLanguage

Properties

Constructors

Methods

JLanguageHelper

Methods

JText

Methods

JElement

Properties

Constructors

Methods

JParameter

Properties

Constructors

Methods

JCache

Properties

Constructors

Methods

JMail

Constructors

Methods

JMailHelper

Methods

JFactory

Methods

JRegistry

Properties

Constructors

Methods