中文
Select Page

Widget Setup

Introducing the Scoop Widget

The Scoop Widget is a React component that can be embedded on any web page in order to display listings from the Scoop content distribution network. In a matter of moments you can add a wealth of destination promotion content to your client’s website.

This documentation outlines how to setup the widget on a website:

Step 1 – Request Scoop to setup a content license for the website
Step 2 – Add the widget snippet to the various webpage(s)
Step 3 – Add smartlinks (optional)

Two special cases, Listicles and Trails, are explained in Appendix A and B respectively.

Widget Scope

The widget will operate differently on each website, according to its Site Scope and Page Scope.

The Site Scope determines which geographical regions and listing types will be permitted for the widget on this website. The site scope is setup via a content license (refer Step 1).

The Page Scope determines the specific state of the widget for a given webpage. The page scope is setup using widget data-props (refer Step 2).

Step 1 – Request a Content License

Each website must have a unique content license in order to access the Scoop content. You should email Scoop at [email protected] to request a license be setup for your website. The following information should be provided:

  • Client organisation name
  • Client website domain
  • Regions for the widget
  • Listing types for the widget

The regions and listings types that you specify will limit the site scope of the widget. You can limit the page scope of the widget on a page by page basis – by region, listing type and other filters – but only within this overarching site scope.

On occasion it may be necessary to setup multiple content licenses for a website, for example if the website has various sub-regional pages. Please get in touch if you think this is the case and we can provide guidance.

To identify the regions and listing types for your website you should go to https://scoop.com.au and use the Region and Type filters:

By way of example, your request may look something like the following:

Scoop Content License Request
Client = Harvey Visitor Centre
Domain = http://www.harveyvisitorcentre.com.au/
Regions = Harvey
Listing Types = Events, Accommodation, Wineries, Things To Do

Once the content license has been setup by Scoop you will be emailed a License ID for use in the widget snippet. This License ID is specific to the website in your request.

Step 2 – Add the Widget Snippet

Each webpage on which the widget will display requires a unique code snippet. The purpose of this small snippet is to embed the widget on the page and provide the page scope for the widget. An example snippet is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<div class="sc-container">
<div id="sc-widget-target">
<div id="sc-listings-target" class="container">
<div 
data-component="SCListings" 
data-prop-license="99999" 
data-prop-region="harvey-area" 
data-prop-type="wineries" 
data-prop-categories="10061" 
data-prop-url-write="true" 
data-prop-url-type="simple" 
data-prop-url-stem="/merlot-wineries/" 
data-prop-hide-search-title="true">
</div>
</div>
</div>
</div>
<script>
var uniqueValue = new Date().getTime().toString();
var script = document.createElement('script');
script.src = "https://deployments.azureedge.net/scoopwidget.js?v=" + uniqueValue;
document.head.appendChild(script); 
</script>

The first part is the HTML that will be used to contain the widget and includes the data-props that inform the widget of the page scope. The second part is the JavaScript that embeds the widget, loading it from our Azure server.

The widget has over 20 data-props, some of which are mandatory. Some of the data-props set the initial state of the widget but do not restrict the user from changing the widget state. Other data-props fix the widget in a specific state and stop the user from changing that specific state.

The widget has over 20 data-props, some of which are mandatory. Some of the data-props set the initial state of the widget but do not restrict the user from changing the widget state. Other data-props fix the widget in a specific state and stop the user from changing that specific state.

Of particular note are the data-props for Feature and Category. Each of these two data-props have a “standard” version and a “fixed” version:

data-prop-features – the feature IDs provided via this data-prop will be in effect when the widget initially loads but can be removed by the user should they wish.

data-prop-fixed-features – the feature IDs provided via this data-prop will be in effect at all times and cannot be removed by the user should they wish. Features are specific to a Listing Type so these fixed features will only be in effect for their respective listing type.

data-prop-categories – the category IDs provided via this data-prop will be in effect when the widget initially loads but can be removed by the user should they wish.

data-prop-fixed-categories – the category IDs provided via this data-prop will be in effect at all times and cannot be removed by the user should they wish. Categories are specific to a Listing Type so these fixed categories will only be in effect for their respective listing type.

When you are deciding on what data-props to set for the widget you should consider whether to use fixed features/categories. You may have, for example, a page focussed on film events but you are not fussed if the user removes the film feature and views all events – in this case you would use data-prop-features=10372. In contract, you may have a page focussed on Chenin Blanc producers where you do not want the user to break out to other wine varieties – in this case you would use data-prop-fixed-features=10046. From the user’s perspective they will see that the active filter for Chenin Blanc does not have a small “x” for removing the filter.

A full list of the data-props is included as Appendix D of this document. The most critical and often-used data-props are as follows:

Common Data Props


M = Mandatory; I = Sets initial state; F = Fixes state

Note 1 – Region ID and Type ID

To find the values for Region ID and Type ID you should first go to https://scoop.com.au and use the Region and Listing Type dropdowns in the widget to make a selection for region and listing type. You will note that the region dropdown is hierarchical.

Once you have your selections for region and listing type then reference the following JSON file: https://scoopapiprod.azurewebsites.net/api/getMetadata?license=10245

Note that the region values in this JSON file are in a flat, non-hierarchical structure. Search the JSON file for your selected region and then use its corresponding textURLAlias value for the data-region. As an example, if you wish to use the region known as “Margaret River Region” then the textURLAlias value in the JSON file will be “Margaret-River-Wine-Region”, and you would specify the following in the widget snippet:

data-prop-region=”Margaret-River-Wine-Region”

Note that the listing type values in this JSON file are also in a flat, non-hierarchical structure. Search the JSON file for your selected listing type and then use its corresponding txtListingTypeSEO value for the data-prop-type. As an example, if you wish to use the listing type known as “Things To Do” then the txtListingTypeSEO value in the JSON file will be “Attractions”, and you would specify the following in the widget snippet:

data-prop-type=”Attractions”

Note 2 – Feature ID and Category ID

To find the values for Feature ID or Category ID you should first go to https://scoop.com.au and use the filter dropdowns in the widget to make selections. You will need to be familiar with the Chrome browser inspect tool to find the corresponding ID values.

As an example, if you wish to find the Feature ID for the Events “Film” filter you would look at the DOM and see that the value is 10372:

That being the case you would specify the following in the widget snippet:

data-prop-features=”10372″

or possibly

data-prop-fixed-features=”10372″

Note that it only makes sense to use a features data-prop when that feature has an “ALL” value. Please get in touch to discuss further.

As another example, if you wish to find the Category ID for the Events “Indoor Films” filter value you would look at the DOM and see that the value is 18267:

That being the case you would specify the following in the widget snippet:

data-prop-categories=”18267″

or possibly

data-prop-fixed-categories=”18267″

Note 3 – URL Writing

The widget is capable of updating the page URL to reflect the selections made by the user. In doing so, the user can share a link directly to their selections meaning that the person using the shared link will be returned to the page with the widget in the same state as when shared. If this function is not enabled then the share links will be back to the same page but with the widget in its default state.

To enable the URL writing function of the widget specify the following in the widget snippet:

data-prop-url-write=”true”

There are two methods available for the way in which the URL is written:

Simple – this method utilises URL query parameters appended to the default page URL. In doing so it should not impact your website page flow. As an example, the following URL might be generated for wineries in the Margaret River region that produce Cabernet:

http://example.com/?region=margaret-river-wine-region&type=wineries&categories=10036

Complex – this method utilises URL rewriting to incorporate segments of your page URL in the Region and Listing Type properties of the widget. URL rewriting is very complex and should not be undertaken lightly. If you feel that your site would benefit from this method please get in touch to discuss further. Refer to this article for further information on URL rewriting – https://www.smashingmagazine.com/2011/11/introduction-to-url-rewriting/.

Step 3 – Add Smartlinks (optional)

Smartlinks are HTML links that are placed adjacent to the widget that, when clicked, update the widget to a different state. Typically smartlinks are placed above the widget as follows:

Appendix A – Listicles

A listicle is a collection of listings that you wish to show in the grid/map at the same time, often of different listing types. Your winery client, for example, may wish to show restaurant, brewery and gallery recommendations for their local area – a great way to undertake destination promotion.

By default the widget shows listings for a given listing type so if the listings you are wanting to collect together are of different types you should use listicles. Note that the feature/category filters will not display when the grid is showing listings of different types, because features/categories are listing type dependent.

Listicles can be used via the widget data-props to set the initial state of the widget on the page. It is more common, however, for listicles to be used via smartlinks – the user clicks a smartlink titled “Our favourite things to do nearby” and the widget displays a group of selected listings.

To create a listicle you use the favourites functionality of the widget:

  • Make sure that you are using the widget on the page where the listicle will be used
  • Clear out all current favourites
  • Use the widget to favourite each of the selected listings
  • When finished, go into favourites mode and you should see your selected listings
  • Use the favourite sharing function, specifically the email sharing option, to generate a widget share link (URL)

Once you have the widget share link for your listicle then you may use that link as a smartlink. If, instead, you intend to setup widget data-props then you may map the various URL query parameters to the relevant data-props.

To create another listicle then repeat the process above.

Often a listicle will simply be a collection of similar listings, for example “Top 10 Ice Creameries in Perth” or “Best Diving Spots in Western Australia”. In these cases it would not be common to link these listings together using a trail because they may be geographically spread.

In other cases the listicle may be highly suited to a trail, for example a regional hotel that may want to create a series of day trips. Setting up a trail is similar to creating a listicle except that the listings are viewed on the map and the trail has additional trail-specific attributes – see Appendix B for further details.

Appendix B – Trails

A trail is a collection of listings that you wish to show on the map at the same time, each listing displayed as part of a journey/trip. Your hotel client, for example, may wish to show day trip idea for their local area – a great way to undertake destination promotion.

To create a trail you use the favourites functionality of the widget, similar to how a listicle is created (see Appendix A):

  • Make sure that you are using the widget on the page where the trail will be used
  • Clear out all current favourites
  • Use the widget to favourite each of the selected listings
  • When finished, go into favourites mode and map view and you should see your selected listings on the map, with a trail panel on the left side
  • Adjust the trail attributes as required
  • Use the favourite sharing function, specifically the email sharing option, to generate a widget share link (URL)

Once you have the widget share link for your trail then you may use that link as a smartlink. If, instead, you intend to setup widget data-props then you may map the various URL query parameters to the relevant data-props.

To create another trail then repeat the process above.

Appendix D – Widget Caching

The widget content is cached on the Scoop server for 12 hours, for performance reasons. The first request served by the widget after the cache has expired will trigger an update of the content in the cache. This means that the person who triggered that request may experience a one-off delay of up to 10 seconds. Every person in the next 12 hour period will get cached content.

To help alleviate this issue it is possible to use a free service like Uptime Robot to regularly trigger a cache hit, say every hour. To find the URL for the cache hit you should use the Network tab of Google Chrome inspect tools and search for “getListings” – this is the URL that you can use within Uptime Robot. Contact Scoop should you require further details.

Appendix D – Data Props

The full list of widget data-props is as follows:

Data Props


M = Mandatory; I = Sets initial state; F = Fixes state

Join Scoop Club

Receive info on the best events in WA to your inbox weekly, plus exclusive invitations, special offers and more.

Email
First Name
Last Name

Interests

  Gig Guide  Galleries & Museums
  Food & Wine  Jazz Rhythm & Blues
  Popular Music  Classical Music
  Theatre & Dance  Business & Political
  Film  Kids & Family
  Sports  Literature
Select your preferences above so we can update you with news on things you love most.
 
Subscribe today and you could win – one lucky new subscriber is rewarded every week!
 

SCOOP