Joomla! Documentation - User contributions [en]

Accessing the database using JDatabase/2.5

2012-11-20T17:08:08Z

Haydenyoung:

{{underconstruction}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

We need to ensure that the record does not exist before attempting to insert it, so adding some kind of record check before executing the insertObject method would be recommended.

====Updating a Record====

=====Using SQL=====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query(); // Use $db->execute() for Joomla 3.0.
catch (Exception $e) {
// Catch the error.
}
</source>

=====Using an Object =====

Like insertObject, the JDatabaseDriver class provides a convenience method for updating an object.

Below we will update our custom table with new values using an existing id primary key:

<source lang="php">
// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

try {
// Update their details in the users table using id as the primary key.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id');
} catch (Exception $e) {
// catch the error.
}
</source>

Just like insertObject, updateObject takes care of escaping table names for us.

The updateObject method will throw a RuntimeException if there is a problem inserting the record into the database table.

We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.

====Deleting a Record====

Just as there are select, insert and update method calls, there is also a delete method for remove records from the database.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// delete all custom keys for user 1001.
$conditions = array(
'user_id=1001',
'profile_key LIKE \'custom.%\'');

$query->delete($db->quoteName('#__user_profiles'));
$query->where($conditions);

$db->setQuery($query);

try {
$result = $db->query(); // $db->execute(); for Joomla 3.0.
} catch (Exception $e) {
// catch the error.
}
</source>

===Transactions===

The Joomla 12.1 Framework introduces SQL transactions (where supported) via the JDatabaseDriver's transactionStart, transactionCommit and transactionRollback. This supersedes the queryBatch method which was introduced in 11.1.

IMPORTANT NOTE: Transactions can only be used against transaction-aware storage engine such as InnoDB (many tables in Joomla still use the MyISAM storage engine which cannot support transactions).

<source lang="php">
$db = JFactory::getDbo();

try {
$db->transactionStart();

$query = $db->getQuery(true);

$values = array($db->quote('TEST_CONSTANT'), $db->quote('Custom'), $db->quote('/path/to/translation.ini'));

$query->insert($db->quoteName('#__overrider'));
$query->columns($db->quoteName(array('constant', 'string', 'file')));
$query->values(implode(',',$values));

$db->setQuery($query);
$result = $db->query();

$db->transactionCommit();
} catch (Exception $e) {
$db->transactionRollback();
// catch any database errors.
}
</source>

Anything between the transactionStart and transactionCommit methods are not executed until transactionCommit is called. If an exception occurs, we can roll back the changes using the transactionRollback method. This allows us to return the database to the original state if a problem occurs even though we may execute a number of changes to the database's tables.

Accessing the database using JDatabase/2.5

2012-11-20T16:50:50Z

Haydenyoung: Transactions.

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

We need to ensure that the record does not exist before attempting to insert it, so adding some kind of record check before executing the insertObject method would be recommended.

====Updating a Record====

=====Using SQL=====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query(); // Use $db->execute() for Joomla 3.0.
catch (Exception $e) {
// Catch the error.
}
</source>

=====Using an Object =====

Like insertObject, the JDatabaseDriver class provides a convenience method for updating an object.

Below we will update our custom table with new values using an existing id primary key:

<source lang="php">
// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

try {
// Update their details in the users table using id as the primary key.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id');
} catch (Exception $e) {
// catch the error.
}
</source>

Just like insertObject, updateObject takes care of escaping table names for us.

The updateObject method will throw a RuntimeException if there is a problem inserting the record into the database table.

We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.

====Deleting a Record====

Just as there are select, insert and update method calls, there is also a delete method for remove records from the database.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// delete all custom keys for user 1001.
$conditions = array(
'user_id=1001',
'profile_key LIKE \'custom.%\'');

$query->delete($db->quoteName('#__user_profiles'));
$query->where($conditions);

$db->setQuery($query);

try {
$result = $db->query(); // $db->execute(); for Joomla 3.0.
} catch (Exception $e) {
// catch the error.
}
</source>

===Transactions===

The Joomla 12.1 Framework introduces SQL transactions (where supported) via the JDatabaseDriver's transactionStart, transactionCommit and transactionRollback. This supersedes the queryBatch method which was introduced in 11.1.

IMPORTANT NOTE: Transactions can only be used against transaction-aware storage engine such as InnoDB (many tables in Joomla still use the MyISAM storage engine which cannot support transactions).

<source lang="php">
$db = JFactory::getDbo();

try {
$db->transactionStart();

$query = $db->getQuery(true);

$values = array($db->quote('TEST_CONSTANT'), $db->quote('Custom'), $db->quote('/path/to/translation.ini'));

$query->insert($db->quoteName('#__overrider'));
$query->columns($db->quoteName(array('constant', 'string', 'file')));
$query->values(implode(',',$values));

$db->setQuery($query);
$result = $db->query();

$db->transactionCommit();
} catch (Exception $e) {
$db->transactionRollback();
// catch any database errors.
}
</source>

Anything between the transactionStart and transactionCommit methods are not executed until transactionCommit is called. If an exception occurs, we can roll back the changes using the transactionRollback method. This allows us to return the database to the original state if a problem occurs even though we may execute a number of changes to the database's tables.

Accessing the database using JDatabase/2.5

2012-11-20T15:21:29Z

Haydenyoung: /* Using SQL */

Accessing the database using JDatabase/2.5

2012-11-20T15:21:00Z

Haydenyoung: /* Deleting a Record */

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

We need to ensure that the record does not exist before attempting to insert it, so adding some kind of record check before executing the insertObject method would be recommended.

====Updating a Record====

=====Using SQL=====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query();
catch (Exception $e) {
// Catch the error.
}
</source>

=====Using an Object =====

Like insertObject, the JDatabaseDriver class provides a convenience method for updating an object.

Below we will update our custom table with new values using an existing id primary key:

<source lang="php">
// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

try {
// Update their details in the users table using id as the primary key.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id');
} catch (Exception $e) {
// catch the error.
}
</source>

Just like insertObject, updateObject takes care of escaping table names for us.

The updateObject method will throw a RuntimeException if there is a problem inserting the record into the database table.

We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.

====Deleting a Record====

Just as there are select, insert and update method calls, there is also a delete method for remove records from the database.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// delete all custom keys for user 1001.
$conditions = array(
'user_id=1001',
'profile_key LIKE \'custom.%\'');

$query->delete($db->quoteName('#__user_profiles'));
$query->where($conditions);

$db->setQuery($query);

try {
$result = $db->query(); // $db->execute(); for Joomla 3.0.
} catch (Exception $e) {
// catch the error.
}
</source>

Accessing the database using JDatabase/2.5

2012-11-20T15:20:40Z

Haydenyoung: /* Deleting a Record */ Deleting records from the database.

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

We need to ensure that the record does not exist before attempting to insert it, so adding some kind of record check before executing the insertObject method would be recommended.

====Updating a Record====

=====Using SQL=====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query();
catch (Exception $e) {
// Catch the error.
}
</source>

=====Using an Object =====

Like insertObject, the JDatabaseDriver class provides a convenience method for updating an object.

Below we will update our custom table with new values using an existing id primary key:

<source lang="php">
// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

try {
// Update their details in the users table using id as the primary key.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id');
} catch (Exception $e) {
// catch the error.
}
</source>

Just like insertObject, updateObject takes care of escaping table names for us.

The updateObject method will throw a RuntimeException if there is a problem inserting the record into the database table.

We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.

====Deleting a Record====

Just as there are select, insert and update method calls, there is also a delete method for remove records from the database.

<source lang="php">
$db = JFactory::getDbo();
$query = $db->getQuery(true);

// delete all custom keys for user 1001.
$conditions = array(
'user_id=1001',
'profile_key LIKE \'custom.%\'');

$query->delete($db->quoteName('#__user_profiles'));
$query->where($conditions);

$db->setQuery($query);

try {
$result = $db->query(); // $db->execute(); for Joomla 3.0.
} catch (Exception $e) {
// catch the error.
}
</source>

Accessing the database using JDatabase/2.5

2012-11-20T14:22:17Z

Haydenyoung: /* Using updateObject */

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

We need to ensure that the record does not exist before attempting to insert it, so adding some kind of record check before executing the insertObject method would be recommended.

====Updating a Record====

=====Using SQL=====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query();
catch (Exception $e) {
// Catch the error.
}
</source>

=====Using an Object =====

Like insertObject, the JDatabaseDriver class provides a convenience method for updating an object.

Below we will update our custom table with new values using an existing id primary key:

<source lang="php">
// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

try {
// Update their details in the users table using id as the primary key.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id');
} catch (Exception $e) {
// catch the error.
}
</source>

Just like insertObject, updateObject takes care of escaping table names for us.

The updateObject method will throw a RuntimeException if there is a problem inserting the record into the database table.

We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.

====Deleting a Record====

Accessing the database using JDatabase/2.5

2012-11-20T14:20:56Z

Haydenyoung: /* Using an Object */

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

We need to ensure that the record does not exist before attempting to insert it, so adding some kind of record check before executing the insertObject method would be recommended.

====Updating a Record====

=====Using SQL=====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query();
catch (Exception $e) {
// Catch the error.
}
</source>

=====Using updateObject=====

Like insertObject, the JDatabaseDriver class provides a convenience method for updating an object.

Below we will update our custom table with new values using an existing id primary key:

<source lang="php">
// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

try {
// Update their details in the users table using id as the primary key.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id');
} catch (Exception $e) {
// catch the error.
}
</source>

We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.

====Deleting a Record====

Accessing the database using JDatabase/2.5

2012-11-20T14:19:51Z

Haydenyoung: /* Updating a Record */ Updating a record using an object.

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

====Updating a Record====

=====Using SQL=====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query();
catch (Exception $e) {
// Catch the error.
}
</source>

=====Using updateObject=====

Like insertObject, the JDatabaseDriver class provides a convenience method for updating an object.

Below we will update our custom table with new values using an existing id primary key:

<source lang="php">
// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

try {
// Update their details in the users table using id as the primary key.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id');
} catch (Exception $e) {
// catch the error.
}
</source>

We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.

====Deleting a Record====

Accessing the database using JDatabase/2.5

2012-11-20T10:54:24Z

Haydenyoung: /* Updating a Record */ Updating a record.

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

====Updating a Record====

The JDatabaseQuery class also provides methods for building update queries, in particular [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#update update] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#set set]. We also reuse another method which we used when creating select statements, the where method.

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
'profile_value=\'Updating custom message for user 1001.\'',
'ordering=2');

// Conditions for which records should be updated.
$conditions = array(
'user_id=42',
'profile_key=\'custom.message\'');

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

try {
$result = $db->query();
catch (Exception $e) {
// Catch the error.
}
</source>

====Deleting a Record====

Accessing the database using JDatabase/2.5

2012-11-20T08:43:33Z

Haydenyoung: /* Using an Object */

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

====Updating a Record====

====Deleting a Record====

Accessing the database using JDatabase/2.5

2012-11-20T08:37:35Z

Haydenyoung: /* Using an Object */ Added commenting.

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 42;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

The insertObject method will throw a [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.

====Updating a Record====

====Deleting a Record====

Accessing the database using JDatabase/2.5

2012-11-20T08:32:45Z

Haydenyoung: /* Inserting a Record */ Inserting a record using insertObject.

{{inuse}}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.

===The Connection===

Joomla supports a generic interface for connecting to the database, hiding the intricacies of a specific database server from the Framework developer, thus making Joomla code easier to port from one platform to another.

To obtain a database connection, use the [http://api.joomla.org/Joomla-Platform/JFactory.html#getDbo JFactory getDbo] static method:

<source lang="php">
$db = JFactory::getDbo();
</source>

The getDbo method will return a reference to a high-level abstract class called [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html JDatabaseDriver]; the Joomla Framework hides the specifics of the database server, which is loaded dynamically by getDbo via Joomla's configuration file.

Alternatively, if your class inherits from the JModel (or a decendent class) getDbo method:

<source lang="php">
$db = $this->getDbo();
</source>

{{JVer|3.0}} users should note that the JModel class has been renamed JModelLegacy and will eventually be deprecated in favour of the class JModelBase. Therefore, any Joomla 3.0 core or extension code should use JFactory::getDbo() to obtain a database connection.

===The Query===

Joomla's database querying has changed since the new Joomla Framework was introduced "query chaining" is now the recommended method for building database queries (although string queries are still supported).

Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.

To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:

<source lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);
</source>

The JDatabaseDriver::getQuery takes an optional argument, $new, which can be true or false (the default being false).

To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.

Some of the more frequently used methods include; select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.

====Selecting Records from a Single Table====

Below is an example of creating a database query using the JDatabaseQuery class. Using the select, from, where and order methods, we can create queries which are flexible, easily readable and portable:

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all records from the user profile table where key begins with "custom.".
// Order it by the ordering field.
$query->select(array('user_id', 'profile_key', 'profile_value', 'ordering'));
$query->from('#__user_profiles');
$query->where('profile_key LIKE \'custom.%\'');
$query->order('ordering ASC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The query can also be chained to simplify further:

<source lang="php">
$query
->select(array('user_id', 'profile_key', 'profile_value', 'ordering'))
->from('#__user_profiles')
->where('profile_key LIKE \'custom.%\'')
->order('ordering ASC');
</source>

Chaining can become useful when queries become longer and more complex.

====Selecting Records from Multiple Tables====

Using the JDatabaseQuery's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#join join] methods, we can select records from multiple related tables. The generic "join" method takes two arguments; the join "type" (inner, outer, left, right) and the join condition. In the following example you will notice that we can use all of the keywords we would normally use if we were writing a native SQL query, including the AS keyword for aliasing tables and the ON keyword for creating relationships between tables. Also note that the table alias is used in all methods which reference table columns (I.e. select, where, order).

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Select all articles for users who have a username which starts with 'a'.
// Order it by the created date.
$query
->select(array('a.*', 'b.username', 'b.name'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');

// Reset the query using our newly populated query object.
$db->setQuery($query);

// Load the results as a list of stdClass objects.
$results = $db->loadObjectList();
</source>

The join method above enables us to query both the content and user tables, retrieving articles with their author details. There are also convenience methods for [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#innerJoin inner], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#leftJoin left], [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#rightJoin right] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#outerJoin outer] joins.

We can use multiple joins to query across more than two tables:

<source lang="php">
$query
->select(array('a.*', 'b.username', 'b.name', 'c.*', 'd.*'))
->from('#__content AS a')
->join('INNER', '#__users AS b ON (a.created_by = b.id)')
->join('LEFT', '#__user_profiles AS c ON (b.id = c.user_id)')
->join('RIGHT', '#__categories AS d ON (a.catid = d.id)')
->where('b.username LIKE \'a%\'')
->order('a.created DESC');
</source>

Notice how chaining makes the source code much more readable for these longer queries.

====Inserting a Record====

=====Using SQL=====

The JDatabaseQuery class provides a number of methods for building insert queries, the most common being [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#insert insert], [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabaseQuery.html#columns columns] and [http://api.joomla.org/Joomla-Platform/Database/JDatabaseQuery.html#values values].

<source lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Reset the query using our newly populated query object.
$db->setQuery($query);
</source>

Since Joomla 3.0 there has been a change in how the Joomla database class executes a query.

When executing a query in the Joomla Framework 11.4 we use the JDatabase's [http://api.joomla.org/11.4/Joomla-Platform/Database/JDatabase.html#query query] method:

<source lang="php">
try {
// Execute the query in Joomla 2.5.
$result = $db->query();
} catch (Exception $e) {
// catch any database errors.
}
</source>

For Joomla Framework 12.1 and higher, we use the JDatabaseDriver's [http://api.joomla.org/Joomla-Platform/Database/JDatabaseDriver.html#execute execute] method:

<source lang="php">
try {
// Execute the query in Joomla 3.0.
$result = $db->execute();
} catch (Exception $e) {
// catch any database errors.
}
</source>

Since the phase out of PHP 4.x support, PHP's exception model has been widely implemented in the Joomla Framework. Therefore, we can wrap our database execution in a try...catch block to catch any unexpected database errors that may arise. Any database-specific errors will be thrown using an instance of the [http://api.joomla.org/Joomla-Platform/Database/JDatabaseException.html JDatabaseException] class although it is best practice to catch the generic Exception object from which JDatabaseException inherits.

=====Using an Object=====

The JDatabaseDriver also class provides us with a convenience method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.

<source lang="php">
$profile = new stdClass();
$profile->user_id = 42;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

try {
$result = $db->insertObject('#__user_profiles', $profile);
catch (Exception $e) {
// catch any errors.
}

The insertObject method will throw a PHP [http://php.net/manual/en/class.runtimeexception.php RuntimeException] if there is a problem inserting the record into the database table.
</source>

Notice here that we do not need to escape the table name; the insertObject method does this for us.

====Updating a Record====

====Deleting a Record====

Accessing the database using JDatabase/3.1

2012-11-20T07:26:00Z

Haydenyoung: 3.0 documentation.

Accessing the database using JDatabase/2.5

2012-11-20T06:33:03Z

Haydenyoung: /* Inserting a Record */ Inserting a record using a chained query.

Accessing the database using JDatabase/2.5

2012-11-20T04:27:42Z

Haydenyoung: /* The Connection */ Links to various useful classes and methods.

Accessing the database using JDatabase/2.5

2012-11-20T04:13:13Z

Haydenyoung: /* Selecting Records from Multiple Tables */ Chaining a query with multiple joins.

Accessing the database using JDatabase/2.5

2012-11-19T14:50:12Z

Haydenyoung: /* Selecting Records from Multiple Tables */ A chained multi-table query.

Accessing the database using JDatabase/2.5

2012-11-19T13:54:24Z

Haydenyoung: /* Selecting Records from a Single Table */ Example of chaining.

Accessing the database using JDatabase/2.5

2012-11-19T12:35:14Z

Haydenyoung: /* Selecting Records from a Single Table */ Example of a simple query.

Accessing the database using JDatabase/2.5

2012-11-16T14:04:00Z

Haydenyoung: /* The Query */ Introduction to query chaining.

Accessing the database using JDatabase/2.5

2012-11-16T06:21:30Z

Haydenyoung: /* Usage */ Connection usage.

Accessing the database using JDatabase

2012-11-16T05:17:00Z

Haydenyoung:

{{underconstruction}}

{{version/tutor|1.5,2.5,3.0}}{{multiversion|The '''{{PAGENAME}}''' Tutorial is available in these versions:-|version|pages=no}}

==Supported Storage Connectors==

The table below outlines the database and storage connectors available for Joomla! as well as which version of Joomla they became available in.

To make a connector available in Joomla's installer or global configuration manager, you will need to ensure the PHP library is installed (E.g. for PHP5 and MySQL the php5-mysql library would need to be installed).

{| class="wikitable"
! scope="col" | Database
! scope="col" | Joomla Versions
|-
| MySQL || {{JVer|1.5}}{{JVer|2.5}}{{JVer|3.0}}
|-
| Postgresql || {{JVer|3.0}}
|-
| Microsoft SQL Server || {{JVer|2.5}}{{JVer|3.0}}
|-
| Microsoft SQL Azure || {{JVer|2.5}}{{JVer|3.0}}
|-
| Oracle DB || {{JVer|3.0}}
|-
| SQL Lite || {{JVer|3.0}}
|-
| PHP Data Objects (PDO)* || {{JVer|3.0}}
|}

* PHP Data Objects is a database abstraction layer and is shipped with PHP 5.1+.

Accessing the database using JDatabase/2.5

2012-10-28T03:54:51Z

Haydenyoung:

Accessing the database using JDatabase

2012-10-28T03:51:27Z

Haydenyoung: /* Supported Storage Connectors */

{{inuse}}

{{version/tutor|1.5,2.5,3.0}}{{multiversion|The '''{{PAGENAME}}''' Tutorial is available in these versions:-|version|pages=no}}

==Supported Storage Connectors==

The table below outlines the database and storage connectors available for Joomla! as well as which version of Joomla they became available in.

To make a connector available in Joomla's installer or global configuration manager, you will need to ensure the PHP library is installed (E.g. for PHP5 and MySQL the php5-mysql library would need to be installed).

{| class="wikitable"
! scope="col" | Database
! scope="col" | Joomla Versions
|-
| MySQL || {{JVer|1.5}}{{JVer|2.5}}{{JVer|3.0}}
|-
| Postgresql || {{JVer|3.0}}
|-
| Microsoft SQL Server || {{JVer|2.5}}{{JVer|3.0}}
|-
| Microsoft SQL Azure || {{JVer|2.5}}{{JVer|3.0}}
|-
| Oracle DB || {{JVer|3.0}}
|-
| SQL Lite || {{JVer|3.0}}
|-
| PHP Data Objects (PDO)* || {{JVer|3.0}}
|}

* PHP Data Objects is a database abstraction layer and is shipped with PHP 5.1+.

Accessing the database using JDatabase

2012-10-28T03:48:48Z

Haydenyoung: Supported storage connectors.

Accessing the database using JDatabase/2.5

2012-10-28T03:17:50Z

Haydenyoung:

{inuse}

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

===The Connection===

===The Query===

Accessing the database using JDatabase/2.5

2012-10-28T03:17:33Z

Haydenyoung: New 2.5/3.0 page for database connections and query chaining.

Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further, and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.

==Usage==

===The Connection===

===The Query===

Accessing the database using JDatabase

2012-10-28T02:16:27Z

Haydenyoung: Multiple versions of this tutorial are now available.

{{inuse}}

{{version/tutor|1.5,2.5,3.0}}{{multiversion|The '''{{PAGENAME}}''' Tutorial is available in these versions:-|version|pages=no}}

Accessing the database using JDatabase/1.5

2012-10-28T02:12:16Z

Haydenyoung:

Accessing the database using JDatabase/1.5

2012-10-28T02:07:24Z

Haydenyoung: Re-organizing pages into the various version implementations. This article will replace the existing Accessing the database using JDatabase article.

Adding JavaScript

2012-10-28T02:04:22Z

Haydenyoung:

{{version/tutor|1.5,2.5,3.0}}

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

More information about JQuery is available at http://docs.jquery.com/How_jQuery_Works. For API documentation, visit http://docs.jquery.com/.

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

More information about Mootools is available at http://mootools.net/. For API documentation, visit http://mootools.net/docs/core.

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]] from the Joomla! Framework 11.1 documentation

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==
http://api.joomla.org/Joomla-Platform/HTML/JHtmlBehavior.html#methodframework

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-11T08:24:18Z

Haydenyoung: /* External Links */ Link to latest api docs.

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

More information about JQuery is available at http://docs.jquery.com/How_jQuery_Works. For API documentation, visit http://docs.jquery.com/.

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

More information about Mootools is available at http://mootools.net/. For API documentation, visit http://mootools.net/docs/core.

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]] from the Joomla! Framework 11.1 documentation

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==
http://api.joomla.org/Joomla-Platform/HTML/JHtmlBehavior.html#methodframework

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-11T08:23:42Z

Haydenyoung: /* See Also */

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

More information about JQuery is available at http://docs.jquery.com/How_jQuery_Works. For API documentation, visit http://docs.jquery.com/.

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

More information about Mootools is available at http://mootools.net/. For API documentation, visit http://mootools.net/docs/core.

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]] from the Joomla! Framework 11.1 documentation

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-11T08:21:32Z

Haydenyoung: /* JQuery */ Links to getting started with JQuery.

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

More information about JQuery is available at http://docs.jquery.com/How_jQuery_Works. For API documentation, visit http://docs.jquery.com/.

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

More information about Mootools is available at http://mootools.net/. For API documentation, visit http://mootools.net/docs/core.

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]]

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-11T08:19:08Z

Haydenyoung: /* Mootools */ Some links to mootools.

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

More information about Mootools is available at http://mootools.net/. For API documentation, visit http://mootools.net/docs/core.

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]]

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-08T06:42:40Z

Haydenyoung:

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

For more information, see [[#External Links]]

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]]

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-08T06:21:43Z

Haydenyoung: Remove from Cookie Jar

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

For more information, see [[#Further Reading]]

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]]

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-08T06:21:10Z

Haydenyoung:

{{cookiejar}}

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

For more information, see [[#Further Reading]]

== See Also ==

[[JHtmlBehavior::framework/11.1| JHtmlBehaviour::framework method]]

[[Ajax using MooTools]]

[[Adding Javascript moo.fx to your component]]

== External Links ==

http://en.wikipedia.org/wiki/JavaScript

http://www.w3schools.com/js/default.asp

http://mootools.net/

http://jquery.com/

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-10-08T06:06:28Z

Haydenyoung: Introduction to javascript frameworks.

{{cookiejar}}

JavaScript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include JavaScript in their extensions using existing API methods.

There are a number of methods for including JavaScript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline JavaScript===

Blocks of JavaScript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');
?>
</source>

===External JavaScript===

Alternatively, you may wish to separate your JavaScript into a separate file. Separating your JavaScript into an external file can make your template code easier to read especially if the JavaScript is lengthy or complex.

There are two ways to include a JavaScript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed JavaScript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed JavaScript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javaScript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (JavaScript) from the main PHP code, ensures all JavaScript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a JavaScript file is included only once (I.e. there is no .js file duplication).

== Using a JavaScript Framework ==

A Javascript framework provides developers with generic functionality for handling various coding tasks in a familiar, consistent and platform-independent way. A framework enables the developer to forget about the intricacies of implementing a certain function in different web browsers and focus on the requirements of the software.

Two Javascript frameworks are provided as part of Joomla 3.0; JQuery and Mootools. JQuery is a newly introduced framework which integrates with Joomla's new Bootstrap HTML framework; Mootools is Joomla's legacy Javascript library which is now superseded by JQuery and is included for backwards compatibility with 3rd party extensions.

In nearly all cases you should use a framework when developing Javascript in your extensions or templates and including one is very simple with Joomla's API.

=== JQuery ===

As of Joomla 3.0 it is highly recommended you use the JQuery framework for all your Javascript as it is loaded by nearly every template which uses the Bootstrap HTML/CSS framework. In those few instances where JQuery is not available, you can easily include the framework using the JHTMLJQuery class' framework method.

To include the JQuery framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('jquery.framework');
</source>

Using the framework method ensures JQuery is included correctly, only once, and ensures it doesn't clash with Mootools (if also loaded).

Then it is just a matter of leveraging the JQuery framework:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
(function($) {
$(document).ready(function() {
alert($("#list li").size());
});
})(jQuery);
');
</source>

=== Mootools ===

Unless you are maintaining Javascript code which leverages Mootools or you are developing an extension for a Joomla version prior to 3.0 it is recommended you use JQuery instead.

Firstly, you will need to include the Mootools code in your extension. To include the Mootools framework in your extension, you add the following code to your view.html.php or tmpl file:

<source lang="php">
JHtml::_('behavior.framework');
</source>

The above code results in the same outcome as the similar JQuery framework statement; that is it ensures Mootools is included correctly and only once.

Then using Mootools is almost identical to JQuery:

<source lang="php">
JFactory::getDocument()->addScriptDeclaration('
window.addEvent('domready', function() {
alert($("list").getElements("li").length);
});
');
</source>

For more information, see [[#Further Reading]]

== See Also ==

== References ==
<references/>

== Further Reading ==

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-09-17T23:02:46Z

Haydenyoung: See also heading

Adding JavaScript

2012-09-17T23:01:28Z

Haydenyoung: Further reading heading.

Adding JavaScript

2012-09-17T23:01:01Z

Haydenyoung: New heading for covering Mootools. Keeping the heading generic for upcoming JQuery update.

Adding JavaScript

2012-09-17T22:59:39Z

Haydenyoung:

Adding JavaScript

2012-09-17T22:55:27Z

Haydenyoung: Keep spelling of JavaScript same throughout document.

Adding JavaScript

2012-09-17T22:53:43Z

Haydenyoung: Usage introduction.

{{cookiejar}}

Javascript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include Javascript in their extensions using existing API methods.

There are a number of methods for including Javascript in your Joomla extensions; some of these are described below.

==Usage==

There are three methods for embedding JavaScript into your code using the Joomla API; [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script]. These methods should be called either in your component's View class (<yourcomponent>/views/<yourview>/view.html.php) or template script (<yourcomponent>/views/<yourview>/tmpl/<yourtemplate>.php or in the case of a module, in its template script (<yourmodule>/tmpl/<yourtemplate>.php).

===Inline Javascript===

Blocks of Javascript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline Javascript Declaration");
});
');
?>
</source>

===External Javascript===

Alternatively, you may wish to separate your Javascript into a separate file. Separating your Javascript into an external file can make your template code easier to read especially if the Javascript is lengthy or complex.

There are two ways to include a Javascript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed Javascript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed Javascript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (Javascript) from the main PHP code, ensures all Javascript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a Javascript file is included only once (I.e. there is no .js file duplication).

'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

== References ==
<references/>

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-09-17T13:19:42Z

Haydenyoung:

{{cookiejar}}

Javascript (also known as ECMAScript) is a scripting language primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include Javascript in their extensions using existing API methods.

There are a number of methods for including Javascript in your Joomla extensions; some of these are described below.

==Usage==

===Inline Javascript===

Blocks of Javascript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline Javascript Declaration");
});
');
?>
</source>

===External Javascript===

Alternatively, you may wish to separate your Javascript into a separate file. Separating your Javascript into an external file can make your template code easier to read especially if the Javascript is lengthy or complex.

There are two ways to include a Javascript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed Javascript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed Javascript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (Javascript) from the main PHP code, ensures all Javascript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a Javascript file is included only once (I.e. there is no .js file duplication).

'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

== References ==
<references/>

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-09-17T13:10:01Z

Haydenyoung:

{{cookiejar}}

Javascript (also known as ECMAScript) is a scripting language and is primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include Javascript in their extensions using existing API methods.

There are a number of methods for including Javascript in your Joomla extensions; some of these are described below.

==Usage==

===Inline Javascript===

Blocks of Javascript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline Javascript Declaration");
});
');
?>
</source>

===External Javascript===

Alternatively, you may wish to separate your Javascript into a separate file. Separating your Javascript into an external file can make your template code easier to read especially if the Javascript is lengthy or complex.

There are two ways to include a Javascript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed Javascript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed Javascript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (Javascript) from the main PHP code, ensures all Javascript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a Javascript file is included only once (I.e. there is no .js file duplication).

'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

== References ==
<references/>

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-09-17T13:09:11Z

Haydenyoung:

{{inuse}}
{{cookiejar}}

Javascript (also known as ECMAScript) is a scripting language and is primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include Javascript in their extensions using existing API methods.

There are a number of methods for including Javascript in your Joomla extensions; some of these are described below.

==Usage==

===Inline Javascript===

Blocks of Javascript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline Javascript Declaration");
});
');
?>
</source>

===External Javascript===

Alternatively, you may wish to separate your Javascript into a separate file. Separating your Javascript into an external file can make your template code easier to read especially if the Javascript is lengthy or complex.

There are two ways to include a Javascript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed Javascript into Joomla's index.php via the jdoc head tag:

<source lang="html4strict">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed Javascript includes would result in the index.php rendering the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html4strict">
<head>
...
<script type="text/javascript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (Javascript) from the main PHP code, ensures all Javascript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a Javascript file is included only once (I.e. there is no .js file duplication).

'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

== References ==
<references/>

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-09-17T13:07:59Z

Haydenyoung: Restructured this page and provided better documentation for including javascript in Joomla.

{{inuse}}
{{cookiejar}}

Javascript (also known as ECMAScript) is a scripting language and is primarily used in client-side web site development to extend and enhance an end-user's experience. Joomla provides developers with easy-to-use mechanisms to include Javascript in their extensions using existing API methods.

There are a number of methods for including Javascript in your Joomla extensions; some of these are described below.

==Usage==

===Inline Javascript===

Blocks of Javascript code can be declared directly within a component or module's display template using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration addScriptDeclaration] method:

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline Javascript Declaration");
});
');
?>
</source>

===External Javascript===

Alternatively, you may wish to separate your Javascript into a separate file. Separating your Javascript into an external file can make your template code easier to read especially if the Javascript is lengthy or complex.

There are two ways to include a Javascript file using the Joomla API. The first involves using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html JDocument] class' [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript addScript] method:

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

The second uses the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] class' [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method:

<source lang="php">
<?php
// Add the path parameter if the path is different than 'media/system/js/'
JHTML::script('sample.js', 'templates/custom/js/');
?>
</source>

==Description==
The Joomla API's [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration], [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] and [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods embed Javascript into Joomla's index.php via the jdoc head tag:

<source lang="html">
<jdoc:include type="head"/>
</source>

Using the [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScript JDocument::addScript] or [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] methods to embed Javascript includes would result in the index.php rendering the following HTML:

<source lang="html">
<head>
...
<script type="text/javascript" src="/media/system/js/sample.js"></script>
...
</head>
</source>

Calling the class method [http://api.joomla.org/1.5/Joomla-Framework/Document/JDocument.html#addScriptDeclaration JDocument::addScriptDeclaration] would render the following HTML:

<source lang="html">
<head>
...
<script type="text/javascript">
window.addEvent("domready", function() {
alert("Embedded block of JS here");
});
</script>
...
</head>
</source>

Using these methods is highly recommended as it clearly differentiates another scripting language (Javascript) from the main PHP code, ensures all Javascript is correctly embedded between the <head></head> tags and, in the case of JDocument::addScript and JHTML::script ensures that a Javascript file is included only once (I.e. there is no .js file duplication).

'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

== References ==
<references/>

[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Adding JavaScript

2012-09-17T10:29:51Z

Haydenyoung:

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

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

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

The above code must be added to your template's template.php file. Usually this file is located at (example): /templates/(theme name)/layouts/template.php

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

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

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

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

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

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

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

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

== References ==
<references/>

Setting up your workstation for Joomla! development

2012-03-12T07:40:38Z

Haydenyoung: Update xdebug and xampp versions. Removed information regarding xdebug from 2010.

{{RightTOC}}

== Introduction ==
This article provides detailed instructions for setting up your workstation for Joomla! development. Note that there are many possible configurations for doing Joomla! development. Any environment that supports Apache, MySql, PHP, and Subversion should work for writing Joomla! code and extensions.

This document provides step-by-step instructions for setting up and working with Apache, PHP, xdebug, Subversion. This instruction uses Eclipse IDE from chapter 4 and onwards. Please refer to the following links for other development tools:

* [[NetBeans overview]] which also references to a video tutorial of NetBeans

The example used and screenshots are for Windows XP, but the basic steps are the same for Linux.

== Install XAMPP ==
XAMPP is an easy-to-install package that bundles the Apache web server, PHP, XDEBUG, and the MySql database. This allows you to create the environment you need to run Joomla! on your local machine. The latest version of XAMPP is available at [http://www.apachefriends.org/en/xampp.html the XAMPP web site]. Downloads are available for Linux, Windows, Mac OS X and Solaris. Download the package for your platform.

''Important Note Regarding XAMPP and Skype:'' Apache and Skype both use port 80 as an alternative for incoming connections. If you use Skype, go into the Tools-Options-Advanced-Connection panel and deselect the "Use 80 and 443 as alternatives for incoming connections" option. If Apache starts as a service, it will take 80 before Skype starts and you will not see a problem. But, to be safe, disable the option in Skype.

'''Update'''

''As of August 5, 2010, XDebug has been updated (to version 2.1) which fixes some important bugs (for example, watching local variables for nesting functions). The latest XAMPP package (1.7.3) now includes this new version of XDebug. If you just want to update XDebug, you can download the latest module from [http://www.xdebug.org]. There is a handy website that tells you which XDebug binary you need, depending on your phpinfo() information [http://xdebug.org/find-binary.php here]. To use it, you just copy the output of your phpinfo() display and paste it into the form on the site.''

===Installation on Windows===

Installation for Windows is very simple. You can use the XAMPP installer executable (for example, "xampp-win32-1.7.3-installer.exe"). Detailed installation instructions for Windows are available [http://www.apachefriends.org/en/xampp-windows.html here].

For Windows, it is recommended to install XAMPP in "c:\xampp" (not in "c:\program files"). If you do this, your Joomla! (and any other local web site folders) will go into the folder "c:\xampp\htdocs". (By convention, all web content goes under the "htdocs" folder.)

If you have multiple http servers (like IIS) you can change the xampp listening port. In <xamppDir>\apache\conf\httpd.conf, modify the line Listen 80 to Listen [portnumber] (ex: "Listen 8080").

===Installation on Linux===

==== Install xammp ====
Open Terminal and enter:
sudo tar xvfz xampp-linux-1.7.7.tar.gz -C /opt
(replace ''xampp-linux-1.7.7.tar.gz'' with the version of xammp you downloaded).
It has been reported that the MYSQL database of xampp 1.7.4 does not work with Joomla 1.5.22

This installs ... Apache2, mysql and php5 as well as an ftp server.

''sudo /opt/lampp/lampp start''

and
''sudo /opt/lampp/lampp stop''

starts/stops all the services

==== Test your xammp localhost server ====
Open your Browser and point it to
http://localhost
The index.php will redirect to
http://localhost/xampp

There you will find instructions on how to change default usernames/passwords. On a PC that does not serve files to the Internet or LAN then changing the defaults is a personal decision.

==== Get Joomla ====
Download the latest Joomla instalation zip [http://www.joomla.org/download.html]

Unzip to your hard drive

Connect to localhost with an FTP client
Default
nobody
lampp

Create a folder for your Joomla on the localhost server

FTP the unpacked Joomla installation files to the newly created Joomla folder.

'''Important:'''
* The xammp installation sets the correct Ownership of the files and permissions.
* Using the '''CHOWN command''' will '''cause Ownership problems with xampp'''.
* '''Using nautilus''' to manipulate folders/files on localhost will '''cause Ownership problems with xampp'''.

'''Database info'''

Host
localhost

Default Database name
test

Default Database user
root

There is no default Password.

Administrator password is your choice.

Installing Sample Data is recommended for the novice user.

After installation delete the installation directory and point your Browser to:
http://localhost/yournewjoomlafolder
or
http://localhost/yournewjoomlafolder/administrator

==== Creating a link in the Ubuntu menu ====
'''To create a GUI for xammp connected to your Ubuntu menu'''

Open up the Terminal and type
sudo gedit /usr/share/applications/xampp-control-panel.desktop

Then copy the following into the gedit and save.

[Desktop Entry]
Encoding=UTF-8
Name=XAMPP Control Panel
Comment=Start and Stop XAMPP
Exec=gksudo "python /opt/lampp/share/xampp-control-panel/xampp-control-panel.py"
Icon=/usr/share/icons/Tango/scalable/devices/network-wired.svg
Terminal=false
Type=Application
Categories=GNOME;Application;Network;
StartupNotify=true

If the control panel fails to launch, try running the Exec command directly in the terminal:

gksudo "python /opt/lampp/share/xampp-control-panel/xampp-control-panel.py"

If you receive the error:

Error importing pygtk2 and pygtk2-libglade

Install the missing libraries:

sudo apt-get install python-glade2

=== XDebug PHP debugger ===

The XAMPP package for Linux does not includes the XDebug PHP debugger. To install XDebug on Debian or Ubuntu:

- Install the ''build-essential'' package:
<pre>sudo apt-get update
sudo apt-get install build-essential
sudo apt-get install autoconf</pre>
- Download the [http://www.apachefriends.org/en/xampp-linux.html development package] for your version of XAMPP and extract it over your existing installation:
<pre>sudo tar xvfz xampp-linux-devel-1.7.7.tar.gz -C /opt </pre>
- Build XDebug:
<pre>wget http://xdebug.org/files/xdebug-2.1.3.tgz
tar xzf xdebug-2.1.3.tgz
cd xdebug-2.1.3/
/opt/lampp/bin/phpize</pre>
After this you will have following output on your console…
<pre>Configuring for:
PHP Api Version: 20090626
Zend Module Api No: 20090626
Zend Extension Api No: 20090626 </pre>
<pre>./configure --with-php-config=/opt/lampp/bin/php-config
make
sudo make install </pre>
Then the output will be this.. please monitor the directory specified.
<pre>Installing shared extensions: /opt/lampp/lib/php/extensions/no-debug-non-zts-20090626/ </pre>

Create a folder in your temp folder that will holds the data file generated by XDebug:
<pre>sudo mkdir /opt/lampp/tmp/xdebug
sudo chmod a+rwx -R /opt/lampp/tmp/xdebug </pre>

Alternative installations:

Install using PHP extensions community library (PECL) bundled with xampp:
sudo /opt/lampp/bin/pecl install xdebug

On Ubuntu/Debian you can install using:
apt-get install php5-xdebug

(warning: this will also install Apache and PHP from apt repositories).

'''Warning for 64bit users'''

When compiling XDebug or installing via apt-get, you will receive an error when (re)starting xampp:

/opt/lampp/lib/php/extensions/no-debug-non-zts-20090626/xdebug.so: wrong ELF class: ELFCLASS64

This is because xampp runs 32bit but XDebug is 64bit. To overcome this problem, either make xdebug.so on a 32bit machine or download it from:

http://downloads.activestate.com/Komodo/releases/7.0.1/remotedebugging/Komodo-PHPRemoteDebugging-7.0.1-69775-linux-x86.tar.gz

and install it to /opt/lampp/lib/php/extensions:

wget http://downloads.activestate.com/Komodo/releases/7.0.1/remotedebugging/Komodo-PHPRemoteDebugging-7.0.1-69775-linux-x86.tar.gz
sudo tar xzf Komodo-PHPRemoteDebugging-7.0.1-69775-linux-x86.tar.gz
cp Komodo-PHPRemoteDebugging-7.0.1-69775-linux-x86/5.3/xdebug.so /opt/lampp/lib/php/extensions/no-debug-non-zts-20090626/xdebug.so

===Installation on Mac OS X===
Mac OS X actually includes an Apache server out-of-the-box, but most developers will prefer to use the integrated tools and configurability provided by XAMPP.

As with most programs on Mac, installation is a breeze. Visit [http://www.apachefriends.org/en/xampp-macosx.html Apache Friends - Mac OS X] for the universal binary download.

Once the file has finished downloading, just open the disk image, and drag the XAMPP folder to the "Applications" folder alias.

To start the server, open "XAMPP Control.app" and press the start button next to Apache.

=====A Little Troubleshooting=====
Many Mac users have a little difficulty at this stage when trying to set up another instance of Apache on their machine. If you cannot start XAMPP's Apache, you have two options:
<br />
'''You can change the listening port of XAMPP.''' In \Applications\XAMPP\xamppfiles\etc\httpd.conf, modify the line that says, "Listen 80" to Listen [portNumber]. E.g.:
<pre>Listen 8080</pre>

'''You can change the listening port of the pre-installed Apache server.''' In finder, go to "/etc" (CMD+SHIFT+G); from here you will be able to navigate through the normally hidden Apache files. Find the folder labeled Apache2, and edit the "http.conf" file. Modify the line that says, "Listen 80" to Listen [portNumber]. E.g.:
<pre>Listen 8080</pre>

''Note: If you choose to change the port of the pre-installed Apache server, you may need to restart your computer for changes to take effect. You will also have to authenticate as an administrator to change these files.''

===Test XAMPP Installation===

Once XAMPP is installed and you have started the Apache service with the XAMPP Control Panel tool, you can test it by opening your browser and navigating to "http://localhost". You should see the XAMPP welcome screen similar to the one below.

[[Image:xampp_phpinfo_screen.png]]

Select the link called "phpinfo()" in the left-hand menu. This will display a long screen of information about the PHP configuration, as shown below.

[[Image:xampp_phpinfo_conf_file.png]]

At this point, XAMPP is installed successfully. Notice the "Loaded Configuration File" which is highlighted in the screenshot above. We will be editing this file in the next section to configure XDebug.

==Edit PHP.INI File==

====For Windows====

Starting with version 1.7, XAMPP includes the XDebug PHP debugger, but it needs to be configured for use. To do that, we will edit the "php.ini" file to configure XDebug. The "Loaded Configuration File" in the screenshot above tells you what "php.ini" file is being used. For Windows, this is normally "c:\xampp\apache\bin\php.ini".

<blockquote>''Important note for Windows 7 & Vista users: As of April 2009 (XAMPP version 1.7.0), the file "php_xdebug.dll" that is included with XAMPP does not work with Windows 7 & Vista. The symptom of this problem is that the Apache server will stop if this version of XDebug is loaded. To correct this problem, download XDebug version "Xdebug 2.0.0 / 5.2 VC6" from the [http://xdebug.org/download.php XDebug website]. This will download a file called <code>php_xdebug-2.0.0-5.2.2.dll</code>. Save this file in the extensions folder (for example, <code>c:\xampp\php\ext</code>) and change the php.ini file to point to this file, as shown below. With this file, XDebug works correctly with Windows 7 & Vista, including 64-bit.''
</blockquote>

We need to edit this file to configure XDebug as follows:
# Find the line "implicit_flush" and set it as follows: <pre>implicit_flush = On</pre>
# Find the section called "[Zend]" and comment out all of the lines by putting a semi-colon (";") at the start of each line.
# Find the line: zend_extension = "c:\xampp\php\ext\php_xdebug.dll" and uncomment it out.
# Find the "[XDebug]" section and uncomment out all of the lines (except for the first comment line). For Windows, it should look like the example below:

<pre>
[XDebug]
;; Only Zend OR (!) XDebug
zend_extension_ts="C:\xampp\php\ext\php_xdebug.dll"
xdebug.remote_enable=true
xdebug.remote_host=localhost
xdebug.remote_port=10000
xdebug.remote_handler=dbgp
xdebug.profiler_enable=1
xdebug.profiler_output_dir="C:\xampp\tmp"
</pre>

For Windows 7 & Vista, you will use the file downloaded from the XDebug site. So the first line will be
<pre>
zend_extension_ts="C:\xampp\php\ext\php_xdebug-2.0.0-5.2.2.dll"
</pre>

For PHP version 5.3 or later, the "_ts" has been dropped, so the first line will read
<pre>
zend_extension="C:\xampp\php\ext\php_xdebug.dll"
</pre>

In XAMPP 1.7.3 on Windows 7 (currently not verified/tested with prior Windows versions), XDebug may not work correctly if the path to the DLL file is in quotes. In this case, the line should be
<pre>
zend_extension = C:\xampp\php\ext\php_xdebug-2.1.0-5.3-vc6.dll
</pre>

====For Linux====

We will edit the "php.ini" file to configure XDebug. The "Loaded Configuration File" in the screenshot above tells you what "php.ini" file is being used. For Linux, it will be something like "/opt/lampp/etc/php.ini".

We need to edit this file to configure XDebug as follows:
# Find the line "implicit_flush" and set it as follows: <pre>implicit_flush = On</pre>
# Add the following lines at the end:
<pre>;xDebug Configuration starts

zend_extension = /opt/lampp/lib/php/extensions/no-debug-non-zts-20090626/xdebug.so

xdebug.profiler_output_dir = "/tmp/xdebug/"
xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=10000
xdebug.remote_handler="dbgp"

;xDebug Configuration ends </pre>

'''If using php5-xdebug on Ubuntu'''
The xDebug Configuration detailed above can be appended to:
<pre>/etc/php5/apache2/conf.d/xdebug.ini </pre>
It should already contain the "zend_extension" variable and only needs the following variables added:
<pre>xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=10000
xdebug.remote_handler="dbgp"</pre>

'''Tip for users with LAN or remote servers:'''
<pre>xdebug.remote_host="localhost"</pre>
Should be set to the IP address of your Eclipse workstation [LAN users] or your public IP. For example:
<pre>xdebug.remote_host=192.168.0.199</pre>

====For Mac OS X====

XAMPP for Mac OS X includes the XDebug PHP debugger, but it needs to be added to the "php.ini" file so that XDebug runs when Apache is started. To do this, open up the php.ini file, located at "/Applications/XAMPP/xamppfiles/etc/php.ini".

We need to edit this file to configure XDebug as follows:
# Find the line "implicit_flush" and set it as follows: <pre>implicit_flush = On</pre>
# Add the following lines at the end:
<pre>;xDebug Configuration starts

zend_extension="/Applications/XAMPP/xamppfiles/lib/php/php-5.3.1/extensions/no-debug-non-zts-20090626/xdebug.so"

xdebug.profiler_output_dir = "/tmp/xdebug/"
xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=10000
xdebug.remote_handler="dbgp"

;xDebug Configuration ends </pre>

Be sure to navigate to the directory where you targeted the extension and check to see that the file path is correct. The folders in your XAMPP installation may be named differently.

The current (as of Sept 2010) version of the XAMPP binary for OS X contains the 2.0.4 version of Xdebug which will not let you see the variable data from included files when running xdebug. You can download a newer version from http://code.activestate.com/komodo/remotedebugging/. Unzip and copy one of the xdebug.so files to /Applications/XAMPP/xamppfiles/lib/php/php-5.3.1/extensions/no-debug-non-zts-20090626. As of Oct 2, 2010 this binary is still out of date (2.1beta3 rather than the stable 2.1) but it will show the variable data appropriately.

===Test XDebug Installation===
Now, we need to check that XDebug is installed correctly. To do this, we need to re-start XAMPP. In Windows, we can just browse to the "c:\xampp" folder in Windows Explorer and double-click the program "xampp-control.exe" to open the application shown below.

[[Image:Xampp-control.png]]

Press the "Stop" button for "Apache". The button with then read "Start". Press "Start" for Apache and wait a few seconds and the green "Running" message will again display. Then press "Exit" to close the application.

In Windows, if you get "ERROR: MySQL service not started [-1]", you may be able to correct this by going to c:\xampp\mysql and running mysql_uninstallservice.bat followed by mysql_installservice.bat.

In Linux, to restart XAMPP execute the command

<pre> sudo /opt/lampp/lampp restart </pre>

In Mac, open the "XAMPP Control" application, stop, and then start the Apache service again.

Once XAMPP has been restarted, open a browser and navigate to "http://localhost" to display the XAMPP welcome message (if you set XAMPP to listen to another port, you must append the port to the url; e.g.:"http://localhost:8080/"). Press the "phpinfo()" link again to display the PHP information screen. Scroll down to the lower part of the screen. You should see a section for "XDebug" as shown below.

[[Image:Phpinfo_xdebug.png]]

Look at the settings you entered in the "php.ini" file above. You should see these same settings in the xdebug display, as shown below.

[[Image:Xdebug settings.png]]

At this point, XDebug is set up correctly.

== Install Eclipse ==
===Install Java===
Eclipse is written in Java, so before you can install Eclipse, you need to make sure you have a recent version of Java running. Note that many Linux distributions include third-party Java runtimes (or JVM's for "Java Virtual Machine"), some of which don't work with Eclipse. The safest thing is to make sure you are running the Sun JRE (Jave Runtime Environment). You can download the latest Java version at [http://www.java.com/en/ www.java.com]. If you already have a recent version of the Sun JRE (for example, 1.5 or 1.6), you can skip this step.

Another option for Mac OS X Snow Leopard users is to download the OS X packages from http://www.open.collab.net/downloads/community/ for Subversion after you've installed Subclipse. This will install the appropriate JavaHL library to make the installed JVM work properly.

===Download Eclipse===
The next step is to download Eclipse. The easiest thing is to install the Eclipse PDT (PHP Development Tools) "all-in-one" bundle. This is available [http://www.eclipse.org/pdt/downloads/ here]. Download PDT 2.2.0 All In Ones / Eclipse PHP Package. There are downloads for Windows, Linux, and Mac OS X. When you download, you will be asked to pick a download mirror. At the time of this writing, the name of the Windows download is "eclipse-php-helios-win32.zip" and is 143mb.

Installing Eclipse is very easy -- you just unzip the file to a target directory. In Windows, it is best to use a third-party "zip" program to do the unzipping. In some cases, Windows Explorer will not correctly unzip this archive and Eclipse won't run correctly. One good option is 7 Zip, available [http://www.7-zip.org/ here].

I created a directory called "c:\eclipse_php" for the target. When the file is extracted, you will see a folder called "eclipse" and under that folder 5 folders and six files.

Eclipse will use the default Java JVM for your system. In Windows, this is normally the right one (from Sun). In some Linux distributions, the default JVM may be a third-party program that doesn't work correctly with Eclipse. In this case, you can specify the JVM to use by editing the eclipse.ini file in the eclipse folder as as follows, substituting the correct path to your installed Sun version of the Java JVM:
<pre>
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
512M
-vm
/usr/lib/jvm/java-1.5.0-sun/jre/bin/java
-vmargs
-Xms512m
-Xmx512m
</pre>
Note that the path to the JVM goes on the line below the "-vm". Also note that the file ends with a blank line.

At this point, you should be able to start up Eclipse. Just find the "eclipse.exe" file inside the eclipse folder and double-click to execute it. In Linux: /path/to/your/eclipse/folder/eclipse

==== Eclipse download for Ubuntu====
:Eclipse can be found in the Ubuntu Software Centre (or Synaptic Package Manager) and when installed from there it places a menu item in the 'Programming' menu.

===Alternative (Easy) Installation===

An alternative way to install Eclipse with the phpEclipse environment is to use [http://www.easyeclipse.org/site/distributions/php.html EasyEclipse for PHP]. This includes everything you need (including Subclipse) in one simple install for most platforms. The following instructions are not applicable for EasyEclipse for PHP.

===Create an Eclipse Workspace===
The first time you launch Eclipse, the screen below displays.

[[Image:eclipse_workspace_default.png]]

Before we can start using Eclipse, we need to create a workspace. This is the folder where all of the Eclipse files and project information will be stored. Since we will be working on web-based projects, we want our project PHP and HTML files to be visible to XAMPP. So we will create our workspace in the "c:\xampp\htdocs" folder (in linux: "/opt/lampp/htdocs").

To do this, press the Browse button, navigate to the "c:\xampp\htdocs" or "/opt/lampp/htdocs" folder, and press the New Folder button. Create a directory called something like "joomla_development" and make sure it says the same thing in the Folder field. (You can click on a different folder and then click on the new folder to get the name in the Folder field.) The screen should look like the one below.

[[Image:eclipse_workspace_new.png]]

Press OK. Then we go back to the Workspace Launcher, as shown below.

[[Image:Eclipse_workspace_created.png]]

Before pressing OK, you can check the box so that you won't need to go through this screen each time you start Eclipse.

Now you should see a splash screen and then a "Welcome to Eclipse" screen, as shown below.

[[Image:Eclipse_welcome.png]]

Close this window and the normal Eclipse workbench will display, as shown below.

[[Image:Eclipse_workbench.png]]

At this point, Eclipse is installed.

== Configure Eclipse ==
===Set Newline Character (Windows/Mac Only)===
Let's do one final configuration setting, which only applies if you are running Windows or Mac. As you may know, Windows and Linux use different characters to terminate lines in text files. Since the Joomla! source code repository is on a Linux machine, we need to tell Eclipse to create Linux-style patch files. Although Mac is Unix based, for the sake of standardization, Mac users should use these settings too. To do this, we'll navigate to Window / Preferences, expand the General tree, and select "Workspace". This is shown in the screenshot below.

[[Image:Workspace_preferences.png]]

Make two changes. Select Other / UTF-8 for the Text file encoding and Other / Unix for the New text file line delimiter, as shown above. Press OK.

At this point, Eclipse is set up and we can start working with PHP files.

==Configure XDebug==
''Note: Getting XDebug to work on some workstations can be difficult. XDebug is NOT required to be able to use Eclipse for PHP development. If you are new to Eclipse for PHP, you can skip this section and use Eclipse without XDebug if desired. You can install XDebug later if you need it.''

===Edit XDebug Eclipse Settings===
The first thing we need to do is to tell Eclipse to use the XDebug we installed earlier. Navigate to Window / Preferences, as shown below. (Mac users: Eclipse / Preferences...)

[[Image:Window_preferences_menu.png]]

This will open the Preferences dialog. Expand the PHP node on the left and select "Debug" to display the screen below.

[[Image:Debug_preferences.png]]

Notice that the "Break at first line" box is checked. This means that the debugger will always break or suspend execution at the first line of code. We'll see this later on when we run the debugger.

Select XDebug for the PHP Debugger. You might get the message below.

[[Image:Debug_port_message.png]]

If so, just ignore it and press OK. (We're going to change the ports now anyway.)

In order to ensure compatability with php.ini, press the "Configure" link for the PHP Debugger to display the screen below.

[[Image:Installed_debuggers.png]]

Highlight the XDebug line and press Configure to display the screen below.

[[Image: Xdebug port.png]]

Change the port number to "10000" as shown, to match what we put in the "php.ini" file earlier. (I also changed the port number for the Zend debugger to "10001" just to get rid of the port 9000 warning message.)

On some systems, you may get Javascript errors like the following: <blockquote>''A Runtime Error has occurred. Do you wish to Debug? Line: 1 Error: Syntax error''</blockquote>

If so, you can eliminate these messages by changing the "Output Capture Settings / Capture stdout" from "copy" to "off".

===Set Debug Options===
Next, we need to set some options. Select the menu Window / Preferences to open the Preferences dialog. Expand PHP and Debug and select "Workbench Options", as shown below.

[[Image:workbench_options.png]]

Change the settings as shown above. You can experiment with these settings to make Eclipse best for you.

Next, select the "PHP Servers" item on the tree to display the screen shown below.

[[Image:php_servers.png]]

Select the "Default PHP Web Server" (the only one in the list) and press the Edit button to display the Edit Server dialog shown below.

[[Image:edit_server.png]]

Recall that we created our workspace, called "joomla_development", under the "c:\xampp\htdocs" directory. So the URLs to the HTML and PHP files in our project will need to include the "joomla_development" directory name (for example, "http://localhost/joomla_development/Test Project/test.php"). If we change this here, Eclipse will create the URLs for us automatically. So complete the screen as shown above and press OK.

=== Test XDebug ===
Now we finally get to have some fun. We're going to write a simple PHP script and run and debug it to test that Eclipse is set up correctly. If you are already familiar with Eclipse, you can just skip over this section. If not, we'll go through some basics.

===Eclipse Terminology===
First, some quick Eclipse terminology. In Eclipse, we talk about the workbench, perspectives, and views. The workbench is just the whole screen. It has an edit area, where we will edit our PHP files, and a series of views around the outside. A view is an area that displays information about a file or some other resource. A perspective is just a pre-packaged layout of views designed for a specific purpose. When we're writing PHP programs, two perspectives are of interest: the PHP perspective and the PHP Debug perspective.

Let's open the PHP perspective. We can select Window / Open Perspective / PHP, as shown below.

[[Image:Php_perspectieve_menu.png]]

Now the workbench displays a different set of views, including the PHP Explorer, in the upper left, and three views in the lower left. Note that Eclipse has pretty good Help, which you can access by pressing F1 or selecting Help / Help Contents from the menu. The screen below shows some of the contents available, including Getting Started, Basic Tutorials, and other useful information.

[[Image:Php_help.png]]

===Create a Project===
Remember that we created a workspace when we launched Eclipse. Before we can write any code, we need to create a project. A project stores a group of related program files. For example, the entire Joomla! application will be one project. We're going to create a test project that we can use to test our setup. We'll select the menu File / New / PHP Project, as shown below.

[[Image:New_project_1.png]]

This will open the first screen in the new project wizard, shown below. Enter the project name, in this case "Test Debug", and press Finish.

[[Image:New_project_2.png]]

Our new project will now show in the PHP Explorer view.

===Create and Run a PHP File===
Next, we need to create a PHP file. Select the "Test Debug" project, right click, select New / PHP File, as shown below.

[[Image:New_php_file.png]]

Press the Browse button and select the "Test Project" for the source folder. The New PHP File wizard will display, as shown below. Enter "test.php" for the file name, and press Finish.

[[Image:New_php_file_2.png]]

An empty PHP file will now display in the editor. Enter the code shown below, and press the Save button in the upper left toolbar to save the "test.php" file.

[[Image:Php_test_file.png]]

Now, we're going to execute the script. We'll select the file "test.php" and right-click and select Run As / PHP Web Page, as shown below.

[[Image:Run_as_menu.png]]

The script will be run in your default browser, and should display as shown below.

If your php files are set by default to open in a text editor, you may get an error. If so, go to Window/Preferences/General/Web Browser and explicitly select your preferred option.

[[Image:Run_test_php.png]]

Note that the "phpinfo()" command displays information about your PHP configuration. This is the same screen we saw earlier, when we clicked on the "phpinfo()" link in the XAMPP home page.

===Debug a PHP File===
Now, let's try debugging this script. Again, select the "test.php" file and right-click, but this time select "Debug As / PHP Web Page", as shown below.

[[Image:Debug_as_web_page.png]]

This time, the browser opens and suspends. (Note: If Eclipse does not suspend at the first line, try closing Eclipse and re-starting it.)

Go back to Eclipse and open the PHP Debug perspective by selecting Window / Open Perspective / PHP Debug, as shown below.

[[Image:Open_debug_perspective.png]]

This opens the Debug Perspective, with the "test.php" file suspended, as shown below.

[[Image:Debug_perspective.png]]

Recall from earlier that the "Break at first line" option was selected. This is why the debugger has suspended here, on the first line in our program.

There is a lot going on in this screen. The Debug view in the upper left shows the "frame" information. In this case, we are suspended on line 2. The editor window is now in the middle of the screen. A small blue arrow shows where the program is suspended.

In the upper right is the Variables view. This shows the variables that are in scope at this point in the program.

The toolbar in the Debug perspective is important. The tools are labeled below.

[[Image:Debug_toolbar.png]]

*Resume: Resume execution until the next breakpoint or until the program is finished.
*Terminate: Terminate the debug session. It is important to always terminate the session before trying to run a new session. This must be done even if the browser is closed.
*Step Into: Used to step into a called function.
*Step Over: Used to step to the next line.

If you are familiar with debuggers from other IDEs, these commands will probably be familiar. If not, you can read more about it in the Eclipse help documentation and experiment on your own.

To finish, let's press the Step Over button. The Debug view and editor now show that we are on line 3. Note that this means that we are about to execute line 3. Also, note the change in the Variables view. Now the variable $mytest has a value of "this is a test" because line 2 has now executed.

Press Step Over again. Now we're on line 4. Look at the browser window. It should now say "this is a test", since now line 3 has executed. Press Step Over again and look at the browser window. Now it shows the output of "phpinfo()".

Finally, press Resume. Notice that the program is no longer suspended and the browser no longer shows that it is waiting to complete the page. The script has completed, but our debugger session is still running.

To close the debugger, select the "Remote Launch" in the Debug view and press the Terminate button. Two things happen. In the browser, a new window launches showing a terminate message. In Eclipse, the PHP perspective automatically displays. This is because we set this in the Debug preferences.

Now we had to manually open the Debug perspective, which is an extra step. We can tell Eclipse to do this automatically for us. We just go to Window / Preferences / Run/Debug / Perspectives, select "PHP Web Page", and check "Always" for "Open the associated perspective when launching", as shown below.

[[Image:Php_debug_preferences.png]]

At this point, the XDebug is working correctly in Eclipse.

===Troubleshooting Tips===
====Debugger Doesn't Stop at Breakpoint====
This can happen if another application is using the port you chose for XDebug. If you experience this problem, try changing the port from 10000 to 10002 or some other value. You have to change the port number in your <code>php.ini</code> file as well as in the Eclipse preferences. You also have to re-start your Apache server to make the change effective.

== Install Eclipse Subversion ==
Before we can start coding in Joomla!, we need to be able to work with the Subversion (SVN) source code repository. Subversion is a third-party plugin for Eclipse, so we need to use the Eclipse Update Manager to install it. To do this, navigate to Help / Software Updates, as shown below.

[[Image:Eclipse_help_software_updates.png]]

The Software Updates and Add-ons dialog will display. Select the "Available Software" tab. The list of available update sites will display. Press the "Add Site" button to display the Add Site dialog. Enter "http://subclipse.tigris.org/update_1.6.x" as the URL, as shown below.

[[Image:Subclipse_update_site_1.6.png]]

Press OK and the "Available Software" tab should again display, this time with additional options from the Subclipse site. Select all Subclipse options as shown below. Then press the "Install" button.

[[Image:Eclipse_install_update_1.6.png]]

Eclipse will work for a minute and then display the Install window, shown below. Press the "Next" button. A "Review Licenses" window appears. Click "I accept the terms of the license agreements". Now click finish.

[[Image:Eclipse_install_update2_1.6.png]]

After the files have been downloaded and installed, Eclipse will show the message below recommending that you restart Eclipse. Press "Yes" and Eclipse will restart.

[[Image:Eclipse_install_update3.png]]

Once Eclipse has restarted, we can test that the Subversion plugin is working. Select File / Import as shown below.

[[Image:File_import.png]]

Then expand the SVN element in the tree. You should see an option called "Checkout Projects from SVN", as shown below.

[[Image:Svn_checkout_projects.png]]

At this point, the plugin has been installed successfully. Press "Cancel" to cancel the import. (We'll import the Joomla! project in the next section.)

== Setting up your workstation for Joomla! development -- Part 2 ==
This article is continued here: [[Setting up your workstation for Joomla! development -- Part 2]]. This includes checking out the Joomla! source code, debugging Joomla! from Eclipse, creating patch files, and Eclipse tips and tricks.

[[Category:Development]]
[[Category:Bug Squad]]