Customising BookyFlow

Here we will discuss ways that you can modify BookyFlow to suit your own requirements.

BookyFlow, whilst it works fine \'out of the box\' should nevertheless be seen as a toolkit. It's extremely common for designers and developers to want to customise the layout (I'm not sure if that's a comment on my design skills or not).

This section places a strong emphasis on advising you how to override files in an update safe way. This allows you to customise how BookyFlow works in such a way that you can update to new versions of BookyFlow without losing out your changes.

If you're going to modify how it works, it is recommended that you read this section on the basic conventions used when customising BookyFlow.

Read This First

####### Overriding files

As of BookyFlow 10.7 you can override virtually all of the code in BookyFlow Core and its plugins. In previous versions of BookyFlow you would be encouraged to put your code into the

/bookyflow/remote_plugins directory. This advice has now changed. Instead we would encourage you to locate your theme/template's override directory and store your override files there. If you already have files/overrides in the /bookyflow_remote plugins directory there's no need to move

them. The 10.7 changes don't affect existing functionality with respect to overriding those files, instead it builds upon it.

####### How do you find the override directory?

Joomla

Your Joomla template exists in your site's root directory/templates/TEMPLATENAME/. The BookyFlow override directory is under that in /html/com_bookyflow/

Example : /public_html/templates/TEMPLATENAME/html/com_bookyflow/

Wordpress

Your Wordpress theme exists in the /wp-content/themes/THEMENAME/ directory. The BookyFlow override directory is under that in /html/com_bookyflow/

Example : /wp-content/themes/THEMENAME/html/com_bookyflow/

In the rest of this document we will refer to this directory as the override_directory. Template files can be copied directly into the override_directory, whereas scripts and other files need to go into a subdirectory called 'custom_code' (override_directory/custom_code)

BookyFlow supports child templates/themes, and you are encouraged to use them.

If the directory does not initially exist, you can safely create it. If you want to override BookyFlow scripts, you will also need to create a subdirectory called custom_code (

/html/com_bookyflow/custom_code ).

####### Property type overrides

There is a subset of directories that can exist in the override_directory/ directory which correspond to property type IDs, so if I have a property type of 2 (in a default BookyFlow installation that would be for Car property types) then in that directory override_directory/2/ I can put BookyFlow template files and Minicomponent scripts that will only be called when the property being shown is a car.

####### Customising Hints and tips

If you would like to edit some of the core BookyFlow functionality, for a large part this can be done easily in a way that is upgrade safe (i.e. will not be overwritten by an upgrade of BookyFlow). Many techniques are discussed at length in other sections, but to summarise :

  • If you rename a BookyFlow minicomponent, to modify its functionality, it\'s important to not only rename the file. For example if you have a minicomponent called j00005foo.class.php, and you want to rename it to j00005bar.class.php, you must also change the class name to j00005bar too, in the file itself.

  • If you want to copy a minicomponent (for example so that you\'ve got a backup while you edit another version of that file) [do not]{.mark} simply rename it to something like j00005foo_backup.class.php. Instead, rename it to xj00005foo.class.php, otherwise BookyFlow will try to run that script as it follows the naming pattern it\'s expecting, and this could result in unpredictable behaviour.

  • If you want to change the language strings/labels used, you can edit a language file, but before you do that we would encourage you to first use the Label Translations feature. This can be used even if you are not using multiple languages, if you simply want to reword one string from another. Changes are saved to the database so if you upgrade, your customisations are not lost. All language strings can be edited through the Label Translations and Translate Language File Strings menu options in the administrator area.

Customising templates/layout

The two biggest items that our users customise in BookyFlow are languages and template files. Languages are addressed elsewhere, so here we will talk about what to do if you want to modify BookyFlow template files.

I need to point out that these template files aren't like template/theme files in Joomla or WordPress. You cannot include PHP in them. All dynamic data that is used to populate template files is collected in a calling script and put into PHP arrays, which are then handed to the patTemplate class which in turn uses the template file to generate the output.

Where are BookyFlow templates?

I'm going to assume that I don't need to tell you how to navigate to a subdirectory and physically edit files.

BookyFlow Core templates reside in the /bookyflow/assets/templates directory.

You can see an example here https://github.com/WoollyinWalesIT/bookyflow/blob/master/assets/templates/bootstrap5/frontend/to p.html

Template Overrides

There are two types of overrides; basic template overrides, and template packages.

####### Basic Overrides

BookyFlow Core templates

Copy the BookyFlow template file you want to customise ( e.g. basic_module_output.html ) into the override_directory for your Wordpress theme or Joomla template and BookyFlow will use that template instead of the Core copy (create the parent directories if required).

These directories are not overwritten when BookyFlow is updated, therefore any time you edit a template file, your customisations are mostly safe, however occasionally a Joomla template or WordPress theme update can overwrite those changes. Child themes make this less of a problem, but not everybody knows about or wants to use them.

Property type specific templates

In the override directory you can create a sub-directory with a number. That number can correspond to a property type id in BookyFlow. Templates placed in that directory will then be used if the property being shown is of that property type id.

For example, if you create a sub-directory of 6 (in a default installation of BookyFlow, this is the Villa property type id), and then copy property_details.html into that directory, you will now have a custom version of property details that will be used if the property being shown is a Villa type property.

BookyFlow Plugin templates

In the /override_directory/ create a subdirectory with the same name as the plugin, so if you're overriding the Bootstrap 5 Hero Slider plugin then you would copy the index.html file from the plugin's directory in /bookyflow/core-plugins to the html directory of the theme/template.

{width="4.739583333333333in" height="2.6145833333333335in"}

####### Shortcode template overrides

>= BookyFlow 10.6

Introduction

Shortcode overrides are a little like basic overrides. They require that you know which template file(s) are used when a shortcode is used, but they are a powerful addition that arrived in BookyFlow 10.6.

They are used to tell a shortcode that it should use a different template file, and not the default. Sounds complicated? It's not really. Let me give you an example.

An example of overriding a template in a shortcode Let's look at the show_rooms.html template file.

This is one of the template files that is used on the Property Details page. That page uses a shortcode ( {bookyflow_script show_property_rooms PROPERTY_UID=N} ) to output the rooms list. show_rooms.html is written to display rooms in rows because in the property details page, they're in a column and this is the best layout in that location.

In this scenario I want to show the rooms on a page of their own, as well as in Property Details, but instead of rows one room wide, I want to show three rooms (columns) to a row. In show_rooms.html I can easily change the first instance of

\<div class=\"col-sm-12\">

To

\<div class=\"col-sm-4\"> However if I do that, the rooms list in Property Details won't look right, they'll all be squished up. What I can do is put a shortcode like

{bookyflow show_property_rooms &property_uid=1}

in an article, and then copy show_rooms.html into the override_directory, and rename it to something unique like show_rooms_cols.html and change col-sm-12 to col-sm-4 in that file.

I can then modify the shortcode like this

{bookyflow show_property_rooms &property_uid=1&show_rooms.html=show_rooms_cols.html} And the layout will look something like this

{width="6.241656824146982in" height="1.9885411198600176in"}

It's still not perfect, I'll need to play around with the markup in show_rooms_cols.html to improve how it looks, but now I have a unique layout on a different page, without spoiling the layout in the property details page.

You could use exactly the same technique with other shortcodes, including plugins like the Search Form Elements plugin to have multiple forms with different layouts/markup.

Summary

This is a relatively simple example of a powerful feature. You can have as many shortcodes as you like, each pointing to different template files. It's useful because you don't need to edit any

code to achieve different results from the same source script. Just edit the html in the override template file and you're in business.

If you make a typo in the name of the override template file, BookyFlow will fall back to using the original template instead.

####### Template override packages

Template override packages are a little used feature of BookyFlow that you can potentially use to distribute different layouts for BookyFlow. See here for more information.

Minicomponent Overrides

You can copy a file (with the jnnnnnxxxx.class.php naming pattern) from

/bookyflow/core-minicomponents or plugins in /bookyflow/ core-plugins into the override_directory/custom_code directory. Once you have done that, you will need to visit the Administrator > BookyFlow > Tools > Rebuild minicomponent registry page. Once you have done that BookyFlow will use the new script instead of the one in /bookyflow/core-minicomponents.

####### Property type specific minicomponents

>= BookyFlow 10.7.0

From BookyFlow 10.7 you are able to have property type specific minicomponents (updated version of the plugin manager is required).

In this example screenshot, we have a property type 11 (Tool Hire Centre)

{width="5.4375in" height="2.625in"}

Having the Single Person Supplements configuration tab in the business configuration page doesn't make sense, so we'll create a copy of j00501suppliments.class.php in that directory, remove the settings completely so that the constructor just contains

And rebuild the registry.

Now we've removed the Supplements tab for properties of type 11.

The main reason for adding this functionality is to allow site developers to tweak the property configuration tabs for individual property types. That said, you are not limited to customising just tabs, you can have customised versions of minicomponents for any property type.

Function overrides

>= BookyFlow 10.7.0

Most BookyFlow function files exist in the functions directory at

https://github.com/WoollyinWalesIT/bookyflow/tree/master/libraries/bookyflow/functions

Some are CMS specific and can be found here https://github.com/WoollyinWalesIT/bookyflow/tree/master/libraries/bookyflow/cms_specific in the relevant sub-directory, depending on your CMS, in the file called cms_specific_functions.php

You should not modify any of these files, otherwise you will have difficulty upgrading in the future.

Instead, you can create your own function override file in your theme/template html/com_bookyflow/custom_code/custom_functions.php file.

This file is included by BookyFlow before other function files, so you can put your customised versions of functions in there.

Class overrides

\< BookyFlow 10.7.0

You can override class files by putting your customised class files into

remote_plugins/custom_code

Once you have copied a file into there, remember to rebuild the registry in admin > BookyFlow > Tools menu.

>= BookyFlow 10.7.0

From BookyFlow 10.7.0 onwards you can additionally have custom versions of class files in the

override_directory/custom_code/ directory.

Map style overrides

>= BookyFlow 10.7.0

BookyFlow' map styles are stored in https://github.com/WoollyinWalesIT/bookyflow/tree/master/assets/map_styles

and configured in site configuration. You can copy a map style into the theme/template html/com_bookyflow/custom_code directory and rename it to custom_map_style.style to have your own map styles that aren't overwritten by updates to BookyFlow.

jQuery UI overrides

Create a file called custom_jquery_ui.css in the override_directory/custom_code directory and BookyFlow will use that. Due to when it\'s called Jquery UI css declarations here will override the defaults.

CSS and Javascript files

BookyFlow CSS and Javascript files can be found in the /bookyflow/assets directory. You can override these by placing copies in the override_directory/custom_code directory.

Router override

Joomla only.

A custom copy of components/com_bookyflow/router/router.php can be put into the

override_directory/custom_code directory and BookyFlow will use that instead of the default.

Additionally the code for scanning for the router.php file will look in both remote_plugins and core-plugins to see if there's a file it can use, if there isn't a copy in the override directory.

Access Control override

From BookyFlow v10.7

It is possible to dynamically set which tasks appear in the BookyFlow main menu based on the property type.

In the override directory create a subdirectory of the property type id (this is the same process as for having property type specific template files).

Create a file called access_control_pattern.php It's contents would look something like this.

The above example would prevent the REST API menu options from appearing and being accessible, even through the address bar of the browser.

Overrides and the REST API

The overrides mentioned in this document will also be used when using REST API endpoints. Most of them (templates/css/javascript) would not be used in that context, however classes, functions and the router will be used. When the REST API starts up it needs to detect the override directory, however for performance we don't include any CMS frameworks at that point (and even if we did, Jooma will throw an error because there's no template set on REST API calls). This means that the REST API code does its own thing to find the overrides.

To do this it'll scan the theme or template directories looking for /html/com_bookyflow and if it finds one it'll use the files found there. This means that if you've got two copies of /html/com_bookyflow in different directories it may be using the wrong set of files.

Bear that in mind.