中文
Select Page

Widget Documentation

Introduction

Our mission is to build the world’s most sophisticated community-based content distribution network and develop Perth and WA as a regional hub for arts, events, culture and travel.

The Scoop website (https://scoop.com.au/) already represents more than 1,000 local galleries, museums, theatres, arts, event and community organisations and at any given time profiles 500 to 1000 events online. The Scoop website also showcases the state’s largest online travel guide, representing more than 3,500 lifestyle and travel businesses in Perth and regional WA. Listings are free and content is centrally quality-controlled by the Scoop Content Team, providing the arts and events community with free access to the audience they need to be a success.

The Scoop Listing Widget (“Widget”) is a web component that can be embedded on any web page in order to display listings content from the Scoop content distribution network.

Architecture

The listing content is stored in an secure, enterprise database hosted on the leading Microsoft Azure platform. This allows us to monitor and scale performance to ensure that listing content is delivered as fast as possible.

The widget has been developed using the modern and popular React framework. React is a declarative, efficient, and flexible JavaScript library for building user interfaces. It lets us compose complex UIs from small and isolated pieces of code called “components”. React is developed by Facebook and has a very active user community.

The widget communicates with the backend server using the standard HTTPS protocol.

Content

The Widget displays listings from the Scoop content distribution network. Each listing may contain a large number of descriptive elements including the following:

  • Listing Name
  • Listing Type (Events, Attractions, Accommodation, Galleries, Bars & Restaurants etc)
  • Short Description
  • Long Description
  • Event Dates (for Events listings only)
  • Images and Videos
  • Features and Categories – various descriptive items that are specific to the listing type
  • Contact Details
  • Location Details, including precise map positioning
  • Related Events
  • Related Listings

User Interface

The standard user interface for the Widget is a grid layout, showing multiple listings that meet the search criteria. Note that in the diagram below the vertical bar on the left side is for explanatory purposes only.

The major elements of the standard layout are as follows:

Element
AThis is the WIDGET TITLE that displays the WHAT value at the top of the widget. The value is updated by the widget as the WHAT value is changed. A widget data-prop can be used to disable the display of the WIDGET TITLE.
BThese are 3 the PRIMARY FILTERS that can be used to filter the listings: [1] the WHERE filter that can be used to filter the listings by location, [2] the WHAT filter that can be used to filter the listings by type, and [3] the KEYWORD filter that can be used to filter the listings by text. Note that the primary filters will dictate which secondary filters are displayed.
CThese are the SECONDARY FILTERS that can also be used to filter the listings. Note that the secondary filters that display are dictated by the values of the primary filters. Note also that, in certain circumstances, secondary filters may disappear or be disabled when zero listing counts would result.
DThis is the grid top bar that provides functions for swapping view (Grid and Map) and swapping language (English and Chinese), and displays the number of listings that match the search criteria.
EThis is the first row of listings that meet the search criteria. In the example above note that the active listing is highlighted with a dark grey background.
FThis shows a specific listing in QUICKVIEW. When a specific listing is clicked that listing will become active and be displayed in the quickview format. In the quickview format further detail is displayed for the listing, including details made visible by clicking on the Brief, Details and Contact tabs.
GThese are the remaining rows of listings that meet the search criteria. Paging controls at the bottom of the grid can be used to move between pages.

The widget can be changed from the grid view to the map view. In the map view the listings are plotted on an interactive map. The listings on the map can be popped open by a click.

Authentication

The widget must be supplied with a DATABASE LICENSE key in order for it to operate. This key is specific to each widget installation and can only be supplied by Scoop. The key also dictates which locations and listing types will be available via the widget.

Embedding

The widget is very easily embedded on a web page, through the use of [1] a simple Javascript tag, [2] some basic DIV tags, and [3] a jQuery function.

[1] This javascript tag links in the widget javascript file. Note that the src attribute shown below is indicative only – the correct src attribute will be supplied by Scoop.

1
<script type="text/javascript" src="https://widget/widget.js"></script>

[2] These DIV tags are used by the widget to (a) position itself on the web page. The data-props in the 3rd DIV inform the widget of certain parameter values – these data-props should be updated each time the widget is used, to influence widget behaviour and appearance. The various parameters are discussed in the following section.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
<div class="sc-container">
 
 
<div id="sc-widget-target">
 
 
<div id="widgetProps" data-component="SCListings" data-prop-server="dev" data-prop-url-write="false" data-prop-url-stem="/blah/" data-prop-license="blah" data-prop-region="blah" data-prop-type="blah">
</div>
 
 
</div>
 
 
</div>

[3] This jQuery function forces the widget to initiate/render itself on the web page. Note that it may be possible to replace the jQuery ready function with something different such as pure javascript.

1
2
3
4
5
<script type="text/javascript">
jQuery(document).ready(function() {
   window.updateHabitat();
});
</script>

 

Properties

The widget accepts a number of data-props that influence widget behaviour and appearance:

Data Prop
data-prop-licenseMandatory
Single
The database license key required by the widget – this will be supplied by Scoop at licensing time.
data-prop-regionMandatory
Single
The region code required by the widget, which dictates the starting location for the WHERE dropdown. Region codes can be supplied by Scoop.
data-prop-typeMandatory
Single
The listing type code required by the widget, which dictates the starting location for the WHAT dropdown. Listing type codes can be supplied by Scoop.
data-prop-listingOptional
Single
The listing code for a specific listing, should it be intended that the widget starts with showing a listing in quickview. Listing codes can be supplied by Scoop.
data-prop-fromOptional
Single
A from date that can be used to filter Events listings. This can be either a specific date or the following literals: TODAY, TOMORROW, WEEKEND, NEXT10 or NEXT30.
data-prop-toOptional
Single
A to date that can be used to filter Events listings. This can be either a specific date or the following literals: TODAY, TOMORROW, WEEKEND, NEXT10 or NEXT30.
data-prop-featuresOptional
Multiple, comma-delimited
A list of feature codes that can be used to filter listings. Feature codes are tied to specific listing types and are represented in the widget by the dropdowns. Feature codes can be supplied by Scoop.
data-prop-fixed-featuresOptional
Multiple, comma-delimited
A list of feature codes that can be used to filter listings. Feature codes are tied to specific listing types and are represented in the widget by the dropdowns. These “fixed” features cannot be overridden by the end user. Feature codes can be supplied by Scoop.
data-prop-categoriesOptional
Multiple, comma-delimited
A list of category codes that can be used to filter listings. Category codes are tied to specific listing types and are represented in the widget by the values in the feature dropdowns. Category codes can be supplied by Scoop.
data-prop-fixed-categoriesOptional
Multiple, comma-delimited
A list of category codes that can be used to filter listings. Category codes are tied to specific listing types and are represented in the widget by the values in the feature dropdowns. These “fixed” categories cannot be overridden by the end user. Category codes can be supplied by Scoop.
data-prop-keywordsOptional
Multiple, space delimited
A series of keywords that can be used to filter listings. The listing title and descrioption will be searched.
data-prop-url-writeMandatory
Single
A TRUE or FALSE to indicate whether or not the widget should update the browser URL as the widget conditions change.
data-prop-url-stemOptional
Single
Used in conjunction with the data-prop-url-write to indicate to the widget what the baseline URL stem is for the current webpage. Any URL segments or query strings added to the URL by the widget will be added after this URL stem.
data-prop-url-typeOptional
Single
Must be one of two values: (i) SIMPLE which means that the deeplinking will only use URL query strings, or (ii) COMPLEX which means that the deeplinking will use URL segments for the WHERE and WHAT and will use URL query strings for everything else. Only takes effect if the data-prop-url-write is set to true.
data-prop-cacheOptional
Single
A TRUE or FALSE to indicate whether or not the widget should make use of the server-side caching . This should generally be set to TRUE unless instructed by Scoop.
data-prop-layoutOptional
Single
A GRID or MAP to indicate to the widget which layout should be used at startup.
data-prop-hide-search-titleOptional
Single
A TRUE or FALSE to indicate to the widget whether or not the Widget Title should be displayed.

The Embedding section above provides an example of how data-props are provided to the widget.

URL Integration

It is also possible to pass data-prop values to the widget via the browser URL, provided the data-prop-url-write is set to TRUE.

If the data-prop-url-type is set to COMPLEX then the data-prop-region and data-prop-type are supplied to the widget via the final 2 URL segments, and all remaining values are passed as URL query strings. If the data-prop-url-type is set to SIMPLE then all values are passed as URL query strings.

Query strings values must have the text “data-prop-” removed from the front of the data-prop name – for example rather than data-prop-categories=”12345″ you would use categories=”12345″.

The following is an example of data-props being supplied to the widget via the URL using the COMPLEX method:

https://mydomain.com.au/mypage/western-australia/events?categories=12345

In this example the value “western-australia” is the data-prop-region, the value “events” is the data-prop-type and the value “12345” is the data-prop-categories.

The following is an example of the same data-props being supplied to the widget via the URL using the SIMPLE method:

https://mydomain.com.au/mypage?region=western-australia&type=events&categories=12345

In this example the value “western-australia” is the data-prop-region, the value “events” is the data-prop-type and the value “12345” is the data-prop-categories.

Styling

The widget renders itself in to the host webpage as standard HTML (with associated CSS). While the overall structure of the widget cannot be significantly altered, virtually all visual components can be styled via CSS to suit the specific client requirements. Where possible the widget should pick up much of the styling of the host website.

Scoop can provide a basic CSS template that can be used and altered as required.

Assistance

Please contact Scoop should you require any assistance or have any questions regarding any aspect of the widget, including database licensing, widget configuration and data-prop codes.

Phone: +61 8 62800068
Email: [email protected]

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 [signup-promo-text] – one lucky new subscriber is rewarded every week!
 
SCOOP