Data Collection Driver File

The custom plugin should declare at least one driver for the guests data collection of the back-end. Such drivers are meant to define the list of fields (information) to be collected from each guest. A list of fields is composed of key-attribute pairs to define every single field to be collected from the various guests.

A driver file is a custom PHP Class that extends the default framework of VikBooking and that implements the various methods to define the labels (keys) and attributes of each field. Here's an example of a driver file that the main plugin should load (file "mycountry.php").

<?php
/** 
 * @package     VikBooking
 * @subpackage  checkin_paxfields_mycountry
 */

// No direct access
defined('ABSPATH') or die('No script kiddies please!');

// require the class file for declaring a custom type of field called "myinfo"
require_once dirname(__FILE__) . DIRECTORY_SEPARATOR . 'myinfo.php';

/**
 * Helper class to support custom pax fields data collection types for "My Country" (filename my_country.php).
 */
final class VBOCheckinPaxfieldsMyCountry extends VBOCheckinAdapter
{
    /**
     * The ID of this pax data collector class.
     * 
     * @var     string
     */
    protected $collector_id = 'mycountry';

    /**
     * Returns the name of the current pax data driver.
     * 
     * @return  string  the name of this driver.
     */
    public function getName()
    {
        return '"My Country"';
    }

    /**
     * Tells whether children should be registered.
     * 
     * @param   bool    $precheckin     true if requested for front-end pre check-in.
     * 
     * @return  bool    true to also register the children.
     */
    public function registerChildren($precheckin = false)
    {
        /**
         * Return true if your driver requires children to be registered.
         * The return value can also change depending on the registration type:
         * during back-end check-in registration or during front-end pre check-in.
         */
        return false;
    }

    /**
     * Returns the list of field labels. The count and keys
     * of the labels should match with the attributes.
     * 
     * @return  array   associative list of field labels.
     */
    public function getLabels()
    {
        return [
            'first_name'  => __('First Name', 'vbocustomcheckindriver'),
            'middle_name' => __('Middle Name', 'vbocustomcheckindriver'),
            'last_name'   => __('Last Name', 'vbocustomcheckindriver'),
            'date_birth'  => __('Date of birth', 'vbocustomcheckindriver'),
            'country'     => __('Country', 'vbocustomcheckindriver'),
            'myinfo'      => __('Custom Information', 'vbocustomcheckindriver'),
            'notes'       => __('Comments', 'vbocustomcheckindriver'),
            'sign'        => __('Sign contract', 'vbocustomcheckindriver'),
        ];
    }

    /**
     * Returns the list of field attributes. The count and keys
     * of the attributes should match with the labels.
     * 
     * @return  array   associative list of field attributes.
     * 
     * @see     the attribute of type "mycountry_myinfo" is a custom field
     *          that must be defined through a specific class file.
     */
    public function getAttributes()
    {
        return [
            // field attributes of type "text" will display a text input field
            'first_name'  => 'text',
            'middle_name' => 'text',
            'last_name'   => 'text',
            // field attributes of type "calendar" will display a datepicker input field
            'date_birth'  => 'calendar',
            // field attributes of type "country" will display a dropdown menu to pick a country
            'country'     => 'country',
            // you can specify custom input fields, such as "mycountry_myinfo" (input rendering will be declared later)
            'myinfo'      => 'mycountry_myinfo',
            // field attributes of type "textarea" will display a text-area input field
            'notes'       => 'textarea',
            // this (optional) field of type "signature" will display a contract signature field
            'sign'        => 'signature',
        ];
    }

    /**
     * Builds the list of front-end (pre-checkin) pax fields for the extended collection type.
     * Check-in pax fields data collector implementations may override this method, if needed.
     * 
     * @param   array   $def_fields     list of default pre-checkin field labels and attributes.
     * 
     * @return  array   the list of pax fields to collect in the front-end during pre-checkin.
     * 
     * @since   1.17.2 (J) - 1.7.2 (WP)
     */
    public function listPrecheckinFields(array $def_fields)
    {
        /**
         * Do not override (declare) this method at all, or return empty lists, if you would like
         * to collect the default guest information during the pre-checkin. Example:
         * 
         * // return no labels, nor attributes by default
         * return [ [], [] ];
         */

        /**
         * The code below will copy the same guest registration fields for back-end to use them during
         * the front-end pre-checkin guests registration, by adding a field to upload documents.
         */

        // use the same fields for the back-end guests registration
        $labels = $this->getLabels();
        $attributes = $this->getAttributes();

        // for pre-checkin we keep any default field of type "file" for uploading IDs
        foreach (($def_fields[1] ?? []) as $field_key => $field_type) {
            if (!is_string($field_type)) {
                // not looking for a list of options
                continue;
            }
            if (!strcasecmp($field_type, 'file') && ($def_fields[0][$field_key] ?? null)) {
                // append this pax field of type "file" for uploading IDs
                $labels[$field_key] = $def_fields[0][$field_key];
                $attributes[$field_key] = $field_type;
            }
        }

        // return the new list of pre-checkin pax fields
        return [$labels, $attributes];
    }

    /**
     * Performs a validation over the guest registration fields data for a given reservation.
     * Custom drivers can override this method to implement their own validation method.
     * 
     * @param   array   $booking        The booking record involved with the guests registration.
     * @param   array   $booking_rooms  The booking room records involved with the guests registration.
     * @param   array   $data           The guests registration data to validate.
     * @param   bool    $precheckin     True if validating pre-checkin fields.
     * 
     * @return  void
     * 
     * @throws  Exception
     * 
     * @since   1.17.7 (J) - 1.7.7 (WP)
     */
    public function validateRegistrationFields(array $booking, array $booking_rooms, array $data, bool $precheckin = true)
    {
        if (!$precheckin) {
            // no validation needed during back-end registration
            return;
        }

        // get all field labels as an associative list
        $labels = $this->getLabels();

        // list of mandatory guest fields (field label keys must match)
        $mandatory_gfields = [
            'first_name',
            'last_name',
            'date_birth',
        ];

        // list of mandatory fields for the main guest only
        // this is how fields can be validated depending on the guest number
        $mandatory_main_gfields = [
            // the room main guest will need to specify also the country of residence
            'country',
        ];

        // iterate over all rooms booked
        foreach ($booking_rooms as $index => $booking_room) {
            if (!is_array(($data[$index] ?? null)) || !$data[$index]) {
                throw new Exception(sprintf('Missing guests registration data for room #%d.', ($index + 1)), 500);
            }

            // count expected room registration guests data
            $room_adults = $booking_room['adults'] ?? 1;
            $room_children = $booking_room['children'] ?? 0;
            $room_guests = $this->registerChildren($precheckin) ? ($room_adults + $room_children) : $room_adults;

            if ($room_guests > count($data[$index])) {
                throw new Exception(sprintf('Please fill the information for all guests (%d) for room #%d.', $room_guests, ($index + 1)), 500);
            }

            // scan room guests for the expected room guest registration data
            for ($g = 1; $g <= $room_guests; $g++) {
                if (!is_array(($data[$index][$g] ?? null))) {
                    throw new Exception(sprintf('Please fill the information for the guests #%d for room #%d.', $g, ($index + 1)), 500);
                }

                // build guest mandatory fields
                $mand_fields = $mandatory_gfields;

                if ($g === 1) {
                    // merge main guest-level mandatory fields for validation
                    // the validation for the main guest (index 1) can be different
                    $mand_fields = array_merge($mand_fields, $mandatory_main_gfields);
                }

                // ensure no mandatory field is empty
                foreach ($mand_fields as $mand_gfield) {
                    if (!is_string($data[$index][$g][$mand_gfield] ?? null) || !strlen($data[$index][$g][$mand_gfield])) {
                        // throw an error by using the existing language definition constant
                        throw new Exception(JText::sprintf('VBO_MISSING_GFIELD_REGISTRATION', ($labels[$mand_gfield] ?? $mand_gfield)), 500);

                        // if you prefer, an error can be thrown with a custom message like below:
                        // throw new Exception(sprintf('%s is required to complete the pre-checkin.', ($labels[$mand_gfield] ?? $mand_gfield)), 500);
                    }
                }
            }
        }

        // validation succeeded if this code-point is reached, no need to return anything
    }
}

In the above example, our driver "MyCountry" is declaring a field of type "mycountry_myinfo", which is not one of the default and existing types of field to collect specific details from each guest. For this reason, this particular type of field must be defined through a specific class file (which has been previously loaded/required by the main driver file).

This is how a custom type of field for the guests data collection should be defined.

<?php
/** 
 * @package     VikBooking
 * @subpackage  checkin_paxfield_type_mycountry_myinfo
 */

// No direct access
defined('ABSPATH') or die('No script kiddies please!');

/**
 * Defines the handler for a pax field of type "mycountry_myinfo" (filename myinfo.php).
 */
final class VBOCheckinPaxfieldTypeMycountryMyinfo extends VBOCheckinPaxfieldType
{
    /**
     * Renders the current pax field HTML.
     * 
     * @return  string  the HTML string to render the field.
     */
    public function render()
    {
        // get the field unique ID
        $field_id = $this->getFieldIdAttr();

        // get the guest number (fields could be displayed only to a specific guest number)
        $guest_number = $this->field->getGuestNumber();

        // get the field class attribute
        $pax_field_class = $this->getFieldClassAttr();

        // get field name attribute
        $name = $this->getFieldNameAttr();

        // get the field value attribute
        $value = $this->getFieldValueAttr();

        // build list of our "myinfo" custom values
        $customtypes_opt = '';
        foreach ($this->loadMyCustomValues() as $custom_code => $custom_type) {
            $sel_status = $custom_code == $value ? ' selected="selected"' : '';
            $customtypes_opt .= '<option value="' . $custom_code . '"' . $sel_status . '>' . $custom_type . '</option>' . "\n";
        }

        // compose HTML content for the field
        $field_html = <<<HTML
<select id="$field_id" data-gind="$guest_number" class="$pax_field_class" name="$name">
    <option></option>
    $customtypes_opt
</select>
HTML;

        // return the necessary HTML string to display the field
        return $field_html;
    }

    /**
     * Helper method that returns a list of custom values.
     *
     * @return  array
     */
    private function loadMyCustomValues()
    {
        return [
            'VGT' => __('I am vegetarian', 'vbocustomcheckindriver'),
            'VGN' => __('I am vegan', 'vbocustomcheckindriver'),
            'ALL' => __('I have no food preference', 'vbocustomcheckindriver'),
        ];
    }
}

This is how guests will be registered (checked-in) in the back-end section of Vik Booking. Thanks to our custom driver we are collecting the desired information from each guest, including our custom field "myinfo" (called "Custom Information"):