Joomla! Documentation - User contributions [en]

Accessing the database using JDatabase

2009-12-24T01:06:18Z

Mkopinsky: /* Preparing the query */

J1.5:Developing a MVC Component/Using the Database

2009-12-23T21:24:50Z

Mkopinsky: /* Creating the Installation SQL File */

== Introduction ==

In the first two tutorials, we showed you how to build a simple model-view-controller component. We had one view which retrieved data from a model (which was created in the 2nd tutorial). In this tutorial, we will be working with the model. Instead of the data being hard coded in the model, the model will retrieve the data from a table in the database.

This tutorial will demonstrate how to use the JDatabase class to retrieve data from the database.

== Retrieving the Data ==

Our model currently has one method: getGreeting(). This method is very simple - all it does is return the hard-coded greeting.

To make things more interesting, we will load the greeting from a database table. We will demonstrate later how to create an SQL file and add the appropriate code to the XML manifest file so that the table and some sample data will be created when the component is installed. For now, we will simply replace our return statement with some code that will retrieve the greeting from the database and return it.

The first step is to obtain a reference to a database object. Since Joomla! uses the database for its normal operation, a database connection already exists; therefore, it is not necessary to create your own. A reference to the existing database can be obtained using:

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

JFactory is a static class that is used to retrieve references to many of the system objects. More information about this class can be found in the API documentation [http://docs.joomla.org/JFactory JFactoryAPI].

The method name (getDBO) stands for get DataBase Object, and is easy and important to remember.

Now that we have obtained a reference to the database object, we can retrieve our data. We do this in two steps:

* store our query in the database object
* load the result

Our new getGreeting() method will therefore look like:

<source lang="php">function getGreeting()
{
$db =& JFactory::getDBO();

$query = 'SELECT greeting FROM #__hello';
$db->setQuery( $query );
$greeting = $db->loadResult();

return $greeting;
}</source>

hello is the name of the table that we will create later, and greeting is the name of the field that stores the greetings. If you are not familiar with SQL, it would be helpful to take a tutorial or a lesson to get yourself up to speed. One such tutorial can be found at [http://www.w3schools.com/sql/default.asp w3schools].

The $db->loadResult() method will execute the stored database query and return the first field of the first row of the result. See [http://api.joomla.org/Joomla-Framework/Database/JDatabase.html JDatabase API reference] for more information about other load methods in the JDatabase class.

== Creating the Installation SQL File ==

The Joomla! installer has built-in support for executing queries during component installation. These queries are all stored in a standard text file.

We will have three queries in our install file: the first will drop the table in case it already exists, the second will create the table with the appropriate fields, and the third will insert the data.

Here are our queries:

<source lang="mysql">DROP TABLE IF EXISTS `#__hello`;

CREATE TABLE `#__hello` (
`id` int(11) unsigned NOT NULL auto_increment,
`greeting` varchar(25) NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8;

INSERT INTO `#__hello` (`greeting`) VALUES ('Hello, World!'), ('Bonjour, Monde!'), ('Ciao, Mondo!');</source>

You might find the prefix on the table names rather odd. Joomla! will replace this prefix with the prefix used by the current install. For most installs, this table will become jos_hello. This allows multiple installs of Joomla! to use the same database, and prevents collisions with other applications using the same table names (i.e. two applications might share a database, but might both require a 'users' table. This convention avoids problems.)

We have specified two fields in our database. The first field is id, and is called the 'primary key'. The primary key of a database table is a field that is used to uniquely identify a record. This is often used to lookup rows in the database. The other field is greeting. This is the field that stores the greeting that is returned from the query that we used above.

We will save our installation queries in a file called install.sql. (Note: In the original version of this file, install.utf.sql was used - this was incorrect. Also see [[Talk:Developing_a_Model-View-Controller_Component_-_Part_3_-_Using_the_Database | discussion]].)

=== Creating the Uninstall SQL File ===

Though we might hope that people will never want to "uninstall" our component, it is important that if they do, nothing is left behind after uninstalling our component. Joomla! will look after deleting the files and directories that were created during the "install", but we must manually include queries that will remove any tables that were added to the database. Since we have only created one table, we only need one query:

<source lang="mysql">DROP TABLE IF EXISTS `#__hello`;</source>

We will save this uninstall query in a file called uninstall.sql. (Note: In the original version of this file, uninstall.utf.sql was used - this was incorrect. Also see [[Talk:Developing_a_Model-View-Controller_Component_-_Part_3_-_Using_the_Database | discussion]].)

== Updating our Install File ==

We need to change a few things in our install.xml file. First, we need to add our two new sql files to the list of files to install. Secondly, the SQL install files have to be placed in the admin directory. Thirdly, we need to tell the installer to execute the queries in our files on install and uninstall.

Our new file looks like this:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>3.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>models/hello.php</filename>
<filename>models/index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

<install>
<sql>
<file charset="utf8" driver="mysql">install.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file charset="utf8" driver="mysql">uninstall.sql</file>
</sql>
</uninstall>

<administration>

<menu>Hello World!</menu>


<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>

</administration>
</install></source>

You will notice two attributes present on the <file> tags within the <install> and <uninstall> sections: charset and driver. The charset is the type of charset to use. The only valid charset is utf8. If you want to create install files for non-utf8 databases (for older version of MySQL), you should omit this attribute.

The driver attribute specifies which database the queries were written for. Currently, this can only be mysql, but in future versions of Joomla! there may be more database drivers available.

== Conclusion ==

We now have a component that takes advantage of both the Joomla! MVC framework classes and the JDatabase classes. You are now able to write MVC components that interact with the database and can use the Joomla! installer to create and populate database tables.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden

== Download ==

The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8110/29435/com_hello3_01.zip com_hello3_01]

[[Category:Database]]
[[Category:Development]]