Configuration
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. |
| 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) 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 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: 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. |
| 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: 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.