1. You are here:  
  2. Home
  3. Developer's Guide
  4. Customising Jomres
  5. Customising templates/layout
  6. Make your own template override package

This manual is being depreciated. Much of the information here is out of date.

The new Jomres Documentation, updated in 2022, can be found at Jomres.net/documentation.

Make your own template override package

Who is this article for?

Long-term Jomres users and developers who would like to provide their own template packs for Jomres. Also it's useful for users who want to develop their own Jomres template sets and install those sets on multiple Jomres sites.

Why are we offering Template Override Pack functionality?

Jomres supports having template overrides in templates/themes, however sometimes you need to take things further.

The majority of our users are developers who are setting up sites for their clients. For them, the standard template override feature is sufficient, they make the changes the client requests then move on.

Many of our users, however, are long-time Jomres users (thank you!) and for these users, if they update a template like Leohtian, their existing overrides can be overwritten when the template is updated. This is where Template Override Packs (TOP) come in.

What's in a TOP plugin?

A typical TOP plugin will have a plugin_info.php file, a minicomponent with the trigger number 00001 and a number of template files.

Let's take a look at the Template Package Booking Form Layouts plugin together, this will help you to understand.

directory structure

This plugin info file has a class called plugin_info_template_package_booking_form_layouts, and if you open it you will see some basic plugin information. If you intend to create your own template packs, then you will need a plugin_info.php file. You must ensure that the name of the class is changed to reflect your own template pack's name.

The $this->data name array key should also reflect the name of the pack in the same was that the class does. Aside from those two fields, if you do not intend to distribute this plugin then you don't really need to do much with the rest of the data in the plugin_info.php file.

The next file in our example plugin is called j00001template_package_booking_form_layouts.class.php

The 00001 number ensures that this script is triggered as soon as Jomres starts.

The important lines in this file are :

$this_plugin = "template_package_property_details";
$ePointFilepath=get_showtime('ePointFilepath');

$template_path = str_replace ( JOMRESPATH_BASE , "" , $ePointFilepath );

     $template_packages = get_showtime('template_packages');
        if (is_null($template_packages))
            $template_packages = array();

     $template_packages[$this_plugin][] = array (
            "template_name"=>"dobooking.html",
            "title"=>"Booking form > Rooms list in columns",
            "description"=>"Rooms list in columns, feedback messages above the rooms list and sticky Totals.",
            "screenshot"=>"",
            "path"=>$template_path);

set_showtime('template_packages' , $template_packages );

 

Let's break down what it does.

$this_plugin = "template_package_property_details";

This line sets the plugin's name. It can be anything you want but it needs to be valid PHP as it is used as the template package array index, so something like "my_first_template_pack" would work fine, however "my first template pack" would not.

$ePointFilepath=get_showtime('ePointFilepath');

The absolute path relative to the server's root, of the location of this script.

$template_path = str_replace ( JOMRESPATH_BASE , "" , $ePointFilepath );

This is then changed to determine the path to arrive at the path to these template files, relative to Jomres' root. If you are making your own package then it's safe to just copy these two lines.

     $template_packages = get_showtime('template_packages');
        if (is_null($template_packages))
            $template_packages = array();

"showtime" in Jomres is a singleton object that is used to make information available to various scripts on Jomres. Here we are pulling the variable "template_packages" from the showtime object. If it's not yet set then we will set it to be an empty array. Again, you can just copy this into your own 00001 script.

     $template_packages[$this_plugin][] = array (
            "template_name"=>"dobooking.html",
            "title"=>"Booking form > Rooms list in columns",
            "description"=>"Rooms list in columns, feedback messages above the rooms list and sticky Totals.",
            "screenshot"=>"",
            "path"=>$template_path);

In the example plugin there are actually three templates that are overridden, but I will only show the main override here.

Here's where we define the template we intend to override, in this case dobooking.html which is the template file that is used by hotels/B&Bs etc. We give this a title and a description. As of 9.9.3 the description and any screenshot aren't yet used, this is functionality we will provide later if the feature proves popular.

set_showtime('template_packages' , $template_packages );

Finally we save this new information to the showtime object. Once installed this information is then available to the Template Override Packages page.

A real world example

Documenting a feature is all very well, but practical examples where you can see a use for a feature will help even more, so let's have a look at a common requirement.

Many users have different requirements for what is displayed on a Jomres page. We have long taken the view that it's easier for us to collate as much information as is relative to a template, and add it. That way, it's easier for users to remove the information they don't want, than to instead ask us how to add more.

For example, we will show you the Random Accommodation plugin which you often see on the front page of Jomres Leohtian sites

random accommodation

 

On hover you can see a Read More button. Clicking on that opens up a modal like this

modal

 

Let's say, for example, that we don't want to want to show the address details in this template. We could modify this file, but if the Leohtian template is updated any changes we make to this file will be lost, therefore we are going to make a TOP plugin. This plugin can then be zipped up and uploaded to multiple Jomres sites, or even sold on to other Jomres users if you think they'll like the pack.

First we will make a new directory in the remote plugins, like this :

remote plugins directory

Inside that directory I will create a new plugin_info.php file, and in that I will put this :

// ################################################################
defined( '_JOMRES_INITCHECK' ) or die( '' );
// ################################################################

class plugin_info_my_first_template_package
    {
    function __construct()
        {
        $this->data=array(
            "name"=>"my_first_template_package",
            "category"=>"Templates",
            "marketing"=>"A simple template package example where the address has been removed from the property header.",
            "version"=>(float)"0.1",
            "description"=> "A simple template package example where the address has been removed from the property header.",
            "lastupdate"=>"2017/06/13",
            "min_jomres_ver"=>"9.9.4",
            "manual_link"=>'',
            'change_log'=>'',
            'highlight'=>'',
            'image'=>'',
            'demo_url'=>'',
            'third_party_plugin_latest_available_version' => '',
            'developer_page'=>''
            );
        }
    }

 

Next I will create a 00001 script which tells Jomres that files are available. I'll call it j00001my_first_template_package.class.php and it will contain :

// ################################################################
defined('_JOMRES_INITCHECK') or die('');
// ################################################################

class j00001my_first_template_package
{
    public function __construct()
    {
        $MiniComponents = jomres_singleton_abstract::getInstance('mcHandler');
        if ($MiniComponents->template_touch) { $this->template_touchable = false; return; }
        
        $this_plugin = "my_first_template_package";
        $ePointFilepath=get_showtime('ePointFilepath');

        $template_path = str_replace ( JOMRESPATH_BASE , "" , $ePointFilepath );

        // Add information about this/these template files to the template packages singleton array.
        $template_packages = get_showtime('template_packages');
        if (is_null($template_packages))
            $template_packages = array();
            
        $template_packages[$this_plugin][] = array (
            "template_name"=>"property_header.html",
            "title"=>"Property header with the address removed",
            "description"=>"",
            "screenshot"=>"",
            "path"=>$template_path);

        set_showtime('template_packages' , $template_packages );
    }

    public function getRetVals()
    {
        return null;
    }
}

Once I have created that file, I will need to rebuild the registry to make sure that Jomres includes this script every time it runs.

Now I can copy property_header.html from the \templates\jr_leotian\html\com_jomres directory into this one. When I've chosen this template in the Template Override Manager then this version of that file will be used instead of the one in \templates\jr_leotian\html\com_jomres. When that's done I can customise this file as much as I want to remove the address details, this file will not be overwritten when Leohtian is updated.

Distribution

If I want to re-use this package on other installations, all I need to do is zip up the contents of the directory.

plugin zipped up

With these files in a zip file, you can use the Jomres Plugin Manager Third Party Plugins page to upload these changes to other sites.

Updates

In the plugin info file you should also add some information if you plan to distribute the plugin.

'third_party_plugin_latest_available_version' => "",
'developer_page'=>''

These two lines will tell Jomres where it can get updated version information about the plugin, and offers a link to a url where the update can be downloaded from. This could be a direct link, or to a shop page.

'third_party_plugin_latest_available_version' => "http://localhost/versions/my_first_template_package.json",
'developer_page'=>'http://localhost/versions/'

 

Your template versions file should be a json file : my_first_template_package.json which contains the following information.

{
  "version": 3.1,
  "releaseDate": "2017-06-12"
}

 

 

 

 

 

 

 

Back to Jomres.net