Arlo Web Controls
The Arlo Web Controls allows you to create a range of dynamic controls (aka widgets) for displaying event and training related data on your website. It works by providing a simple control definition and templating system that integrates with the Arlo API.
The javascript application offers a range of functionality:
- Creating controls to display your data in your webpages.
- Fetching data for you platform from the Arlo API.
- Processing data into more usable formats, with generated fields and template helpers.
- Paging data.
- Providing a templating system which allows you to control what data to display and how to display it
- Providing you with opportunities perform addtional processing on the data/rendered html.
- Creating controls that display data from multiple resources with sub controls
It has been designed to reduce the complexity of achieving this as much as possible, to allow you to simply decide what data to display, and where and how to display it. While the simpler features of the application can be used by developers with minimal experience, it also offers a range of advanced features which give the more experienced developer a significant amount of flexibility to create more complicated widgets.
Arlo Web Controls can be used to create widgets of the following types:
- Upcoming events list
- Event template
- Online activities list
- Category list
- Venue or venue list
- Presenter or presenter list
- Event Template
- Event Template Catalogue
- Filters
- Region Selector
- Internationalisation
CalendarControl
The separate ArloCalendarControl can be used to show the events in a calendar.
Contents
- Getting Started
- Code Editor Example
- Control Configuration
- Filters
- Control Callbacks
- Custom URLs
- Custom Templates
- Template Helpers
- Sub Controls
Getting Started
The following information explains the general process of adding simple controls to your page. This will be demonstrated with upcoming event controls.
Include Arlo Web Controls in your page
Download the Arlo Web Controls library loader and include it in your page, but we suggest you to just refer directly from our fast and reliable CDN.
<script src="https://connect.arlocdn.net/jscontrols/1.0/init.js" defer></script>
Please note that the script above contains the "defer" attribute, which makes sure that initialisation script loads before the init.js file
Add control containers to your HTML
Place elements on the page where you would like the controls to appear. For this example, we will add two controls (more than one control of the same type can be added to a page!).
These DOM elements should have id attribute that you will specify as the targetElement in your control configuration.
<div id="upcoming-events-control1"></div>
<div id="upcoming-events-control2"></div>
Add the Arlo Web Controls initialisation script
This is where you will specify the configuration options for each control, and start the application.
The initialisation script should only be run after the Arlo Web Controls library has fully loaded.
To do this, place your initialisation script code inside a document event handler called arlojscontrolsloaded.
document.addEventListener("arlojscontrolsloaded", function () {
//Your initialisation script code here
});
-
First you will specify configurations for each control that you want to add to the page.
-
Then you will create a new Arlo Web Controls application and start it, passing it your platform ID and an array containing your control configurations.
<script>
document.addEventListener("arlojscontrolsloaded", function () {
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
targetElement: "#upcoming-events-control1",
template: "#upcoming-events-control1-template",
customUrls: {
eventtemplate: "http://example.com/eventtemplatepage.html",
venue: "http://example.com/venue.html",
presenter: "http://example.com/presenter.html"
},
top: 5
};
var upcomingEventsControl2 = {
moduleType: "UpcomingEvents",
targetElement: "#upcoming-events-control2",
template: "#upcoming-events-control2-template",
customUrls: {
eventtemplate: "http://example.com/eventtemplatepage.html",
venue: "http://example.com/venue.html",
presenter: "http://example.com/presenter.html"
},
top: 10
};
new ArloWebControls().start({
"platformID": "demo.arlo.co",
"modules": [
upcomingEventsControl,
upcomingEventsControl2
]});
});
</script>
Explanation of the example configuration above:
-
Define a configuration for an upcoming events control/module (
moduleType: "UpcomingEvents") that will display 5 events (top: 5).
This control will be displayed in the DOM element with id#upcoming-events-control1.
It will look for a template in a script element with an id of#upcoming-events-control1-template. See provide a template. -
Define a configuration for a second upcoming events control/module (
moduleType: "UpcomingEvents") that will display 10 events (top: 10).
This control will be displayed in the DOM element with id#upcoming-events-control2.
It will look for a template in a script element with an id of#upcoming-events-control2-template. See provide a template. - Start the application, specifying a platform ID (
"demo"is the Arlo demo platform, you should specify your own), and the two Upcoming Events Control configurations specified previously.
Provide a template
Arlo Web Controls use a simple templating language provided by the Underscore javascript utility library.
You can provide a customisable template for each control using two different methods.
-
Provide the id of a template specified in a script tag in the HTML.
var upcomingEventsControl = { moduleType: "UpcomingEvents", targetElement: "#upcoming-events-control", top: 5, customUrls: { eventtemplate: "http://example.com/eventtemplatepage.html", venue: "http://example.com/venue.html", presenter: "http://example.com/presenter.html" }, template: "#upcoming-events-control-template" };<script id="upcoming-events-control-template" type="text/html"> <%= Name %> </script> -
Provide a string, or a function that returns a template string - this allows you to programmatically generate a template using javascript. The string or function return value should be a valid Underscore template.
var upcomingEventsControl = { moduleType: "UpcomingEvents", targetElement: "upcoming-events-control", top: 5, customUrls: { eventtemplate: "http://example.com/eventtemplatepage.html", venue: "http://example.com/venue.html", presenter: "http://example.com/presenter.html" }, template: function(){ return "<%= Name %>"; } }; var upcomingEventsControl = { moduleType: "UpcomingEvents", targetElement: "upcoming-events-control", top: 5, customUrls: { eventtemplate: "http://example.com/eventtemplatepage.html", venue: "http://example.com/venue.html", presenter: "http://example.com/presenter.html" }, template: "<%= Name %>" };
Starting the application
To load your controls, you must create a new ArloWebControls application and start using some initialisation configuration. The following table explains these configuration options.
| Configuration Option | Type | Description |
|---|---|---|
platformID |
string |
This property tells the application which Arlo Platform it should retrieve data for. Your platform name is your full domain name for your Arlo Platform. Copy the whole domain, but not the whole URL (for eg do not copy the http part and the slashes) platformID: YOUR_PLATFORM.arlo.co |
modules |
array | Here is where you pass control definition objects that the application will create for you. |
googleMapsAPIKey |
string |
The application has the capability of displaying google maps based on event venue location data.
To do this it requires a google maps API key, which will you need to acquire from here.
You need to enable the following Google Map APIs for your project:
|
showDevErrors |
boolean |
The application can offer some useful information when creating your control templates and configurations. Set this property to true to have the application log any errors to the console.
|
Full configuration example
<script>
new ArloWebControls().start({
"platformID": "demo.arlo.co",
"googleMapsAPIKey": "apikeyacquiredfromgoogle",
"showDevErrors": true,
"modules": [
upcomingEventsControl,
upcomingEventsControl2
]});
});
</script>
Code Editor Examples
The editors on the documentation pages for the different controls allow you to view and modify the template/css and javascript used to create the demo controls seen at the start of each pages documentation page. You can modify the code to fine tune the control to your needs. You can then take this code and add it to your own page to use this control with your own platform. Heres how:
-
The HTML
- Copy the css and font file links into the <head></head> of your page.
- Copy the element with class 'arlo' (and the elements within) below the external resources the HTML section to where you would like the control to appear on your page.
- Copy the template scripts, Arlo Web Controls script, and any external scripts to the bottom of your HTML page, before the </body> closing tag.
-
The CSS
- Copy the code in the CSS section into a <style></style> tag on your page. Or save it to a file in your webserver and link to that file.
-
The Javascript
- Copy the code in the javascript section into a <script></script> tag at the bottom of you HTML page, before the </body> closing tag.
Control Configuration
The following configuration options apply to all control types that the Arlo Web Controls application can produce. More specific control configuration options can be found on the control type specific documentation pages.
General Control Configuration Options Table
| Field | Type | Default | Description |
|---|---|---|---|
| moduleType | string | The type of control to create. Example: For an Upcoming Events control, we specify moduleType: "UpcomingEvents". |
|
| targetElement | string | The id of the DOM element that the control will be displayed in. Example: targetElement: "#my-control" |
|
| maxCount | number | 10 | The number of results to display. Example: maxCount: 5 |
| template | string/function |
The template used to render the control. Can be a javascript function or the id of the script tag containing the template.
See 'Provide a template' for more information. Example: template: "#my-control-template"
|
|
| includeLoadMoreButton | boolean |
Specifying this option allows you to provide a button that loads more data for your controls (paging). It will load the next X results, where X is the value of the maxCount configuration variable (which defaults to 10).Example: includeLoadMoreButton: true
|
|
| loadMoreButtonText | string |
Specifying this option allows you to customize the text of the button that loads more data for your controls (paging). The value for this option will be the label of the button. Example: loadMoreButtonText: "Load More"
|
|
| callbacks | string | This options lets you provide callbacks to perform additional processing at various stages of the event control life cycle. See the control callbacks section for more information. | |
| customUrls | string | Certain properties in the event data contain urls to where more information can be found. This property allows you to override this value to point to a url of another page containing an ArloJSControls control that will load and display this information from the API. See the custom urls section for furthur explanation and examples. | |
| filter | object |
The filter configuration property allows you to provide an object with key/value pairs that will used to apply filters to the control. See the filter configuration section for further information. |
|
| noResultsText | string | "No Results Found" |
When the api returns no results for a control, it will show a no results found message. This option allows you to customise the text for that message. You can also set some custom HTML to render instead. Example: noResultsText: "<img src='no-results.jpg' />"
|
| type | string | "list" |
A control can display its list items (e.g. events) as either a "list" or a "table".This results in producing either a HTML unordered list or table. You can also set some custom HTML to render instead. Example: type: "table"
|
| tableHeaders | array |
If you configure your control type to be "table", then you can use this configuration option to provide table headers.You should pass an array of strings, each representing a table header element. The headers will be ordered according to their position in the array. Example: tableHeaders: ["Name", "Summary", "Cost"]
|
|
| requestConfig | object |
Allows you to override a few of the api request ajax options.Options
requestTimeout: { cache: false, requestTimeout: 5000 }
|
|
| endRequest | function | Allows you to run a function at the end of the control's API call. |
Filter Configuration
This configuration option allows you to filter the collection of data rendered by a control.
To use this feature you should provide a filter property in the control configuration whose value is an object with key/value pairs representing the filters.
The available key/value pairs depend on the control you are configuring. You can view the API documents to find available filters for a controls' resource type.
Note: These values can be overriden if:
- If an upcoming events control is paired with a filter control
- If a control is configured by a querystring
For most filters, you may provide either a single value or an array of values to filter the control data by.
The example below demonstrates the use of filters with numbers, strings and arrays as values. It will return events with IDs 1, 2, 4, 7, or 8, which are tagged with Popular, are based on Template 43, and are located in Auckland, Sydney, or Wellington.
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
template: "upcoming-events-control-template",
targetElement: "#upcoming-events-control",
customUrls: {
eventtemplate: "http://example.com/eventtemplatepage.html",
venue: "http://example.com/venue.html",
presenter: "http://example.com/presenter.html"
},
filter: {
eventID: [1,2,4,7,8],
tag: "Popular",
templatecategoryid: 43,
locname: ["Auckland", "Sydney", "Wellington"]
}
}
};
Control Callbacks
Control callbacks give the developer an opportunity to perform additional processing on the data used by the control or the DOM elements produced by the control. These callbacks can be defined directly in the callback function, refer to an external function (see onShow example, below) or be a string containing the name of a global function (on the window object). The following information discusses the callbacks that you can use and gives examples of how you may want to use them.
Available callbacks
onBeforeRender
The onBeforeRender callback allows you to perform additional processing on the data returned by the API before it is combined with the template to render the control. For example, you may wish to create a new placeholder that you can add to your template.
You should provide a function to be used as a callback. The function will recieve two parameters: the first is the data used to render the template and the second is a reference to the jQuery library. jQuery is exposed as a parameter to make writing your callback easier. The jQuery passed is an isolated version (1.12.4 currently). To use jQuery with any external plugin, such as Bootstrap, you will need to load jQuery and the plugin separately on your page and skip the second argument of the callback function. Then the callback function will use the globally scoped jQuery that has your plugin attached.
The following control configuration example demonstrates using this callback to create a new field called NameAndCode for an Upcoming Events list.
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
template: "#upcoming-events-control-template",
targetElement: "#upcoming-events-control",
customUrls: {
eventtemplate: "http://example.com/eventtemplatepage.html",
venue: "http://example.com/venue.html",
presenter: "http://example.com/presenter.html"
},
callbacks: {
onBeforeRender: function(eventData, jQuery){
eventData.NameAndCode = eventData.Name + "-" + eventData.Code;
}
}
};
This could then be used inside the template as follows
<script id="upcoming-events-control-template" type="text/html">
<%= NameAndCode %>
//Rest of template...
</script>
onShow
The onShow callback allows you to perform additional processing/manipulation on the controls' DOM elements produced after the control is rendered in the browser.
The possibilities are endless here. For an example, you may wish to add a button to each listitem that will collapse/uncollapse the item.
You can achieve this with some jQuery programming. The onShow callback guarantees that the DOM elements are available for manipulation when this code is run.
These callbacks will also be applied when the list changes (E.g. a list filter is applied) or when more list items are added through pressing the controls' Load More button.
You should provide a function to be used as a callback. This callback function will recieve two parameters.
The first is a function that will return an array of listitem DOM elements, each produced by rendering the controls template using a model in the controls data collection.
The second is a reference to the jQuery library. jQuery is exposed as a parameter to make writing your callback easier (In this case can be used to manipulate the list elements). The jQuery passed is an isolated version (1.12.4 currently). To use jQuery with any external plugin, such as Bootstrap, you will need to load jQuery and the plugin separately on your page and skip the second argument of the callback function. Then the callback function will use the globally scoped jQuery that has your plugin attached.
The following control configuration example demonstrates using this callback to add a button that when clicked, removes the listitem from the list. The button would be positioned within the listitem using css.
function addCloseButton(getListItems, jQuery){
var listitems = getListItems();
jQuery.each(listitems, function(index, listitem){
var closeButton = jQuery('');
closeButton.click(function(){
jQuery(listitem).remove();
});
jQuery(listitem).append(closeButton);
});
}
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
template: "#upcoming-events-control-template",
targetElement: "#upcoming-events-control",
customUrls: {
eventtemplate: "http://example.com/eventtemplatepage.html",
venue: "http://example.com/venue.html",
presenter: "http://example.com/presenter.html"
},
callbacks: {
onShow: addCloseButton
}
}
};
Control Custom Urls
Certain properties in the event data contain urls to where more information can be found. This property allows you to override this value to point to a url of another page containing an ArloJSControls control that will load and display this information from the API.
To explain further, consider the following example: You would like the upcoming event items to contain a link to another page in your website that contains an ArloJSControls Event Template control. When that event template page is loaded, the control should be configured to display the full information for the selected event. ArloJSControls is designed to do this through the use of query parameters.
Each property in the customUrls object should contain a key representing the field you are creating a custom url for, and the URL of the page where the control for loading the additional information is loaded.
You must define all customUrls whether they are being used in the template or not. The system needs this to generate the correct URLs for rich snippets.
A table of customisable URLs can be found on each controls' documentation page.
The following will help explain this further.
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
template: "#upcoming-events-control-template",
targetElement: "#upcoming-events-control",
customUrls: {
eventtemplate: "http://example.com/eventtemplatepage.html",
venue: "http://example.com/venue.html",
presenter: "http://example.com/presenter.html"
}
}
};
In the example above, the control is configured to change the events' ViewUri, which would generally take the user to the event template page, to direct the user to http://example.com/eventtemplatepage.html instead.
This url will be customised (per event list item) with a querystring that will tell the javascript control on the target page which eventtemplate data to load. The querystring key will be the same as the customurl config key. The value will be a combination of the eventtemplateid and the event name, though the controller will use only the id to load the data.
Example of URL after applying querystring: http://example.com/eventtemplatepage.html?eventtemplate=11-Great-Event-Name
The control on eventtemplatepage.html will need to be configured to look for configuration options in the query string.
var eventTemplateDemo = {
moduleType: "EventTemplate",
targetElement: "#eventtemplate",
template: "#eventtemplate-template",
queryStringConfig: ["eventtemplate"]
};
Custom Templates
You can write a custom template for your control using HTML combined with the Underscore library templating system.
Writing a template
Templates represent the data for a single data object retrieved from the API. When a control deals with a collection of data objects, it will repeat the template for each data object in that collection.
For example, for an Upcoming Events control, the template will represent a single event, and will be repeated for each event returned by the API.
You can see in the HTML example below the use of property placeholders (interpolated values) using the UnderscoreJS format <%= PropertyName %>.
A full list of available properties can be found on the documentation page for each type of control.
You can also use our template helpers, which allow you to configure how these properties are displayed. A full list of template helpers can be found on the documentation page for each type of control.
These templates give you full control over assigning CSS classes to the HTML elements in your templates. This means you can write a CSS stylesheet with whichever names you choose and apply them in your templates.
The following template example (for an upcoming events list) contains a mix of standard HTML, simple property placeholders and the use of our 'template helpers'.
<div class="title">
<a href="<%= ViewUri %>"> <%= Name %> </a>
</div>
<div class="date">
<span>
<%= formatDate(StartDateTime, "ddd") %>
<%= formatDate(StartDateTime, "DD") %>
<%= formatDate(StartDateTime, "MMM") %>
</span>
</div>
<div class="details">
<span class="time"> </span>
<span class="location"> <%= Location.Name %></span>
<label>Presented By:</label> <%= formatPresenters(Presenters, "ul") %>
</div>
<div class="summary">
<h4>Summary</h4>
<div class="text"><%= Summary %></div>
</div>
<div class="register">
<%= formatRegistrationInfo(RegistrationInfo, "button") %>
</div>
Template Helpers
Template helpers are javascript functions that will perform one of two tasks; process non-simple data fields (such as collections) from the API, and output a HTML representation you can use in your templates, or create a subcontrol to display associated information from another API end point within the rendered template.
You will can use these inside your templates in a similar way to displaying properties, which you have seen previously.
Field Helpers
Field helpers will manipulate the resource data that comes from the API, making it easier to display the information you want in the way you want, without writing any additional code.
The following list contains the general helpers which can be applied in various types of controls. More specific helpers can be found on the specific control type documentation pages.
| Helper Function | Field(s) | Type | Description |
|---|---|---|---|
| formatDate(date, format) | StartDateTime, EndDateTime | dates |
Allows you to format a date. The formatting uses a library called MomentJS.
You can find details on how to write these formatting strings on the MomentJS website. Example: <%= formatDate(StartDateTime, "ddd") %>
|
| createMap(mapConfig) | Location, GeoData | object |
Allows you to embed a Google Maps (image), using the coordinate information of the events' venue. This will construct a map of the specified type that calls the Google Maps API.
The parameter is a simple javascript object that allows you to specify the type, width, height, and zoom settings for the map.
Map Types:
Example: <%= createMap({width: 200, height: 200, zoom: 16, type:'embed'}) %>
|
| formatCollection(collection, format, showLinks) | Presenters, Categories, Tags, TemplateTags | collections |
Allows you to format an event field which is a collection of items. You can choose to show the items in these collections as links,
provided they have the associated ViewUri property used for generating the link. You achieve this by passing true as the third paramter of this function (showLinks).Formats:
Example: <%= formatCollection(Categories, "ul", true) %>
|
Sub Control Helpers
Sub control helpers allow you to embed information from associated resources into your templates. It will create additional api requests based on the associated information you would like to display, and give you control over how to display it.
For each sub control, you will need to provide a configuration object. This object can contain the same configuration options you would usually use for creating a control of that type, as well as some that are specific to configuring it as a sub control.
Each sub control helper is created for a specific control type, so you will need to refer to the documentation for that control type for more information about its sub control options.
Sub control helpers can be configured with the following options:
message: The message to display before the additional information loads.template: The template used for displaying the other running times. Uses the same properties/helpers as the main controls (e.g. For other running times, you can write an UpcomingEvents template).-
targetElement: By default, the sub control will display in the location where it was defined. If you would like the control to load into a separate element, specify its selector using this property. The selector will be scoped to the item being rendered E.g.targetElement: ".presenterSubControl" -
showLoadButton: Whether to show a clickable button that will initiate the loading of the additional information sub control. If set to false, the button will still exist but be styled to 'display: none'. When hidden it is still possible to use it to load the control by using javascript to programmatically click it. Defaults to true. -
loadImmediately: When set to true, the additional information sub control will be loaded immediately with the rest of the event list. Be careful how many sub controls you configure to load immediately, as it will increase the list's loading time.
Example: Presenters sub control for upcoming events list
The following sub control (for upcoming events list) queries the presenters api endpoint to return presenters for each event. It then creates a presenter control (which will have its own template) that will be rendered inside the event list items.
It has been configured to display a clickable message which, when clicked, will load and render the sub control in place of the clickable message. It will render using the specified template, which you need to provide.
<script type='text/template' id='upcomingevent-template'>
<div class="title">
<a href="<%= ViewUri %>"> <%= Name %> </a>
</div>
<div class="presenters-subcontrol">
<%= showPresenterProfiles({message:"Click here to show the profiles for this events presenters",
template:"#presenter-profiles-template"}) %>
</div>
</script>
It would need to be accompanied by a template used to render the presenter data. To create a template for this sub control, you can refer to the documentation for that control type; in this case, the presenter control.
<script type='text/template' id='presenter-profiles-template'>
<div class="presenter-name">
<%= Name %>
</div>
</script>