Headless bookings in the Jomres booking engine

Regular visitors to Jomres.net will have noticed a new form on the landing page of Jomres.net. As promised, here is an article on this new feature.

landing page booking form

What you see here is the first iteration of the New Booking Engine for Jomres. This booking form's javascript pulls information about Villa Elena on the Joomla Portal demo server to build a booking form on the main Jomres.net website. If you're a WordPress user, don't worry, the techniques I describe here are identical to those used in WordPress.

For more information about the rationale for creating it, please see this blog post. Here, I'll talk about ways that you can use the functionality.

Why?

Let's say, for argument's sake, you want to take bookings on your website, but you want the booking form to be on a different server. This is a surprisingly common request but not something that I've been able to provide in the past due to how the old booking engine worked. The booking form and the server functionality were tightly bound, one would not work without the other and both had to be on the same server, used within the context of the CMS. There have also been requests for mobile apps and other methods of making bookings that don't rely on the guest being physically on your website.

These requests required that the booking engine be headless, and the NBE functionality is the game changer that makes this possible.

What?

The NBE at it's core uses the Jomres Booking Engine REST API functionality so, if you want to work with it, the first thing you will need to do is ensure that your server is able to use this functionality. To do that first visit Administrator > Jomres > Tools > REST API test page. If there's anything you need to do, that  page will provide you with guidance.

Once you know that the API is working then you'll be ready to install the NBE plugins. The two that you will need to install on your server are "NBE Common" and "API Feature Booking". These need to be on your server to be able to respond to API Booking requests.

The third plugin doesn't need to be on your server, it really depends on your own use case. This plugin is the "NBE Booking form". For now you can install it, by default it doesn't automatically get used by Jomres, however it does deliver the files you will need.

This plugin provides a number of different files, but the two of interest to us are the iframe.html file, and index.php.

nbe booking form folder

How?

The simplest way of using the NBE Booking form is within Jomres itself. Once the plugin is installed go to Site Configuration, you'll see a new tab New Booking Engine

nbe site config

Because this functionality is new and the NBE can't do everything the old booking engine can do, yet, it doesn't by default override the existing booking engine. It's still, strictly speaking, Beta functionality. If you're not a developer/designer, I do not recommend you install it at this time.

It may be that the old booking functionality does more than you need (manager price overrides/coupon codes/extras/Jintour bookings) then the NBE will be ideal for you, in which case you can switch it on, however in this article I'm demonstrating how we can make bookings headlessly so that you can explore this exciting new feature of Jomres on your own development server(s).

 

NB, there are several ways that you can use the booking form on your own server without overriding the Core jomres booking form. Perhaps you want to include the booking form in a different Jomres template file?

{jomres_script nbe_booking_form PROPERTY_UID={UID}}

I've tested this in the Lux property details template and it works fine.

If you want to include it via a shortcode, then the syntax is almost the same : [jomres nbe_booking_form &property_uid=1] (Wordpress) or {jomres nbe_booking_form &property_uid=1} (Joomla)

If you want to include it in a PHP file then you would do something like this 

<?php echo do_shortcode('[jomres task="nbe_booking_form" params="&property_uid=1"]'); ?>
<?php echo run_jomres_shortcode('jomres task="nbe_booking_form" params="&property_uid=1"'); ?>

in WordPress and in Joomla respectively.

 

Tell me more, tell me more - Was it love at first sight? 

 Yeah, I'm showing my age now, I clearly remember watching Grease in the cinema in 1978.

Anyway, moving on...

As I mentioned before, the two important files are iframe.html and index.php

iframe.html is relatively simple but it performs a couple of important tasks. One is that it calculates the vertical height of the frame. This is needed because this booking form is designed to be used in various places in different ways depending on your needs. The other thing it does is it calls index.php and gives it some information it needs to start building the booking form.

<div class="row-container">
<iframe src="{FORM_URL}" class="iframe"></iframe>
</div>

If it's used by Jomres itself when showing the form then Jomres knows some things about the property to be shown so it builds FORM_URL, which is rendered in iframe.html then passed to index.php. On jomres.net this url is hard coded, but within Jomres the FORM_URL is generated dynamically, and looks something like this :

https://www.jomres.net/booking_form/index.php?property_uid=12&api_url=https://joomla-portal.jomres.net/jomres/api/booking/

 

Download these two files to your desktop. If you want, you can download the NBE Booking Form plugin via this link but please remember that it is constantly being updated and the best source of plugins is through the Jomres plugin manager. I won't be updating that download.

Open the zip file and extract the index.php file. Rename it to index.html and then open it in your favourite browser. Initially it won't do anything if you open it in the browser, but when you change the url in the address bar you'll find that you are able to access Villa Elena on the demo server via your desktop:

index.html?property_uid=12&api_url=https://joomla-portal.jomres.net/jomres/api/booking/

index dot html on the desktop

How cool is that?

It should go without saying that, once you have installed NBE Common and API Feature Booking in your own Jomres installation, you'll be able to access your own installation in the same way. Try it. Visit the REST API test page in Administrator > Jomres > Tools, it'll tell you what url it called, e.g. http://www.domain.com/jomres/api/core/report/ and if you strip off the /core/report/ part of the url, you've got the path to your own Jomres installation's API : http://www.domain.com/jomres/api/

Once you have that, you can change the url in the address bar of your browser to point to your own API, change the property_uid to a test property on your site and go ahead with playing around with it.

 Note : There's a good chance that it might not work immediately because there's a change that's needed in the Jomres core API's index.php file, you can see it here.

 https://github.com/WoollyinWalesIT/jomres/commit/1acffbdcda22f57883a6ab25b48a8ed55fdbf763

If you're running any version of Jomres lower than 10.5.1 then you will need for now to make this change manually on your server.

Index.php (or index.html if you've renamed it) is made in native HTML and javascript. It's possible that you're a React or Vue.js designer, or a fan of some other technology that I haven't even heard of yet. If you are then you'll probably want to build a booking form using the framework that you're most familiar with. In that case you can use this booking form as a pattern for building your own webapp. I could have written the form in Vue.js, I've used it in the past but opted instead to go with a simpler framework that all web app developers should be familiar with.

Is this a security risk, revealing the API like this?

No.

The API is designed, from the ground up, to be secure. You can read a little more about that in my previous article about Jomres Booking Engine REST API.  By default all endpoints are tightly controlled unless the individual plugin allows non-authenticated access.

Accessing the API via the NBE endpoints is just a different way of pulling information from your server, compared to the old booking form. The information exposed is exactly the same, but packaged and presented differently.

Does this form also handle payments?

No, it doesn't. If the property is configured with a payment gateway then once the booking is confirmed by the guest then they are redirected to the booking confirmation page on your website. It's the same page as the old booking form uses, where they can then use the payment form of the gateway. If the property doesn't have a gateway configured then the booking is added to the site without any further actions by the guest or yourself.

Will this change? Probably yes. For example the Bitpay payment gateway has a lovely modal popup for taking payments without the guest needing to leave your website. I'd like to investigate further whether or not that, or something like it, can be used by the headless booking functionality but that's to be explored in the future if this new functionality proves to be popular.

You need to get involved!

Over the years I've worked on dozens, if not hundreds of projects for Jomres. Some have been completed to provide new features that users have requested. Others have had to be dropped because of a lack of interest by my users. I'm just one man and features like this are incredibly time consuming to create. If not enough people show an interest in this I'll be forced to put the feature into maintenance mode without exploring it's full potential, so if you agree with my vision of what a booking portal can become, I encourage you to leave feedback as it occurs to you. The best place to do that is here.

 

 

  • Created on .

ABOUT US

vince picDeveloped and maintained by Vince Wooll, Jomres was initially conceived in early 2005 as a Mambo based solution to a client’s hotel management needs. While it wasn't originally expected to be an online booking system it quickly morphed into one as users requested more and more features.

As the number of feature requests grew Vince knew that he would need to dedicate more time to the project and in July 2005 Jomres was formally released as a commercial project. Since then, Jomres has become one of Mambo’s, and now Joomla’s, longest running projects. It has survived various versions of Mambo, then Joomla 1.0, 1.5, 1.6, 1.7, 2.5 and 3.

Aladar joined the project in 2010 after using Jomres for his own projects. He was active on the forum, helping other members of the community and eventually Vince invited him to join the team. Between 2010 and 2018 he was an integral part of the project and made many significant contributions.

Whilst not formally part of the Jomres project, Rodrigo Rocco and Vince have become firm friends. Rod is a freelancer who specialises in doing custom work for Jomres users and developing custom plugins for the system that take advantage of it's modular design. He has built many useful extensions including his fabulous Valentina Template Override Package.

Jomres and the Jomres Logo is trademarked and can't be used without written consent from the owner.

www.jomres.net is not affiliated with or endorsed by the Joomla! Project, Open Source Matters or the WordPress project. The Joomla! & WordPress names and logos are used under a limited license granted by Open Source Matters and the WordPress Projects.

© Copyright 2005 - 2022 Vince Wooll