Here we'll discuss some techniques we use when developing plugins for Jomres.
Different minicomponents are called at different times, depending on their trigger number. We'll refer to these types of scripts by their trigger number, and occasionally offer examples where you can see them in use.
Useful variables
get_showtime('ePointFilepath')
Calling this function will give you the absolute path to this script. If you're using template files to generate layout (and you should be), however you'll need to do something like
$tmpl->setRoot( $ePointFilepath.'templates'.JRDS.find_plugin_template_directory() );
to tell the $tmpl object where your custom template file is located. As a plugin developer you should be distributing plugins that are compatible with Jomres' own templates ( jQuery UI flavour, Bootstrap 2 and Bootstrap 3) in respective directories templatepath/jquery_ui, templatepath/bootstrap and templatepath/bootstrap3.
Hint : If you intend to call other minicomponents from this minicomponent, call get_showtime('ePointFilepath') and put the results in a variable before calling another minicomponent. The instant the next minicomponent is called, get_showtime('ePointFilepath') is reset to the next minicomponent's absolute path.
get_showtime('eLiveSite')
This is a little similar to ePointFilepath, in that it points to the directory this script's running in, relatively from the base of your website. Let's say that your website's at http://www.domain.com, then eLiveSite will point to the url http://www.domain.com/jomres/remote_plugins/xxxxxx/
In the flipwall plugin you'll see that we use this variable to include the flipwall's jquery.flip.js file in the host CMS's header, like so :
jomres_cmsspecific_addheaddata("javascript",get_showtime('eLiveSite').'javascript/',"jquery.flip.js",false);
j00005 scripts.
Including language files
These are generally your setup scripts, where you include functions files, import classes and include language files. Let's see how that's done in funky_search_features plugin j00005funky_search_features.class.php :
$ePointFilepath = get_showtime('ePointFilepath');
if (file_exists($ePointFilepath.'language'.JRDS.get_showtime('lang').'.php'))
require_once($ePointFilepath.'language'.JRDS.get_showtime('lang').'.php');
else
{
if (file_exists($ePointFilepath.'language'.JRDS.'en-GB.php'))
require_once($ePointFilepath.'language'.JRDS.'en-GB.php');
}
Here we're looking to find the current language's language file for this plugin. If it doesn't exist, we'll fall back to the english language file for this plugin (if it exists).
Switching stuff off
Ok, that's mundane enough, let's try something a little bit more fun.
Let's say that our plugin introduces functionality so unique, that we want to disable certain things in the system based on certain conditions. Let's see how Jintour's j00005get_jintour_property_data.class.php file does things.
In a Jintour based property, we can't show the normal dashboard, because Jintour bookings aren't the same as normal bookings, so to switch off the standard dashboard script, we do the following :
unset($MiniComponents->registeredClasses['00013dashboard']);
How cool is that? Just like that, for Jintour based properties, with one line we've switched off (among other things) the dashboard calendar.
Redirecting template calls
Something else we can do, and we typically do this in j00005 scripts, is redirect calls from one of the core template files, to another template file. Again, Jintour's j00005 script gives us an example of how this is done :
if ($_REQUEST['task'] == "editProperty")
{
$current_custom_paths = get_showtime('custom_paths');
$current_custom_paths['edit_property.html'] = $ePointFilepath.'templates'.JRDS.find_plugin_template_directory();
set_showtime('custom_paths',$current_custom_paths);
}
Jintour based properties have less information to show in the property details, so in the event that the currently viewed property is a jintour property (see that script to see how we determine that) we tell Jomres to use the edit_property.html file in our /templates directory, not the one in /jomres/templates/jomres/backend.
Singletons
Jomres makes use of Singletons for a variety of reasons. The main one being that we can ensure that data is called just once and it is retained thoughout a run. Jomres can be triggered in a number of ways, e.g. through the component itself, or via modules and plugins (mambots) consecuitively. This would mean some database intensive queries could be called several times so we sidestep this by using singletons to retain the information called and then reuse it later.
There's a special singleton in Jomres called "Showtime" ( named after my favourite server on Novalogic's Delta Force 2, yes I know I'm a geek ) which can be used to store data throughout a run, so let's say you've generated some data in a 00005 script that you know you'll use later in another script. You can use the Showtime variabled to retain the information temporarily, like so :
set_showtime('my_data', array ( 1, 2, 3 ) );
and then use it later by calling
$my_data = get_showtime('my_data');
Just remember that the data isn't persistent. Once the run completes the data is lost, so if you want to maintain that information you'll need to store it somewhere more permanent.
Plugin templates
A short history of templates.
Confusingly, Jomres names template files "templates" but these should not be confused with Joomla or Wordpress Templates. These are discreet html files that Jomres' adaptation of the patTemplate library uses to build and display output.
Back in the days of Joomla 1.x and Joomla 2.x there was no consensus among extension or template developers of which framework to use, so javascript or css that would work with the default Joomla template often wouldn't work well in a template from one of the template clubs and site integrators ( typically designers working on behalf of clients, or skilled clients themselves ) would often find themselves working hard to make an extension's output fit with their chosen template. This was a huge chore for everybody involved and here at Woollyinwales IT we settled on using the Jquery UI CSS and Javascript framework to achieve some kind of interoperability with templates.
Thankfully, in Joomla 3.x the Joomla team decided that they would ship the product with the Bootstrap framework built in. This forced (ok, strongly encouraged ) all extension and template developers to produce code that was compatible with Bootstrap, meaning that clients could reasonably expect an extension to work well with minimal fiddling in any Joomla template from the get go.
Since then Bootstrap 3 has been released ( Aug 19, 2013 ) and Bootstrap 4's release is imminent.
Template usage in Jomres
All of our main work is developed primarily in Bootstrap 3. This is because BS3's mobile handling is much better than BS2, particularly for things like Modals, which we use quite extensively in Jomres, then the work is back-ported to Bootstrap 2 and Jquery UI if possible.
As a result, we typically provide three sets of templates : jQuery UI, Bootstrap 2 and Bootstrap 3. We would prefer to get rid of the Jquery UI templates, however they're used exensively by Wordpress users, as Bootstrap doesn't work well on Wordpress sites, so for the forseeable future we're stuck with them.
If you're distributing a Jomres plugin, you should offer at least Bootstrap 2 and Bootstrap 3 templates, and if you don't support the Jquery UI templates then make this clear in your shop.
Your Jomres templates should follow the established convention of being contained in the xxxxxxx/templates/ directory of your plugin, then subdirectories for each template framework, so jquery_ui, bootstrap or bootstrap3
If you do that, then you can use the following code to allow the plugin to determine the correct path to the template file :
$tmpl->setRoot( $ePointFilepath.'templates'.JRDS.find_plugin_template_directory() );