Resource booking grid (RBG)

by Gisle Hannemyr

The RBG project creates a visual grid suitable for booking resources by clicking in a slot on the grid and selecting a duration.

Table of contents

Introduction

This project provides the bare bones of a booking grid as a features export. It is used by HNM AS for various projects requiring a grid (Tolfa, Margarita, Langdalen).

It does not implement policy objects or prices.

Grid

The grid created by the RGB module is not a table. It is a HTML-list, themed to look like a grid. CSS is used to control the size of components.

Date and time

The Date project allows several alternative representations of date and time. The field type “Date (Unix timestamp)” is used by RBG. It uses the Unix epoch (int).

Due to a bug in the Date module (see issues [#998076] and [#2994171] at DO for details), site's default time zone must be UTC, and users must not be allowed to set their own timezone.

This will not be ideal, for instance the dates in bylines will be UTC, but this can be mitigated by setting resolution to day rather than minute.

Classes and attributes

RBG has the following 4 classes built-in. The classes are described in this section. The description of each class consists of a list of attributes and a brief explanations of the attributes that are not self-explanatory. A number in a square bracket connects the attribute to its explanation.

  1. RBG category: A caregory of resource, users may navigate between categories using tabs above the grid.
  2. RBG resource: A bookable resource.
  3. RBG booking type: The type of booking. Placeholder for additional attributes.
  4. RBG booking: A booking of a specific resource for a specific duration.

The data type or Drupal field is indicated insite parentheses for each attribute. The prefix “rel:” here means that the attribute is an entity relation to another class.

All of the classes execpt “RBG Booking” have an attribute named “Weight”. This attribute is used for sorting instances when they are used together in the GUI (typically in lists or pull-down menus). For example, if we want the Member booking type to be listed as the first item in the pull down menu that allows the user to select a booking type, even if Family has presedence when the texts are sorted alphabetically (the default). To achieve this, Member is given the weight “1” and Family the weight “2”.

RBG category

This class alows for a level of abstraction above the actual resources (e.g. the rooms). If there is just a single category, it should be named “Default”.

Attributes:

  1. The Name attribute is used to name the category (e.g. “Default”). At least one category must exist. Every resource instance will belong to one (and only one) category.
  2. The Visibility attribute may be set to “Public” to indicate that the category grid is to be shown publicly (i.e. the category shall be visible to visitors who are not logged in). If it is set to “Private” the grid is shown, but personal data is not exposed. If it set to “Hidden”, a user must be logged in on the service to view the category. With the “Private” setting, only the logged in user will see be able to see the name of the person that owns the booking (unless the booking is set to “Private”). The public will see that the resource is booked, but not the name of the booker or other personal data.

RBG resource

This class is used to represent the bookable resource (e.g. a physical room or a pseudo-room).

Attributes:

  1. The Name may is shown publicly above the grid. It may be a room number, or a noun.
  2. The Capacity is the maximum number of people who can occupy the resource. It is typically used with rooms.

RBG booking type

This class describes the various types of booking that are known to the system. Its purpose is to allow developers to extend it with additional attributes.

Attributes:

  1. The booking type has a Name. It may be used to distinguish between “Member” and “Family” bookings. If there is just a single booking type, it should be named “Default”.
  2. The RGB colour is a hexadecimal representation (e.g. “#88ffdd”) of the colour that is used in the visual grid (the booking calendar) to indicate the booking type visually. (RGB stands for Red, Green and Blue, and is a colour model suitable for computer screens).
  3. Restricted may have three values: 0: disabled (i.e. not visible), 1: open to all, 2: only available to those with permission “Administer RBG” [not part of the features export yet].

RBG booking

This is the actual booking of a resource.

Attributes:

  1. The Title is shown publicly in the grid unless the private flag is set. It is may, for instance be the name of the person that owns the booking.
  2. The Owner is always the member who the booking is made for (either by self-service booking, or by the booking master on behalf of a member). I.e. it is the owner of the booking node. A user with the permission to book can create, edit and delete own booking instances). The booking master can do the same thing to all booking instances.
  3. The Arrival-Departure attribute records the planned times for arrival and departure. The default duration is determined by the constant RBG_DEFDURD. The form is altered to display the last available departure day (if less than 30 days away) below the departure field, and the duration is shortened if necessary.
  4. The Private flag can be set to indicate that personal data about the booking should not be shown, only that the resource is booked. Overrides the Public setting in the RBG Resource class.
  5. A booking can be in two different States, “Pending” and “Confirmed”.
  6. The comment may be used to add any comment to a booking. For instance, when booking on the waiting list, users can enter a text to indicate room preference.

Deployment

Setting up

Do this to set up RBG from scratch, optionally making use of a backup from a previous development site if such a thing exists. In square brackets, there are notes about things done to prototype the Tolfa Booking website.

  1. Create a clean D7 install.
  2. Install the Drupal Bootstrap theme and a sub-theme it (use less) [Name the sub-theme “Tolfa”].
  3. Install the latest development version of Date (7.x-2.x-dev) with my patch. Copy this one from g61.no.
  4. Enable Bootstrap theme and the subtheme. Set the latter default. Disable Bartik. Make sure the Bootstrap base theme is still enabled.
  5. Install the Bootstrap Date & Time picker bridge module and the bridge modules it relies on.
  6. Clone or install libraries: Bootstrap Date & Time picker, moment.js, moment-timezone.
  7. If some half-baked site ecists, clone its environment, otherwise create something similar from scratch:
    • Restore original settings.php to point to correct database.
    • Enable Backup and Migrate.
    • Set up the private file system path. [Use /var/private/tolfa.]
    • Roll back stable backup if one exists.
  8. Check settings:
    • Site's default time zone must be UTC. Users must not be allowed to set their own timezone.
    • First day of week should be “Monday” (affects Drupal). Default language should be “Norsk bokmål” (affects first day of week in BDTP).
    • Configure blocks to remove sidebars (“All pages except those listed”) from from path rbg*.
  9. Check that the BDTP works in authored field.

When enabled, the RBG project provides four types of content (called “classes” in the jargon of object-oriented service development). All classes appear when you use the GUI and navigate to Structure » Content types » Add content.

When the service is enabled for the first time, no instances of these classes exists. What instances to create depends on the service you intend to create. This is a minimal setup you may use for testing the project:

  1. Create at least one RBG category: “Default” (the grid will not appear until at least one category exists).
  2. Create at least one RBG resource: “R1”.
  3. Create at least one RBG booking type: “Default”.

For setting up for Tolfa, skip this and instead see, see Tolfa Booking.

After doing this, click on the link: “Resource booking grid”. You should see the grid, and the superuser should be able to book “R1” by clicking at at a frame in the grid.

Note that almost no policies are enforced by RBG, except:

  1. A booking can not overlap an existing one.
  2. Booking type is required.

  3. Some booking types mat be restricted.

Manual tests

Troubleshooting

Notes on the implemetation

The form builder for the booking form is in the Date module, and the presentation of the elements can be altered in hook_date_text_process_alter().

Final comments

[TBA]

Last update: 2019-05-05