Upcoming Events
The Upcoming Events javascript control (widget) can be used to produce a list of events for displaying on your website. Using the attributes associated with an event, you can configure the control to display these attributes any way you like. A common use of this list is as a widget on the homepage of your website to promote your upcoming trainings or events, showing the event's name and the date it runs.
The list can be a general one of all your upcoming events, or it can be configured to show only specific events based on configuration options, such as a set of filters.
This article will guide you through integrating a JavaScript control that will call the API and render a list of events according to your configuration options, template, and CSS.
Contents
- Getting Started
- Code Editor Example
- Control Configuration
- Custom Templates
- Template Helpers
- Sub Controls
- Pairing with Filter control
Getting Started
The following code block contains a simple example of all the elements necessary to create an Upcoming Events control on your webpage.
Based on the general getting started guide.
<div id="upcoming-events-control"></div>
<script src="//connect.arlocdn.net/jscontrols/1.0/init.js" charset="utf-8" defer="defer"></script>
<script id="upcoming-events-control-template" type="text/html">
<%= Name %>
</script>
<script>
document.addEventListener("arlojscontrolsloaded", function () {
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
targetElement: "#upcoming-events-control",
maxCount: 5,
template: "#upcoming-events-control-template"
};
new ArloWebControls().start({
"platformID": "demo.arlo.co",
"modules": [
upcomingEventsControl
]});
});
</script>
Explanation of the example configuration above:
- Define a container for an upcoming events control.
- Load the Arlo JS Controls application code onto the page
-
Define a configuration for an upcoming events control (
moduleType: "UpcomingEvents") that will display 5 events (maxCount: 5). This control will be displayed in the DOM element with id#upcoming-events-controland rendered using the template in the script element with id#upcoming-events-control-template. - Start the application, specifying a platform ID of "
demo", and the Upcoming Event Control configuration.
Code Editor Example
For an explanation about the demo control code editors and how you can integrate these demos into your own page, click here.
Complex Control
See the Pen Upcoming Events All In One by Arlo Software Ltd. (arlosoftware) on CodePen.
Basic Control
See the Pen Upcoming Events Simple by Arlo Software Ltd. (arlosoftware) on CodePen.
Upcoming Event Control Configuration
To create an upcoming events control, you should use a moduleType value of "UpcomingEvents".
Example: moduleType: "UpcomingEvents"
The upcoming events control has the following config options, as well as the shared configuration options.
| Field | Type | Default | Description |
|---|---|---|---|
| eventFullMessage | string | "Event Full" |
This option allows you to set the message that will be displayed when an event is full. |
| queryStringConfig | array |
Allows you to specify that the control should look for the 'event' query string value in order to configure itself. If the query string is found when the page loads, the control will be filtered by the event ID assigned to the query string. This means the list will only contain one result. Example: queryStringConfig: ["event"]
|
Filters
The available filters for the upcoming event control can be found here, in the API documentation.
For more information on how to use these filters to configure a control, click here.
Table of Customisable URLs
The following URL data fields can be customised. See custom urls for further information. 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.
| Property Key | Affected event data field |
|---|---|
| eventtemplate | ViewUri |
| venue | Location.ViewUri |
| presenter | Presenters - each presenter objects ViewUri |
Upcoming Event - Full Configuration Example
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
targetElement: "upcoming-events-control",
maxCount: 5,
template: "upcoming-events-control-template",
eventFullMessage: "Registration Limit Reached",
filterId: "eventFilter",
callbacks: {
onBeforeRender: function(eventData, jQuery){//Do something with eventData},
onShow: function(getEventListItemsFunction, jQuery){//Do something with list item elements}
},
customUrls: {
eventtemplate: "http://example.com/eventtemplatepage.html",
presenter: "http://example.com/presenterpage.html",
venue: "http://example.com/venuepage.html"
}
};
<script id="upcoming-events-control-template" type="text/html">
<%= Name %>
</script>
Custom Templates
You can write a custom template for your control using HTML combined with the Underscore library templating system.. See the general template guide for more information.
Available template properties
From API
| Field | Description |
|---|---|
| Name | A string representing the name of the template associated with this event, up to 128 characters long. Field from the EventTemplate. |
| Code |
A string representing the short code used when referring to this event, up to 32 characters long.
By default this value is based off the EventTemplate Code with a unique
integer ID appended. For example, MGMT101-001 for the first Event instance based off a template with code MGMT101.
|
| Summary | A string representing a short plain text one-line or one-paragraph summary of this event, suitable for display in lists and search results. If the summary is blank, this field will be omitted. Field from the EventTemplate. |
| Description |
A structure containing marked-up text representing the description for this event used in sitations that require the event's full HTML content. This field is not suitable for display in lists and can contain arbitrary HTML including
tables, lists and images.
Field from the EventTemplate.
Structure fields
|
| StartDateTime |
A DateTimeOffset value indicating when this event starts.
The value of this field can be formatted using the formatDate() template helper. See template helpers section below for more details.
|
| EndDateTime |
A DateTimeOffset value indicating when this event ends.
Like StartDateTime, this field can be formatted using the formatDate() template helper. See template helpers section below for more details.
|
| TimeZoneID | An integer value that identifies the time zone of this event. |
| TimeZone |
A string containing the time zone abbreviation (3-5 characters) to use when expressing the full time zone of this event, such as AEST or NZDT.
|
| Location |
A structure containing locality information for the event, including a display description of the location, the name and physical address of the venue, and map coordinates (if available).
Structure fields
|
| PlacesRemaining |
Integer value indicating the number of registration spaces available for the event. Note this value is often null
unless administrators have specifically enabled it, and it may contain a value only when the spaces available drops
below a predefined threshold such as 5 or 10 remaining spots. The purpose of this field is to promote events that are nearly full.
|
| AdvertisedOffers | An array of AdvertisedOffer structures representing all promoted offers (pricing) for the event, including base offers and discounts (if any). |
| Presenters |
A list of presenters associated with this event. This field can be displayed by using the formatPresenters() template helper. See template helpers section below for more details.
If the event has no presenter, this field will be omitted.
Structure fields
|
| Notice |
A string with a short note to be shown with the date in lists. This field is usually reserved for special notices that apply to one date in a list but not others such as For registered members only. If the event has no value for this field, it will be omitted.
|
| RegistrationInfo |
A structure containing information about registration for this event. This field can be displayed by using the formatRegistrationInfo() template helper. See template helpers section below for more details.Structure fields
Important notes
|
| Provider |
A structure representing information about a custom organizer managing this event. This field can have a value if Arlo is accepting registrations for an event run by an outside party who want their details promoted with the event in lists.
This field can be displayed by using the formatProviders() template helper. See template helpers section below for more details.Structure fields
|
Generated fields
| Field | Description |
|---|---|
| Duration | The length of time the event runs for. The unit of measurement is dynamic and adjusted depending on the length of the event. For example it could display '4 hours', for a four hour event within one day or '3 days' if the event takes place over a 3 day period. |
| DurationDescription | Displays the event duration, followed by timespan (startdatetime to enddate time). E.g. 3 weeks, 1:00 PM - 4:00 PM |
| DurationWithTimeSpan | Timespan followed by the duration between the two times. E.g. 9:00AM - 5:30PM (8.5 hours) |
| DateSpan |
Field changes depending on the date range the event spans. Automatically generated based on the dates spanned by the event's start and end datetimes.
Examples of how dates are formatted based on the span.
|
| Credits | An unordered list of credits created from the credits object in the API results. |
| EventFullMessage |
If the event is not full, the value will be and empty string, otherwise it will display "Event Full" by default.
This default can be changed by configuring the control with a eventFullMessage. E.g. eventFullMessage: "Full"
|
Template Helpers
Beside the global template helpers, the following template helpers are also available in your upcoming event templates.
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 complicated code.
| Helper Function | Field(s) | Type | Description |
|---|---|---|---|
| formatRegistrationInfo(format) | RegistrationInfo | string |
Allows you to specify how the registration info/link should be displayed. You have three options for the format.Formats
If the RegistrationInfo field from the API does not contain the ViewUri property used for generating the link/button, it will default to plain text. Example: <%= formatRegistrationInfo("link") %>
|
| formatAdvertisedOffers(config) | AdvertisedOffers | string |
Advertised offers is a collection of structures representing the offers (or prices) for the event.
This view helpers provides you with a means of choosing how to display this information.
It has many configuration options to offer full flexibility of the information displayed, but each option has sensible defaults
so you do not have to specify them all.
Example: <%= formatAdvertisedOffers({ showPriceWithTaxInclusive: true, showSingleOffer: false, showLabel: true, showCurrencyCode: true, showMessage: true, showTaxRate: true }) %>
|
| formatSessionsInformation(config) | Sessions | string |
This field is a collection of structures representing the sessions associated with an event, provided it is a multi-session event.
Like the event itself, each session has a set of fields associated with it. You can choose which fields to display using the fields
config option (and array). You can also choose to show the associated advertisedOffers of the sessions.
Example: <%= formatSessionsInformation({ fieldsToDisplay: ["Name", "AdvertisedOffers"], advertisedOffersConfig: {freeText:"Free", showTaxRate: false} }) %>
|
Sub Control Helpers
Additional information helpers allow you to embed information from other resources into your templates. See general sub controls documentation for more information
| Resource(s) | Helper Function | Description |
|---|---|---|
| Events | showOtherRunningTimes(config) |
Allows you to display the other running times of an event.
Example: <%= showOtherRunningTimes({message:"Click here to show other running times of this event", template:"#other-running-times-template"}) %>
|
| Presenters | showPresenterProfiles(config) |
Allows you to display the profiles of the presenters for the event.
Example: <%= showPresenterProfiles({message:"Click here to show the profiles for this events presenters", template:"#presenter-profiles-template"}) %>
|
| Event Template | showEventTemplateInformation(config) |
Allows you to display the information from the events template.
Example: <%= showEventTemplateInformation({message:"Click here to show this events templates information", template:"#eventtemplate-template"}) %>
|
| Venues | showVenueInformation(config) |
Allows you to display more detailed information about the venue for this event.
Example: <%= showVenueInformation({message:"Click here to show more detailed venue information", template:"#venues-template"}) %>
|
Upcoming Event Paired with Filter Control
To create an event list with dynamic, user configurable filters (using html selects, checkboxes etc) you can combine your events list with a filters control. Filters are page controls that allow you to filter the list based on various data properties.
Live Example
When filters are applied, they will update the url to reflect the current filter state. The resulting url will load the page with filters applied (for bookmarking or sending url to others). You can have multiple filter controls on the same page which could be listened to by one or more list controls.
In order to filter to your events list, you should provide an additional filter control configuration. In this configuration, you will
define a unique filterControlId property. You will then define the same property in the event list configuration to tell it which filter control to listen to.
Below are step by step instrutions for pairing an events list control with a filter control.
Step 1
You have an events list configured with a filterControlId. Important: The filterControlId must contain no spaces and only alphanumeric characters.
var upcomingEventsControl = {
moduleType: "UpcomingEvents",
targetElement: "#upcoming-events-control",
maxCount: 5,
filterControlId: "myFilter",
template: "#upcoming-events-template"
};
Step 2
Now you should add an additional filter control configuration, configured using the same filterControlId.
At this point you should have exactly the same result as in step 1.
var filterControl = {
moduleType: "Filters",
targetElement: "#filters",
template: "#filter-template",
filterControlId: "myFilter"
};
Step 3
Now you can use the filter view helpers to configure and place your filters inside the filters template. You can, of course, use arbirary HTML here to add additional elements.
<script type='text/template' id='filter-template'>
<%= showFilter({filterCode: "locname"}) %>
<%= showFilter({filterCode: "templatecategory",
config:{top:10, orderby: "count"},
displayStyle: "ul",
callbacks:{onBeforeRender: "beforeFilterRender",
onRender: "afterFilterRender"} }) %>
<br />
</script>
Please view the filter documentation for a thorough guide on how to configure filters.