Advanced Technical Manual
This user-manual is designed as a reference guide for technical users looking to implement the widget and utilise advanced features. A guide for non-tech users to assist with managing and maintaining the widget can be found on the Basic User Manual page. For more detail please contact Scoop at [email protected].
Introduction to the Scoop Widget
Our CONTENT represents more than 5,800 events, suppliers and attractions and growing at 100 per month; by far the largest in WA. Missing and out of date content will be immediately updated by the Scoop content team.
You can place the widget on MULTIPLE PAGES, representing the best of your region, broken down by location and/or content type (e.g. events, galleries, wineries, aboriginal experiences, tours, accommodation, fishing).
Our content can drive your MARKETING, providing the content and tools your website needs for industry and destination promotion, including the ability to create and share customisable trails and itineraries as part of your web, social media and email marketing strategies.
Currently the Scoop content includes over 6,000 listings, covering all geographic areas within Western Australia, in the following listing types:
Arts & Events – Events; Business Events; Workshops & Short Courses; Clubs & Associations; Art Galleries, Museums & Libraries
Lifestyle & Travel – Accommodation; Food & Drink; Places To Go; Shopping; Things To Do; Wineries
Functions & Venues – Caterers; Function Services; Function Venues
Building & Design – Architects, Builders & Designers; Commercial Designs; Residential Designs; Developers; Developments; Suppliers & Retailers; Product Ranges
The widget has six major components:
- Primary Filters – this includes (i) the WHERE filter for selecting the location, (ii) the WHAT filter for selecting the type of listing, (iii) the KEYWORDS for performing a keyword listing search, (iv) the SHARE icon for sharing the search results, and (v) the FAVOURITES icon for favouriting listings.
- Search Title – a title for the active search (this can be turned off if desired).
- Secondary Filters – the range of advanced filters that can be used to further filter listings; these filters change according to the selected WHAT value.
- Grid Controls – controls for (i) switching between grid view and map view, (ii) switching the language between EN and CN, and (iii) a count of the number of listings in the active search.
- Listing Grid – the area in which the actual listings will display; clicking a listing will open the QUICKVIEW panel for that listing.
- Paging Controls – located at the bottom of the grid, these controls can be used to move between pages and limit the number of listings in the grid.
Each of these components can be turned off using widget controls if desired.
The widget has a large number of properties that can be used to influence functionality, visibility and styling. See the “Widget Data Props” section at the end of this page for the full set of properties.
The mandatory properties are the most critical, as follows:
How to setup the widget
Setting up the Scoop Widget on your website is a simple two step process:
STEP 1 – Request a content license from Scoop.
STEP 2 – Add the Scoop Widget code snippet to your page(s).
Optionally, you may also choose to add “searchlinks” to your page, to make it easy for your visitors to find your recommendations.
Each of these steps is described in more detail below.
STEP 1 - Request a content license from Scoop
- Client organisation name (example: Dongara Port Denison Visitor Centre)
- Client website domain (example: https://myvisitorcentre.com.au)
- Regions for the widget (example: Dongara, Port Denison, Bookara)
- Types for the widget (example: Events, Accommodation, Things To Do, Food and Drink)
The Regions and Types that you specify will limit the overarching widget scope for your website. You can further limit the widget on a page by page basis – by Region, Type and other filters – but only within this overarching widget scope. The content license ID that you are assigned must be referenced in the widget code snippet in Step 2.
STEP 2 - Add the widget code snippet to your page(s)
Each webpage on which the widget is to display requires a unique widget code snippet. The purpose of this small snippet is to embed the widget on the page and provide the widget scope for that specific page.
It is essential to provide a WHERE scope (Region) and a WHAT scope (Type) for the widget but you may also choose to limit the scope of the widget by various FILTERS that are available for each Type. For example, if the Type is “Wineries” then there will be filters available for “Wine Variety” and “Cellar Door Open Days”. If the Type is “Events”, however, there will be filters available for “Date” and “Venue”. Each Type has numerous filters available.
When you specify a FILTER scope for the widget you can specify whether that scope should be “hard” or “soft”. A “soft” filter will be in force when the widget initially loads on the page but can be subsequently overridden by the website visitor. A “hard” filter will also be in force when the widget initially loads on the page but cannot be subsequently overridden by the website visitor.
The screenshot shows an example widget code snippet, configured as follows:
- License (data-prop-license) set to the value “12345” (note that this is a dummy value).
- Region (date-prop-region) set to “western-australia”, which indicates that listings for all geographical areas in Western Australia will be permitted.
- Listing Type (date-prop-type) set to “events”, which indicates that only events listings will be permitted.
- URL Write (data-prop-url-write) set to “true”, which indicates that the widget will actively write the page URL.
- URL Type (data-prop-url-type) set to “simple”, which indicates that the widget will write the page URL using query parameters.
- URL Stem (data-prop-url-stem) set to “/mypage/”, which indicates that when the widget writes the page URL it will prefix the query parameters with the value “/mypage/”.
- Grid Image Size (date-prop-grid-image) set to “small”, which indicates that the images used for grid listings will be small (as opposed to medium or large).
- Max Rows (date-prop-max-rows” set to “2”, which indicates that the maximum number of rows the widget will display will be 2.
- Headless (data-prop-headless) set to “true”, which indicates that the only widget component that will display will be the grid itself, i.e. no filters, controls etc will display.
You can use our simple Widget Snippet Generator to generate the baseline code for your snippet. You should then customise the code snippet, adding any additional data-props as required. For example you may add data-props for feature, category, dates etc.
How the widget operates and appears can be configured using over 50 widget properties, including which widget components display, how many grid rows display, the widget font family and size, which deeplinking method should be used and whether SEO data should be written by the widget. The full set of widget properties can be found in the Widget Data Props section below.
Note that you can have widgets on numerous pages on your website, each displaying different content and having different widget properties if you wish. You can even have more than one widget on a given page!
OPTIONAL STEP 3 - Add "searchlinks" to your widget
Searchlinks are used to provide your website visitors with a series of pre-filtered searches, saving them from having to individually make selections from the widget filters – you have done the hard work for them! The searchlink buttons can be placed adjacent to the widget and, when clicked, they update the widget to a different search state. In the screenshot you can see a Margaret River Region page that has a series of searchlinks for common searches such as Events, Food & Drink, Things To Do, Accommodation etc.
You can use our simple Searchlink Snippet Generator to get the code for your snippet. To use this generator you should do the following:
- Setup the widget on your page as per Step 2 above
- Repeat for each Searchlink (maximum of 10):
- Use the widget to set filters for your searchlink
- Click the share icon at the top-right of the widget and select to share to email
- Copy the share link that is generated
- Use the copied share link in the SearchLink Snippet Generator
- Generate the code snippet
- Use the code snippet on your website, typically just above the widget.
Listing, Feature and Category Codes
Some of the widget properties may require you to know a Listing ID, Feature ID or Category ID. Using the Chrome Dev Inspect Tool you can determine these values from the DOM. To use the Inspect tool do the following:
- Select the Chrome menu at the top-right of your browser window.
- Select More Tools > Developer Tools.
- Right-click on any page element and select Inspect Element.
In the first screenshot you can see a specific listing being selected using the inspect tool. Looking at the DOM we can see that the Listing ID for that listing is 109394.
In the second screenshot you can see a filter dropdown being inspected. When using the inspect tool on the filter itself (Music) we can see from the DOM that the Feature ID is 10081. When using the inspect tool on the values of the filter (Choral, Classical, Concert Tours etc) we can see from the DOM that the Feature ID’s are 76375, 16050, 18272 etc.
You may wish to create a collection of “recommended” listings for your website visitors, for example a regional winery may wish to display their recommended local galleries or beaches. This is a great way to promote not only your business but your entire destination – give your potential visitors another reason to come to your business by also promoting what is great in your local area.
You can do this by using the favourites function to select the intended listings and then using the share link for that collection of favourites as the basis of a widget searchlink. The screenshot shows a “Yallingup Art Gallery Trail”, which was displayed as a result of the website visitor clicking the corresponding searchlink above the widget.
Customising the widget appearance
HEADLESS WIDGET – The widget can operate in a “headless” mode which removes all widget components apart from the listing grid. This can great for showing your website visitors a listing “sampler”, particularly when used in conjunction with the ability to restrict the number of rows in the listing grid.
HIDING COMPONENTS – A number of the individual widget components – including primary filters and secondary filters – can be hidden using widget properties. This can be useful if you do not want your website visitors changing these values.
WIDGET VIEW – the widget has 3 views – grid view, map view and trails view. Which view you choose for a particular widget depends on what type of listings you are displaying. If the listings were all in close vicinity location-wise you may choose to display them in the map view (or trails view) rather than in the grid view.
GRID IMAGE SIZE – There are 3 different images sizes for the listing grid – small, medium and large – that can be set using widget properties.
FONTS – You can set the font family and font-size used by the widget to reflect those used on your website. These are set using widget properties.
GENERAL STYLING – The widget is an actual part of your webpage so all the standard CSS techniques can be used by yourself or your developer to impact styling.
The screenshot shows the widget being used in “headless” mode.