Current version

Documentation for v2.x.

Setup

Guidance for installing and upgrading classroombookings.

Setup

Requirements

classroombookings is web-based software. This means that there is no executable (.exe) file - it must be run on a web server and accessed through a web browser. You are expected to have sufficient knowledge of setting up web servers in order to set it up.

Setup

Installation

Please make sure your server environment is set up and meets the requirements before continuing.

Summary

The procedure for installing classroombookings should be straightforward for those familiar with web based software.

For more details guidance, continue reading.

Create the database

Classroombookings needs its own empty database. The procedure for doing this will vary depending on your server or hosting configuration, but you will commonly use an administrator-level account (such as 'root') to create the database and user account. It is easy to do this using visual tools like Adminer, HeidiSQL and phpMyAdmin, but it is possible to do it via the mysql command line client.

Using the command line client

This example shows how to log in to a server as the root user, creating the database crbs_db and user crbs_user with the password 6vTccw7zYF. Replace these with your own choice of names and password.

$ mysql -u root -p

Enter password: ********
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 3285
Server version: 10.3.8-MariaDB mariadb.org binary distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> CREATE DATABASE crbs_db;
Query OK, 1 row affected (0.010 sec)

MariaDB [(none)]> GRANT ALL ON crbs_db.* TO 'crbs_user' IDENTIFIED BY '6vTccw7zYF';
Query OK, 0 rows affected (0.003 sec)

MariaDB [test_db]> exit;
Bye

Make a note of the database name, username and password. You will need them later.

Download, extract and upload

If you have the ability to download and extract zip files on the server itself, it's quicker, safer and more efficient to do that.

This example shows how to do this on the command line using the tools wget and unzip. Replace the URL to the zip file with the latest version, from the Download page. Change directory into the web server document root or classroombookings folder first, as the zip file will be extracted into the current folder.

$ wget https://github.com/craigrodway/classroombookings/releases/download/v2.0.0/classroombookings-v2.0.0.zip

$ unzip classroombookings-v2.0.0.zip -d .

If you don't have command line access to the server, download the zip file of the latest version from the website using a web browser and save it to your computer. Extract the archive to a temporary folder. You will then need to transfer all of these files to the server. How you do this will depend on what protocols your server supports, but this is commonly done via SCP, SFTP or FTP.

Filesystem permissions

There are two folders that need 'write' permissions from the web server user. This is essential for core functionality (user sessions and log files) and uploaded files (user import CSV, school logo, room photos) to work properly.

On Unix-based systems, this is usually represented by 664 or 775 in numeric values; or 'drwxrwxr-x' in its string representation.

If these aren't already set, you should be able to do this on the command line like in this example:

$ chmod -R 775 local
$ chmod -R 775 uploads

If you don't have command line access, most file transfer applications such as WinSCP or FileZilla allow these to be set via the interface.

Run the installer

Using a browser, visit the IP address or URL on the server where the classroombookings files were extracted. You should see the following page.

In the Database connection details section, enter the details for connecting to your database. In the Configuration section, ensure the auto-detected URL matches the address that will be used by all users to access classroombookings. If it is not correct, change it to the address that will be used.

Click Next. The installer will test the database connection using the details provided.

If the database connection test was successful, the next page will be displayed.

Enter the name of your school in the School name field.

Enter the desired username and password of the initial administrator-level user. This user will be created during the installation process. Remember the details you use, you will need these to log in after classroombookings has been installed.

Click Next.

The final page checks if certain requirements are met and displays the status. If all items are OK, you can finish the installation by clicking Install.

If there are any problems, the status will show an Error indicator and some guidance notes about what needs to be done.

Once it has been installed, click the link to go to the Login page. Enter the administrator user details you created earlier.

Setup

Upgrading

If you already have an existing Version 2 installation of classroombookings and want to update it to the latest release of Version 2, the process should be straightforward and familiar if you have installed or updated Version 2 already.

Check that your hosting envrionment or server meets the requirements, and then proceed with the steps below.

Summary

If everything still works, you can safely remove your backups of the application, assets, and index.php file.

There is no upgrade process to run, but any database changes that need to be done will be made automatically without any intervention.

Special notes

Sometimes it may be necessary to carry out extra tasks for individual upgrades. Check below if that is the case for your version upgrades.

v2.0.1

There is a new file favicon.ico to add to the root folder, along with index.php. Extract this file from the downloaded archive along with application, assets and index.php.

Setup

Upgrading (from version 1)

If you already have an existing Version 1 installation of classroombookings and want to update it to Version 2, the process should be straightforward but involves some manual intervention.

Check that your hosting envrionment or server meets the new requirements, and then proceed with the steps below.

Overview

The upgrade process carries out a number of tasks:

Backup your database

The upgrade process makes several changes to the database, so it is a good idea to make a backup copy should any of these fail. It is easy to do this using visual tools like Adminer, HeidiSQL and phpMyAdmin, but it is possible to do it via the mysqldump command line client.

This example demonstrates how to use the command to create a copy of the crbs_db database and save it to the crbs_db_backup.sql file, logging in as the crbs_user user.

$ mysqldump -u crbs_user -p crbs_db > crbs_db_backup.sql
Enter password: ********

Download, extract and upload

If you have the ability to download and extract zip files on the server itself, it's quicker, safer and more efficient to do that.

This example shows how to do this on the command line using the tools wget and unzip. Replace the URL to the zip file with the latest version, from the Download page. Change directory into the web server document root or classroombookings folder first, as the zip file will be extracted into the current folder.

$ wget https://github.com/craigrodway/classroombookings/releases/download/v2.0.0/classroombookings-v2.0.0.zip

$ unzip classroombookings-v2.0.0.zip -d .

...
replace ./index.php? [y]es, [n]o, [A]ll, [N]one, [r]ename: y
...

If you don't have command line access to the server, download the zip file of the latest version from the website using a web browser and save it to your computer. Extract the archive to a temporary folder. You will then need to transfer all of these files to the server. How you do this will depend on what protocols your server supports, but this is commonly done via SCP, SFTP or FTP.

Filesystem permissions

There are two folders that need 'write' permissions from the web server user. This is essential for core functionality (user sessions and log files) and uploaded files (user import CSV, school logo, room photos) to work properly.

On Unix-based systems, this is usually represented by 664 or 775 in numeric values; or 'drwxrwxr-x' in its string representation.

If these aren't already set, you should be able to do this on the command line like in this example:

$ chmod -R 775 local
$ chmod -R 775 uploads

If you don't have command line access, most file transfer applications such as WinSCP or FileZilla allow these to be set via the interface.

Run the upgrade process

Using a browser, visit the IP address or URL on the server where the classroombookings files were extracted. You should see the following page.

The upgrade process will try to automatically detect the URL your classroombookings installation uses, and populates the URL field. Check that this is correct, and adjust it if necessary.

It will also find your existing database settings, test your connection and check your current install.

If any errors are present, the status will report an error and display some guidance notes.

If all checks are successful, click the Upgrade button.

When complete, the confirmation page will be displayed.

Check that your installation works as expected by logging in with your account details and confirm the various pages load OK.

If everything is fine, you can safely delete the following folders and files from version 1, as they are no longer required:

Managing

Guidance on how to manage and configure your installation.

Managing

Introduction

you can start changing settings to match your school and adding various items that make it work.

On a fresh installation, the suggested order for getting started is set out below.

As an administrator user, all of these can be done from the main Control Panel page.

Managing

School Details

You can use the School Details section to manage global information and settings for classroombookings.

School name and Website address

This is where you can add the name of your school, which is displayed in the header area of all pages. The Website Address isn't currently used but could be displayed in future versions, if populated.

This setting allows you to upload an image of the school logo, which will be displaye on the login page.

Managing

The School Day

Use the school day section to set up how your day operates - primarily, the lesson/period times. You do not need to enter breaks - just the periods that you want rooms to be able to be booked on.

Some people find it useful to add "Before school" and "After school" periods, if rooms are sometimes used "out of hours".

When adding a Period, tick all of the weekdays that it is applicable to.

Managing

Timetable Weeks

Use the Week Cycle page to configure the timetable weeks that occur within the academic year.

These are essential for making recurring bookings. The flexibility in defining the weeks allows multi-week timetables to run throughout the academic year; but instead of alternating in a week one/week two fashion, you define each week in the year to a specific timetable week.

When you create a recurring booking, it is assigned to a room and period for the given day on the timetable week that the date falls on.

Example: creating a booking for Period 1 in Room 1 on a Monday in "Week 1" will ensure that the booking occurs every Week 1 on a Monday at Period 1 in Room 1.

If you only operate a simple one-week timetable, a week still needs to be added. Give it a name like 'Timetable', and tick all of the weeks in the year.

Each week can have its own colours, to help differentiate them in the Bookings page. Enter the colours using their hexadecimal format, E.g. 0074d9.

Managing

Academic Year

Classroombookings needs to know the dates of your Academic Year before the timetable weeks can be configured. Use the Academic Year link to set the start and end date for the year, typically from September to July.

Managing

Holidays

Holidays in classroombookings are periods of time where bookings cannot be made. The time can be as short as a single day, or a range of days spanning multiple weeks.

Only enter the dates that fall within the holiday itself inclusive. Holidays affect bookings for all rooms and all periods during the time period that the holiday lasts.

Managing

Rooms

Rooms are the entities that users can make a booking for.

When adding a room, some of the information you enter (e.g. owner, location, photo and any custom fields) will be accessible and visible on the bookings page to other users.

The Room owner setting allows you to designate a classroombookings user as the owner of that room. This gives the user the special permission of being able to delete other user's bookings in their room.

Custom Fields

If you wish to highlight certain features of the rooms, you can do this using the custom fields section. Common uses for these are things like room capacity, number of computers available, or whether it has certain equipment such as printers or projectors.

Create your custom fields before adding rooms; it will save time.

Managing

Settings

Use the Settings page to control global settings for the installation. The settings are described in detail below.

Bookings

Booking in Advance

This option can be used to limit the number of days ahead that teacher user accounts can make bookings, based on the current day when making the booking.

Example: Setting value is 3 days. If today is Monday, teachers can book rooms between now and Thursday (+ 3 days).

Maximum active bookings

This option can be uesd to limit the number of active bookings a user can have at one time. An 'Active' booking is any single booking for a user that where the date and period date start time is now or in the future.

Example: Setting value is 5. If a teacher has 4 active bookings, they can only make one more. After they have made booking #5, they can't create any more. Once their earliest active booking takes place (has passed), they can create another one.

Display Type

This option changes the focus and layout of the bookings page.

Columns

This determines which data aspect is shown on the bookings table across the top of the grid, and the options available change depending on the Display Type option above.

User details

Use this setting to specify whether a booking's user is visible to other users on the bookings screen. Usually these will be displayed, but they can be turned off if you don't want teacher-level users to see the names of others on bookings.

Date formats

These options control how the date and time is displayed to users on the bookings page in different areas.

The values should be PHP date/time format strings (view reference)

Common formats

Format Example
l jS F Y Thursday 16th April 2020
d/m/Y 16/04/2020
jS M 16th Apr
g:i 8:30
H:i 16:45

Login Message

This section controls the message that can be displayed to users on the login page. It is useful of reminding users about things, giving special instructions, or telling them how to get support.

Maintenance Mode

When Maintenance Mode is enabled, Teacher users are prevented from viewing and making bookings, and the message will be displayed at the top of very page.

This is useful if you want to temporarily prevent changes from being made by most users.

Managing

Users

Users are central to accessing classroombookings. Users are identified by a username and password combination, and all passwords are stored locally in the classroombookings database in a secure hashed format.

There are currently only two types of users: Administrator, and Teacher. Administrator users can do anything within the system. Teacher users can only create bookings for bookable rooms, up to number of days ahead as configured in the Booking in Advance setting. Teacher users to not have access to any of the management features.

Import from CSV

It is also possible to bulk import users from a CSV file using the Import users page.