The Events Module List View can be filtered by Category, Host, or by finding Events which are happening between given dates.

Introduction

The Events Module includes the following optional features for helping Users navigate the List View.

• Browse by Category

• Browse by Host (requires Authors Module)

• Browse by Month/Date - Finds Events which are happening during this month

• Search Events which are happening between two Dates

You may be familiar with many of these if you've used the Blog Module Navigation, however the main difference between them is how they handle dates; navigating the Blog Module by date would use the post's Release Date, whereas the Events Module will check to see if a given date falls between the Event Start and Event End dates.

Using the Navigation Options to Filter the Map and Calendar Views

You can use the Navigation Options on the Map and Calendar Layouts- these are List Layouts too!

However, certain features just won't have the same effect. For example, filtering the Calendar Layout by Date does not make sense- as the Calendar controls already give you an option to navigate by Date- using the Archive Navigation on the Calendar would cause certain Events to be "missing" from the Calendar, even if the User had navigated to a different month. On the other hand, it's perfectly possible that you might wish to filter the Calendar by Host or Category- to allow the User to focus on the type of Events which interest them most.

Using two List Views on the Same Page- and only filtering one of them

As the Events Navigation options are powered by URL parameters, the parameters will filter all Events List Views on the Page the same way.

If you want to provide a Calendar and an Events List together on the Page for example, and you only wish one of them to be affected by the filters in the URL, you can do so by only using the use_adv_search: 'true' parameter on the List View you want to be filtered.

User Feedback

Each Events Navigation Article will explain how you can use Liquid Logic to dynamically show the currently applied filter. Here, we'll show an example of some Logic that will check for any of the applied filters:

{% assign now = "now" | date: "%s" %}
{% if context.params.range_type == "past" %}
  <h2>Past Events</h2>
  <a href="{{context.headers.PATH_INFO}}?range_field=events&range_type=future&range_gt={{now}}">
    Future Events</a>
{% elsif context.params.range_type == "future" %}
  <h2>Future Events</h2>
  <a href="{{context.headers.PATH_INFO}}?range_field=events&range_type=past&range_lt={{now}}">
    Past Events</a>
{% elsif context.params.module_field_12_4 %}
  <h2>Events hosted by {{context.params.host_name | url_decode}}</h2>
{% elsif context.params.range_type == "month" %}
  <h2>Events in {{context.params.range_gt | date: "%b-%y"}}
    {{context.params.range_gte | date: "%b-%y"}}</h2>
{% elsif context.params.range_type == "between" %}
  <h2>Events between {{context.params.range_gt | date: "%d-%b-%y"}}
    {{context.params.range_gte | date: "%d-%b-%y"}} and 
    {{context.params.range_lt | date: "%d-%b-%y"}}
    {{context.params.range_lte | date: "%d-%b-%y"}}</h2>
{% elsif context.params.category %}
  <h2>Category: {{context.exports.categories.data[context.params.category].name}}</h2>
{% else %}
  <h2>All Events</h2>
  <a href="{{context.headers.PATH_INFO}}?range_field=events&range_type=past&range_lt={{now}}">
    Past Events</a>
{% endif %}

Of course, you can use this for inspiration and edit as you wish.

Related Documents

• Searching - Keyword

• Searching - Advanced Filtering

We'll explain how to output a List View of Events and link you to the docs on advanced Filtering and Navigation

Introduction

The Events Module comes with a wide range of options for your List View. You can output Events as:

• A standard List

• A Map

• A Calendar

You can also use our Navigation options with any of these views.

Outputting a List View

You can output a List View in any Liquid File - that means:

• Pages

• Templates

• Headers

• Footers

• Layouts

• Code Snippets

• Content Sections

Basic List views will also work in workflow and auto-responder emails, but be aware that any features which depend on JavaScript or URL parameters will not be supported in this context- that includes the Map and Calendar Layouts.

Use the following Liquid Syntax to output an Events List view:

{%- include 'module'
    id: '12'
    layout: 'design_system/1/list'
    per_page: '2000'
    show_pagination: 'false'
    sub_model: 'true' 
-%}

Introduction

Once you've added a Host to Events, you can use Datasources to output the Host's Details on the Event List or Detail Layouts.

Syntax

Add the following Liquid:

{% include "modules/siteglide_authors/get/get_item_author"
   author_id: this.properties.module_field_12_4
   author_layout: "design_system/1/author"
   author_layout_type: "detail"
%}

This Option Lets you filter Events by Host

Prerequisites

• You have installed the Events Module

• You have installed the Authors Module

• You have added at least one Author as an Event Host

Introduction

This article explains:

• How to include the Browse by Host (Author) Option when including a Blog List

• Default Layout Examples

• How to give feedback to the User about their results e.g. in the screenshot "Events hosted by Regina Alexander"

Add "use_adv_search" parameter to include for Event List View

The "use_adv_search" parameter is needed to allow filtering from the URL to apply to your Event Items, this can be added to the include for Event List like so:

{%- include 'module'
    id: '12'
    layout: 'default'
    per_page: '20'
    show_pagination: 'true'
    sort_type: 'created_at'
    sort_order: 'desc'
    use_adv_search: 'true' 
-%}

To Include this Option

Include the following liquid to dynamically get a list of available Event Hosts for the User to select.

{%- include 'modules/siteglide_authors/get/get_authors'
    author_layout: 'design_system/1/author'
    author_layout_type: 'list'
    author_field: 'module_field_12_4' 
-%}

The author_field will be module_field_12_4 if you are using Siteglide's Authors Module. The layouts are structured in the same way as Category Layouts in the previous section.

Default Layout Examples with Explanation

wrapper.liquid

<div class="row no-gutters">
  <div class="col-12">
    <h2>Authors</h2>
    <ul>
      {%- include 'modules/siteglide_system/get/get_items', item_layout: 'item' -%}
    </ul>
  </div>
</div>

item.liquid

<a
  class="authorAnchorSidebar" 
  href="{{context.location.pathname}}?module_field_12_4={{this.id}}&author_name={{this.name | url_encode}}"
>
{% if this['Image'] -%}
    <img src="{% if this['Image'] contains 'http' -%}{{this['Image']}}{% else -%}{{this['Image'] | asset_url}}{% endif -%}" alt="{{this['Image Alt']}}">
  {% endif -%}
  <li>{{this['name']}}</li>
</a>

To filter the Blog List View, you need a link to the Blog List View slug, followed by "?module_field_12_4={{this.id}}". Siteglide will be able to read the URL and filter the list.

User Feedback - Displaying the currently applied filter

To make it easier to give feedback to the User, you can optionally include the Host's name in the URL:

<a href="{{context.location.pathname}}?module_field_12_4={{this.id}}&host_name={{this.name | url_encode}}"></a>

On the List view, you can then include the following liquid to read the URL and decode the Author name you are currently filtering by:

{% if context.params.module_field_12_4 %}
  Events hosted by {{context.params.host_name | url_decode}}
{% endif %}

The Map Layout is a List Layout which demonstrates how you can use the Google Maps API to visualise Events from the Siteglide database.

Prerequisites

• You've Installed the Events Module

• You've added Events in the Admin

• You've added a Location to at least one Event

Introduction

The Map Layout is a List Layout which demonstrates how you can use the Google Maps API to visualise Events from the Siteglide database. In order to use this Layout, you'll need to create an account with Google and follow the instructions to generate an API key.

We've tried to expose just enough of the JavaScript to allow you to customise your Layout, while keeping as much Liquid as possible tucked away to keep things simple. Despite this, you will need to refer to the Google Maps API docs for any advanced customisation work you'd like to carry out.

Outputting the Map Layout on a Page

The Events Module Map Layout is an example of a List Layout. Like all List Layouts, you can output the Events Module Map Layout in any Liquid File, including Pages, Templates and Layouts. However, it also requires JavaScript to function properly, so it will not be supported inside an Email e.g. Autoresponder or Workflow.

To output the map, output the List Layout as normal, and choose a Map Layout in the layout parameter.

{%- include 'module'
    id: '12'
    layout: 'design_system/1/map'
    per_page: '5000'
    show_pagination: 'false' 
-%}

There are a few parameters which work particularly well on the Map Layout, because we will want to disable Pagination and show all enabled and released Events at once:

• per_page: 5000 - Makes sure the first Page shows all Events that are enabled and released

• show_pagination: 'false' - Hides Pagination Controls

You can use filtering Parameters as normal to filter Events and only show some on the Map.

• category_ids - Add a comma-seperated string of Category IDs to display

• item_ids - Add a comma-seperated string of Item IDs to display

You can also use URL parameters to carry out advanced filtering.

How does the Map Layout Convert Event Locations to a JavaScript array?

You'll notice in the wrapper.liquid file that the ordinary Liquid which fetches the item.liquid files is outputted inside a JavaScript <script> element. This is very important as it allows the Liquid data to be converted to the JavaScript array that Google Maps needs.

//---Events Module Map View Options--- 
//--- The Events Module Items should be loaded into a JavaScript Array- 
//--- this allows them to be used by Google Maps. Changing the format in the item.liquid 
//--- file may cause errors.
var locations = [	
	

<div data-gb-custom-block data-tag="-" data-0='modules/siteglide_system/get/get_items' data-1=', item_layout: ' data-2='item'></div>
];

The item.liquid file should be left in the format of a JSON object, but you may choose to add more variables:

{	
    id: "{{this.id}}",
	lat: {{this.properties.module_field_12_7 | split: ',' | first | times: 1 | default: "invalid" }},
	lng: {{this.properties.module_field_12_7 | split: ',' | last | times: 1 | default: "invalid" }},
	name: {{this.properties.name | json }},
	address: {{this.properties.module_field_12_6 | json }},	
    slug: {{this.full_slug | json }},	
    event_start: "{{this.properties.module_field_12_2 | date: "%d/%m/%Y %H:%M T%z"}}",	
    event_end: "{{this.properties.module_field_12_3 | date: "%d/%m/%Y %H:%M T%z"}}",	
    valid: "
{% if this.properties.module_field_12_7 == blank %}invalid{% else %}valid{% endif %}"
}{% unless forloop.last %},{% endunless %}

Here, we also use Liquid Logic to check for Events with no location data set and exclude them from the List.

Clustering

We've added Marker Clustering to the Map- which is useful if you're displaying multiple Events in the same area. Each time the map is moved, or zoomed in or out, an Event Triggers which will re-draw the markers.

The following behaviour was chosen by us for convenience and demonstration purposes, but can be changed by following the Google documentation.

If any markers are too close to each other, they will be "clustered" under a clustering marker, which will display a number for the number of Events in that location:

Clicking on the clustering marker will zoom in by an increment of 1, unless the User is at maximum zoom. As soon as we have zoomed in enough to display more of the markers without causing confusion, we will do so:

If we reach maximum zoom and some Events are still clustered (perhaps at the same location), the next click on the clustering marker will reveal an "infowindow" containing details on all Events at that location:

Customising the Map

We've split the JavaScript for the Map Layout into two files:

• wrapper.liquid - Here we define the variables which form the key "settings" needed to to set up the Map the way you want it

• assets/js/modules/module_12/default_map.js - This contains the rest of the code needed to make the map functional. For advanced developers who wish to edit using the Google Maps API docs, you can edit this file.

Customising the Options

These options are all explained by comments in the wrapper.liquid JavaScript. Make sure to follow each line except the last with a comma:

• map_selector: "#map" - The Selector for the Element into which you want to render the map.

• zoom: 3 - Sets the initial zoom on the Map. 1 is minimum and 22 is maximum.

• center: false - Sets the initial center of the Map. Should be in format {lat: Float, lng: Float} or false. If false, we will find the mid-point between all event locations and center there.

• show_info_windows: true - Info Windows give the event information as a modal when you click an event marker.

• markers.animation: - Select an animation option from the Google Maps Documentation. String e.g. "DROP".

• show_summary: false - Shows a summary of the Events visible on the current Map Viewport.

• summary_selector: "#mapSummary" - Selector for Element which will contain any summary. String

Customising the Event Detail Popups (infowindows)

To do this, you'll need to carefully edit the default_map.js file. You'll need to understand how to concatenate Strings and Variables in JavaScript to construct a larger String containing HTML code.

We keep the infowindows for markers and clusters separate. This is because they use different variables, and because it allows you to be more flexible.

1 - Define infowindow HTML for markers

Find the comment in the code: //Define infowindow for markers

Next, you'll need to edit the variable here. It's value should be an HTML String containing the content you'd like for the infowindow. You can move the variables around however you like, as long as the syntax remains correct!

content: '<h2>'+locations[i].name+'</h2><a href="'+locations[i].slug+'">View Details</a><br><br><p>'+locations[i].address+'</p><p>Starts: '+locations[i].event_start+'<br>Ends: '+locations[i].event_end+'</p>'

2 - Define infowindow HTML for cluster markers

Find the comment in the code: //--Cluster Markers--- Add a marker clusterer to manage the markers.

Next, you'll need to edit the variable here:

infoWindowContent = infoWindowContent + '<h2>'+c.markers_[i].event_data.name+'</h2><a href="'+c.markers_[i].event_data.slug+'">View Details</a><br><br><p>'+c.markers_[i].event_data.address+'</p><p>Starts: '+c.markers_[i].event_data.event_start+'<br>Ends: '+c.markers_[i].event_data.event_end+'</p><br><br>'

This is slightly more complicated, because the JavaScript will loop over this and display it for each Event inside the cluster at this level of zoom.

3 - Edit the CSS

As normal, you can use custom CSS to edit the styling of any of the infowindows. Use any classes you added in the previous two steps to target them.

Customising the Map - Advanced- Following Google's Documentation

Beyond this- you'll have to refer to the Google Maps API documentation to guide you. Good luck!

You'll be able to make changes in:

• The Page

• item.liquid and wrapper.liquid file

• default_map.js file

If you'd like to see the core functionality of the Events Module expanded, please make a suggestion on the Roadmap and we'll consider it for a future release.

The Article will show you how to adapt your Liquid Syntax and Events Layouts to allow the User to Search for Events by Keyword

Introduction

You can also allow the User to search for Events by keyword. This requires a slightly different Liquid parameter from the other navigation methods, but you can use both parameters if you choose.

Liquid Syntax

Although all other Events Navigation options require you to set the use_adv_search: 'true' Liquid parameter, keyword search requires the use_search parameter.

{%- include 'module'
    id: '12'
    layout: 'design_system/1'
    per_page: 20
    show_pagination: 'false'
    use_search: 'true' 
-%}

If you wish to use both types of Navigation for your Events, you can set both types of search parameter to 'true'.

{%- include 'module'
    id: '12'
    layout: 'design_system/1'
    per_page: 20
    show_pagination: 'false'
    use_search: 'true'
    use_adv_search: 'true' 
-%}

HTML and JavaScript Syntax

This code can be included in one of your Events Navigation Layouts. Keyword Search will be activated if you've set the Liquid parameter above and the JavaScript below sets the keyword parameter in the URL.

<div class="row no-gutters">
  <div class="col-12">
    <h2>Search Events by Keyword</h2>
    <form title="Search events by Keyword" id="events-archive-search">
      <div class="form-group">
        <label for="eventsSearch">Add Search Keyword</label>
        <input id="eventsSearch" type="text">
      </div>
      <input
        value="Search" 
        class="btn btn-primary" 
        type="submit" 
        data-slug="/module-12" 
        onclick="events_search()"
      />
    </form>
  </div>
</div>
{% comment %}
This example function will search for events in the future with this keyword. 
You'll need to use the "use_search" and "use_adv_search" parameters in your Liquid tag.
{% endcomment %}
<script>
  function events_search() {
    event.preventDefault();
    var keyword = document.querySelector("#eventsSearch").value;
    var url_string = window.location.pathname+"?keyword="+keyword;
    location.assign(url_string);
  }
</script>

Searching and Filtering at the Same Time

The following example also filters for future Events at the same time as it searches for keywords. You need to have set both use_search and use_adv_search parameters in the Liquid (see Syntax section above). You can adjust the JavaScript to remove this, or switch it to fetch Events in the Past.

<script>
  function events_search() {
    event.preventDefault();
    var keyword = document.querySelector("#eventsSearch").value;
    var url_string = window.location.pathname+"?keyword="+keyword+"&range_lt={{now}}
    &range_type=past&range_field=events";
    location.assign(url_string);
  }
</script>

Step 1: Install the Events Module

Install from the Modules tab on the Site you're working on from Portal:

For more information on how to install and manage modules:

Step 2: Create Event Items or Edit Existing

Create or manage existing items:

Give it a name and fill in any other fields:

Step 3: Setup the Pages/Layouts

You then need to output the Events on the site. You'll likely want to create a Page called Events:

Step 4: Customising the Layouts or Functionality:

Your Events will work out of the box but Siteglide is all about flexibility and recognising each project is different. You have total control to customise the Layouts and how the Events Module works. We recommend looking at the SiteBuilder Events Layouts as a starting point as there might be existing Layouts that can save you a lot of time.

The Events Module is linked to eCommerce Module, to give you full functionality and flexibility when selling Tickets (or other Products) related to Events.

Ready to build Events?

Want to Filter Items?

Want to Customise the Module Further?

This option allows you to provide the User with links to months when Events are happening - or let them Search between any two dates.

Prerequisites

• You've installed the Events Module

• You've updated your System Files to at least version 2.4.4.0

Introduction

This article will show:

• How to add a parameter to the main Events Module "include" Liquid Tag to enable advanced filtering by Event Start and Event End dates.

• How to include the Archive Navigation Feature

• An explanation of the three main sub-Layouts available in in the Default Layout: (1) Search Between Two Dates (2) Browse By Months (3) Browse by Months under Year Header.

• How to give User Feedback about Search Results

Add "use_adv_search" parameter to include for Event List View

The "use_adv_search" parameter is needed to allow filtering from the URL to apply to your Event Items, this can be added to the include for Event List like so:

Past Events and Future Events

By default, the List View will show all Events that are enabled, released and not yet expired.

If you just want to filter the List so it either shows Events that have already happened in the Past- or those Events which will happen in the Future, it may not be necessary to include the entire Archive Feature.

Filter by Past Events

Filter by Future Events

Using Liquid Logic to "Toggle" between Past and Future Events

Including the Archive Navigation Feature

Firstly, you will need to provide the following Liquid to include your Archive layout:

Parameters

• archive_layout-The layout parameter refers to the main layout folder followed by a path to the folder storing any archive layouts you are using. In the example, an /archive folder is used.

• archive_layout_type- The type parameter refers to the name of the Archive Layout file.

In the default/archive/ folder we have 3 different optional types of Archive Layout you can choose by entering their names in the type parameter. We will show the liquid tag for including each.

Include: Browse By Months

Include: Browse By Months Under Years Header

Include: Search Events Between Two Dates

Events Archive Layouts

The following examples will take you through the different options:

Browse by Month

In this example, we use the events_archive_months object and loop over the array. For each iteration, a URL link is outputted which has three range parameters:

• `range_gte` = An epoch format date for midnight on the beginning of the first day of the selected month

• range_lt = The date above + 1 month. We don't use lte because the date is the first valid date in the next month- we want every date up until then.

• range_field =events - This parameter is important as it makes sure that the Event Start and Event End fields are used instead of Release Date for the filtering.

Browse by Months, organised into Years

This Layout does not just organise the Months available under the relevant Year Headers, it also will skip any Years without an Event.

This example uses the same links as the previous one. However, it also organises the links into the years in which they belong by first looping over the years in the events_archive_years and then using the group_by liquid filter and another loop to output the month links grouped under the current iteration's year. Learn more about this Liquid at the pOS docs:

Search Events between two dates

In the Default Layout, this Option also includes the Previous "Browse by Months Organised into Years" Option for convenience- though the code can be simply removed if you prefer. We have removed it in this article's example.

It also adds a Form for directly manipulating the URL parameters to find the exact dates the User is interested in.

In this example a form is used to take user input. The Siteglide function automatically adds the dates to the URL parameters in the correct format. You can rewrite the error function to customise the way the form handles invalid dates entered.

***A note about Date Entry Inputs on different Browsers ***Different Browsers may display the Date Input fields very differently. 3rd party Javascript Plugins are available for making sure these display with your desired Design.

Custom Layouts

This is a relatively complex feature, so some understanding of Liquid will be necessary to understand how to create a Custom Layout. The best way to start would be to copy one of the Default layouts and edit it to provide the changes you need.

Any Layouts included with the above Liquid will get access to the events_archive_years and events_archive_monthsarrays, which contain detailed data about the years and months respectively which contain valid Events. This can be used to generate dynamic buttons to the User so they can browse.

events_archive_years

events_archive_months

The following URL Parameters will cause Results in the List to Filter:

• range_gt - greater than

• range_gte - greater than or equal to

• range_lt - less than

• range_lte - less than or equal to

For the above to work, remember to set the use_adv_search: true parameter (see start of article)!

The pOS documentation website has some useful tips on how to use liquid to convert date formats and manipulate dates and times. See the following useful filters, and browse the docs for more:

Feedback for the User - Displaying the currently applied filter

In the examples, you may notice another URL parameter is used: range_type. The s_events_date_search Siteglide function for filtering Events by user-inputted dates adds the parameter range_type="between". This would allow the following liquid on the List Layout to identify that this search is between two dates:

Whereas, you could use another range_type to indicate that different feedback should be given to the User. e.g. the parameter month in this example changes the sentence structure from "Events between" to "Events in" to communicate the different kind of filtering that is now taking place.

Note- in both of these examples- the gte and gt dates are both outputted- this is because only one is expected to be available. The Layout is designed to accept either

You can dynamically output a navigation menu of Categories which have Events assigned to them. The User can then filter the Events.

Prerequisites

• You have Installed Events Module

• You have

Introduction

This Article will show:

• How to include this Navigation Option when including the Events List

• The Default Layouts with explanation

• How to give the User Feedback on the type of results they are seeing.

To Include this Option

Include the following liquid to dynamically get a list of available Events Categories for the User to select:

The parameters refer to Layouts which will be used to display the Category links.

• categories_layout should be the path to the folder in the Events Module where your Category Navigation files are stored.

• The category_layout_type is the sub-folder where the wrapper and item files are stored for filtering the Events list by category e.g. list. The category_layout_type exists because some Events layouts may have a different partial layout for Categories within a Events preview, footer or sidebar.

Default Layout Examples with Explanation

wrapper.liquid

item.liquid

The link should be the slug of your Events List view followed by ?category={{this.id}}. Siteglide will be able to read the Category id from the URL and populate the List View on refresh. In this example we use the context object to automatically get the slug of the current Events Page.

User Feedback - Displaying the currently applied filter

You may wish to give the User some feedback about the current filter/ search terms that are applied on the Events List. For Categories, you can use {{context.exports}} object to get the name of the category you are filtering by: