How to create a new elastix module?

djgreencable

Joined
Feb 5, 2010
Messages
6
Likes
0
Points
0
#1
Hi everybody

First of all i want to thank you all for this amazing work and i hope somehow you all can help me be part of this great Elastix community.

I would to know a quick overview how to create an elastix module. I already have been read the quick overview in this subject at http://www.elastix.org/component/option ... rs_manual/ "how to develop new elastix module" and i try the example available in this guide but so far no success.
Can you teach me how can i create elastix modules and how this amazing package works?

Thanks, :)


PS - My main goal is to create new elastix modules and make them availables for the community.
 

brandizzi

Joined
May 28, 2012
Messages
18
Likes
0
Points
0
#2
I suffered to discover how to create modules, so let me share what I discovered.

First, a recommendation: for me, the best way to develop modules for Elastix is to install Elastix in a separate machine (I'd suggest a VM, e.g. in VirtualBox) and write the code in a development machine. So, install Elastix in a VM now.

The Developer addon

To create modules, the first step is to install the Developer addon to Elastix. Log into Elastix and go to "Addons", then click on "Install" on the Developer addon.



After doing that, there will be a "Developer" option in the first-level Elastix menu. There will be four submenus - "Build module", "Delete module", "Language admin" and "Load module". We will use mostly "Load module" and "Delete module" in the beginning. "Build module" can be very useful after learning the basics.



Module format

AFAIK, there are two module formats to Elastix. As examples of modules following these formats, you can see this one and this one. Apparently, the second format is the most modern, so I just studied this one and will only explain it.

In this format, the modules are distributed in tar.gz packages with a specific layout. This file can contain various modules. The tar.gz file should have a directory, which I will call base directory. This directory should contain a subdirectory named setup, which has a file named installer.php. This file will be executed during the modules installation but, as far as I tested, it can be empty.

The base directory should have a file named menu.xml, too. As you can suppose, it is a XML file which describes the menu structure of the modules contained in the package. In this file, you can define menus which does not point to any module (so you can put submenus on it) as well as menus which points to a module. An example of the structure of this file can be seen below; we will return to it in the future.

Code:
Finally, the base directory should contain a subdirectory named modules. If a menu item points to a module, its module attribute should be valued as yes. In this case, there should be a directory with the same name of the menuid attribute value in the modules directory. So, in the example above, the modules directory should have a subdirectory called sndlevelmenu.

Each module directory should have at least a file called index.php. This file is responsible to generate the HTML to be presented by the module. However, one cannot just output text as it is common in PHP. The index.php file should contain instead a function named _moduleContent(), which expects two parameters. The first one is a reference to a Smarty object; the second argument is the module name. After the execution, this function should return a string containing the HTML to be shown.

Below there is an example of a valid index.html:

Code:
An example
Let's thus create a module as an practical example. This module will show the current date and time in the server, so it will be called servertime. I will use Unix commands to create the necessary components, so I hope you are experienced with it. (If not, you may have a hard time with Elastix anyway but you can just ignore the commands in that case).

First, I will create the necessary directory tree. The base directory will be called servertime and it will have the mandatory setup and modules directory. The only module it will contain will be called servertime as well.

Code:
$ mkdir -p servertime/setup servertime/modules/servertime
The resulting tree follows:



After that, I will create the obligatory installer.php file. Since I do not want to execute any setup instalation in this module, I will just leave it empty.

Code:
$ touch servertime/setup/installer.php
Now, I will create our menu.xml file. Let us put our module under the Reports menu, so the parent of our menu item will be reports. The menuid will be servertime as expected. The resulting file follows:

Code:
(To discover the menu id of your wanted parent item just examine the URL of the module. Suppose you wanted to put your module under the Email menu. Just click in the Email option and observe the URL. It will be something like https:///index.php?menu=email_admin, so the parent of your menu should be email_admin.)

After that, we just need to create the index.php of our module. It will be pretty simple:

Code:
Now, just create a tar.gz package containing the base directory:

Code:
tar zvcf servertime.tar.gz servertime/
(The resulting package is attached to this message for your convenience. The form )

Installing and removing modules

Once you have your packaged modules, the Developer addon comes to the rescue. Go to Developer > Load module and select the resulting tar.gz file. Then, click in Save. To see the result, go to Reports and will note that a Server time option appeared.



Click on it to see the result:



To remove the module, go to Developer > Delete module. Check on Delete files (to assure everything will be cleaned up). In level, select level 2, because our module is a child of a level 1 menu (Reports). In Level 1, select Reports and in Level 2 select Server time.



Note that, if you update the code of the module, you should first delete the previously installed version of it. It can and will be a PITA but it is the only way to deal with the problem AFAIK. http://forum.elastix.org/old_files/servertime.tgz
 

Members online

No members online now.

Latest posts

Forum statistics

Threads
30,902
Messages
130,886
Members
17,564
Latest member
Mai Tuyen
Top