Archived

Difference between revisions of "Creating a simple module/Using the Database"

From Joomla! Documentation

< Archived:Creating a simple module
(11 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
== Creating a table on install ==
 
== Creating a table on install ==
 
To create the xml table on install we are going to add the following lines into ''mod_helloworld.xml'':
 
To create the xml table on install we are going to add the following lines into ''mod_helloworld.xml'':
<source type="xml">
+
<source lang="xml">
 
<install>
 
<install>
 
     <sql>
 
     <sql>
Line 33: Line 33:
 
*The ''update'' tag will update the databases if a database needs to be amended when updating the module.
 
*The ''update'' tag will update the databases if a database needs to be amended when updating the module.
  
Note that we have both schemas for mysql and microsoft SQL - again you can choose to tailor your module for one or both of these systems.
+
Note that we have both schemas for MySQL and Microsoft SQL - again you can choose to tailor your module for one or both of these systems.
 +
 
 +
In this example we will just show the example files for the MySQL database. Creating the Microsoft SQL Server will be left as an exercise for the reader.
 +
 
 +
In our install.mysql.utf8.sql file we will create the table and place some hellos into it
 +
 
 +
<source lang="sql">
 +
CREATE TABLE IF NOT EXISTS `#__helloworld` (
 +
`id` int(10) NOT NULL AUTO_INCREMENT,
 +
`hello` text NOT NULL,
 +
`lang` varchar(25) NOT NULL,
 +
 
 +
  PRIMARY KEY (`id`)
 +
) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1;
 +
 
 +
INSERT INTO `#__helloworld` (`hello`, `lang`) VALUES ('Hello World', 'en-GB');
 +
INSERT INTO `#__helloworld` (`hello`, `lang`) VALUES ('Hola Mundo', 'es-ES');
 +
INSERT INTO `#__helloworld` (`hello`, `lang`) VALUES ('Bonjour tout le monde', 'fr-FR');
 +
</source>
 +
 
 +
In the uninstall file we'll just remove the table.
 +
 
 +
<source lang="sql">
 +
DROP TABLE IF EXISTS `#__helloworld`
 +
</source>
 +
 
 +
Finally we'll just leave a placeholder in the updates file. There is an SQL file for each component version. Each file name must match the version string in the manifest file for that version. Joomla uses this string to determine which SQL files(s) to execute, and in what order they will be executed.
 +
 
 +
''Important Note:'' These files are also used to set the version number in the #__schemas table. This version number must be present in the current version of the component in order for the new SQL files to be run during the update. For example, if you have version 1.0 and are updating to version 1.1, the 1.1.sql file will not be executed if there was no 1.0.sql file in the 1.0 release. For this reason, it is good practice to have a SQL update file for each version, even if there is no SQL change in that version.
 +
 
 +
<source lang="sql">
 +
# Placeholder file for database changes for version 1.0.0
 +
</source>
  
 
== Making the request in the helper file ==
 
== Making the request in the helper file ==
 +
Now on installing our module we should find that there is a helloworld database set up in our database schema with our hello's in. We must now retrieve this from the database to display to the user. We will now amend the ''getHello'' function we placed in the helper file in the last part.
 +
 +
For now we'll ignore using form fields to choose a hello and just retrieve the English shout
 +
 +
<source lang="php">
 +
//Obtain a database connection
 +
$db = JFactory::getDbo();
 +
//Retrieve the shout
 +
$query = $db->getQuery(true)
 +
            ->select($db->quoteName('hello'))
 +
            ->from($db->quoteName('#__helloworld'))
 +
            ->where('lang = '. $db->Quote('en-GB'));
 +
//Prepare the query
 +
$db->setQuery($query);
 +
// Load the row.
 +
$result = $db->loadResult();
 +
//Return the Hello
 +
return $result;
 +
</source>
 +
 +
== Conclusion ==
 +
Using modules with database connections for Joomla! is a fairly simple, straightforward process. Using the techniques described in this tutorial, a lot of modules can be developed with little hassle, with updates easy to manage
 +
 +
<noinclude>
 +
[[Category:Module Development]]
 +
</noinclude>

Revision as of 18:03, 13 May 2013

This page has been archived. This page contains information for an unsupported Joomla! version or is no longer relevant. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.


Many modules in Joomla require using a database. It is assumed in this tutorial that you already understand the basics of using the JDatabase class. If you don't please read the documentation on accessing the database using JDatabase before continuing this tutorial

Creating a table on install[edit]

To create the xml table on install we are going to add the following lines into mod_helloworld.xml:

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

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

<update> 
    <schemas>
        <schemapath type="mysql">sql/mysql/updates</schemapath> 
	<schemapath type="sqlazure">sql/sqlazure/updates</schemapath> 
    </schemas> 
</update>

There are 3 sections to this code:

  • The install tag adds the database table
  • The uninstall tag removes the database table if the module is uninstalled. Note that not all modules will want to use this feature (and it's not required).
  • The update tag will update the databases if a database needs to be amended when updating the module.

Note that we have both schemas for MySQL and Microsoft SQL - again you can choose to tailor your module for one or both of these systems.

In this example we will just show the example files for the MySQL database. Creating the Microsoft SQL Server will be left as an exercise for the reader.

In our install.mysql.utf8.sql file we will create the table and place some hellos into it

CREATE TABLE IF NOT EXISTS `#__helloworld` (
	`id` int(10) NOT NULL AUTO_INCREMENT,
	`hello` text NOT NULL,
	`lang` varchar(25) NOT NULL,

  PRIMARY KEY (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 AUTO_INCREMENT=1;

INSERT INTO `#__helloworld` (`hello`, `lang`) VALUES ('Hello World', 'en-GB');
INSERT INTO `#__helloworld` (`hello`, `lang`) VALUES ('Hola Mundo', 'es-ES');
INSERT INTO `#__helloworld` (`hello`, `lang`) VALUES ('Bonjour tout le monde', 'fr-FR');

In the uninstall file we'll just remove the table.

DROP TABLE IF EXISTS `#__helloworld`

Finally we'll just leave a placeholder in the updates file. There is an SQL file for each component version. Each file name must match the version string in the manifest file for that version. Joomla uses this string to determine which SQL files(s) to execute, and in what order they will be executed.

Important Note: These files are also used to set the version number in the #__schemas table. This version number must be present in the current version of the component in order for the new SQL files to be run during the update. For example, if you have version 1.0 and are updating to version 1.1, the 1.1.sql file will not be executed if there was no 1.0.sql file in the 1.0 release. For this reason, it is good practice to have a SQL update file for each version, even if there is no SQL change in that version.

# Placeholder file for database changes for version 1.0.0

Making the request in the helper file[edit]

Now on installing our module we should find that there is a helloworld database set up in our database schema with our hello's in. We must now retrieve this from the database to display to the user. We will now amend the getHello function we placed in the helper file in the last part.

For now we'll ignore using form fields to choose a hello and just retrieve the English shout

//Obtain a database connection
$db = JFactory::getDbo();
//Retrieve the shout
$query = $db->getQuery(true)
            ->select($db->quoteName('hello'))
            ->from($db->quoteName('#__helloworld'))
            ->where('lang = '. $db->Quote('en-GB'));
//Prepare the query
$db->setQuery($query);
// Load the row.
$result = $db->loadResult();
//Return the Hello
return $result;

Conclusion[edit]

Using modules with database connections for Joomla! is a fairly simple, straightforward process. Using the techniques described in this tutorial, a lot of modules can be developed with little hassle, with updates easy to manage