Skip to main content

Calendar Widget

1.0.0
Widget
Try Now

Calendar Widget - Configuration Options

The Calendar widget allows site owners to display a live availability calendar on their site, based on real-time availability and pricing data in the SynXis CR.  The calendar includes parameters to filter results and unlock confidential rates based on stay criteria, room code, rate code, access code, IATA number, etc…

The Calendar widget can also be used as a date picker.  When dates are selected, the total price is updated to reflect the selected stay.  If dates are selected that are not available due to restrictions, a message will display explaining the restriction.  A Search button may be displayed and configured to link to the SBE or a custom endpoint.

The base styling of the calendar is very simple by default, but highly customizable through CSS and render templates.  Callbacks exist for api response, date selection, on change of month, on submit, and on error.

Configuration Options

Property  Type  Required  Default  Description 

api

string

yes

-

Api Key

chain

string

yes

-

SynXis CRS Chain ID

hotel

string

yes

-

SynXis CRS Hotel ID

currency

string

yes

-

ISO Currency Code.  Only products setup in SynXis CR with pricing in this currency will be considered in the price calculation.

locale

string

-

(browser locale)

Locale to use for number/currency format.  Defaults to the guest's browser locale.  ISO Code, e.g. "en-US"

env

enum

-

ccrs

The SHS environment from whitch to pull pricing:
ccrs - CCRS Environment
cuat - CUAT Environment

primary-channel

string

-

WEB

Primary channel to use when pulling data from SynXis CR.  Default WEB is for Booking Engine channel.

secondary-channel

string

-

GC

Secondary channel to use when pulling data from SynXis CR.  Default GC is for Booking Engine secondary channel.

calendar-config

object

-

-

Calendar properties to be used in react-day-picker module (http://react-day-picker.js.org/api/DayPicker)
Commonly used params include:
numberOfMonths, firstDayOfWeek

adult

number

-

1

Number of adults used in the pricing calculation.

child

number

-

0

Number of children used in the pricing calculation.

child-ages

JSON array

-

[]

Array of child ages used in the pricing calculation (e.g. '[1, 8]').

length-of-stay

number

-

1

Length of stay used in the pricing calculation.  A value greater than 7 should not be used to avoid slow performance.  Performance will decrease exponentially as length-of-stay increases.

start-date

date string

-

-

The Arrival date (YYYY-MM-DD) preselected on the calendar.

end-date

date string

-

-

The departure date (YYYY-MM-DD) preselected on the calendar.

rooms

number

-

1

Number of rooms used in the pricing calculation.

rate-list

JSON array

-

-

Optional Array of room codes to unlock and/or filter by, e.g. '["A1K","S1K"]'

room-list

JSON array

-

-

Optional Array of rate codes to unlock and/or filter by, e.g. '["AAA","AARP"]'

access-code

string

-

-

Optional Access code value to filter price - if present access-code-type is required

access-code-type

enum

-

-

Access code type - if present, the access-code value is required.  Valid values:
Promotion - promotion or corporate code
Group - group code

iata-number

string

-

-

TA agency or IATA number.  Include rates assigned to the IATA number in the pricing calculation.

only-check-requested

bool

-

false

If true, pricing will be based only on products matching the filtering criteria (access codes, iata, room/rate codes, etc...).  If false, pricing will consider public rates along with rates "unlocked" by the filtered criteria.

include-taxes

bool

-

true

If true, the displayed price will include taxes and fees.

price-type

enum

-

Minimum

CRS price type to display:
Minimum - lowest price
Maximum - highest price
Average - average price

hide-legend

bool

-

false

Hide legend section of display

hide-prices

bool

-

false

Hide prices on calendar days

hide-submit

bool

-

false

Hide submit button section of display

prevent-price-calculation

bool

-

false

Prevent pricing recalculation and display of new total price after each new date range is selected.

prevent-selection

bool

-

false

Prevent selection of dates.  Calendar is view-only.

sbe-redirect

bool

-

true

Button click automatically opens the SynXis Booking Engine with the widget stay criteria and filtering applied.

sbe-custom-url

string

-

-

White label domain to use in place of be.synxis.com if sbe-redirect is true and the property uses a white label domain.

on-api-response

function name

-

-

Name of a global function to trigger when a response is returned from the API Lead Availability request.  Arguments include:
responseData - pricing data returned from Lead Availability service call
this.state - object containing variables defining the widget state (includes input params, etc...)

on-day-select

function name

-

-

Name of a global function to trigger when user completes date range selection. Arguments inclded:
startDate - Selected arrival date (YYYY-MM-DD)
endDate - Selected departure date (YYYY-MM-DD)
restrictions - Array of Restriction Codes applicable to the selected stay (see Restriction Codes table below for possible values)
this.state - object containing variables defining the widget state (includes input params, etc...)

on-error

function name

-

-

Name of a global function to trigger on error.  Arguments:
exception - exception object
this.state - object containing variables defining the widget state (includes input params, etc...)

on-month-change

function name

-

-

Name of global function triggered on month change. Arguments:
day - the first day of the last month that was displayed previously
numberOfMonths - number of months displayed
this.state - object containing variables defining the widget state (includes input params, etc...)

on-submit

function name

-

-

Name of a global function to trigger on button click.  This will override the default submit method that opens the SynXis Booking Engine.  Arguments:
this.state -object containing variables defining the widget state (includes input params, etc...)

render-error-message

lodash template

-

-

Custom render template to override display/rendering of error messages.  Variables:
t - Function to retrieve text labels by label key ¥ (see description at bottom of this table)
error - An error string

render-day-number

lodash template

-

-

Custom render template to override the display/rendering of the day-of-month number in calendar day boxes  Variables:
dayFormatted - the applicable date in YYYY-MM-DD format
day - the applicable day of month (1, 2, ...)
locale - the applicable ISO locale code

render-day-price

lodash template

-

-

Custom render template to override the display/rendering of the price in calendar day boxes.  Variables:
dayFormatted - the applicable date in YYYY-MM-DD format
CurrencyCode - the applicable ISO currency code
Value - the applicable price as an unformatted numeric value
locale - the applicable ISO locale code

render-restriction-message

lodash template

-

-

Custom render template to override the display/rendering of the restriction message. Variables: 
cause - Restriction Cause code for the restriction that caused failure.  See Restriction Causes table below.  Note: more than one restriction may apply, but only the Least Restrictive Failure code is actually displayed.
extra - A value (usually numeric) to be passed as second parameter to label function calls for interpolation into an "%{extra}" placeholder in the label. (e.g. if extra=2, then '<%= t("%{extra}-night-minimum-stay", extra) %>' injects "2-night-minimum-stay")
t - Function to retrieve text labels by label key ¥ (see description at bottom of this table)

render-legend

lodash template

-

-

Custom render template to override the rendering of the legend section.  Variables:
t - Function to retrieve text labels by label key ¥ (see description at bottom of this table)

render-spinner

lodash template

-

-

Custom render template to override the render of the loading spinner.  No variables.

render-submit-button

lodash template

-

-

Custom render template to override the rendering of the calculated price display and button.  Varibles:
onSubmit - submit function to attach to button onClick handler
isSubmitDisabled - bool indicating if submit functionality was disabled using the hide-submit parameter
t - Function to retrieve text labels by label key ¥ (see description at bottom of this table)
priceForStay - object containing pricing info for the stay
locale -
the applicable ISO locale code
includeTaxes - boolean indicating whether taxes and fees are included in the price
nights - number of nights for the selected stay

labels

object

-

defaultLabels

Object containing label keys and values to override default labels.  See Labels section below for JSON example containing all default label keys and values.

¥ - 't' is a function that returns label text for a given label key.  Label text can include placeholder variables, so an optional object with "extra" placeholder values can also be provided with the key.  For example, if the label text for the "shs-widgets--generic.restriction.MinStayArrive" label key is "%{extra}-night minimum stay", then '<%= t("shs-widgets--generic.restriction.MinStayArrive", {"extra": 2}) %>' in a lodash template renders the text “2-night minimum stay”).

Restriction Codes

The supported restriction codes used by the API and the on-day-select callback are:

Restriction Code
Limit
NoSellDay

NoDeparture

NoArrive
MaxLeadDays
MinStayThrough
MaxOccupancyExceeded
Closed
ZeroFinalPrice
NoAvailableInventory
SeasonalClosure
MinStayArrive
LeadDaysTime
MaxAdultOccupancyExceeded
MaxChildOccupancyExceeded
MaxStayArrive

 

Default Labels

The following JSON String is a list of all labels used by the Calendar Widget.  Any or all of these may be translated or overridden using the “labels” parameter in the widget definition. 

{
    "shs-widgets--generic.error.InvalidPromoOrCorporateCode.title": "The promo code you entered is invalid",
    "shs-widgets--generic.error.InvalidPromoOrCorporateCode.description":
        "Enter a different code or continue shopping below.",
    "shs-widgets--generic.error.InvalidGroupCode.title": "The group code you entered is invalid",
    "shs-widgets--generic.error.InvalidGroupCode.description": "Enter a different code or continue shopping below.",
    "shs-widgets--generic.error.ERROR.title": "Oops..",
    "shs-widgets--generic.error.ERROR.description": "Something went wrong. Please try again in a minute.",
    "shs-widgets--generic.error.InvalidChainId.title": "Invalid chain ID",
    "shs-widgets--generic.error.InvalidChainId.description": "Please make sure you are providing a valid chain ID",
    "shs-widgets--generic.error.InvalidApiKey.title": "Invalid API Key",
    "shs-widgets--generic.error.InvalidApiKey.description":
        "Your API Key is invalid. Please make sure you typed it correct.",
    "shs-widgets--generic.error.ReferrerNotAllowed.title": "Invalid domain",
    "shs-widgets--generic.error.ReferrerNotAllowed.description": "Your website is missing an access for this widget.",
    "shs-widgets--generic.error.InvalidRequest.title": "Error",
    "shs-widgets--generic.error.InvalidRequest.description":
        "Something wrong with your configuration. Please validate parameters.",
    "shs-widgets--generic.error.InvalidHotelId.title": "Invalid hotel ID",
    "shs-widgets--generic.error.InvalidHotelId.description": "Please make sure you are providing a valid hotel ID",
    "shs-widgets--calendar.error.InvalidApiKey.title": "Invalid API Key",
    "shs-widgets--calendar.checkOut": "Check out",
    "shs-widgets--calendar.totalPrice": "From %{price} total for %{nights} night(s)",
    "shs-widgets--calendar.includingTax": "Including taxes and fees",
    "shs-widgets--calendar.excludingTax": "Excluding taxes and fees",
    "shs-widgets--calendar.infoMessage": "%{type} price shown in %{currency} for a %{los}-night stay",
    "shs-widgets--calendar.minimum": "Lowest",
    "shs-widgets--calendar.average": "Average",
    "shs-widgets--calendar.maximum": "Highest",
    "shs-widgets--calendar.restriction": "You selected a restricted date.",
    "shs-widgets--calendar.restriction.MinStayThrough":
        "There is a %{extra} night minimum length of stay required for your selected dates.",
    "shs-widgets--calendar.restriction.MaxStayThrough":
        "There is a %{extra} night maximum length of stay required for your selected dates.",
    "shs-widgets--calendar.restriction.NoAvailableInventory": "A date within your stay is not available.",
    "shs-widgets--calendar.restriction.NoArrive": "No arrival allowed on your selected arrival date.",
    "shs-widgets--calendar.restriction.NoDeparture": "No departure allowed on your selected departure date.",
    "shs-widgets--calendar.search": "Search",
    "shs-widgets--calendar.noCheckIn": "No Check-in",
    "shs-widgets--calendar.noCheckOut": "No Check-out",
    "shs-widgets--generic.restriction.Limit": "Not available",
    "shs-widgets--generic.restriction.NoSellDay": "Not available",
    "shs-widgets--generic.restriction.NoDeparture": "No Check-Out",
    "shs-widgets--generic.restriction.NoArrive": "No Check-In",
    "shs-widgets--generic.restriction.MaxLeadDays": "No Check-In",
    "shs-widgets--generic.restriction.MinStayThrough": "%{extra}-night minimum stay",
    "shs-widgets--generic.restriction.MaxOccupancyExceeded": "To many guests - max %{extra}",
    "shs-widgets--generic.restriction.Closed": "Not available",
    "shs-widgets--generic.restriction.ZeroFinalPrice": "Not available",
    "shs-widgets--generic.restriction.NoAvailableInventory": "Not available",
    "shs-widgets--generic.restriction.SeasonalClosure": "Not available",
    "shs-widgets--generic.restriction.MinStayArrive": "%{extra}-night minimum stay",
    "shs-widgets--generic.restriction.LeadDaysTime": "This stay requires a %{extra} lead days time",
    "shs-widgets--generic.restriction.MaxAdultOccupancyExceeded": "Too many adults for selected number of rooms",
    "shs-widgets--generic.restriction.MaxChildOccupancyExceeded": "Too many children for selected number of rooms",
    "shs-widgets--generic.restriction.MaxStayArrive":
        "There is a maximum length %{extra} nights for your selected dates.",
    "shs-widgets--generic.restriction.MaxStayThrough": "This stay requires a maximum of %{extra} nights."
}

At present default labels are only provided in English.  If the widget needs to be displayed in other languages, then all label values should be overridden with the desired translation.  A future enhancement will provide defaults in all CRS-supported languages and allow them to be customized through the BE Designer application in SynXis Control Center. 

If Render Templates are used, custom label key value pairs may be added to the labels object and referenced in Render Templates using the "t" function (e.g. t("my-custom-label") ).

 

Events

No events are currently supported for the Calendar Widget.  Events will be added in future releases.