Arlo

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

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(
                                        "plaformID": "demo",
                                        "controls": [
                                            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-control and 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
  • ContentType: String representing the content type of the description, usually application/xhtml.
  • Text: Text content of the description.
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
  • IsOnline: Boolean value indicating whether this event is an online (webinar) or venue-based event. This field is omitted if false, and is present only when the value is true.
  • Name: String display value describing the locality. By default this value is often the city of the venue, but may be customised to be any string such as state or suburb. This value is suitable for use in search results and lists where a description of the event's location is required.
  • VenueID: Integer value representing the ID of the venue associated with this event. This field is omitted when IsOnline is true.
  • VenueName: String representing the name of the venue where this event will run. This field is omitted when IsOnline is true.
  • VenueRoomName: String representing the name of the room where this event will run. This field is omitted when IsOnline is true, or where no room information is available.
  • StreetLine1-StreetLine4: Strings representing the street address where this event will run. This field is omitted when IsOnline is true.
  • Suburb: String representing the suburb where this event will run. This field is omitted when IsOnline is true.
  • City: String representing the name of the city where this event will run. This field is omitted when IsOnline is true.
  • State: String representing the state where this event will run. This field is omitted when IsOnline is true.
  • PostCode: String representing the post code where this event will run. This field is omitted when IsOnline is true.
  • Country: String representing the country where this event will run. This field is omitted when IsOnline is true.
  • PointLatitude: Decimal (float) value with the map latitude coordinate where this event will run. This field is omitted when IsOnline is true, or where map coordinates are not available.
  • PointLongitude: Decimal (float) value with the map longitude coordinate where this event will run. This field is omitted when IsOnline is true, or where map coordinates are not available.
  • ViewUri: String representing URI containing information about the location or venue where this event will run. This field is present only if a URL with additional information is available.
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
  • PresenterID: An integer value identifing the presenter.
  • Name: String value with the full display name of the presenter.
  • ViewUri: String representing a URI containing information about the presenter such as their profile. This field is present only if a URL with additional information is available.
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
  • RegisterMessage: String value with text to be shown in any register link or button -- see notes below.
  • RegisterUri: String representing a URI where registrations for this event may be placed. If registrations are not being accepted for this event, this field will be omitted.
Important notes
  • If the RegisterUri field has a value, it should be used in conjuction with the RegisterMessage field to produce a labelled link or button.
  • If the RegisterUri field is null or missing, the RegisterMessage must still be displayed as text (not a link). In these situations, this field usually contains a custom text message to be displayed for the event such as Call us for more information. Ensure your display logic can handle displaying registration information as plain text, or as link/button.
  • It is important any code uses the RegisterMessage property for links/labels and does not assume it will always have the value "Register". The message field can contain other values such as "Join waiting list" when an event is full but the waiting list feature is enabled for the event.
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
  • Name: The display name of the provider.
  • WebsiteUri: String representing a URI where more information about this provider may be found. If no more information is available, this field will be omitted.
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.
  • One day (or less): Tuesday 1 June 2021
  • Multiple days, same month: Wednesday 2-5 June 2021
  • Multiple days, multiple months: 3 June - 22 October 2021
  • Mutiple years: Fri 27-Dec-2021 to 02-Jan-2022
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
  • "button" will show the registration info as a button
  • "link" will show the registration info as a normal link
  • "message" will show the registration info as plain text

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.

  • showSingleOffer: Depending on the display room available on your page, you may want to only show the best offer. If set to true, only the best offer will be displayed. Defaults to false.
  • showPriceWithTaxInclusive: Display prices including tax. Defaults to true
  • showLabel: Show the label associated with the price. Defaults to true
  • showMessage: Show the additional message associated with the price. Defaults to false
  • showCurrencyCode: Show the currency code (e.g. AUD) the price is in. Defaults to false
  • showTaxRate: Show the tax rate applied to the price (e.g. incl/excl. GST). Defaults to true
  • freeText: Change the default text for a free event. Default to "Free"

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.

  • fields: An array of strings, each representing the fields you wish to display for the session.
  • advertisedOffersConfig: If you want to display advertised offers, you can pass this option to the view helper along with its config based on the AdvertisedOffers template helper above.

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.