Over/Step by step to a Joomla Module - Advanced installation
From Joomla! Documentation
Articles in this Series
This is a multiple article series on how to develop a module for Joomla! version Joomla 3.x. We go step by step from basic functionality to some more advanced. At the end of the tutorial we'll use your custom module to show you, how you can use the powerful output override ( = change ) methods provided by Joomla!. The only prerequisite for overrides is that the module or component comply to the Joomla! best practices. Navigate the articles in this series by using the navigation box to the right (the Articles in this series). Start with the first and follow them one by one. The next article builds on the knowledge and the files from the previous.
As the links on this page are references, you should open them in a new browser window/tab.
Should have's to complete this tutorial
In this step we add the advanced installation possibilities 'Installation script', 'Update server' and 'Table creation'. You should have some deeper knowledge of Php or follow the J3.x:Developing a MVC Component/Introduction before adding those to your module.
You can find a script.php in the downloaded tutorial zip file. It includes the same methods as installation scripts for components and other extensions. It lets you add extra functionality. You can use another name for this file. As an example - you can create a folder in images/ and copy some default images to this new folder.
- install : executes when extension gets installed
- uninstall : executes when extension gets uninstalled
- update : executes when extension gets updated
- preflight : executes before install/uninstall/update
- postflight : executes after install/update
You add it to the xml file with
mod_yourmodule.xml Installation script
<!-- Runs on install/uninstall/update --> <scriptfile>script.php</scriptfile>
You of course add the physical file to the folder you use to create the zip installation file.
If you publish your module to other users as on the JED extensions.joomla.org/, it's recommended that you supply automatic updates on a server of your choise. Here we only show you one example of the code in the xml file. Please read more here Deploying an update server
mod_yourmodule.xml Update server
... <updateservers> <server type="extension" priority="1" name="Your Module Update Site">http://www.myserver.xy/updates/yourmodule.xml</server> </updateservers> </extension>
Add the update information at the bottom of the xml file. In addition you have to add the xml and update zip files on the update server. An example xml is included in the tutorial example data. The zip file is the latest of the installation zip of your module.
Add a table for the module
You should consider a small backend component as soon as you want to use a table with your module. You shouldn't force users to maintain the table with a database tool. It is realy easy to create a single list view to allow the user to see the entries and delete any unwanted entries. You can also provide methods to retrieve and store the data from the module. Just follow the component tutorial. The use of a component for data retrieval was explaind in another part of this tutorial.
In case you have reasons not to provide a component, we add some tips here.
You can find a sql folder in the zip file you downloaded. Copy this to your modules 'root' folder where you create the installation zip file. You have to include this for the new installation. It's hard to install and update a database table if the code wasn't executad at installation. Any update sql file is additionaly executed at new installation.
You have to supply an empty update sql file for your first version!
This example only includes the MySql database.
... /media /sql *new directory* /updates *new directory* /mysql *new directory* 1.0.0.sql *new file* install.mysql.sql *new file* uninstall.mysql.sql *new file* /tmpl ...
- In install.mysql.sql you create the table(s).
- In uninstall.mysql.sql you delete the table(s).
- In the folder /updates/mysql you add the empty sql with a version number. The version number has no relation to the modules number! It's up to you. Here 1.0.0.sql
- In the folder /updates/mysql you add updates to the table(s). Increase the version number. The next would in this case be 1.0.1.sql
Include the sql in the xml file.
mod_yourmodule.xml Include the sql
<files> ... <folder>sql</folder> </files> <languages folder="langs"> ... </languages> <install> <sql> <file charset="utf8" driver="mysql">sql/install.mysql.sql</file> </sql> </install> <uninstall> <sql> <file charset="utf8" driver="mysql">sql/uninstall.mysql.sql</file> </sql> </uninstall> <update> <schemas> <schemapath type="mysql">sql/updates/mysql</schemapath> </schemas> </update> <config>
- Edit the install.mysql.sql and the uninstall.mysql.sql with your table definitions.
- Add the sql folder to the files tag and the install, uninstall, update tags as above.
- Create the installation zip file.
- Uninstall the module if it is previously installed.
- Install with the new installation file.