Tutorials/Create a backend module - 2. Survive updates

Date: June 10, 2010 Oxid version: 4.3.1

In the first part of this tutorial, you learned how to start coding a new backend module with a minimum of fuss. In this part I'll show you how to place your files in the Oxid eShop folders so that a system update won't overwrite what you've done.

Create your own module folder
Create a folder with the name of your module in the shop's module folder. Mine is modules/bpx_genpics. Ideally this folder will contain all the files needed to make your module run. Oxid eShop in the present version still requires scattering module logic in the system folders, but a workaround is explained later.

Create a custom menu definition
We want to move the declaration of the new menu item in the admin section to the newly created module folder. The menu file must be named menu.xml for Oxid to find and include it.

modules/bpx_genpics/menu.xml:

Again, this will add the menu item "bpx_genpics" to the end of the "Service" section of the admin menu. Oxid will merge the main admin/menu.xml with all menu.xml files it finds in the modules folder, creating the admin menu with the specified custom additions. You should then remove the custom submenu we previously added in the admin/menu.xml file. When you refresh the backend (you may have to clear the tmp folder) your custom module should still be there.

Is your module update-safe?
A normal system update process (explained here in German) overwrites and adds new system files in all folders except custom module folders. We've made a start in giving our files a unique prefix: bpx_, so our files should be safe from overwriting. Also the menu declaration is safe within the modules folder. This is the best we can do with the present version of Oxid.

Get your files together with symlinks
The module files are now located here:


 * admin/bpx_genpics.php
 * out/admin/tpl/bpx_genpics.tpl
 * out/admin/de/bpx_de_lang.php
 * out/admin/en/bpx_en_lang.php
 * modules/bpx_genpics/menu.xml

However:

If you have shell access to your server, you can use symbolic links to move all your custom module files into your module folder. Use these commands on your linux server (the path to your shop may be different):

$ cd /srv/http/oxid/admin $ sudo mv bpx_genpics.php /srv/http/oxid/modules/bpx_genpics $ sudo ln -s /srv/http/oxid/modules/bpx_genpics/bpx_genpics.php bpx_genpics.php $ cd /srv/http/oxid/out/admin/tpl $ sudo mv bpx_genpics.tpl /srv/http/oxid/modules/bpx_genpics $ sudo ln -s /srv/http/oxid/modules/bpx_genpics/bpx_genpics.tpl bpx_genpics.tpl $ cd /srv/http/oxid/out/admin/de $ sudo mv bpx_de_lang.php /srv/http/oxid/modules/bpx_genpics $ sudo ln -s /srv/http/oxid/modules/bpx_genpics/bpx_de_lang.php bpx_de_lang.php $ cd /srv/http/oxid/out/admin/en $ sudo mv bpx_en_lang.php /srv/http/oxid/modules/bpx_genpics $ sudo ln -s /srv/http/oxid/modules/bpx_genpics/bpx_en_lang.php bpx_en_lang.php

With this change, your module files, including translation files, are all in one place in your module folder (modules/bpx_genpics), making it easier to manage your module. The original module files that were scattered inside the Oxid system folders have been replaced by symbolic links. If these links are deleted for any reason, you can easily replace them. In addition you can make a backup of all your module files in one sweep just by downloading your module folder.

The next step
Our module is now update-safe, and the next step will really dive into the coding!