From Jomres v4 manual

Preamble

The Jomres plugin handling functionality is designed to make it possible to allow thirty party developers to design and distribute additions and alterations to the standard Jomres functionality. If you just want to edit some core Jomres code, you're probably better off reading the article How to edit the Jomres core code and still upgrade on the subject, as this article dwells more on the intricacies of creating a plugin for Jomres.

Before we start, I'd like to point you to The Jomres license article where you can see a description of the blended license that Jomres uses to allow third party developers to write for Jomres while not breaking the terms of the Jomres proprietary license itself.

Introduction

This article is written in such a way to show an intermediate to advanced php developer how to quickly write a plugin for Jomres. We'll do this by working through an existing dummy plugin that demonstrates the basic structure of a plugin.

First, you'll probably want to download the dummy plugin and extract it locally.

Media:dummy_third_party_plugin.zip

Note: Due to a wee bug in v4.1 the manager's menu option doesn't show up if you install this plugin although the administrator area button does show. Upgrade to v4.1.1 to see the button in the manager's menu.

Basic file access security

You should ensure that none of your plugin scripts can be called except by Jomres itself, this reduces the likelihood of attackers compromising the server by bypassing security features and calling files directly.

All Jomres minicomponents are classes, so they shouldn't normally expose functionality via the url (eg, by an attacker accessing the file directly by calling www.domain.com/jomres/remote_plugins/j06000dummy_third_party_plugin.class.php) however a simple but effective extra layer of security is to add the following line to the top of your minicomponents and other php files.

defined( '_JOMRES_INITCHECK' ) or die( 'Direct Access is not allowed.' );

Setting tasks

When a user does something in Jomres they're calling a "task". Many of the Jomres tasks are hard coded into jomres.php, eg "dobooking" or "viewproperty" however it is possible to create new tasks by assigning them a trigger point of 06000, (and 06001, 06002 or 06005 if you're running v4.2 or later).

An example of a custom task can be taken from the dummy plugin. The file j06000dummy_third_party_plugin.class.php creates the task dummy_third_party_plugin which is viewable by anybody accessing the system. To see the task's output they would, on a Joomla installation, use the url www.domain.com/index.php?option=com_jomres&task=dummy_third_party_plugin. Look in j00011manager_option_13_dummy_third_party_plugin.class.php to see how the url's constructed to be cms agnostic.

The 06001/2/5 tasks are new as of v4.2, previous to that all custom tasks would use the 06000 task and it would be left to the individual minicomponent to perform checks to ensure that the user had the necessary privilleges to access that task. The 06001/2/5 task options add an extra layer of security, but the minicomponent should still perform it's own security checks to ensure that the user has rights to a given element, eg if a manager's accessing a guest's details you'd still want to cross reference the guest against the managers's property by doing something like:

$property_uid=getDefaultProperty();
$query="SELECT guests_uid FROM #__jomres_guests WHERE `guests_uid`= ".(int)$guestUid." AND `property_uid` = ".(int)$property_uid." ";

In 4.2 the rights are as follows:

• 06000 Any user can access the task, regardless of their registered state.
• 06001 User must be either a Receptionist or a Property Manager.
• 06002 User must be a Property Manager.
• 06005 User must be a registered user of the system, but they don't need to be a receptionist or a property manager.

Finding the path to your plugin

When adding a plugin, you're likely to want to know the path to the plugin so that you can include files or css/javascripts. Previous to v4.2 you'd use the following declaration to get two variables which would give you this information, like so:

global $ePointFilepath,$eLiveSite;

$ePointFilepath gives you the path to your plugin's directory, eg /var/www/html/jomres/remote_plugins/dummy_third_party_plugin, whereas $eLiveSite gives you the relative path, such as www.domain.com/jomres/remote_plugins/dummy_third_party_plugin.

As of v4.2 we use a new singleton called "showtime" which holds much of our runtime information and provides us with an extra layer of security by doing away with the need to call the variables globally. For backward compatability those global variables are still available however it's recommended that you use the get_showtime function to reduce the danger of cross site scripting, like so:

$ePointFilepath = get_showtime('ePointFilepath');
$eLiveSite = get_showtime('eLiveSite');

Some typical files in a plugin

Next we'll look at the files in the plugin. Note that filenames with a . have been had the "." replaced with a ",", this is due to limitations of this wiki software.

• dummy_third_party_plugin_foo,class,php
• index,html
• j00001dummy_third_party_plugin_start,class,php
• j00011manager_option_13_dummy_third_party_plugin,class,php
• j06000cron_dummy_third_party_plugin,class,php
• j06000dummy_third_party_plugin,class,php
• j10002dummy_third_party_plugin,class,php
• j16000dummy_third_party_plugin,class,php
• plugin_dependencies_check,php
• plugin_exclusions_check,php
• plugin_info,php
• plugin_install,php
• plugin_uninstall,php
• Reservations2,png
• language - en-GB,php
• templates - admin_dummy_third_party_plugin,html
• templates - dummy_third_party_plugin_a,html

This plugin is a reasonably complete yet useless example of a plugin. In essense it installs several files which add a new button to the manager's toolbar, and one to the administrator's control panel, which links to a dummy task which displays the text "Hello World". Naturally in a real world example we would (hopefully) include more files for a complex plugin, or less for a simpler one.

In it's basic form, a plugin need only contain the plugin_info.php file for it to be installable via the Jomres Third Party Plugin installer. Usually though you'd probably want to include a minicomponent or two to build up your plugin's functionality. For example, if you were just modifying the Property Manager's dashboard you could quite easily get away with just two files, plugin_info.php and j00013dashboard.class.php. So long as the plugin_info.php script is correctly structured, you'll be able to install the script.

Plugin naming

Plugin names are words seperated by underscores, so a valid plugin name would be "slideshow_carousel". This is because Jomres needs to know the name of the class to run within the plugin_info.php. Assuming the plugin's called "slideshow_carousel" then inside plugin_info.php the class and constructor method would be called

class plugin_info_slideshow_carousel
	{
	function plugin_info_slideshow_carousel()
		{

Similarly, the 'name' index

"name"=>"slideshow_carousel",

Needs to have the same name.

The last lastupdate index needs to be in the format yyyy/mm/dd

"lastupdate"=>"2009/06/23",

The rest of the fields are generally freeform, however you should try to avoid html in the description as this may cause errors.

The zip file itself should be called "slideshow_carousel.zip".