PBBooking Documentation

System Requirements

PBBooking has the following minimum system requirements.

  • Joomla versions 3.5 or later
  • PHP >= 5.4
  • Support for Javascript on the client

Installation & Upgrading

Please note: if you are upgrading from an earlier version of PBBooking and have created template overrides, these WILL need to be recreated. There have been changes to the naming of input elements in the booking forms and the location of the scripts and CSS loaded by the views. Review the original views that can be found in the components/com_pbbooking/views/pbbooking/tmpl directory.

Once you have obtained the latest build of PBBooking from the Purplebeanie.com Download Site, you can install as you would any other Joomla component. This documentation assumes that you are using the latest Joomla 3.5 build. At time of writing this was Joomla 3.5.1

Firstly click on the Extensions Menu from the top Joomla menu bar and select the Extension Manager option from the dropdown menu. After ensuring the selected tab says Upload Package File select the package file from where you downloaded it using the Choose File button and click Upload & Install.

The zip file will be uploaded, decompressed, and installed. Depending on your internet connection this make take a minute or two. The zip file for PBBooking 3.0.0 is a 3MB file as it includes additional libraries including the Zend GData library. Please ensure that your host has set the max_file_uploads to at least 5MB in the php.ini file.

Once the component has been installed and a successful message has been shown you are ready to start configuring the component.

The PBBooking installation script will automatically try to update your database schema and data if you are running an older version of the application, however while very care has been taken in testing this, please ensure you back up your data prior to upgrading.

The minimum you need to configure to use your new booking system is to create a menu item and publish it to the front end of your Joomla installation. To create a new menu item access the Joomla back end for your site, click on Menus highlight the menu you wish to add PBBooking to and then click Add New Menu Item.

The will bring up the New Menu Item screen. See below.

Installation a new menu item
From this screen click the Select button next to the Menu Item Type text field.

PBBooking Menu Items
PBBooking adds two new menu types to Joomla. These are highlighted in red in image above and are found under the Purple Beanie Online Booking section. To add appointment booking to the front end of your web site choose Standard PBBooking Layout. The other will be discussed later.

Once you have named your the menu item as you would like it to appear click the Save button to return to the Joomla menu listing.

Congratulations. At this point PBBooking will now be installed on the front end of your web site and able to accept bookings using the default data. We will now move on to configuration and customisation.

Configuration

The previous section has shown how to get a basic installation of PBBooking working on the front end of your website. This section will look at the configuration options that are available to adapt PBBooking to the needs of your business.

The Main Pbbooking Dashboard
The screenshot above shows the main PBBooking dashboard. It provides a quick overview of activity within your PBBooking installation, along with general announcements about PBBooking releases and news and offers easy access to day to day areas for configuration and also management. The icons in green are sections that relate to day to day usage, the icons in black are links to configuration items. Please note that some of the options shown are only available in the subscriber versions.

The table below provides a brief overview of each menu and its function.

NamePurpose
ResourcesDefines resource availability.
ServicesCreate services and link to calendars.
Global Trading HoursCreate global trading hours for defining views.
Custom FieldsDefines the custom fields that are completed during the booking process.
HolidaysCreate blocked date ranges that effect one or more calendars.
System EmailsEdit and manage email templates. Prior to 3.2 this was in the main configuruation.
SMS TemplatesCreate and manage SMS templates. This requires the subscriber version.
Client RemindersConfigures client reminders and send timings.
Testimonial ConfigurationConfigures the testimonial modules.
ConfigurationMake configuration changes.
Multi Language SupportOverride messages and labels for multi language.
Manage DiariesAllows you to view, manage, and edit existing appointments.
Reports & ExportsThis icon allows access to the reports menu. Currently only basic reports are shown.
TestimonialsAn interface to view testimonials that have been completed by clients.

Resources

The resources section is used to create, edit, and delete, resources. In previous versions resources were also known as calendars. They are any person, room, or equipment that is capable of performing a service and they are central to calculating availability of services.

Each Resource can have different trading hours, to reflect different rosters that staff may be working, with different services associated with each calendar. This ensures that services can only be booked when staff are available that can perform that service.

For example, in our Natural Health & Wellness Clinic, each of our therapists can perform a variety of services. Each therapist has been created as a resource. As all our staff work different rosters, each calendar has different trading hours to determine when that service can be offered.

Each PBBooking Resource can be linked to a specific Google Calendar. The Resources events are still created within the PBBooking installation but are copied to Google Calendar each time the Google Calendar synchronisation is run. For more details see the Calendar Integration section.

Calendar / Resource listing

In the above image no resources have been linked to Google calendar as can be seen from the unlinked badge in the Is Google Calendar column.

Create or Edit Calendars / Resources

Whether creating or editing resources the process and required information is the same. To demonstrate we will will step through creating a new calendar.

Firstly, click on the New button on the top left of the screen. This will bring up the Create or Edit Calendar window.

The Calendar / Resource Create & Edit Screen

This may look complicated at first but we’ll step through each section and explain.

There are four fieldsets that need to be reviewed for each calendar.

The Calendar Integration Options defines other external sources that your calendar will synchronise to. Currently only Google Calendar is supported. To link a Resource to a Google Calendar set the Enable Google Calendar Integration to Yes. You will then need to enter the Calendar Id to link this Resource to.

Information about finding the Google Calendar ID can be found in this blog post http://purplebeanie.com/PBBooking/3-1-0-release-update-so-google-api-v3.html.

Please note, while you can link to multiple Google Calendars you can only line to 1 Google Calendar account. This means if you are using calendars from other people’s accounts the calendar must be shared with you in their Google account.

Calendar Trading Hours

In addition to the Global Trading Hours already defined each resource can define it’s own Trading Hours. This allows you to have staff that work additional shifts or meeting rooms available at different times.

The Max Bookings field allows you to set the maximum number of bookings that can be taken on any given day. Leave this blank, or set to to 0 for no limit. Any other number will reflect the maximum number of bookings that Resource will accept before displaying as busy on the front end.

Class Schedule

If you enable Group Bookings for a resource the Class Schedule replaces the Calendar Trading Hours. This functions as a white list, any times listed in the Class Schedule will show as available, all other times will be shown as busy. Once a class is full the time will be blocked.

You can define multiple classes on the same day if required. For example, you could create a class at 10am in the morning, 12pm, and at 6pm.

Calendar Trading Hours Use Case

There are two main questions that are inevitably asked about Calendars and the way they are configured:

  1. Why do I need to enter the trading hours both for the main Trading Hours & Block Days and the Calendar Trading Hours?
  2. Why does each PBBooking calendar need to be configured separately to work with Google Calendar.

The best way to answer this is to describe the problem this was designed to solve.

PBBooking was originally developed for our Natural Health & Wellness Clinic. Like most health centres, day spas and doctors clinics in Australia we offer many different services delivered by a mix of part time staff, contracts, and, independent businesses. Thus, the availability of different services may vary depending on when each staff member works.

For example, although our clinic is open 5 days a week, and our main trading hours are Monday – Friday, our Beauty Therapist works only Wed-Friday, hence beauty services, linked to the beauty therapist calendar, are only available on those days.

In a similar fashion, by allowing each PBBooking calendar to be linked to a different Google calendar, the Google calendar can be shared with staff allowing them to see only their appointments and not the appointments of others.

Services

Unless you also happen to work in the natural health and wellness industry you will probably want to define your own list of services that are available for clients to book. The Services menu is the heart of making this happen.

The main services menu

The image above shows the main services list. There is no real restriction to the number of services that can be defined in PBBooking, however where extremely large numbers of services are being delivered you may need to modify the user interface for a more friendly customer experience.

The main list view provides an overview of all defined services, the duration, which calendars the services have been linked to.

In PBBooking service durations are specified in minutes. PBBooking has primarily been developed for clinics, doctors, day spas, and beauty salons. It does not handle services with a duration longer than your available trading hours.

Create or Edit a Service

Regardless of whether you are creating, or editing, a service the process is very similar. If you wish to edit a service check the checkbox next to the service and click Edit otherwise click the New button.

Creating or editing a service

Creating or editing a service

When creating a service it is necessary to supply the following information:

  • Name – the name you wish to give to the service. This is how it will be shown in the front end. For example: 30 minute remedial massage
  • Duration – the length of the service in minutes. This is used for calculating when the service can be performed. As stated above, PBBooking does not handle use cases where services are longer than the available trading hours on a give day.
  • Price – the amount the service costs. This field is mandatory, even if only a 0 is entered. If you do not wish to display the price this can be configured in the main PBBooking Configuration and is not controlled on a per service basis. The actual details of the currency can be configured using the language file and the main PBBooking configuration.
  • Linked Calendars – these are the calendars that can perform the service. In multi page view the user will be able to choose which calendar the appointment is booked in. In the single page view the appointment will be booked in the first available calendar.
  • Require Payment – this checkbox determines whether the user needs to pay for the service prior to the booking being accepted. Currently only Paypal is available as a Payment gateway, however more payment gateways are coming soon.
  • Is Variable Service – this is new in PBBooking 2.4.5.9. A variable service allows the user to specify the duration they wish to book for. A minimum duration needs to be provided.
  • Minimum duration – this is only used when the service is a variable service. It is used to determine the minimum amount of time a user can book for.

Trading Hours

One of the most important customisations to be made to PBBooking is to make sure you businesses trading hours are being used. There are two places trading hours must be defined in PBBooking.

  1. The main trading hours interface defines the hours used when drawing most of the views.
  2. The calendar specific trading hours are defined in the edit calendars interface. This is discussed later.

Defining trading hours and shifts

The screenshot above shows the main Trading Hours Configuration interface. This contains two sections.

  1. Opening Hours
  2. Configure Shift Times

We will discuss each of the sections in turn.

Opening Hours

The Opening Hours tab defines the hours for which your business is trading. The availability of specific resources can then be determined using the Calendar trading hours. This is used to determine the starting time and the ending time for drawing calendars and allowing booking.

Setting trading hours is simple. For each day of the week that you are open make sure the Is Trading Day box is checked. Then complete the Opening Time and Closing Time text fields with the relevant opening and closing time.

Opening & closing times must be entered in 24 hour format with the leading 0 as needed. The format of hours can be changed in the front end to more localised time formats.

Configure Shift Times

The second tab on the Trading Hours & Holidays Interface is the Shift configuration tab. Shifts are best thought of as a logical way to group the available time slots in your day. One shift can finish and the next shift can start straight away, or there can be a gap between shifts if you require a regular break, such as lunch break, during the day.

It is important to remember that even when shifts are continuous appointments cannot be booked over a shift end time.

Shifts require four pieces of information.

  1. The actual shift text field. This is used as an index in an associative array. It can only contain letters, numbers, -, _. It cannot contain spaces or UTF-8 characters.
  2. Shift display label is the label given to this shift in views. This can be any text and is free of all formatting restrictions.
  3. Shift start is the time that the shift starts from. This must be entered in 24 hour format including leading 0s.
  4. Shift end is the time that the shift starts from. This must be entered in 24 hour format including leading 0s.

To add additional shifts, click the Add Shift button on the bottom right of the screen. Shifts can also be deleted by marking the checkbox on the left of the shift table and clicking the Delete Shift button.

Customfields

Customfield showing default custom fields

Custom fields allow you to define fields for user input as part of the booking process. The following fields are available available:

  • select box;
  • check box;
  • radio box;

If you are defining any of the above as input fields you must define values. To create values simply enter the possible values separated by a ‘|’ character.

For example: A select box for titles would have: values of Mr|Mrs|Miss|Ms and a radio box for gender would have: Male|Female

Each custom field can be defined as Is Required? if the field is mandatory. This will enforce error checking in the front end and prevent the appointment being saved without the field being completed.

Any of the custom fields can now be used in the email body to the client. To include a custom field, simply use the place holder in your email body.

For example: A radio button custom field for gender could be accessed as |*gender*|

Special Email Customfields

There are two special custom fields that are available for emails. These are:

  • |*booking_details*| – inserts a table containing the client booking details into the email.
  • |*URL*| – inserts a URL string for validation. This custom field is only available in the Email Body email template.

Holidays

Holidays allows business owners to block specific date ranges in single, or all calendars, on a once-off or recurring basis. Block Dates are the easiest way to book holidays in PBBooking.

In the front end times covered by a block date range will appear as busy.

The holiday listing showing my holidays

The screenshot above shows the Holidays display. Each holiday is defined with a start date, end date, and a block note. To create a new block date click on the New button on the top left. There is some mandatory information and some optional information for a block date.

Configuring a new holiday.

  • Start Date – the start date is the date the block will commence from. The block will be inclusive of this date.
  • End Date – the end date is the date the block will finish on. The block will be inclusive of this date.
  • Block Note – the block block note is an optional note displayed in the block date range table to remind administrators what the block was created for.
  • Calendars – this is the calendars that blocked date range should be applied to. At least one calendar must be chosen for the block dates to function correctly.
  • Make recurring – this checkbox determines whether the block should be made a recurring block. Recurring blocks will recur based on the recurrence interval and the recurrence frequency until the specified end date.
  • Recurrence Interval – used in conjunction with the recurrence frequency to specify how frequently the block should re-occur.
  • Recurrence Frequency – used in conjunction with the recurrence interval to specify how frequently the block should re-occur. Available options for Recurrence Frequency are Daily, Weekly, Monthly, Yearly.
  • End Date – this is the date the recurrence block should re-occur to and is non inclusive. ie. if you want the end date date to be included in the block you should add one more recurrence to the end date.

Client Reminders

Client Reminders allow you to send a reminder email to clients about their upcoming booking. If you are using Google Calendar integration Client Reminders will only be sent to clients where events have been created in PBBooking. Reminders will not be sent for events that have been created in Google Calendar and synchronised to PBBooking.

Defining a new reminder to be sent to clients

To enable reminders make sure Yes is selected under the Enable Reminders select box and you have entered the number of Days In Advance you would like to send the client a reminder. You also need to go to Configuration to the Integration Settings tab and ensure Enable Cron is set to yes.

The following settings are required when setting up reminders.

  • Days in advance – from the date the page is accessed reminders for appointments recurring this many days in advance will be sent.

For example: having this set to ‘1’ means that if the reminders web page is accessed on the 5th November, reminders for events occurring on the 6th November will be sent. If this was set to ‘2’ reminders for events occurring on the 7th November would be sent.

  • Reminder email subject – this is the subject of the email that is sent to the client
  • Reminder email body – this is the body of the email that is sent to the client. All custom field merge tags can be used. The special custom field tag |*booking_details*| can also be used to send details of the booking.

Client Reminders & Security

To allow the use of remote cron services in shared hosting environments that might prevent the use of local cron jobs, the cron page is on the publicly accessible section of the website. As a security precaution reminders will only be sent once and only for the reminder period specified in the configuration setup.

You may wish to further secure this using .htaccess and mod_rewrite to prevent un-authorized access other than from approved IP addresses. If you are running a cron job on your local host this would presumably be the host’s IP address. This documentation does not include instructions for setting up a cron job or scheduled task. Numerous resources exist on the internet explaining how to set up a cron job.

Setting up a Cron Job

For more detailed information about setting up a Cron job to send testimonials or client reminders you can access the knowledge base article here: http://www.purplebeanie.com/support?view=kb&prodid=2&catid=2&kbartid=2.

Please note: If your host is using mod_security you may receive a 406 error when trying to run task. If this is the case you will need to specify a user agent string using the -A command with curl.

Surveys & Testimonials

It’s always nice to get feedback from past clients and the Testimonial section allows you to do exactly that.

To enable surveys you first of all need to configure the setup from the Testimonial Configuration section.

Configuring Testimonials to get feedback from clients

The interface to setting up surveys / testimonials is very similar to scheduled reminders. The following settings are required when setting up surveys.

  • Testimonial email subject – this is the subject of the email that is sent to the client
  • Testimonial email body – this is the body of the email that is sent to the client. All custom field merge tags can be used.

For example: having this set to ‘3’ means that if the cron web page is accessed on the 5th November, survey emails for events occurring on the 2nd November will be sent. If this was set to ‘2’ survey emails for events occurring on the 3rd November would be sent.

The questions to include on the survey are defined in the Questions section of the configuration. For each question the following information is required:

  • Field label – the question you are going to ask as it will be displayed to the client Field variable name – the name that will be stored in the database. This cannot contain unicode characters, spaces, or symbols other than ‘_’.

For example: to define a radio box asking whether the client would utilise your services again the Field Values would be defined as: yes=Yes I Would|no=No I Wouldn’t.

To allow the use of remote cron services where shared hosting providers prevent the use of local cron jobs, the cron page is on the publicly accessible section of the website. As a security precaution reminders will only be sent once and only for the reminder period specified in the configuration setup.

You may wish to further secure this using .htaccess and mod_rewrite to prevent unauthorised access other than from approved IP addresses.This documentation does not include instructions for setting up a cron job or scheduled task. Numerous resources exist on the internet explaining how to set up a cron job.

Once a user completes a testimonial the result will be found under the Testimonials tab in the back end.

System Emails

The System Emails section allows you to configure each of the messages that will be sent to the user or admin.

Configuring Testimonials to get feedback from clients

Some of the emails may not be relevant if you are using the free version of PBBooking.

To edit an email template click the check box and then click the edit button at the top of the screen.

The message can be edited in the editor at the bottom of the page. You can use any of the custom fields you have defined in the custom field section by enclosing it in an |*variable*| format. You may also use tags for:

  • |*URL*| to insert the URL the client should click to validate an appointment.
  • |*booking_details*| to insert the booking details table.
  • |*booking_ref*| to insert a booking reference the client can quote.
  • |*calendar_name*| this will be replaced with the name of the calendar the appointment has been booked in.

SMS Templates

This section will allow you to define the SMS messages that are sent to clients on specific events. This will require:

  1. The subscriber version of PBBooking
  2. An account with SMSGlobal
  3. The SMS plugin to be published see the section on the SMS Plugin.

Main PBBooking Configuration

The main PBBooking Configuration Menu

The Configuration section is where you will find the majority of configuration options for PBBooking. We will step through each of the tabs and the available configuration options in the next few sections.

Validation Settings

The validation settings selection

Validation settings allows you to define the workflow users for client validation. In the current subscriber versions of PBBooking three different validation methods have been defined.

  • Validation by Client – when using validation by client the client will receive an email after their booking with a link to click on to validate their appointment. Once validated the appointment will be confirmed.
  • Automatically Approved – when using automatically approved validation the appointment will be confirmed immediately.
  • Validation by Admin – when using validation by admin the administrator will receive an email after the booking with a link to click on to validate the appointment. Once validated the appointment will be confirmed and the client will receive a confirmation email.

It is important to note in PBBooking that pending appointments are not included when calculating availability. This means that multiple pending appointments can be created for the same slot and the first one validated will be booked.

If you choose to make a service a paid service this will override the chosen validation method. Appointments will then not be validated until paid.

View Settings

View settings defines many of the default display options

The View Settings interface allows you to control various aspects about how PBBooking is displayed without having to edit code. For any other configuration changes more advanced than what can be done through this interface you will need to use template overrides.

Each setting is defined in the table below.

SettingFunction
Prevent booking Within (minutes)Prevents booking within the specified minutes.
Maximum days in advance to allow bookingsDefines how far out clients can book.
Show LinkDetermines whether back link is shown.
Show PricesAre prices shown on the front end.
Time IncrementIncrement used for the grid in multi page view and gap between starting times in single page.
Week CommencesWhich day of the week to start from
Fields to Include in Manage DiariesPlace check boxes next to which fields you would like to include in the manage diaries interface if you are not happy with the default.
Enable ShiftsDetermines whether shifts are displayed in the front end or ignored.
Currency Symbol PositionControls whether the currency symbol appears on the left or the right of the price in the services select box.
Checkout StyleAllows you to easily change between single page view and multi page view.
Block Closed Days in Single PageIf a day is blocked determines whether it should be shown as blocked in the single page view. This is the default if multi page view if only one calendar is defined.
Disable AnnouncementsControls whether announcements are shown on the dashboard.
Disable Pending BookingControls whether pending bookings are shown on the dashboard
Show Busy on Front EndThis only works on the multi page view and show the booking details.
Force Select CalendarIn the single page view this setting forces a user to choose a calendar before choosing a service. This can allow clients to choose their preferred therapist or hair dresser while booking. This setting cannot be enabled if using Service Groups. They will cause unpredictable behavior as both settings solve a similar problem in different ways
Convert Client TZ OffsetThis setting turns on dynamic time zone conversion in the single page checkout.
Individual view calendar header colourA colour picker that allows you to define the colour of the header cell in the individual view.
Enable RecaptchaTurns on and off recaptcha on the front end. This requires that you have enabled and setup the Joomla! Recaptcha plugin.

Please note: It is not possible to use both Force Select Calendar and Service Groups at the same time. They are both different solutions to a similar problem and attempting to use both at the same time will cause problems.

Integration Settings

The Integration Settings define general integration options.

Integration settings

Integration settings

Currently the following settings are possible.

  • Enable CRON – this is a global setting to enable or disable the cron jobs. This only applies to scheduled tasks and reminders it does not effect Google Calendar Integration this is defined under the Google Calendar Settings.
  • Enable self service – switches on or off the self service on the front end.
  • Hours notice required for changes – this specifies the number of hours needed to allow clients to delete their appointments through the self service.
  • Display past appointments – controls whether appointments are shown on the front end.

Google Calendar Settings

In 3.1 PBBooking has changed from using the Google Calendar v2 API to the Google Calendar v3 API. The major difference between the two versions of the API is that authentication and access is now done using OAuth2.

From the Dashboard click configuration and go to the Google Calendar Settings tab. Under this tab ensure that:

  • Enable Google Calendar Integration is set to Yes
  • Sync Forward Events is set to One Month or greater
  • Sync Google Events to PBbooking is set to Yes if you wish to sync events entered into Google Calendar back to PBBooking
  • Google Cal Sync Secret is set to your preferred sync secret.
  • Google Query Max Results is set to a value appropriate for your site. Anywhere between 100 and 250 – 300 works well for most sites.

Google calendar settings defines the connection settings for Google Calendar

For now the Auth Code can be left blank. We will get this from Google.

Click the Link Calendar button and this will open a Google authorisation prompt in a new window or tab.

Select the user you wish to link this installation to

From the list of accounts, choose which account you would like to grant PBBooking access to. Only one account’s credentials are stored, so if you need to access calendars from more than one account you need to share these from within Google Calendar.

If you are not currently logged in to your account Google will ask you for your password to login. Just enter your password as normal.

Google will now display a landing page advising that Purplebeanie Online Booking for Joomla would like to Manage Your Calendars. Just click Accept.

The permissions page showing the permissions you are granting

From the next page copy the code in the text box to your clipboard. The code may be longer than the text box so ensure that you have copied all of it.

Copy the Auth Code to the space in the PBBooking Settings

Once copied, close the window to return to your PBBooking configuration and enter the code you just copied into the Auth Code box. Then click Save & Close.

Congratulations, you are all done. PBBooking is now configured to access your Google Calendar installation using OAuth2 and the new (v3) API.

What Can Go Wrong?

As with all things in life there are things that can go wrong. So let’s look at some of the things that can go wrong with the new v3 API.

Firstly, Google has now introduced daily quotes to many of their services. These quotas are based on the developer API key and for Google Calendar a maximum of 500,000 queries per day can be issued.

By default PBBooking 3.1.0 will use the main PBBooking Subscriber key so that installation is as simple as possible. This means you will be sharing 500,000 queries per day with all other users. If you are a high traffic site I would strongly encourage you to grab your own API key. Raise a support ticket for details.

Secondly, OAuth2 uses refresh tokens that allows PBBooking to sync with Google Calendar off a scheduled task or cron job. Each Google account is allowed a maximum of 25 refresh tokens at any given time. Each time you grant an application offline access using OAuth2 a new refresh token is created.

When you exceed 25 refresh tokens the creation of the 26th token will invalidate the first token. If the PBBooking refresh token is invalidated the sync process will stop. You will receive an email notifying you and will need to re-link the installation.

Google Query Max Results

The Google Query Max Results is used when retrieving events from Google Calendar. This needs to be set appropriately based on the number of months worth of forward events that are being fetched from the Google Calendar. Bear in mind that Google may restrict the number of results that can be retrieved at any given time.

Advanced Settings

The Advanced Settings tab in the configuration area are for settings that are new, require extra configuration, or are still in experimental stages.

The advanced settings is home to more complex or experimental settings

There are currently three additional settings that can be configured from the Advanced Settings tab.

Multi Language Support

This switches on multi language support for PBBooking. This assumes you have already configured multi language support for your Joomla site by enabling the Joomla System Language Filter and the Joomla System Language Code plugins and that you have created valid menus for each language you wish to support.

Enable multi language support

Once multi language support for PBBooking has been switched on you can configure the language overrides from the Multi Language Support menu available from the dashboard.

The new multi language control center on the dashboard

Convert Client TZ Offset

This setting, when enabled, will store the client’s browser reported time zone offset along with their booking details. When this is enabled dates and times will be displayed both in the server’s local time zone and the user’s time zone.

Booking Details

This allows you to define the booking details table that is used in emails. This is the html code that will replace the |*booking_details*| smart tag in emails. This template is rendered using Twig. You can find more documentation on the Twig templating language here http://twig.sensiolabs.org/documentation.

Previous subscriber versions of PBBooking were using Mustache for templating. If you have previously overridden this template you may need to make sure your changes are Twig compatible. The format for Twig is largely the same as Mustache however it has more support for conditionals and formatting in the

Access Control

From version 2.4.4 PBBooking supports Joomla’s Access Control List to restrict access to allow site administrators to control access to different parts of the booking system.

To access the ACL rules go to PBBooking Configuration and select Options from the menu bar.

Access the Access Control settings from the main configuration

The permission levels can be changed in the resulting window. The default permissions are to allow public access to all PBBooking functions.

Displaying the current Access Control settings

Currently the following actions are defined:

  • Create Booking – allows a user to create a booking in the calendar.
  • Delete Own Booking – allows a user to delete their own bookings through the self service interface. NB. the users still need to be logged in for this to work.
  • Browse the calendar – allows a user to browse the calendar.
  • Access Manage Diaries – allows a user with back end access to access the manage diaries interface.
  • Edit Configuration – allows a user with back end access to edit the configuration settings.

Multi Language Support

Multi Language Support has been redeveloped in the 3.0.0 products to make it easier to maintain. This assumes that you have previously configured the site to use the Joomla System – Language Filter extension. Fore more information see the Joomla documentation at http://docs.joomla.org/Language_Switcher_Tutorial.

To enable the configuration options for multi language support you first need to tell PBBooking that you wish to use multiple languages for PBBooking. To do this go to the main PBBooking Configuration menu item and click on the Multi Language Settings. Just check the Enable Multi Language Support checkbox to switch on multi language support.

Currently multi language support is only available for the following options:

  • calendars
  • services
  • custom fields
  • client focussed email messages

Configuration Multi Language Support in Calendars, Services, & Custom Fields

To add a new language override click on the Multi Language Support icon on the dashboard then click the New button the top left.

The new multi language control center on the dashboard

This will bring up the new entry dialog shown below.

Creating a new language entry

Once you select an Override Type from the first drop down box, the Current Field Names will be populated with a list of possible values that you can define an override for. For example to override the calendar name select Resources from the top drop down box. This will load a list of Calendars in the Current Field Name drop down box.

Select the value you wish to to edit (ie. Massage Therapist 1) which will load the current primary language value into the Primary Value text area. This value cannot be changed through the multi language support interface. To change the Primary Value it must be changed in the Resource itself.

From the Language Tag select which language you would like to create an override for. All installed languages will be shown in this select box. Then enter the override value into the text area labelled override value and click save.

If you have enabled multi language support but have not defined a language override for the string required the default, primary value will be used.

PBBooking Management

So now that you’ve got PBBooking installed and running to your satisfaction you want to know how to manage it on a day to day basis. This section will step through some of the more common tasks with managing your web based calendar.

Manage Diaries

Manage diaries is the day to day workhorse. This is where you can view upcoming events in the different calendars, edit events, and create new events. The Manage Diaries interface has gone through significant change in the latest release to make this easier to use.

The new manage diaries interface has had a big upgrade

Much of this wouldn’t be possible without the awesome jQuery Full Calendar Plugin.

Create Appointments

To create appointments in the diary simply click the time slot where you would like the appointment to begin. This will load the appointment creation dialog. This is loaded by AJAX from the server so on slow connections the dialog may take a couple of seconds to fully appear.

Create a new appointment quickly and easily

The Event Start will be automatically populated based on the time slot you clicked into in the diary. The Event End will also be automatically populated after you select a service from the Service drop down box.

Unlike in the front end, in the administration section it is assumed that you know which of your calendars support different services. A booking created in the back end can be assigned to any calendar. This is selected from the Calendars drop down.

The custom fields are automatically created from the custom fields you have defined for your site. They must be filled out for the event to save correctly. Creating an appointment from the administration interface gives the ability to create a recurring appointment. To make an appointment recurring check the Make recurring check box and fill out the details of recurrence.

Recurring appointments cannot be created without specifying an end date.

Once you select save. The appointment will be written to the nominated diary.

The event will now appear in the diary.

The event now appears in the manage diaries view

Clicking on an appointment in the main manage diaries screen allows you to edit an event.

Just click on an event to edit

The event description is based on all custom fields merged together with a new line character. Much like creating an event, editing an event gives you the option to make the event recurring.

When editing an event the Event Start and Event End fields can be changed using time pickers that will appear when the focus is on these boxes. The Calendar can also be changed using the drop down box.

It is also possible to modify the time of an event by dragging and dropping the event on the calendar.

Delete Appointments

Sometimes clients cancel or for some other reason you need to delete an event from the calendar.

To delete an appointment simply click on the event and then click the delete button in the bottom right of the edit screen.

If the event you have chosen is a recurring event you can check the Delete all future events under the Deletion Settings section of the Event Edit window to delete all future sibling recurrences.

PBBooking Default Plugins

From the 3.2 release there are a number of default plugins bundled with the core. The goal of using plugins was to increase functionality without adding extra code bloat and extra configuration settings for users that were only using the core functionality.

Extra plugins are all defined as plugin type pbbooking and can be viewed from the Plugin Manager by setting the Type filter to pbbooking.

The configuration for each extra plugin is done within the plugin itself to prevent users being overwhelmed with extra configuration settings that may not be needed.

The following sections will cover each of the default plugins.

Hot Chilli Software: Send SMS

The Hot Chilli Software: Send SMS plugin will enable SMS messages (as defined in the SMS templates) to be sent to clients on specific actions. At this stage the following actions are defined:

  • a pending event is created
  • an event is validated
  • a reminder is sent

You will need an account with SMS Global for these functions to work.

Once you have an SMS Global account login to the control panel and go to Account Settings under the account drop down on the top right of the SMS Global Dashboard. From the left hand side menu select the API Keys menu item.

These API keys can be entered in the API Username and API Password section in the Send SMS Plugin.

Once setup ensure the plugin status is set to enabled.

Message status and send messages can be reviewed from your SMSGlobal dashboard.

Hot Chilli Software: Jump to Booking Content Plugin

The Jump to Booking Content Plugin will enable you to use a plugin in your com_content articles to jump directly to a booking page with a specified calendar ID and date. To enable this plugin access through the plugin manager and set the Status to Enabled.

You can also use the editor area to control the markup used to generate the booking button.

The field |*URL*| is required. This will be replaced with the generated URL to link to.

Once the plugin has been enabled in your article content you can define tags like the below.

{pbbookingjump calendar=1;date='2016-12-30'}

{pbbookingjump instance1;date='next week'}

{pbbookingjump instance2;date='next month'}

The calendar will be used to specify which calendar is jumped to and the date will be used to specify which date. Dates can be entered either as absolute dates in the format YYYY-MM-DD or a relative date format accepted by PHP’s date syntax.

Hot Chilli Software: Payments Plugin – Paypal

In version 3.2 the Payments system have all been migrated out to plugins to allow both multiple payment providers and more payment options. At this stage plugins have only been developed for Paypal, and Alta User Points.

If you have previously been using PayPal payments the settings will be migrated to the plugin and the plugin automatically enabled.

The PayPal plugin requires your API details which are available from your PayPal account. From the PayPal Summary click Seller Preferences under Selling Tools and then select API Access and click Update. This will allow you to create or view API keys.

Please note that API access is not available for personal accounts. You will need a premier or business account.

Hot Chilli Software: Payments Plugin – Alta User Points

Hot Chilli Software: Online Service Booking Admin Events Plugin

The final additional plugin included in 3.2 is the Admin Events Plugin. This will send emails to clients based on admin initiated events. For example if an appointment is created, deleted, or updated from the back end.

To use this plugin set the status to enabled and define the messages in the main System Emails section of the pbbooking component.

Appendix A – Credits & Acknowledgements

As with any project there are always credits and acknowledgements that need to be given. First and foremost, my wife. She has put up with many nights of me tapping away at the keyboard both in actual coding and user support requests.

Other thanks go to:

Appendix B – Frequently Asked Questions

These are some of the most common support requests. Have a quick read over these before submitting a support ticket to see if these can get you back on track straight away.

How Do I Change The Currency Symbol?

The currency symbol is defined in the front end language file. On an english installation this will be located at: /language/en-GB/en-GB.com_pbbooking.ini Line 6 has a reference to: COM_PBBOOKING_CURRENCYSYMBOL Change this to your preferred currency symbol.

Why Isn’t The URL In the Validation Email?

Chances are you have edited the message body field in the PBBooking Configuration section and removed the |*URL*| tag. When preparing the message to send this tag is removed and replaced with the full URL defined using the Joomla JURI library.

Why Doesn’t My Page Look Like The One on the Web?

Welcome to the world of CSS and cross browser compatibility. The demo server runs a standard Joomla 2.5 installation and out of the box installation of PBBooking. There has been no customisation to the template.

Changes you make to the CSS and html of your template will affect the layout of components.

You can customise the CSS of PBBooking by editing the user_view.css or the user_view_multi.css file. Both these files are located in the media dir at /media/com_pbbooking/css/user_view.css.

Appendix C – Cookie Use Policy

With the use of cookies becoming a concern in some sections of the world it is worth covering where and how PBBooking using cookies.

In versions of PBBooking prior to 2.3.1 PBBooking makes no additional usage of cookies on top of that used as a standard part of the Joomla! CMS.

In version 2.3.1 of PBBooking the ability to save entered user data between screen refreshes was introduced to improve the user experience. This makes use of a cookie to save user data. The only information stored in this cookie is the contents of any customfields that might have already been completed.

PBBooking accesses information stored in the current PHP session and, if the user is currently logged in, will access their username for the purposes of auto completing the booking registration form.

Appendix D – Sync to Google

In Version 3.0.0 the Google Calendar integration has been changed form live integration to a task that can be run on a scheduled task or cron job. This has been done for two reasons:

  1. Improved performance in the front end – live integration with Google Calendar was leading to large delays loading sites with a more than one or two calendars and shorter time increments. The reason for this was that calculating the availability on each site required a separate lookup to Google Calendar. 2, Improved reliability in the front end – live integration on busy sites was resulting in Google Calendar time outs and disconnections, moving to a scheduled task means the booking system will continue to work even though a live connection to Google Calendar cannot be made.

The URL used for the scheduled task is

http://localhost/j330devcomm/index.php?option=com_pbbooking&controller=cron
                  &task=sync&format=raw&view=cron&google_cal_sync_secret=yoursecretkey 

where localhost/j330devcomm is replaced by your domain name and yoursecretkey is replaced by the secret key you defined in the Google Calendar Integration.

Setting up a Cron Job

For more detailed information about setting up a Cron job you can access the knowledge base article here: http://www.purplebeanie.com/support?view=kb&prodid=2&catid=2&kbartid=2. Please note: If your host is using mod_security you may receive a 406 error when trying to run task. If this is the case you will need to specify a user agent string using the -A command with curl.