Arlo

Category Catalogue

The Category Catalogue javascript control (widget) allows you to generate a list of categories with each category displaying its event templates, and each event template displaying the next running event created from that template. The category list can be filtered by navigating a traversable category tree filter. It also provides the ability to show the current category's parents' header and footer information. See the Code Editor example below to gain a clearer understanding of how this control works.

This article will guide you through integrating a category catalogue control into your webpage that will call the API and render event templates according to your configuration options, template, and CSS.

Contents

Getting Started

The following code block contains an example of all the elements necessary to create an Event Template Catalogue control on your webpage.
There is is a lot going on here as this control, as this is the most complicated control type to configure.
Based on the general getting started guide. 

                                        
                        <div id="arlo-category-header"></div>
                        <div id="categorylist-filter"></div>
                        <div id="categorylistitemevent-filter"></div>
                        <div id="catalogue"></div>
                        <div id="arlo-category-footer"></div>
                           
                        <script src="//connect.arlocdn.net/jscontrols/1.0/init.js" charset="utf-8" defer="defer"></script>     

                        <script type='text/template' id='catalogue-template'>
                            <div class="arlo-category-name arlo-h3"><%= Name %></div>
                            <%= showCategoryEventTemplateCategoryItems({
                                template: "#eventtemplatedemo-template",
                                loadImmediately: true,
                                showDescendants: true,
                                maxCount: 4,                        
                                includeLoadMoreButton: true,
                                loadMoreButtonText: "Load More",
                                callbacks: {onShow: "onShowEventTemplateCategoryList"},
                                customUrls: {
                                    eventtemplate: "http://example.com/eventtemplatepage.html",
                                    venue: "http://example.com/venue.html",
                                    presenter: "http://example.com/presenter.html"
                                }
                            }) %>
                        </script>
  
                        <script type='text/template' id='eventtemplatedemo-template'>
                            <%- Title %>
                            <div class="nextrunning-<%= EventTemplateID %>" 
                                    data-registeruri="<%= RegisterInterestUri %>" 
                                    data-customuri="<%if(typeof ViewUri!=='undefined'){%><%=ViewUri %><%}%>">
                            </div>
                        </script>
 
                        <script type='text/template' id='arlo-category-header-template'>
                            <%- Name %>
                            <%= Description.Text %>
                        </script>
                        <script type='text/template' id='arlo-category-footer-template'>
                            <%= Footer.Text %>
                        </script>
                        <script type='text/template' id='categorylistitemeventfilter-template'>
                            <%= showFilter({filterCode: "locname", showCount: false}) %>
                        </script>
                        
                        <script>
                        	document.addEventListener("arlojscontrolsloaded", function () {
                                var categoryListItemEventFilter = {
                                    moduleType: "Filters",
                                    targetElement: "#categorylistitemevent-filter",
                                    template: "#categorylistitemeventfilter-template",
                                    filterControlId: 2
                                };
                                var catalogue = {
                                    moduleType: "CategoryCatalogue",
                                    targetElement: "#catalogue",
                                    template: "#catalogue-template",                
                                    categoryFilterType: "facet",
                                    categoryFilterTarget: "#categorylist-filter",
                                    nextRunningEventFilterControlId: 2,
                                    loadNextRunningButtonText: "Find Events",
                                    includeLoadMoreButton: true,
                                    loadMoreButtonText: "Load More Categories",
                                    maxCount: 2,
                                    header: {
                                        targetElement: "#arlo-category-header",
                                        template: "#arlo-category-header-template"
                                    },
                                    footer: {
                                        targetElement: "#arlo-category-footer",
                                        template: "#arlo-category-footer-template"
                                    }
                                };
                                new ArloWebControls().start({
                                   "platformID": "demo.arlo.co",
                                    "modules": [catalogue, categoryListFilter, categoryListItemEventFilter]
                                });
	                        });
                        </script>

Explanation of example configuration above:

  • Define a container for the category catalogue control, and the next running event filter control which will be assigned to it.
  • Load the Arlo JS Controls application code onto the page
  • Define a configuration for an category catalogue control (moduleType: "CategoryCatalogue") that will display a list of categories. This control will be displayed in the DOM element with id #catalogue and rendered using the template in the script element with id #catalogue-template.
    Note that the configuration also contains filterControlId, which specifys the id of the filter control that will filter the category list and nextRunningEventFilterControlId options, that allow the user to create filters that will apply to the category items next running events results.
  • Define a configuration for the event filter control that will be used to filter the next running events in the list. This filter control can contain any event based filters.
  • Start the application, specifying a platform ID of "demo", and the Category Catalogue and Filter control configurations.

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.

Category Catalogue

See the Pen Category Catalogue by Arlo Software Ltd. (arlosoftware) on CodePen.

Event Template Catalogue control configuration

To create an event template catalogue control, you should use a moduleType value of "EventTemplateCatalogue".
Example: moduleType: "EventTemplateCatalogue"

The event template catalogue control has the following config options, as well as the shared configuration options.

Field Type Default Description
categoryFilterType string "facet" A catalogue control can have a category filter, which the user interacts with in order to filter the categories that are displayed.
There are two different types of category filter available.
  • "facet": This uses the standard category facet to create a list of category options that lets you specify which category to show.
  • "traversable": This retrieves all categories in the platform and builds a traversable hierarchy that allows you to start at the parent category and work your way down through the sub-categories.
Example: categoryFilterType: "traversable"
categoryFilterTarget string Specifiy a CSS style ID selector of the element where the filter control should be rendered.
If you do not specify a target, the filter will be automatically inserted before the main category control list.
Example: categoryFilterTarget: "#categorylist-filter"
categoryFilterCallbacks string Allows you to run a callback after the category filter has loaded. For the callback object values, you must pass the names of functions attached to the window object as a string, as opposed to passing a function directly.
Example: categoryFilterCallbacks: {onShow: "onCategoryFilterShow"}
Remember: "onCategoryFilterShow" should match the name of a function attached to the window object.
facetFilterStyle string "radios" The element style of the category control. Can either be "select", which renders the filter as a dropdown, or "radios" (the default), which renders the filter as radio buttons.
This only applies if the categoryFilterType (described above) is set to "facet".
Example: facetFilterStyle: "select"
showOnlyCurrentCategoryItems boolean false Only applies if the categoryFilterType (described above) is set to "traversable". By default the catalogue control will list the sub-categories of the currently selected category and their event templates, enable this option to have it only list the event templates of the currently selected category.
nextRunningEventFilterControlId string Specify the ID of the filter control to use when filtering the categories' items' next running events. You should have a corresponding filter control configured with this value.
Example: nextRunningEventFilterControlId: "nextRunningEventsFilter"
loadNextRunningButtonText string 1 The text to show for the button that load more results. For this control, this button will appear below the category list, enabling the loading of more categories.
Example: loadNextRunningButtonText: "Load more"
maxNextRunningEvents number 1 The maximum number of next running events to display for each event template result.
Example: maxNextRunningEvents: 3
header object Provides a way to create a page header by rendering a template that uses information from the currently selected parent category. You can use the same fields listed below. Generally you would use the Name and Description.Text fields for a header.
The header object should provide two properties. targetElement, a css-style ID selector of the target element you want the header to be rendered in, and template, which provides a template used to render the header.
Example: header: { targetElement: "#arlo-category-header", template: "#arlo-category-header-template"}
footer object Provides a way to create a page footer by rendering a template that uses information from the currently selected parent category. You can use the same fields listed below. Generally you would use the Footer.Text field for a footer.
The header object should provide two properties. targetElement, whose value should be a css style id selector of the target element you want the footer to be rendered in, and template, which provides a template used to render the footer.
Example: footer: { targetElement: "#arlo-category-footer", template: "#arlo-category-footer-template"}
nextRunningEventTemplate 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 the overview for more information on custom templates. All fields available to the upcoming events list can be used in the template. The Count field can also be used in the template to display a count of the next running events.
nextRunningOnlineActivityTemplate 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 the overview for more information on custom templates. All fields available to the online activity list can be used in the template.
nextRunningUseRegisterLink boolean By default the next running dates will link through to the event template page, if this option is specified the next running dates will link directly to the register form.

Table of customisable URLS for event template category item sub control

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
presenter Presenters - each presenter objects ViewUri

Displaying the next running events for the results inside the category item sub control

In order to display next running events for this controls' results, you must provide a container in the template where they will be rendered once loaded. The element should contain the exact same attributes as the one below, but the tag name can change. Please copy and paste the one below to avoid problems. 

                <script id="category-item-control-template" type="text/html">
                <%= Name %>
                <div class="nextrunning-<%= EventTemplateID %>"
                     data-registeruri="<%= RegisterInterestUri %>"
                     data-customuri="<%if(typeof ViewUri!=='undefined'){%><%=ViewUri %><%}%>">
                </div>
                </script>

Catalogue - Full Configuration Example

                            var catalogueControl = {
                                moduleType: "EventTemplateCatalogue",
                                targetElement: "#catalogue-control",      
                                template: "#catalogue-control-template",  
                                categoryFilterType: "facet",
                                categoryFilterTarget: "#categorylist-filter",
                                eventTemplateFilterControlId: "eventtemplatefilter",                     
                                maxNextRunningEvents: 2, 
                                resultCountTarget: "#result-count",
                                callbacks: {
                                    onBeforeRender: function(eventTemplateData, jQuery){//Do something with eventTemplateData},
                                    onShow: function(getTemplateListItemsFunction, jQuery){
                                        //Do something with event template list item(s) elements
                                    }
                                },
                                customUrls: {             
                                    eventtemplate: "http://example.com/eventtemplatepage.html",
                                    venue: "http://example.com/venue.html",
                                    presenter: "http://example.com/presenter.html"
                                },
                                header: {
                                    targetElement: "#arlo-category-header",
                                    template: "#arlo-category-header-template"
                                },
                                footer: {
                                    targetElement: "#arlo-category-footer",
                                    template: "#arlo-category-footer-template"
                                }
                            };                 
                     
                            <script id="catalogue-control-template" type="text/html">
                                <%= Name %>
                            </script>

Filtering

The Category Catalogue control can be filtered in two ways. The first is by using a category filter paired with the control. When a category is selected, it becomes the parent category and a list of its direct descendant categories will be displayed. The second way is to pair the control with a event filter control. This allows filtering of the 'next running' events for each categories' event templates.

More detailed information about using filter controls can be found here.

An example of pairing the control with a category filter

  • Configure the control with categoryFilterType and categoryFilterTarget values.
                                var catalogue = {
                                moduleType: "CategoryCatalogue",
                                targetElement: "#catalogue",
                                template: "#catalogue-template",
                                categoryFilterType: "facet", //or "traversable"
                                categoryFilterTarget: "#categorylist-filter",
                            };
  • Create the target element where the filter should be rendered
                                    <div id="categorylist-filter"></div>

An example of pairing the control with a event filter control

  • Configure the control with a nextRunningEventFilterControlId value.
                                    var catalogue = {
                                    moduleType: "CategoryCatalogue",
                                    targetElement: "#catalogue",
                                    template: "#catalogue-template",
                                    nextRunningEventFilterControlId: 2
                                };
  • Create a filter control with the same id as the previous step, as its filterControlId value.
                                    var categoryListItemEventFilter = {
                                    moduleType: "Filters",
                                    targetElement: "#categorylistitemevent-filter",
                                    template: "#categorylistitemeventfilter-template",
                                    filterControlId: 2
                                };
  • Create a template for this filter control, containing whichever event based filters you want.
                                    <script type='text/template' id='categorylistitemeventfilter-template'>
                                    <%= showFilter({filterCode: "locname", showCount: false}) %>
                                </script>
  • Create the target element where the filter should be rendered
                                    <div id="categorylistitemevent-filter"></div>

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
CategoryID An integer value that uniquely identifies this resource within the platform.
ParentCategoryID An integer value that identifies the immediate parent of this category in the tree. This field is omitted if the category has no parent (meaning it is a top-level category).
Name A string representing the name of the category, up to 128 characters long.
SequenceIndex An integer value representing the ordinal sort order of this category within its immediate parent. Use this field to ensure child items are correctly sorted within display lists.
Description A structure containing marked-up text representing the description for this category. This field is often not suitable for display in lists and can contain arbitrary HTML including tables, lists and images.
Structure fields
  • ContentType: String representing the content type of the description, usually application/xhtml.
  • Text: Text content of the description.
Footer A structure containing marked-up text representing the footer info for this category. This field is often not suitable for display in lists and can contain arbitrary HTML including tables, lists and images.
Structure fields
  • ContentType: String representing the content type of the description, usually application/xhtml.
  • Text: Text content of the description.
ViewUri A string representing a URI where more information for this category can be found. This may be an Arlo page, or it may be a custom URI.

Category Items Sub Control

Additional information helpers allow you to embed information from other resources into your templates. See general sub controls documentation for more information

There is only one sub control helper available for the Catalogue Control, and you must use it for the control to function correctly.

The showCategoryEventTemplateCategoryItems sub control

When added to your catalogue category template, it loads a list of event template category items for each category in the list.
For more information, see the api documentation 

                        <%= showCategoryEventTemplateCategoryItems({
                            template: "#eventtemplatedemo-template",
                            loadImmediately: true,
                            maxCount: 4,
                            includeLoadMoreButton: true,                        
                            loadMoreButtonText: "Load More",
                            callbacks: {onShow: "onShowEventTemplateCategoryList"},
                            customUrls: {
                                eventtemplate: "http://example.com/eventtemplatepage.html",
                                venue: "http://example.com/venue.html",
                                presenter: "http://example.com/presenter.html"                            }
                        }) %>

Category Items Subcontrol Configuration

As seen in the getting started guide above, the category template requires a showCategoryEventTemplateCategoryItems sub control in order to display each category's associated event template category items. It has standard sub control configurations, plus the additional ones listed below.

Field Type Default Description
showDescendants boolean conditional When set to true, each category will display the event template category items of any descendant categories, as well as that category's own event template items.
By default, it will only do this if descendants exist. The reason for that is that if showing descendants, you lose ordering category items by sequence.
To force all category items to be ordered alphabetically, set this to true manually. To force all to be sorted by sequence and no descendants shown, set it to false.
Example: showDescendants: true

Available properties for event template category items sub control template

Field Description
CategoryID An integer value representing the parent category of the category item.
EventTemplateID An integer value that identifies the Template ID of the category item. Applicable only if the item is a template, and is omitted if the item is a custom category item such as a link with text.
Title A string representing the title of the item in the category, up to 128 characters long. This is usually the name of the template, or the text to use for a link.
Uri A string with the URL of the item, such as the link to the template page with events.
Summary A string representing a short plain text one-line or one-paragraph summary of this category item, suitable for display in lists and search results. This field is only present if a summary is available for the item.
SequenceIndex An integer value representing the ordinal sort order of this child item within its parent category. Use this field to ensure items are displayed in the correct order in lists.
Code A string with the code of the template. For example, MGMT101. This field is omitted if the item is not a template.
AdvertisedDuration A string with descriptive text of the duration of the template and its events. For example, 4 hours.
AdvertisedPresenters An array of structures representing presenters associated with the template and its events. This field is omitted if the item is not a template.
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.
BestAdvertisedOffers An array of AdvertisedOffer structures representing the best generally available offers for the template and its events. This field is omitted if the item is not a template.
Tags An array of strings representing tags associated with the template. If the template has no tags, this field will be omitted.
RegisterInterestUri The URL of the page where interest can be registered by individuals to run a new event at a different location and/or time. Interest submissions are recorded as Leads in the platform. This field is included only if recording of interest is enabled for the template.
RegisterPrivateInterestUri The URL of the page where interest can be registered by individuals to run an event at a private or onsite location (for internal staff training, for example). Interest submissions are recorded as Leads in the platform. This field is included only if recording of interest in running an event privately is enabled for the template.