Joomla! Documentation - User contributions [en]

Subform form field type

2017-06-10T11:54:01Z

Haydenyoung: Some language syntax and spelling corrections

<noinclude><languages /></noinclude>
<translate>
The '''subform''' form field type provides a method for using XML forms inside one another or reuse forms inside an existing form.</translate>
<translate>
If attribute '''multiple''' is set to '''true''' then the included form will be '''repeatable'''.</translate>

<translate>
The Field has two "predefined" layouts for displaying the subform as either a '''table''' or as a '''div''' container, as well as support for custom layouts.</translate>

<translate>
An example XML '''field''' definition for '''single''' mode:</translate>

<source lang="xml"><field name="field-name" type="subform"
formsource="path/to/exampleform.xml"
label="Subform Field" description="Subform Field Description" /></source>

<translate>
An example XML '''field''' definition for '''multiple''' mode:</translate>

<source lang="xml"><field name="field-name" type="subform"
formsource="path/to/exampleform.xml" multiple="true"
label="Subform Field" description="Subform Field Description" /></source>

<translate>
Example XML of ''exampleform.xml''</translate>

<source lang="xml"><?xml version="1.0" encoding="UTF-8"?>
<form>
<field name="example_text" type="text" label="Example Text" />
<field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
</form></source>

<translate>
An example XML of ''exampleform.xml'' with ''fieldsets''</translate>

<source lang="xml"><?xml version="1.0" encoding="UTF-8"?>
<form>
<fieldset name="section1" label="Section1">
<field name="example_text" type="text" label="Example Text" />
<field name="example_textarea" type="textarea" label="Example Textarea" cols="40" rows="8" />
</fieldset>
<fieldset name="section2" label="Section2">
<field name="example_list" type="list" default="1" class="advancedSelect" label="Example List">
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
</fieldset>
</form></source>

<translate>

Field attributes:</translate>
<translate>

* '''type''' (mandatory) must be ''subform''.</translate>
<translate>

* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>

* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>

* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>

* '''required''' (optional) The field must be filled before submitting the form.</translate>
<translate>

* '''message''' (optional) The error message that will be displayed instead of the default message.</translate>
<translate>

* '''default''' (optional) is the default value, JSON string.</translate>
<translate>

* '''formsource''' (mandatory) the form source to be included. A relative path to the xml file or a valid form name which can be found by ''JForm::getInstance()''.</translate>
<translate>

* '''multiple''' (optional) whether the subform fields are repeatable or not.</translate>
<translate>

* '''min''' (optional) count of minimum repeating in multiple mode. Default: ''0''.</translate>
<translate>

* '''max''' (optional) count of maximum repeating in multiple mode. Default: ''1000''.</translate>
<translate>

* '''groupByFieldset''' (optional) whether to group the subform fields by its fieldset (''true'' or ''false''). Default: ''false''.</translate>
<translate>

* '''buttons''' (optional) which buttons to show in multiple mode. Default: ''add,remove,move''.</translate>
<translate>

* '''layout''' (optional) the name of the layout to use when displaying '''subform''' fields.</translate>

<translate>

Available layouts:</translate>
<translate>

* '''joomla.form.field.subform.default''' render the subform in a div container, without support of repeating. Default for single mode.</translate>
<translate>

* '''joomla.form.field.subform.repeatable''' render the subform in a div container, used for multiple mode. Support groupByFieldset.</translate>
<translate>

* '''joomla.form.field.subform.repeatable-table''' render the subform as a table, used for multiple mode. Supports groupByFieldset. By default each field is rendered as a table column, but if ''groupByFieldset=true'' then each fieldset is rendered as a table column.</translate>

<translate>

'''Be aware'''</translate>

<translate>

If your field in the subform has additional JavaScript logic then it may not work in '''multiple''' mode, because do not see the fields which added by the subform field dynamically. If it happened then you need to adjust your field to support it.</translate>
<translate>

Next example may help:</translate>

<source lang="javascript">jQuery(document).ready(function(){
... here the code for setup your field as usual...

jQuery(document).on('subform-row-add', function(event, row){
... here is the code to set up the fields in the new row ...
})
});
</source>

<translate>
Because of this some extra Joomla! fields may not work for now.


Subform not provide the Validation and Filter.</translate>

<translate>
== Example == 
</translate>

<translate>
'''Problem '''</translate>

<translate>
After adding new rows selects are not "chosen".</translate>
<translate>
See screenshot to get the idea of the problem http://static.xscreenshot.com/2016/10/29/18/screen_6917fc3c8d3c5d679b6442ff249a7b5f</translate>

<translate>

'''Solution '''
</translate>

<translate>
Here is an example how to reinit jQuery Chosen on newly added repeated rows:</translate>

<source lang="javascript">jQuery(document).ready(function(){
jQuery(document).on('subform-row-add', function(event, row){
jQuery(row).find('select').chosen();
})
});
</source>

<translate>
Or a PHP snippet to be used in e.g. your plugin in **onBeforeCompileHead** method or in your component view.</translate>

<source lang="php">
$doc = JFactory::getDocument();
$js = '
jQuery(document).on(\'subform-row-add\', function(event, row){
jQuery(row).find(\'select\').chosen();
})
';
$doc->addScriptDeclaration($js);
</source>

<translate>
So newly added rows now are "chosen" now http://static.xscreenshot.com/2016/10/29/18/screen_8f7dc7709899bac7a43926828e504519</translate>

<translate>
=== See also === </translate>
<translate>

* [[S:MyLanguage/Standard form field types|List of standard form field types]]
</translate>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

Package

2015-08-21T20:36:34Z

Haydenyoung: Fix spelling.

<noinclude><languages /></noinclude>
<translate>
== Note on component dependent modules== 


Sometimes modules (or plugins etc.) use a component's models and helpers and such. In these occasions it would be nice to be able to package your module in this way that it gets uninstalled when the component itself gets uninstalled. This is called dependency management which has been desired in joomla but hasn't been done yet.
It is suggested to follow the standards and just using a package as is described below.
</translate>

<translate>
== What is a package? == 


A package is a extension that is used to install multiple extensions in one go. This is used if you have for example a component and a module that are depending on each other. Combining them in a package will let the user install and uninstall both extensions in one go. Package extensions can be used with Joomla {{JVer|2.5}} and higher.
</translate>

<translate>
== How do I create a package? == 


A package extension is created by zipping all zip files of the extensions together with a xml manifest file. For example if you have a package composed by:
</translate>

<translate>

* '''component''' helloworld
* '''module''' helloworld
* '''library''' helloworld
* '''system plugin''' helloworld
* '''template''' helloworld


The package should have the following tree in your zipfile:
</translate>

-- pkg_helloworld.xml
-- packages <dir>
|-- com_helloworld.zip
|-- mod_helloworld.zip
|-- lib_helloworld.zip
|-- plg_sys_helloworld.zip
|-- tpl_helloworld.zip

<translate>

The pkg_helloworld.xml could have the following contents:
</translate>

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<extension type="package" version="1.6" method="upgrade">
<name>Hello World Package</name>
<author>Hello World Package Team</author>
<creationDate>May 2012</creationDate>
<packagename>helloworld</packagename>
<version>1.0.0</version>
<url>http://www.yoururl.com/</url>
<packager>Hello World Package Team</packager>
<packagerurl>http://www.yoururl.com/</packagerurl>
<description>Example package to combine multiple extensions</description>
<update>http://www.updateurl.com/update</update>
<files folder="packages">
<file type="component" id="com_helloworld" >com_helloworld.zip</file>
<file type="module" id="helloworld" client="site">mod_helloworld.zip</file>
<file type="library" id="helloworld">lib_helloworld.zip</file>
<file type="plugin" id="helloworld" group="system">plg_sys_helloworld.zip</file>
<file type="template" id="helloworld" client="site">tpl_helloworld.zip</file>
</files>
</extension>
</source>

<translate>

When you zip this and try to install it, you will see that every extension will be installed. Also the package will be visible in the extension list to uninstall all the extension of this package.
</translate>

<translate>

Remember to use the package uninstaller instead of individual subpackage uninstallers to avoid orphan extension entries in the extension manager.
</translate>

<translate>
=== Id= <file id="not_arbitrary"> === 
The id element in <file ..> tag are NOT arbitrary!. The "id=" should be set to the value of the "element" column in the "#__extensions" table. If they are not set correctly, upon uninstalling of the package the children ( <file> ) will NOT be found and uninstalled.
</translate>

<translate>
=== Manifest filename and packagename === 
The naming of the manifest file and the ability to uninstall the package file itself are closely related.
The manifest file must have a "pkg_" prefix, the remainder of the manifest name ( without .xml extension ) is to be used as <packagename>. Or, the other way around, a package you want to identify as "blurpblurp_J3" get that as its <packagename> and should be in a manifest file named "pkg_blurpblurp_J3.xml". Failure to do so will make it impossible to uninstall the package itself.

=== Extension tag === 
As of Joomla 3.4, you should include method="upgrade" in the <extension> tag if you wish for your package to succeed in updating itself on subsequent installations.


The version attribute of the <extension> tag should be set to the minimum supported version of Joomla for this package. For example, if your package only supports Joomla 3.2 and above set this to 3.2.
</translate>

<translate>

[[Category:Extensions]]
</translate>

Display error messages and notices

2014-06-20T12:36:31Z

Haydenyoung:

{{RightTOC}}
Errors, warnings and notices can be displayed from any component, module, plugin or template using the methods outlined below.
<source lang="php">
// Get a handle to the Joomla! application object
$application = JFactory::getApplication();

// Add a message to the message queue
$application->enqueueMessage(JText::_('SOME_ERROR_OCCURRED'), 'error');

/** Alternatively you may use chaining */
JFactory::getApplication()->enqueueMessage(JText::_('SOME_ERROR_OCCURRED'), 'error');
</source>

The second argument to the [http://api.joomla.org/11.4/Joomla-Platform/Application/JApplication.html#enqueueMessage enqueueMessage] function is the type of the message. The default is 'message', but 'error' results in a different style for the message. The message will be displayed in place of a special <tt>jdoc:include</tt> statement in your template. Place the following in your template at the location where you want messages to appear.
<source lang="php">
<jdoc:include type="message" />
</source>

== Message ==
<div style="background-color: #c3d2e5; color: #0055bb; border-top: 3px solid #84a7db; border-bottom: 3px solid #84a7db; padding-left: 1em; font-weight: bold;">
Message
</div>
<source lang="php">
JFactory::getApplication()->enqueueMessage('Message');
</source>

== Notice ==

<div style="background-color: #efe7b8; color: #c00; border-top: 3px solid #f0dc7e; border-bottom: 3px solid #f0dc7e; padding-left: 1em; font-weight: bold;">
Notice
</div>
<source lang="php">
JError::raiseNotice( 100, 'Notice' );
</source>

== Warning ==

<div style="background-color: #e6c0c0; color: #c00; border-top: 3px solid #DE7A7B; border-bottom: 3px solid #DE7A7B; padding-left: 1em; font-weight: bold;">
Warning
</div>
<source lang="php">
JError::raiseWarning( 100, 'Warning' );
</source>

== Error ==
<source lang="php">
JError::raiseError( 4711, 'A severe error occurred' );
</source>

== Joomla! 3.x is bootstrapped ==
Since Joomla! {{JVer|3.x}} uses bootstraped templates, the messages will use the standard bootstrap CSS styles for Alerts.

See: http://getbootstrap.com/2.3.2/components.html#alerts

The general syntax remains:

<source lang="php">
JFactory::getApplication()->enqueueMessage('Your Message', 'type');
</source>

Where '''type''' can be one of

* 'warning' - yellow
* 'notice' - blue
* 'error' - red
* 'message' (or empty) - green

== See also ==
* [http://api.joomla.org/11.4/Joomla-Platform/Error/JError.html JError on api.joomla.org]
* [http://api.joomla.org/11.4/Joomla-Platform/Application/JApplication.html JApplication on api.joomla.org]

<noinclude>[[Category:Development]]</noinclude>
[[Category:Tutorials]][[Category:Component Development]]

J2.5:Accessing the database using JDatabase

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.

J2.5:Accessing the database using JDatabase

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.

J2.5:Accessing the database using JDatabase

2012-11-20T15:21:29Z

Haydenyoung: /* Using SQL */

J2.5:Accessing the database using JDatabase

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>

J2.5:Accessing the database using JDatabase

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>

J2.5:Accessing the database using JDatabase

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

J2.5:Accessing the database using JDatabase

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

J2.5:Accessing the database using JDatabase

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

J2.5:Accessing the database using JDatabase

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

J2.5:Accessing the database using JDatabase

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

J2.5:Accessing the database using JDatabase

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

J2.5:Accessing the database using JDatabase

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

J3.x:Accessing the database using JDatabase

2012-11-20T07:26:00Z

Haydenyoung: 3.0 documentation.

J2.5:Accessing the database using JDatabase

2012-11-20T06:33:03Z

Haydenyoung: /* Inserting a Record */ Inserting a record using a chained query.

J2.5:Accessing the database using JDatabase

2012-11-20T04:27:42Z

Haydenyoung: /* The Connection */ Links to various useful classes and methods.

J2.5:Accessing the database using JDatabase

2012-11-20T04:13:13Z

Haydenyoung: /* Selecting Records from Multiple Tables */ Chaining a query with multiple joins.

J2.5:Accessing the database using JDatabase

2012-11-19T14:50:12Z

Haydenyoung: /* Selecting Records from Multiple Tables */ A chained multi-table query.

J2.5:Accessing the database using JDatabase

2012-11-19T13:54:24Z

Haydenyoung: /* Selecting Records from a Single Table */ Example of chaining.

J2.5:Accessing the database using JDatabase

2012-11-19T12:35:14Z

Haydenyoung: /* Selecting Records from a Single Table */ Example of a simple query.

J2.5:Accessing the database using JDatabase

2012-11-16T14:04:00Z

Haydenyoung: /* The Query */ Introduction to query chaining.

J2.5:Accessing the database using JDatabase

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+.

J2.5:Accessing the database using JDatabase

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.

J2.5:Accessing the database using JDatabase

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

J2.5:Accessing the database using JDatabase

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

J1.5:Accessing the database using JDatabase

2012-10-28T02:12:16Z

Haydenyoung:

J1.5:Accessing the database using JDatabase

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