Installation

Coming Soon! 

If you are interested in being an early adopter, please contact your Sabre Account Manager.

 

How to request 

SHS Customers should contact their Account Manager for details on cost and to request access to use widgets.  Customers will need to provide the list of Chains, Brands, and Hotels that will be using widgets, as well as a list of domains for the websites on which they will be placed. 

Access Control 

SHS controls access to widgets through an API Key provided to customers during implementation.  Web developers will include the API Key in the configuration parameters of the widget.  The API Key will restrict access to the specific chains, brands, and hotels configured for that API Key.  The widgets will not display on websites or for hotels/chains that do not belong to the API Key in use. 

Customers should speak with their account managers if changes to chains, brands, hotels, and domains associated with the API Key are required after initial implementation. 

Installation Steps

SHS Widgets are implemented as Web Components that can be added to any website regardless of the technology stack or libraries used.  More information on Web Components can be found at https://www.webcomponents.org/introduction.    

Step 1: Link Widget Library and CSS 

Add the JavaScript libraries and CSS files required by the widget to the HEAD section of the HTML document on which they will be displayed.  Some widgets have dependencies on other widgets that they use internally, so files for more than one widget may need to be added.  See the "Widget Installation" tab for specific requirements for this widget.

It is recommended that the standard HTML 5 DOCTYPE declaration be used, as well as meta tags for utf-8 encoding and responsive web design.  

Example: HTML HEAD Requirements 

<!DOCTYPE html>  
<html>  
<head>  
    <!-- Meta tags for utf-8 and responsive design -->  
    <meta charset="utf-8">  
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">  

    <!-- Script for the Widget -->  
    <script charset="utf-8" src="https://be.synxis.com/public/widgets/libs/{{widget-type}}/web-component-with-libs.js"></script>

    <!-- CSS file for the Widget, if the widget supports one. -->  
    <link href="https://be.synxis.com/public/widgets/libs/{{widget-type}}/web-component-with-libs.css" rel="stylesheet">  

    <!-- Boostrap link  -->  
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css">  
</head>  
<body>  

</body>  
</html> 

Replace {{widget-type}} placeholder above with the actual widget type identifier.  Currently supported widget-types include:

  • shs-widgets-best-price
  • shs-widgets-calendar
  • shs-widgets-search-bar

Note: the shs-widgets-best-price type does not have a default CSS file, so omit the <link> element.

SHS widgets inherit from a Bootstrap CSS file.  If the site already uses Bootstrap, there will be no need to add the reference to the Bootstrap CSS library above.  The widgets will automatically inherit the branding and styling of the parent Bootstrap site.  

The domain name used in file references (be.synxis.com) should match the SBE domain of the environment being used.  If a white label domain is used for SBE, this should be the white label domain.  

Step 2: Add Web Components to HTML body 

Second, place web component elements within the HTML document where they should show.  These may be placed directly in the HTML like any other HTML tag.  

Example: Best Price Widget Web Component Declaration 

<!-- add a best price widget --> 
<sabre-shs-widgets-best-price 
    api="{{api_key}}" 
    chain="{{synxis_chain_id}}"
    hotel="{{synxis_hotel_id}}"
    currency="USD"
    . . . other config params . . . 
></sabre-shs-widgets-best-price> 

Replace the placeholders in brackets (e.g. {{api_key}}) with actual values.

Step 3: Customize Widget Parameters 

Additional parameters can be added to each web component declaration in Step 2 to customize the behavior of each widget instance.   A detailed list of parameters supported by this widget is included on the Configuration tab.

Some things to note about parameter values:

  • Parameters values follow the same rules for quotation as standard HTML elements.
  • It is recommended to use double quotes except when the value is a JSON object.
  • For values that are JSON objects to parse correctly, single quotes should surround the object, and double quotes used within the JSON itself (e.g. param='{"one": 1, "two: 2}').
  • Properly escape quotes used within values if they match the quote type surrounding the value as a whole.

Example: Customized Example of Calendar Widget Web Component 

<!-- Example of best price widget with custom parameters --> 
<sabre-shs-widgets-calendar 
  api="MDAwMTV+dFBKa01RsseUIrVzVqdWNaL21XNkRZSTJnWktGdUpIMFZBaWI4amx0SkxhMXJ0Z2xUcEVGRUg3TUVVSkRVeHcyTjgyaDRONCtzU1VGaVF2NmNKOXgrVFE9PQ==" 
  env="ccrs" 
  chain="6990" 
  hotel="14845" 
  currency="USD" 
  locale="en-US" 
  calendar-config='{ 
    "numberOfMonths": "2" 
  }' 
  start-date="2020-11-18" 
  end-date="2020-11-21" 
  adult="1" 
  child="2" 
  child-ages="[5,7]" 
  on-submit="clickMe" 
  labels='{ 
    "shs-widgets--calendar.noCheckIn": "No Arrival", 
    "shs-widgets--calendar.noCheckOut": "No Departure" 
  }' 
  render-not-available='<span class="error">Sorry. We are sold out!</span>' 
></sabre-shs-widgets-calendar>

Custom Labels 

Each widget supports a parameter named “labels” that takes a string encoded JavaScript (JSON) object as value.  The object may contain key/value pairs to override the default text labels provided by the widget.  All text can be customized by adding the custom text as value for the associated label key.

All labels supported by this widget can be found on the Configuration tab.

The widgets currently support default labels for English only.  Text may be shown in other languages by overriding all labels with the translated text to be used.  

Example: Overriding Default Labels 

<!-- Example syntax of the labels parameter overriding default text --> 
<sabre-widget 
  labels='{ 
    "shs-widgets--calendar.noCheckIn": "No Arrival", 
    "shs-widgets--calendar.noCheckOut": "No Departure", 
    "shs-widgets--calendar.infoMessage": "%{type} price shown in %{currency} for a %{los}-night stay" 
  }' 
</sabre-widget>

Some labels contain named placeholders for dynamic values that will be replaced by the widget (e.g.  %{type} price shown in %{currency}).  Variables are identified by a percent sign followed by a name surrounded by curly braces (e.g. %{currency}).  When overriding or translating labels, the variable name (e.g. currency) should NOT be changed.  

Callback Methods 

Most widgets support callback methods allowing custom functionality to be triggered in response to an action such as clicking a button, selecting a date range, or receiving data from SynXis Services.  Callback functions must be globally available in scope.  The name of the function should be included as a string (with no parentheses) as the value of the parameter associated with the callback (e.g. on-click="handleClick").  

Callback methods supported by this widget are included in the parameter list on the Configuration page. 

Example: Definition of a Callback Method 

<!-- Define a global JavaScript function --> 
<script>  
  function onHotelSelectMethod(hotel) { 
      console.log(hotel); 
  } 
</script> 

<sabre-widget 
  on-hotel-select="onHotelSelectMethod"> 
</sabre-widget>

Events 

Some widgets support JavaScript Events.  Event Listeners may be added in order to execute custom logic when the event is triggered.   

Events can be subscribed to using the window.addEventListener() function including the name of the event and a JavaScript function to be executed.  Event listeners receive a data object as an argument containing Event Data.  A "details" object will be included in the data object containing details specific to the state of the widget.  

Event listeners supported by this widget are listed on the Configuration tab. 

Example: Adding an Event Listener 

<!-- Add event listener to on-click event --> 
<script> 
    window.addEventListener('shs-widgets-best-price__on-click', eventData => console.log(eventData.detail)); 
</script>

Render Templates 

Most widgets support Render Templates that allow web developers to override the HTML template used to render specific components of each widget.  Render template parameter names begin with the word “render” and take Lodash template strings as values (see https://lodash.com/docs/4.17.15#template for information on Lodash templates). 

Each render template supports specific variables that are accessible to the template.  Those variables may be referenced in templates using Lodash template syntax (e.g. <%=myVariable%>).  

The render templates supported for this and the variables supported for each are listed on the Configuration tab. 

Example: Using a Render Template to Override a Portion of the Widget HTML 

<!-- Override the rendering template that generates the submit button HTML --> 
<script> 
  function clickMe() { 
    alert("You clicked me!"); 
  } 
</script> 

<sabre-widgets> 
  render-submit-button='<button onClick="clickMe()">Book for <%=nights%> Nights</button>' 
</sabre-widget>

Note: Because Web Component parameters are passed as strings, developers must be careful when using Boolean and Function variable types within render templates.  For example, a boolean value cannot simply be dropped in place using lodash interpolation, as it will be treated as a string (which always acts as true) even if the string value is "false."

Code Example 10 – Interpolation of Boolean in Render Templates 

<!-- This will NOT work as expected -->
<sabre-widget>
  render-template='<button disabled=<%=isSubmitDisabled%>My Button</button>'
</sabre-widget> 

<!-- If false the above will render as the string value "false" 
     and all strings are treated as true. -->
 <button disabled="false">My Button</button> 

<!-- Instead use the boolean in template logic to replace what is interpolated -->
 <sabre-widget>
    render-template='<button <% if(isSubmitDisabled){ %>disabled="disabled"<%}%>>My Button</button>' 
</sabre-widget> 

<!-- Interpolated properly if true -->
<button disabled="disabled">My Button</button> 

<!-- Interpolated properly if false -->
<button >My Button</button>

Example: Interpolation of Function Reference in Render Templates 

<!-- This will NOT work as expected if onSubmit contains a function because the  function will be converted to a string as part of the interpolation --> 
<sabre-widget> 
   render-template='<button onClick=<%=onSubmit%>My Button</button>' 
</sabre-widget>

<!-- instead, assign the function to a window.variable first, then execute --> 
<sabre-widget> 
   render-template=' 
      <script>   
         <% window.myOnSubmitFunction = onSubmit %> 
      </script> 
      <button onClick="myOnSubmitFunction()">My Button</button>' 
</sabre-widget>

 

Step 4: Style Widgets 

Widget CSS was designed to inherit common settings from Bootstrap stylesheets to minimize extra work required to apply the site’s branding to widgets.  If a site does not use Bootstrap, a link to the Bootstrap stylesheet is required in the HEAD of the HTML document (see Step 1 above).  Web Developers may add custom CSS to override the default CSS in the Bootstrap and Widget stylesheets.   

The stylesheets of each widget type are independent of each other, so each type of widget type may be styled differently without conflict.  The style classes supported by each widget can be viewed by developers inspecting the DOM and by viewing the contents of the default widget stylesheets. 

Example: Styling Widgets 

<!-- Example of overriding the style of the calendar widget box and month outline --> 
<style> 
  .shs-widgets--calendar { 
    background-color: white; 
    border: 1px solid grey; 
    padding: 10px; 
    margin: 10px; 
  } 

  .DayPicker-Month { 
    border: 1px solid grey; 
    margin: 5px; 
  } 
</style>