twzBooking - technical reference

twzBooking is a PHP5 class that manages and displays availability for any number of facilities (rooms, houses, etc). It requires PHP server scripting and a MySQL database. If you already have another application that uses a MySQL database, the same database can be shared with twzBooking.

This page explains the options and settings for changing the look and behaviour of the calendar. Bear in mind also that you can change the look of the calendar substantially with appropriate CSS styling. For more information, see the examples provided in the download.


This image shows some of the key terms used in this documentation:

Calendar - timeline format

These methods only apply to timelines
setTimelineHeading() str Text Sets the heading text for timeline-format calendar.
Text (default = '')
setTimelineWidth() int Pixels Sets the pixel width of the timeline, excluding the location names.
Pixels (default = 600)
setShowDates() bool ShowDates Determines whether to show the earliest and latest dates of the current timeline with the navigation buttons.
ShowDates (default = false)
setDateRange() str FromDate
str ToDate
First and last dates initially shown in the timeline, and therefore the number of days shown. This along with setTimelineWidth() will determine the width of each day cell.
FromDate (default = 'today')

First day shown in the timeline

ToDate (default = '+1 month')

Last day shown in the timeline

showTimeline()   Displays a timeline calendar.

Calendar - month format

These methods only apply to the month-format calendar.
setMonthHeading() str Text Sets the heading text for month-format calendar.
Text (default = '[LocationName] availability')

Can include the special placeholder [LocationName], which will be replaced by the name of the actual location.

setWeekdays() arr Weekday
int FirstDay
Sets the day names and first day of the week for month-format display.
Weekday (default = array('Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'))

Day names must be in the order shown, with Sunday first. Also bear in mind that the day names have to fit into a small space — if you want to change them to 3-letter abbreviations, you'll probably need to also call the setDayWidth() method.
If you want to change the first day but not the day names, this parameter can be null and the default day names will be used.

FirstDay (default = 0)

By default the month calendars show Sunday as the first day of the week. If you want yours to display with a different day first, set the FirstDay parameter (0=Su, 1=Mo, 2=Tu, 3=We, 4=Th, 5=Fr, 6=Sa).

setDayWidth() int Pixels Sets the width of day cells in month-format display.
Pixels (default = 25)

The height of day cells (for both timeline and month format) is set with CSS.
showMonths() int LocationId
str MonthDate
int MonthCount
bool ShowLegend
Displays one or more month-calendars for a single location.
LocationId (required)

id of the location to show (id can be found on the "edit locations" admin page). If you specify an id of 0 then the first active location will be used

MonthDate (required)

date string indicating the first month to show

MonthCount (default = 3)

how many months to show

ShowLegend (default = true)

whether to show a legend

showMonthsAll() str MonthDate
int MonthCount
bool ShowLegend
Displays one or more month-calendars for all locations.
MonthDate (required)

date string indicating the first month to show

MonthCount (default = 3)

how many months to show for each location

ShowLegend (default = true)

whether to show a legend

Calendar - general

These methods apply to both timeline and month formats.
shadeWeekends() bool DoShade Determines whether weekend days are shaded.
DoShade (required)

if true, Saturday and Sunday day cells will be given the CSS classname "we", so they will be shaded with a diagonal pattern.

setMinDate() str MinDate Sets the earliest date that can be viewed by using the calendar navigation buttons.
MinDate (default = 'now')
setMaxDate() str MaxDate Sets the latest date that can be viewed by using the calendar navigation buttons.
MaxDate (default = '+1 year')
setRangeNav() int Position
str Size
str Colour
int HomeStyle
Configure the range navigation buttons. If any parameter is null, its default will be used.
Position (default = 0)

Defines the location of the buttons relative to the calendar and legend. Possible values are: 0=before calendar, 1=before legend, 2=after legend, 3=within header row (only applies to timeline format). Any other value will NOT show the navigation buttons at all. You could also hide the buttons by putting div.rangenav { display:none; } in your CSS. When changing the position, you will almost certainly need to also amend the .rangenav CSS to fine-tune it.

Size (default = 16)

icon size, which can be one of: 16 | 24 | 32 *

Colour (default = 'dgy')

icon colour abbreviation, for example red | grn | brn *
Check the files beginning rn- in the images folder set see what other colours are available.

HomeStyle (default = 2)

Style of the central "home" navigation button. Either 1=circle or 2=square

*The images used for the navigation buttons depend on the Size and Colour values specified. For example if Size=16 and Colour='grn' then icons will be taken from the image file rn-grn-16.png. If you specify a size or colour that's not available (ie the image file is not found), text links will be used instead.
setLegendAll() bool FullLegend By default, the legend only shows the booking status types that appear on the calendar. For example, if the visitor is viewing dates with no booking, the legend will not include "Booked".
FullLegend (default = false)

If true, the legend will always show all booking types, regardless of whether they appear in the accompanying calendar.

cssDayLR() int Pixels Tells twzBooking about any extra day cell width due to margins or borders. By default, day cells have a 1 pixel right margin ( { margin:0 1px 0 0;} in CSS). twzBooking needs to know this so it can determine the correct overall calendar width. For example if each day cell is 25px wide with a 1px right margin, the effective width of each day will be 26px.
Pixels (default = 1)

The extra width that should be accounted for, for each day cell. If you remove the right margin in your CSS, you should call cssDayLR(0). Conversely, if you keep the right margin and add a 1px border to day cells, you should call cssDayLR(3) - that is, 1 pixel for the margin, 1 for the left border and 1 for the right border.

System options

Miscellaneous extras
setImagePath() str PathNav
str PathCal
Sets the relative path to navigation icons and popup calendar icon.
PathNav (default = 'twzBooking/images/')

For admin pages, the default is '../images/'

PathCal (default = 'twzBooking/calendar/')

For admin pages, the default is '../calendar/'

setStatusTypes() arr StatusType Sets the labels and CSS classnames for the different booking status types.

An array indexed by status name, with values being the associated class names.
The default is: array( 'Available'=>'avail', 'Pending'=>'pend', 'Booked'=>'booked', 'Not available'=>'notavail', 'Waiting'=>'wait' ) The first element in the array must be the equivalent of "Available" (that is, no booking). You can specify as many different status types as you want, but only the first four will be shown to visitors; any additional status types can be used by admin users for their own purposes.

For example if you have written custom code that allows web site visitors to request an online booking, their request could be added as a booking of type "Requested", but would not appear for other visitors until the admin user has changed it to "Booked".

setAjaxNav() int AjaxNav Determines how the navigation buttons work for web visitors.
AjaxNav (default = 2)

0 = href - navigation links use a standard href, and the entire page is reloaded (no ajax).
1 = onclick - when a navigation button is clicked, only the calendar is updated, without reloading the entire page. This option will stop bots from following the links, but users must have javascript enabled in their browser.
2 = onclick+href - only the calendar is updated for people with javascript enabled, but the navigation will also work for those without javascript.

If using ajax (value 1 or 2), most twzBooking settings must be in twzBooking-setup.php and not in the actual page, because settings within the page won't be seen by ajax. In other words the page itself should only contain the require_once() and a "show" method (eg showTimeline, showMonths). There is an exception to this rule – the icon size set by setRangeNav().
setRecoverDays() int Days Days (default = 30)

When a booking is removed by the admin user, it can be recovered again within this many days of deletion.

setAutoEcho() bool AutoEcho Determines whether the "show" methods (eg showTimeline) should echo their result directly to the browser.
AutoEcho (default = true)

Normally the "show" methods echo their result directly to the browser. By calling setAutoEcho(false), they will instead return the HTML as a string. This gives you the ability to change the HTML before echoing it; you will need to add your own echo statement to send the output to the browser.

This setting also affects showDoubleBookings and showDeletedBookings, so you also need to change the code on the admin page from, eg $twzBooking->showDoubleBookings(); to echo $twzBooking->showDoubleBookings();

setClickFunction() str FunctionName Usually only the admin user can click on a day in the calendar (to edit a booking). If you want your site visitors to be able to click on a day to perform some action, you can use the setClickFunction method.

the name of a PHP function that accepts two parameters: a date string in the format YYYY-MM-DD, and a StatusId. StatusIds by default are 0=Available, 1=Pending, 2=Booked, 3=NotAvailable (see setStatusTypes).
The function will be called for each day currently shown in the calendar. If you want the specific day to be clickable, the function should return a string containing attributes of the <a> tag to use, otherwise it should return boolean false or an empty string.

Example 1 - link to php script function myfunc($Date, $StatusId) { if(0==$StatusId) // only allow click if status is "available" { return 'href="myscript.php?day='.$Date.'"'; } else return false; } Example 2 - call a javascript/ajax function function myfunc($Date, $StatusId) { list(Year, $Month, $Day) = explode('-', $Date); $Month -= 1; // in JS 0=Jan, 1=Feb, etc return 'href="javascript:void(0)"' . ' onclick="myJsFunc('.$Year.','.$Month.','.$Day.','.$StatusId.')"'; }
isAvailable() int LocationId
str FromDate
str ToDate
str Unavail
Returns true if there are no bookings for the given location between the dates specified, or false otherwise. This is useful if you use custom code allowing visitors to add/check bookings. For example if you have integrated twzBooking with our custom contact form, you might consider calling this method from a pre-processing function.
LocationId (required)

id of the location to check (id can be found on the "edit locations" admin page).

FromDate (required)

First date of the period to check.

ToDate (required)

Last date of the period to check.

Unavail (default = '1,2,3')

Comma-separated list of booking types that should be treated as not available. If you want this method to treat "Pending" bookings as available, set this parameter to '2,3' (see setStatusTypes).

Admin functions

These methods are used in the admin pages; in most cases you won't need to call these yourself
setAdmin() bool IsAdmin Turns on admin mode, which makes days in the calendar clickable for editing, and also shows extra booking types not shown to visitors (eg Waiting)
getStatusTypes()   Returns an array of booking status types.
getLocations()   Returns information about all active Locations; used to populate the form for admin user.
getLocation() int LocationId Returns information about a Location; used to populate the form for admin user.
firstLocationId()   Returns the id of the first active location.
getBooking() int BookingId Returns information about a Location; used to populate the form for admin user.
updateLocation() arr Fields
str &Message
Adds or updates a Location in the database from data POSTed by the admin user.
If a problem occurs, Message will be set to an error string.
updateBooking() arr Fields
str &Message
Adds or updates a Booking in the database from data POSTed by the admin user.
If a problem occurs, Message will be set to an error string.
popupRestrict()   Popup calendars are always restricted by which years can be selected, based on the values of MinDate and MaxDate. However by default, any date can be selected for a given year. For example if MinDate is 2010-07-15, the default calendar will make all dates in 2010 selectable (from Jan 1 to Dec 31). You can use popupRestrict() to stop the user from selecting any days prior to MinDate or after MaxDate. Add this code <?php echo $twzBooking->popupRestrict(); ?> to the page where the popup calendar will appear – preferably in the HTML <head> section, but definitely before the calendar input (popupInput). Also it must be AFTER any call to the MinDate or MaxDate methods.
popupInput() str Fieldame
str Value
str Icon
Returns the HTML for a popup calendar control.
Several calendar icons are provided, the default being cal.gif.
showDeletedBookings()   Echoes a list of bookings recently deleted. See also: setRecoverDays()
showDoubleBookings()   Echoes a list of bookings whose dates overlap with another booking. twzBooking lets you double-book days, which can be useful especially for unconfirmed bookings.
dbOK()   Returns true if the required database tables are present, and there is at least one active location.


Date strings

Several method parameters accept a date string. This must be a string acceptable to the PHP strtotime() function. So depending on the context, it could be an actual date, eg '2010-11-25' or it could be relative to the current date, eg 'now', '-1 week' or '+3 weeks'.
Example: $twzBooking->setDateRange('-7 days', '+28 days');