Actions

User

Over/Step by step to a Joomla Module - Advanced installation

From Joomla! Documentation

< User:Over
module tutorial

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.

Tip-icon.png
A Tip!

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

You should have some knowledge in web technology but you don't have to be an expert at all. If you want to customise or even administrate a web site you will have to learn a little of everything e.g, Html coding, Css styling, Php programming, Sql database, using Javascript and about web servers. If you want to develop extensions for Joomla!, in small or large, you better start with a module before you try a larger project with a component. It is also a nice start to get knowledge on how to modify your sites template design. A Joomla! module is similar to a widget in other contexts. Even if plugins are the shortest extension type in sake of code, they require a little more advanced system knowledge to implement.


Contents

Introduction

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.

Installation script

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.

Update server

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.

Tip-icon.png
A Tip!

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.