The Region Gadget

MVC Enhancement

The Region Gadget is the pivotal item of the gadget set - it is the largest and most option-heavy. As with the Search Gadget, the only required option is the vcID. The gadget on this page was started with the following code:

<script src="//gadgets.impartmedia.com/gadgets.jsz" type="text/javascript"></script>
<script type="text/javascript">
    $w(function() {
        BE.gadget.region('#region-example',{
            vcID:85,
            itemDetailPageURL:'./03-details-and-cart-gadgets.html'
        });
    });
</script>

There is also one special addition option, which must be implemented externally to the region gadget before its initialisation. If you want to completely override the default syntax of the URLs for the products, you must define a global variable called BE_gadgetURLOverrides. This is an object with the product ID as the key, and the URL as the key->value. Example syntax for this option is shown below:

var BE_gadgetURLOverrides = {
    10138: '/Best-Western-Crystal-Hotel.html',
    25480: '/Hotel-Shamrock.html',
    25481: '/Welcome-Stranger-Motel.html'
};

Region Gadget Defaults

If not supplied, these are the default values for the Region Gadget:

accomOnlyMode:          false
advancedPriceView:      null
applyBoundsAlgorithm    true
bookingStatus:          null
campaignID:             null
collapseRefineTools:    true
customMapIcons:         null
defaultSort:            null
defaultRegionLoc        null
defaultRegionRegion     null
defaultRegionState      null
disabledTypes:          null
embedSearch:            true
enableRegionSearch:     false
excludeOperators:null
forceAccomType:         null
forceTourType:          null
forceDefaultTypes:      null
forceMapBounds:         null
forceRegionLoc:         null
forceRegionRegion:      null
forceRegionState:       null
hideCategories:         null
ignoreSearchCookie: true
includedOperators:all
interactiveMapMode:     false
interactiveMapUser:     false
itemDetailPageURL:      '/product/detail.html'
lastMinuteMode:         null
limitLocations:         null
listAllMode:            false
noAdults                45 
noChildren              45
noInfants               45
noConcessions           45
noStudents              45
noObservers             45
noFamily                10
period                  5
refineToolsLocation:    null
showAccomTypeFilter:    true
showAllAccom:           false
showAllLocationsForOperator false
showAllTours:           false
showAllEvents:          false
showCentsInPrices:      false
showEmptyCartButton:    false
showLegend:             false
showList:               true
showLocationFilter:     true
showRoomDetails:        false
showMap:                true
showRefineTools:        true
specificTypes:          null
thumbsInGrid:           true
toursOnlyMode:          false
treatPrimaryTypeAsCategory false
vcID:                   null
vcLocations:            null

All possible parameters are described below. Click the title to see more information.


Note: in addition to its own options, the Region Gadget (if embedSearch is true) can be passed options from the Search Gadget to initialise state.


accomOnlyMode

Only show accommodation operators on the gadget search.

advancedPriceView

If passed an empty array, this option will cause price view (for accommodation only) to render the list grouped according to accommodation type, with inserted headers. If you wish to specify a particular order of the type groups, you can insert strings into the array, like so: ['Houses', 'Farmstay']. This will cause these two groups to be inserted first, with any remaining groups placed afterwards.

advPV

Advanced price view. To add classes to the price view on the region gadget.

agKey

e.g. agKey: "12345678-9abc-0def-g98h-7i6kl5m43210"

When you supply a BookIt Agent’s unique Agent Key, the gadgets will authenticate the end user and tag the booking as a booking received by the BookIt Agent pertaining to the Agent Key specified. BookIt recommends that when used, this parameter should be applied to the Search, Region and Item Details gadgets in order to ensure that agent authentication is always applied, regardless of the web page the end user lands on.

You can obtain a BookIt Agent's unique Agent Key via the BookIt Staff Console when viewing the Agent, or the homescreen of the agent’s BookIt Agent Console.

anchor

vcLocations:[
{
    name:'Hunter Valley Visitor Centre',
        lat:-32.781700,
        lng:151.344888,
        //Optional
        customImage: "{imageUrl}",
        customImageOptions: {
        size: {x:300,y:50},
            origin: {x:0,y:0},
            anchor: {x:200,y:0}
        }
    }
]

applyBoundsAlgorithm

When interactiveMapMode is set to true, a bounds algorithm is applied. The purpose of this is to remove any strange lat longs from the list, and to avoid strange icons being rendered. There may be a case where this algorithm may remove wanted icons. If this occurs, try setting this option to false.

bookingStatus

OPTIONAL. This value is to set to "Booked" by default when a property is unavailable. But the user can still go head and change the text to any customised message, as required, using this option.

businessGroupings

A setting to filter business groupings on the map view. Supplies type IDs to the API to filter.

campaignID

This will put the gadget into campaign mode, and will only show operators that are part of the supplied campaign ID. In campaign mode, the sort order tool is hidden, as the sort order is defined at the campaign level. Should the campaign have used the levels functionality, then the gadget will add classes you can use to style the various levels.

The syntax for converting your level names to classes is: set to lowercase, replace spaces with hyphens, and remove any numbers at the start of the name. So, for example, 'First Class' would become 'first-class'.

Note: your style declarations will need to use !important if you don't set rules any more specific than the ones already in use by the gadget.

categories

A setting to filter operator categories on the map view. Supplies type IDs to the API to filter.

collapseRefineTools

If set to false, this will cause the refine tools (filtering, sorting) to always be shown, rather than hideable.

collapseToursMode

Set to true to show the occurrence of the next available tour product for that operator.

crossDomainSearch

Set to true to use the search cookies from a search gadget hosted on a different domain to the region gadget.

currencyId

Sets the default currency.

customMapIcons

If supplied an object with the appropriate keys ['accom', 'tours', 'events', 'carhire', 'packages'] to match product types, you can override the default map markers with your own. See below for an example:

customMapIcons: {
    'accom':{
        icon:'the/URL/to/the/icon.png',
        pinpoint: [0,0],
        size: [0,0]
    }
}

Where the 'icon' value is a valid URL to a png image for the marker. 'pinpoint' is an array of [x,y] which defines the point where you expect your marker to touch the map. 'size' is an array of [x,y] for the size of your supplied png.

defaultDate

Rather than set a preferred days from today (using the next option below), you can hard-set a particular date you would like the gadget to default to. This options accepts a string of the format 'dd/mm/yyyy', or a JS date object.

defaultProductType

Sets a default product type eg. "accom", "tours", "carhire", "events", "packages"

defaultRegionLoc

When enableRegionSearch is set to true, you can set this parameter to default the location drop down to the option provided.

Note: If the user makes a change the user's selection will be used instead.

defaultRegionRegion

When enableRegionSearch is set to true, you can set this parameter to default the Region drop down to the option provided.

Note: If the user makes a change the user's selection will be used instead.

defaultRegionState

When enableRegionSearch is set to true, you can set this parameter to default the State drop down to the option provided.

Note: If the user makes a change the user's selection will be used instead.

defaultSort

Your preferred sort for the gadget when a user first loads the page. Accepts a string from the list: 'rating', 'price', 'name', 'location', 'instant', 'deal',' lastminute'.

descriptionHover

disabledTypes

If using the embedSearch [true] option below, you can remove items from the product type drop down by setting this option to an array of any of these four strings: 'accom', 'tours', 'events', 'carhire', 'packages'.

embedSearch

If set to false, this allows you to place the search/ refine tools functionality elsewhere in your layout, rather than being attached to the Region Gadget. You will need to initialise a Search Gadget before you start a Region Gadget with this set to false.

enableRegionSearch

Set to true to get the gadget to break down the location refine tools select list into state/region/location. Must have the showRefineTools option set to true.

excludeOperators

Used exclude certain operators. Accepts a four to five digit operator IDs separated out by a comma: eg [1234,12345,54321],

externalSearch

forceAccomType

When showRefineTools is set to true this will default the Accommodation Types drop down to the string value specified.

forceTourType

When showRefineTools is set to true this will default the Tour Types drop down to the string value specified.

forceDefaultTypes

When working in interactiveMapMode, forceDefaultTypes will allow you to set the operator type ID (or IDs) to display by default when the interactive map is viewed. It is recommended that this be used in conjunction with the specificTypes parameter. As a result, if an array of operator type IDs are passed, it will locate the specificTypes that match and set those types to show by default.

forceMapBounds

When showMap or interactiveMapMode is true, this parameter can force the viewport to display a defined boundary. This is done by specifying two lat/longs which define a rectangle. Once you set your bounds the Google API will automatically select the best zoom level to the bounds you've specified.

forceMapBounds: {
  pointA:{
      lat:-36.7858,
      lng:144.2261
  },
  pointB:{
      lat:-36.7395,
      lng:144.3157
  }
}

forceRegionLoc

When enableRegionSearch is set to true this will set the location select list to the value supplied.

forceRegionRegion

When enableRegionSearch is set to true this will set the region select list to the value supplied.

forceRegionState

When enableRegionSearch is set to true this will set the state select list to the value supplied.

forceTourType

googleMapsKey

When utilising the map tab on the region gadget this parameter allows you to implement a Google Map API key. This is especially important if your site has a new domain, as Google only allows an amnesty for missing API keys for sites that included the API before the requirements were changed.

googleMapsKeyGlobal

hideCategories

If supplied an array with any of the strings: 'accom', 'tours', 'events', 'carhire', 'packages' the interactive map mode will not show that primary category.

ignoreSearchCookie

When setting this parameter to true, all search cookies will be ignored from other pages that have loaded the gadgets previously and provide new search results based off of the gadget settings.

includedOperators

Used to include only specified operators. Accepts four to five digit operator IDs separated out by a comma: eg [1234,12345,54321],

interactiveMapMode

If set to true, this will force the gadget into interactive map mode, which shows only the map and a list of the primary (bookable) and secondary product types.

interactiveMapUseOpGroupings

interactiveMapUser

When the interactive map searches accommodation, tours, events, carhire, or packages it runs a reservation request. When this is done it uses default values to run the request. When this mode is set to true the values passed to the search criteria will use the values that the user has currently used for searching.

itemDetailPageURL

This is a recommended option. Like the Search Gadget, this sets the URL for the next gadget in the chain - the Item Details Gadget. This sets where the user goes when they choose a product from any of the views. It accepts and replaces the following tokens: '{name}', '{url}', '{type}', '{id}'.

The '{name}' token is the exact string of the product name, with all characters and punctuation. The '{url}' token is the product name, after the being set to lowercase, and having the following regular expression remove any non-valid characters: [^a-z0-9]. Spaces are then replaced with '-'. The '{type}' token is the internal type string: 'accom', 'tours', 'events', 'carhire', 'packages'. The '{id}' token is the product id, and can be used in conjunction with the '{type}' token to look up the product from the API.

lastMinuteMode

If set to true, this grid will only display operators who have enabled last minute discount rates in their Member Console.

length

limitLocations

Pass an array of location names to limit the gadget to only show operators that match. This also affects the location filter drop-down to only show the supplied locations.

listAllMode

If set to true, it will force the gadget to list view, hide most of the controls, and hide the price buttons.

noAdults

Maximum number of adults that can be selected from the adult drop down.

noChildren

Maximum number of children that can be selected from the children drop down.

noConcessions

Maximum number of concessions that can be selected from the concessions drop down.

noFamily

Maximum number of family members that can be selected from the family drop down.

noInfants

Maximum number of infants that can be selected from the infants drop down.

noObservers

Maximum number of observers that can be selected from the observers drop down.

noStudents

Maximum number of students that can be selected from the students drop down.

origin

period

The default number of days/nights in the chooser, when the user first loads the page.

refineToolsLocation

If you want to refine tools to be placed somewhere else in your page, pass a valid CSS selector as this option to have the gadget insert the refine tools into that element.

restrictedButtonText

showAccomTypeFilter

If set to false, the gadget won't insert the accommodation type filter into the refine tools.

showAllAccom

If set to true, this will show all operators, even if they are unavailable for the time period searched.

showAllLocationsForOperator

When rendering out the price grid by default it will show the operators primary location. Setting this to true will show all their locations seperated by a / symbol.

showAllTours

If set to true, this will show all tour operators, even if they are unavailable for the time period searched.

showAllEvents

If set to true, this will show all events, even if they are unavailable for the time period searched.

showCentsInPrices

By default, the Region Gadget displays the cost of a product rounded to the nearest currency value.  This displays on both the "per night cost" and "total cost" when viewed on the region gadget.

If set to true, the Region Gadget will display the total cost and price per night without any rounding.

Note: If the total cost or price per night has been set by the operator as a total value without any decimals e.g. 50, then the price will still display as 50 (not 50.00).

showCurrencySelector

showDetailsInline

showEmptyCartButton

If set to true, an "Empty Cart" button will appear when cart items are displayed. Selecting this will allow a user to empty ALL product items in their shopping cart.

showFacilitesFilter

showHoverInline

showLegend

If set to true, the gadget will create a small legend describing the different button colours. This will appear to the right of the view choice tabs, unless you're using advancedPriceView, then it will appear in the header row for each group. You can also pass an object to it to set the text for each button type:

{
    'instant':'Immediate booking', 
    'request':'24 hour booking'
}

showList

If set to false, the gadget won't show the tab for the details view.

showLocationFilter

If set to false, the gadget won't insert the location filter into the refine tools. Do not use this option when enableRegionSearch is set to true.

showMap

If set to false, the gadget won't build or show the map view.

showQuantity

showRefineTools

If you want the user to be able to set up some preliminary filtering, set this to true. It is important to note that these fields must be setup correctly inside the Bookeasy console otherwise this will fail to load.

showRoomDetails

If set to true, each operator will have the room name, max guests, and room description displayed for the rate profiled in the search results. This is in addition to the operator name and location that appears as standard. Please note that this parameter does not work in conjunction with the advancedPriceView parameter, as that parameter displays these extra room details by default.

showRoomDetailsInline

showTourTypesFilter

size

stageId

specificTypes

Used in conjunction with interactiveMapMode, if passed an array of type IDs (up to 12), it will output those specific secondary types in the map sidebar, in the order supplied. To look up types for a particular vcID, please refer to the API message getVcOperatorCategories.

thumbsInGrid

If set to false, the gadget will not insert thumbnails into the price grid.

toursOnlyMode

Only show tour operators on the gadget search. Can be set to true/false.

treatPrimaryTypeAsCategory

Used in conjunction with interactiveMapMode:true. When enabled, the four primary types (accom, tours, events, and carhire) will no longer be availability dependent.

vcID

REQUIRED. Set this to the appropriate visitor centre ID to fetch that area's data.

vcLocations

If passed an array of objects, the map will insert markers for the Visitor Centre data supplied. An example of the object format is as follows:

vcLocations:[
    {
        name:'Hunter Valley Visitor Centre',
        lat:-32.781700,
        lng:151.344888,
        //Optional
cusomImage: "{imageUrl}",
        customImageOptions: {
            size: { x: 300, y: 50 },
            origin: { x: 0, y: 0 },
            anchor: { x: 200, y: 0 }
        }        
    }
]