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: |
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. |
initial-month |
Date |
- |
- |
The second date (or greater) of the first month to display (YYYY-MM-02). |
calendar-config |
object |
- |
- |
Calendar properties to be used in react-day-picker module (http://react-day-picker.js.org/api/DayPicker) |
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 rate codes to unlock and/or filter by, e.g. '["BAR","AAA"]' |
room-list |
JSON array |
- |
- |
Optional Array of room codes to unlock and/or filter by, e.g. '["A1K","B2Q"]' |
rate-filter-list |
JSON array |
- |
- |
Optional Array of CRS rate filter codes to unlock and/or filter by, e.g. '["Rack","Gov"]' |
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: |
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: |
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. |
sbe-extra-params |
JSON Array |
- |
- |
A JSON Array of JSON objects containing name/value pairs to add as additional parameters to the SBE Redirect URL. e.g. '[{"name":"level","value":"chain"}]' Note in this example &level=chain will be added to the redirect URL. |
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: |
on-day-select |
function name |
- |
- |
Name of a global function to trigger when user completes date range selection. Arguments inclded: |
on-error |
function name |
- |
- |
Name of a global function to trigger on error. Arguments: |
on-month-change |
function name |
- |
- |
Name of global function triggered on month change. Arguments: |
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: |
render-error-message |
lodash template |
- |
- |
Custom render template to override display/rendering of error messages. Variables: |
render-day-number |
lodash template |
- |
- |
Custom render template to override the display/rendering of the day-of-month number in calendar day boxes Variables: |
render-day-price |
lodash template |
- |
- |
Custom render template to override the display/rendering of the price in calendar day boxes. Variables: |
render-restriction-message |
lodash template |
- |
- |
Custom render template to override the display/rendering of the restriction message. Variables: |
render-legend |
lodash template |
- |
- |
Custom render template to override the rendering of the legend section. Variables: |
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: |
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.
Change Log
Date | Version | Summary |
---|---|---|
14 July 2021 | 4.0.1 (SBE 8.7.1) |
- Added initial-month parameter to specify the first month to display (if not the current month). - Added rate-filter-list support. - Added documentation for sbe-extra-params object allowing custom URL parameters to be added to the SBE redirect URL. |