internal_api

Introduction

This plugin is designed to be a tool for non-Jomres Component Developers to help them interact with Jomres.

At the time of writing, this plugin is designed to make it easy to pull the property list and property details pages through a few lines of code.

Let's say that you are a Joomla developer and you want to pull some pages from Jomres. This a relatively straightforward thing to do, if you're familiar with Jomres, but what if you're not?

Enter the Internal API plugin! It does some magic so you don't have to.

The code

Ok, hypothetically speaking, you're a developer with your own component. Now, you know a property uid and you want to display Jomres' property details page without having to figure out Jomres to do it.


First, you'll need to install the alt_init plugin, then the internal_api plugin. Once that's done, you're ready to use the following lines of code :

require_once(JPATH_BASE.DS.'jomres'.DS.'core-plugins'.DS.'internal_api'.DS.'internal_api.php');
$arguments = array();
$arguments['property_uid'] = 1;
$property_details = internal_api::get("viewproperty",$arguments);

echo $property_details;

Naturally you'd replace the 1 of the property uid with your own code.

That's it. That's all you need to do to import the property details page into your own application.


Let's look at an everso slightly more complicated example, the property list. Again, you know the property uids you want to show, so how would you do it?

require_once(JPATH_BASE.DS.'jomres'.DS.'core-plugins'.DS.'internal_api'.DS.'internal_api.php');
$arguments = array();
$arguments['property_uids'] = array(1,2,3);
$arguments['showheaders'] = true;
$arguments['jomsearch_sortby'] = 2;
$property_list = internal_api::get("listproperties",$arguments);

echo $property_list;

This is a little bit more complicated because you have a couple of options that we didn't see in the previous example, the showheaders option, and the jomsearch_sortby option.

Showheaders should be pretty self explanatory, it defines whether or not the calling script should show the headers. Unless you've got a good reason to set this to false, we advise you to leave it set to true, because with it set to false some crucial javascript may be missing from the page.

The jomsearch_sortby argument refers to the options that are set by the Sort Order dropdown in the property list. In the example above we've set it to 2, which means to sort by property name. If you'd like to see the other sort options, open j01009a_filterproperties.class.php in your favourite editor and see the available options.

Note : The sortby option may produce seemingly misleading property lists if any of the property uids in the list are configured to be featured properties.This is because the 010009 scripts will re-order the results based on whether or not properties are considered featured. Featured properties are bumped to the top of the list, regardless of the sort order chosen.

Note : Any links in the pages passed back will resolve to the Jomres component, meaning if a user clicks on a link they'll be taken from your component to the Jomres component.


Information about the booking items in the cart


require_once(JPATH_BASE.DS.'jomres'.DS.'core-plugins'.DS.'internal_api'.DS.'internal_api.php');
$obj = internal_api::get("getcarttotals",array());


An object will be returned, which looks something like


Object sample :
object(stdClass)[284]
public 'currency_code' => string 'EUR' (length=3)
public 'total' => float 310.66084280321
public 'deposit' => float 164.54012649299
public 'jsid' => string 'HpTtVtpLtgUUmqLpMQLltwUIYDPLYJBmYCVzFBWHnjIlIgnPNw' (length=50)
public 'number_of_bookings' => int 2
public 'items' =>
  array
    'ShvNZaMmqCldPRZlXCPy' =>
      array
        'total' => float 148.3044913474
        'deposit' => float 148.3044913474
    'BGnRxsRrsxslisflZtDv' =>
      array
        'total' => float 162.35635145581
        'deposit' => float 16.235635145581


Get information about the items in the Jomres cart. Regardless of the currency of the booking all figures are converted to the Global Currency code before being returned in this object.

Whilst you're given the total, you're not expected to act on it, that's for your own information/use. Instead you're expected to act on the $obj->deposit sum, taking payment for that.

Don't take another figure in your payment gateway and expect Jomres to adapt accordingly. When the time comes to mark the booking paid and the bookings are created, Jomres will mark the deposit it expected as paid so if you're taking a different figure then your user's records may become confused.

Your script will need to make a note of jsid, as you'll be using that later when you want to create the bookings (until payment is made they're still not created, they're only created in the next step).

And finally, marking the booking as paid.

require_once(JPATH_BASE.DS.'jomres'.DS.'core-plugins'.DS.'internal_api'.DS.'internal_api.php');
// To mark a booking paid, there's a few things we need to pass back to Jomres
$arguments = array();
// First we need the jsid. The Jomres Session ID is initially passed back to the calling script when you've called "getcarttotals" See the previous example.
$arguments['jsid'] = $obj->jsid;
// Then the items. This is a security check to stop a user adding more bookings once the calling component has taken over payment duties
$arguments['items'] = $obj->items;
// Can be true or false. This refers to the deposit. If it's set to false then the booking information will show the deposit as still owing.
$arguments['booking_paid'] = true;
$result = internal_api::get("createbookingsfromcart",$arguments);
 
var_dump($result );


We're assuming that your own component has handled payment, so there will be no checking on Jomres' part that payment has been taken, you're simply telling Jomres that it's been paid and that Jomres should create the bookings in it's system.

We'll re-use $obj here, normally you would be generating the object/data yourself after you've processed payment