Tutorials/Create a backend module - 1. Getting started

Date: June 8, 2010 Oxid version: 4.3.1

Modifying the Oxid backend is not an easy task. I will help you get started by copying an already existing module. Taking the systeminfo module for our starting point, we will create a minimal framework for a new module. The systeminfo module is located in the admin section of your site under Service - System Info. The new module will also live in the Service section.

If you have any problems with this tutorial, please post to my thread in the forum:


 * English: New wiki article for creating modules


 * German: Wikibeitrag zur Modulentwicklung

Get the naming right
To distinguish your module from the hundreds of files in the oxid folders, decide on a (hopefully) unique prefix for your files. For this example I decided on the prefix "bpx_" (based on the name of my company - bitpals.de). Add a short word after the prefix that describes your module. These file names are not visible to the user, so you can choose anything easy to remember. My module will eventually help in automatically generating article pictures, so most of my files will be called "bpx_genpics."

Gather the required files
We will need to look at the these files:


 * admin/menu.xml - describes the complete navigation tree for the admin section
 * admin/systeminfo.php - implementation of the systeminfo module
 * out/admin/tpl/systeminfo.tpl - content of the systeminfo module generated with Smarty tags

Create the module files
We will create the following files based on the systeminfo files:


 * admin/bpx_genpics.php
 * out/admin/tpl/bpx_genpics.tpl

The linux commands (for my server) are:

~$ cd /srv/http/oxid ~$ cp admin/systeminfo.php admin/bpx_genpics.php ~$ cp out/admin/tpl/systeminfo.tpl out/admin/tpl/bpx_genpics.tpl

Note that we're not worried about having the files in their own folder, separate from the Oxid files. We will get to that later. For now let's just do the minimum amount of work to get started.

Edit the admin navigation menu
Open admin/menu.xml and add a line near the end:

This tells Oxid to add the "bpx_genpics" menu item at the end of the "Service" section and make it visible only to administrators.

Edit the php file of the module
Reduce the code in admin/bpx_genpics to a bare, but still functional minimum:  Our class, like the original systeminfo class, extends oxAdminView. Looking at the oxAdminView inheritance diagram you can see that oxAdminView gives us access to all objects in the shop. Note that we're echoing out our template "bpx_genpics.tpl"; if you don't include the template here, you won't get any output.

Edit the template file of the module
Again, reduce the original systeminfo code in out/admin/tpl/bpx_genpics.tpl to the bare necessities:  What's going on here?

The Smarty tag [{debug}] is commented out. If you have problems with rendering remove the comments (the asterisks); when you call up the page, you will get a popup with information on the template.

The Javascript code generates the title of the page. The "ident" strings will need to be translated later.

The DIV at the bottom includes another example of a Smarty tag. This will spit out the Welcome message you defined in the CMS section.

Don't see anything?
Don't worry! Every time you make changes in your code to get your module running, you will have to empty the "tmp" folder, or your changes will not be visible because of the Oxid caching mechanism. The Delete tmp extension will do this for you automatically, so go ahead and install it now.

Create translation files
Note that the menu item for the new module says "bpx_genpics." We'll get this string translated by creating two new files:

out/admin/de/bpx_de_lang.php:  out/admin/en/bpx_en_lang.php:   The page title "ident" strings mentioned above are also included.

The next step
If you've been following along, you now have a working custom backend module that you can expand to your needs. The next tutorial in this series will get into the coding of the module itself.