Manual Bicyclerent

Category: Documentation All Languages
Olaf Sabatschus
Saturday, 27 July 2013 22:33
Hits: 25629


..this manual is currently still under construction, as I am adding new features while it is already being used on live sites in real businesses successfully... 

What is this component & plugin(s) for?

If you are running a (multilingual) bicycle rental business, with a minimum rental period of one day this is for you:

You can automate online-sales with availability check and PayPal payment process including IPN payment tracking and make use of a modern Ajax-based front- and backend for a nice user experience.

You are able to assign your bikes  - for any dateranges - to other stations than their "root" and thus optimize your business in case you have to follow seasonal changes or need to accomodate for peaks at some of your bicycle pool's pick-up places. 

You can assign your bicycles to circles, from which they will be requested, in case you want your stations to cooperate in a very flexible manner. The closest bicycle will do the "trip" to serve the customer by using Google Maps services. You can enable or disable this feature completely and assign as many circles as you like.

This setup has been chosen to accomodate what in reality happens in bicycle rentals: You don't need neither want your customers to use different pick-up and drop-off stations. Usually a bicycle will be rented and returned at the same station. 
Nevertheless, it could happen that you have stations close enough to "help" in case the correct size and type (which is more important than with car rentals for example) are not available where the customer is looking for it in the first place.
Of course it is still up to you to allow for different drop-off places than the bookings' respective pick-up, (there is a comment field where your customers can ask for this), in that case you should make use of the component's option to prevent from booking a choosable amount of days before and after each booking request to allow for transportation and maintenance. 

So the system should help map the "reality" better into your database for the normal "holiday type" of bicycle rentals than a system which assigns bicycles only to one big pool rather than different base stations like this component and then allows for definable interdependent drop-offs and pick-ups. With this component, you will get rid of unnecessary transports but still be able to allow bookings flexibly and precisely defined if you need so to enhance the number of overall bookings.

The component's main features:

The component has been created with the requirements of a real-life bicycle rental station in mind, and thus is adapted to do this job well. It is not intended to work for all kinds of other rentals alike. Instead, it should get your bicycle rentals up and working in short time, if you have one or more stations with an unlimited amount of regions, stations, bicycle types and sizes or if you simply want to rent at one station.

The component has been tested on php 5.3 with mysql 5.5. You should make sure, you are using an adequate, up-to-date system!

Installation & Updates

The installation process works as usual using the Joomla! extension installer from the backend:


New versions can be installed over the old ones, you won't loose your database entries, thus.


Do not delete the old version before installing a new one if you would like to maintain your data!


Let's describe the component's options now which can be found as known from Joomla! in the top right of the backend list screens while using the component.

The first tab (Bicyclerent) offers you these choices: 


The "own access rights" tab is important for you, if you work with a large number of different stations, regsions, partners and roles who should be enabled to work on their own data but not to see all screens of the component or data:

.. you can assign users to groups within the component, independent of Joomla!'s ACL to make your life easy. Each screen can be accessed only by the chosen groups to which you have assigned Joomla! users (under the user rights menu in the component's menu). The users will only see their range of data, except for Joomla! super administrators who will always see and be able to work on all data. This works via "stations" and "regions" in this component, plus via general rights to see a submenu (called "screen" here, also). If you have assigned for example the screen option "Stations" to "Stations Leaders" but not "Station Employees", the employees won't be able to access the Stations screen, yet the leaders wiill.  

The actual assignment of users to groups will be done under the User Rights screen described later, here you do also the assignment to any existing regions / stations, - thus you can limit the locations out of which the respective roles will see data.

Note: For the bookings, bikes, stations, stationlist screens and most others the models of the component have been modified so the data really related to stations will only be queried regarding these rights. You can choose stations / regions under the User Rights submenu and assign them to users, so they can only see the database entries according to their rights. For the User Rights themselves, and for the following listed screens it is advisable though to only allow superadmins access, which is achieved by simply not adding the groups who should not have access to these screens under own component rights in the options.

Below is a recommendable setup if you are using the component's own user rights, Operators are the most restricted role in terms of which data to see - only those with their own Operator id in the database rows.

Station employees can not change things much, but they can see more data than an operator because they're not restricted to data with specific operator id, Station leaders can see and work with more screens but only with the data related to their assigned stations, region employees / leaders see more stations than station employees and superadmins are able to use any screen and function anyway: 

(Note: You will need to assign the users stations / regions under the User Rights submenu of the component!)

Screen Operator Station Employee Station Leader Region Employee Region Leader Superadmin
extra definitions            
station changes            
stations relations          
user rights          
opening hours exceptions      
invoice templates        
custom fields  not implemented not implemented  not implemented  not implemented  not implemented  not implemented 
station list            
alter table id start            
price exceptions            
Availability Calendar


The model for bookings has been added a function to check if the current user is an operator and in that case only show bookings with his operator id. This is a special role with usually less rights than the other roles provide. An operator should normally only be able to see and work with "his" bookings as he is not a station or region leader who is a more "general" manager and needs to access all bookings and some more things related to his locations.  

By default you can't assign operators screen rights other than for the bookings. If you need to, uncomment the according options in the config.xml file in the administrator folder of the package (on your server or simply reinstall after changing it locally). You will then be also able to assign Operators these screen rights.

Sounds complicated? If you don't need to restrict anything, because you do not have other people accessing this component and need to regulate who sees what, just leave this option deactivated!

I will explain this concept a little closer under the User Rights section!

The next tab under options allows you to customize the Google Maps integrations:

These settings will be used to help you find the distances between your stations (API Key), your station location exactly under "station" and decide on how static maps will look like that can be pulled into region and station description pop-ups in the frontend plugin. (more about this later).

The PayPal screen is pretty self-explanatory, in case you want to use the PayPal automation and payment features, you will have to provide the needed data in this tab. The component is not intended to offer all kinds of options - for bicycle rentals usually a one-off payment is needed only, so you'll find the basic settings here only for a regular "buy-now" button. The price of course will be calculated on the fly out of the type of bicycle, duration of reservation, operator factor (prices can be different in case the operator id is found in the url parameters or an operator is logged into the frontend to process any bookings himself) and chosen price calculation method (under "type" of bicycle).

The offline payment option can be used in case you want to offer a bank transfer to your customers:

Furthermore, the regular Joomla! ACL settings have been integrated but are usually not necessary to be changed due the component's own access rights:

This is useful though, if you want to for example not allow general access to backend components, but for the bicyclerent component. Then you can place the respective users into a Joomla! user group that won't be granted access to any except this component.

Frontend booking process

The reservation of a bicycle is done via content plugin:

Open any existing Joomla! content article or create a new and place the following plugin tag where you want the booking form to appear:


You can add more parameters: 

{bicyclerent:booking region=(.*) station=(.*) type=(.*)} 

... where you simply replace the (.*) with the integer id of the respective item (region, station or type) which you can find in the backend in the list or single item views.

The Plugin does not allow for the region to be omitted and only the station to be placed or only a type to be provided - you must go "from the top to the bottom", in the above shown ordering so if you for example want to preselect a station with the id 2 you would have to get the according id of the region this station belongs to from the backend, say this would be 1 and write: {bicyclerentbooking:booking region=1 station=2} . You can omit or also provide a type, so the customer can only choose from Region 1, Station 2 and Type whatever you have put here.

You can also use URL Parameters instead if you are linking to your booking page from elsewhere, the url needs to look like the following, then: 


where the your-booking-url-here could then for example be something like The last parameter is an operator ID (the one freely chosen in this case, not the database primary key as for station and region). The easiest is to direct your browser to the article you are using for the booking plugin and copy the url to use in such a link. You can do this with an "external link" menu type, too which is offered by Joomla! when you are choosing the menu type to link to your article with different parameters if you would like to use the same article in different ways for say different stations preselected.

The Plugin tag will be replaced by something like the following, depending on if a region, station etc. was provided or not (here simply {bicyclerent:booking} was written, as preselected values will be changed into hidden form fields and thus not be visible yet deliver their values: 

 When the user selects a Region, an Info button will appear, 

on hover the respective description will be shown (this is true for Station, Type and Extras as well - all of the descriptions are set in the backend with an editor-type field): As you can see a google static map appears which can be placed there with a plugin-tag-like syntax. More later about this in detail.

After successfully entering all necessary data of the first booking screen (here all shown fields need to be filled out by your customers) and pressing the Lookup Availabillity Button the user will be forwarded to the next screen in case a bicycle is available with the chosen specifications: 

Extras available at the station requested will be shown with their price, respectively and can be checked. The checked ones will be added to the total price in the next step.

The Opening hours will be - depending on the respective choice in the requested station's settings - textual "only" with 24hrs of pickup and dropoff times in 30min steps possible or parsed from your comma-separated input in the respective opening hour field in the station view into the select list of possible options. You will find a more detailed explanation under "station" in this manual.

In case there are any incorrect inputs (currently all fields except phone are required - next version will feature custom fields and the possibiliy to set required to yes or no from the backend) or no bicycle is available according to the choices, error messages will be shown as a modal overlay using lightface:

A meaningful message is shown in the same manner if the second formpage can't be shown because a) the opening hours of the requested station do not allow so (first or last day of rentals lies on a non-working day of the station) or b) there is no bicycle available according to the customer's specifications or c) any error on the server side occured.

In case everything is correct in the second booking screen then (the customer data from the form is with the exception of group and phone number obligatory), terms & conditions are checked also (which appear as a link showing the station specific terms & conditions in a pop-up) the last booking screen is going to be shown after the customer cllicks the booking button. All transitions between the 3 major reservation steps are being done via Javascript / Ajax mechanism so that no page reload is necessary. (Below - some dummy prices have been used, you will briefly see where to put real ones per bicycle type and how to choose between different pricing models).

If you have offline payments enabled under options the combination mentioned under options - offline payments - of .ini language file contents and bank details from the options screen will be shown in this last reservation step as well.

You can freely change all texts shown by changing the included .ini language files (English, German, Spanish included) or creating your own for any other available Joomla! language.

The PayPal button appears or not depending on your options choice for this.

Underneath latest versions will show a PayPal explanation link in the shape of a "secure payment" picture that opens PayPals own recommended link in this respect.

You can change the Button's Locale under Options -> PayPal. If you want to add a PayPal button to the automatically send confirmation email instead or additionally, you can do so by adding a tag to the email templates, later more on this.

Payment Tracking

Payment tracking via PayPal's IPN has been added, mainly to later add the funcionality to delete bookings which have not been paid during a certain period. As not all hosting packages allow for an easy setup of cron jobs, I am thinking about creating a plugin for this task as well.

For the time being the IPN script will check if the correct amount, currency etc. has been paid and in case all is valid it and successfully paid, it will note the paid amount in the paid column of the respective reservation for your convenience.

The Backend - Booking List

The typical entry point for your daily tasks will be the booking list which allows for several ajaxed tasks to be performed. Above the list of reservations (and for some other views) some charts have been added in the latest version, you will also see similar charts for some different statistics for the stations list and the operators list. Future versions might get some more of these.

 You can look up all details of a booking by clicking the details button on the left of the list (5):

You can change booked extras (and look up which extra has been booked by comparing the number in the list with the number of the listing of extras opening) by clicking on the pencil icon in the extras column. Save the changes (multiple extras are allowed) by clicking on the disk icon.

If you need to assing a different bicycle for a reservation number, you can look up the available bicycles by clicking on the pencil in the bicycle column (8), then click on lookup bicycles in the popup and then click on your choice to replace the previously booked bicycle. In case you have chosen a (different) station in the select list (1) you will get the list of bicycles available in that station. This comes in handy if a customer has chosen the wrong station for example and you need to quickly change without deleting the reservation and doing a new one from the frontend. The dates in (7) can be altered and will be considered when looking up available bicycles and of course applied also if there are no conflicting bookings on the chosen bicycle.

You can change the start- and enddate only, too (type the desired range into the according text box(es) (7) and click on the left on the button that says "apply dates") of the respective reservation. You can change the price, paid, customer name as well as note by altering them in the textbox/-area and clicking on the disk symbol underneath.  

Any of the changes will always be securely tested automatically for availability and correct station during the requested booking period.

If you choose to use the pdf invoice generation feature, you will have to download and install the mpdf zip package as well. From then, you can create unlimited invoice templates and after choosing one in select list (2) on the upper right of the filter field area click on the create invoice button to the left of each booking data.You will then be asked to type an invoice number in a pop-up window as well as a VAT tax percentage separated by a pipe | symbol. After that, your invoice will be created. You can replace almost all booking data in your templates so you have a very flexible system to create your invoices. More about the possible tags for booking data under pdf invoices futher down.

Backend - List Views

The typical list view allows you to set orderings (important for example to set the sizes ordering - as you would like them to appear in the frontend booking select list) and to have an overview over your respective items like bikes, stations, regions, types... :



When Clicking on a name of an item or checking the according checkbox on the left and then the Edit button on the top right under the menu bar you get to the single item views.


A region dataset consist of a name and description, the other fields are automatically assigned. 

You have the option (if chosen so under options, more about this later) to replace a plugin-like syntax with Google's Static Maps in each of the component's editor fields (multiple maps possible per item). The use of this is to make your life a little easier and not have to think about url-encoding etc. to place the actual necessary link.

The currently available arguments to override the default settings in the options are all included in the following tag example, you can change the order but remember to leave the space before adress (only 1 space) and to separate the arguments by the pipe symbol "|" :

{bicyclerent:map adress=.. |size_x=.. |size_y=.. | zoom=.. |type=..|float=..|margin=..}

In case you omit some or all of the arguments the settings in your options of the component will be taken.

The replacement with google static map will also be done in case you include the station info into your reservation emails


Before you can save a new station, you will have to create at least one region to assign it to. Use the drag and drop marker feature to get long and lat values for your station. This will be used for distance lookups if a bicycle has to be received from the closest (next) station in the circle (if this is enabled under options and the bicycle is not available at the requested station).


As you can see above, you can use the longitude and latitude of the map's adress OR the adress.

The coordinates are the best choice to make use of the feature to look up the closest bicycle to be rented, if you have circles enabled and a bicycle with the desired specifications can't be found at the station the customer needs it. Simply drag & drop the marker to find the adress & coordinates of your station if you have provided the component with your Google Maps API Key.

Name, description and region are pretty self-explanatory, but let's describe the other available fields as well:

The price factor is used to adapt prices to each station if needed: In general prices are being calculated from a bike type's settings. A station though can make a change in percent of that price, which is noted in this field: 110% makes it 10% more expensive if someone books the type in this station as noted at the type level for example (the type is the next chapter of this manual).

Parse opening hours into select list entries? This is to enable you to to decide wether you only want a certain range of select list options in your frontend booking form or a textual representation with all times from 00:00hrs to 23:30hrs in the actual select list independent of the free text you put into the "opening hours" textfields of each respective weekday.


If you want to let your stations work together in circles, so bicycles can be rented from "related" stations in case the requested station does not have the exact model requested available, you need to set up at least for those stations in circles all distances between them, in both directions.

A set is 2 stations always, you can look up the distance between them with Google Directions Service to make your life easier.

After setting up all distances (both directions! to make it work properly) you will have your distances list view looking something like this:


Now, in case you have enabled the circles under the component's options, everytime a bicycle is not available with the exact requested specifications, the plugin will first collect all stations that are in the same circle as the requested one, then start to look up available bicycles with the wanted features from the closest station in the circles to the further ones. Thus the closest available bicycle will be rented.

Bicycle Type

A bicycle type defines a number of important things like the price and price caculation method.

Remenber to first create the necessary sizes (new ones can later be added to this type as well) that will be shown for this type in the frontend select list for sizes of the chosen type to be able to save the new type.

The available price calculation methods are:

The first two options take the prices from day1 - day.. as long as they are before the chosen end of this period (7 or 14 days) and from than count the additional price per day.

The last one calculates the total price as fixed daily price times the number of bookings days. 

Holding ctrl key pressed allows you to choose multiple sizes that will be available with this type. 

A workaround for Joomla! not offering a method to translate custom components' editor fields will be added to one of the next versions of the component, so you can actually see the description in the frontend in the language the user is currently browsing your webpage.

Note: If you need station specific prices for the same bicycle types you can map them into 2 or more types with the same name into your database and make each type only available at the station(s) accordingly.
Example: You need station A to sell for 10 Euros per day, but station B for 8 for the bicycle type "aluminum race bike shimano 105". Create 2 types with these different prices and assign the according bicycles to these different types, choosing the corresponding type and station(s) under the bicycles submenu.

Price Exceptions

You can additionally add daily prices, if you need so to adapt for example for seasonal differences. The Price Exceptions Screen serves for the purpose of adding, deleting and altering these daily prices, which will be applied if the frontend booking plugin finds a requested daterange overlapping with something entered here for the type and station the customer is searching.

Select a type and station, a daterange and type your price (digits separated with a . not a , - so for example 8.50 is a valid daily amount) and click the save button. To delete any days from the list check the checkbox at the right of the to-be-deleted entries and use the Delete Checked button. You can toggle all checkboxes as well with the related button.


A size simply defines a name and will be related to a bicycle and type. I have chosen this setup (might look a little complicated first) to allow for different types to use different size names - as often in real life the sizes of your models will be different per type.


 A bicycle needs to by assigned to a type, so be sure to create the according type first and then the bicycle(s) belonging to the type. The type will define the bicycle's prices. You also need a size to define a bicycle, so make sure you have the corresponding size set up before creating your bicycle (although you can always change this later, but in a live system it can be a bad idea making you have to change a reservation or two because they had been wrongly set up in terms of their size first and the customer has mistakenly reserved a wrong bicycle due to that).



Station Change

The station change(s) of a bicycle are freely definable dateranges which allow for a bicycle to be bookable at another station than the one it is generally assigned to. In both front- and backend availabiltiy check functions are programmed to also look up the bike's station changes before allowing for booking or any kind of daterange change etc. 

This function helps those rental businesses who have more than one station and want / need to rent their bikes at more than one station during defined dateranges.

Example: You have 3 stations and during the summer period you want a number of bikes from station a in station b, because you usually have more traffic over these months in station b, but thereafter they should automatically be available (and physically there in real life) from station a, again. Assing the related bicycles to Station B in station-changes for the desired date-range. They will be bookable (plus the optional related book-off days) in station b for the chosen date-range, not from a (exception: if you have circles enabled they might be assigned though for a during this time nevertheless)


Operators are a special role in the component. They are  partners who can - (or not) see and change their bookings to some extend but should not be able to work on other things like bicycles, stations etc for a normal use case. 

An operator database entry has the following fields:

You can use the Operator id (freely choosable but must only contain letters, number, _ . - signs) to append to any url to an article with the bicyclerent booking plugin after a question mark for example like ?op_id=t5. If you have other url parameters, separate them each by &parameter=... 

The booking plugin will store the operator id and "assign" this booking to him, so you can easily track and filter from which partners your bookings are coming in. 

The other fields are mainly used to fill the oparator's adress data into the booking plugin when he is logged into the frontend - thus making it easier and faster for him to do multiple bookings after each other. Operators will also see a book again button to call the first page without page reload, which is not available to normal customers. 

PDF Invoice - create your own templates with Editor field and replace booking data with tag syntax on the fly. The language field here is only for your own orientation, so you know when you are wanting an invoice in which language you have written it - a template will always be chosen manually in the booking list screen to be created for a booking.


Availability Calendar

To quickly overview your bookings and availabilities per bicycle the Availability Calendar View exists in the initial release.

For future versions this could be a starting point for a "per day" manual assignment of bicycles by choosing a customer or providing new customer data and then clicking on the respective disponible slots. I have programmed a quite similar view for a pool management tool, already, so one of the future updates should contain this feature.

By clicking on the first column with the bicycle description, a modal 3-month availability calender, only for this bicycle pops up:

 Alter Primary Keys

You can change the start values of the Bookings and Bookers Primary Key fields (integer, auto_increment) if you need so.

Please be warned, that this is only for users, who know what they are doing!

Station List

Station List to quickly see what's to be done. From here you can also call a view "occupation" after choosing station and start as well as end date to see how many staff would be needed on a daily basis or export your bookings to microsoft excel.

..and a glance at the brief summary table "occupation":

Conversation - Choose Language, Station and be creative.. per language and station (or for multiple stations, or simply as a default if you have stations without specific set of conversations) you are able to customize each stations' confirmation email after booking, the terms & conditions text and the text of an email being send after successfull payment (tracked via IPN). Latest addition is a tag system to replace the tags with reservation data on the fly, so your reservation confirmation email can contain a customizable amount of the booking details wherever you need it. You will be reminded of the possiblities above the respective editor fields.

Discount Vouchers

Vouchers offer the possiblity to offer any number of flexible discounts to your customers or groups:

You can Choose a type of discount - percent of total price including the extras or fixed amount in your currency unit. Furthermore you can choose a valid from and a valid to date (if left empty the start or end date will automatically be valid, so if you only need an end date of a voucher just leave the valid from date empty), the number of available uses and you can alter the number it has been used from the backend as well in case you need so besides the discount code (numbers, letters and -_. are allowed). Each time a voucher is being used of course the used count will be increased by 1 automatically until the voucher reaches it's maximum allowance. In case Max Uses is set to 0 there is no restricition enforced in how many times the voucher can be used.

If you can set up a cron job calling /index.php?option=com_bicyclerent&format=raw&task=sendStationList&cpass=xxx where xxx needs to be replaced with the password chosen under options for this function, the system will send the reservations for the next 7 days periodically with your chosen timeintervall for the cron job to the list of email adresses noted for this (field to enter the emails is just above the password field under the component's options' first tab).

More Plugins

There are some more plugins available, currently: