Calendar Widget Arguments & Examples

Driving every LiveWhale Calendar view is an underlying widget that sets certain configurations. Here’s an example of an out-of-the-box configuration, showing a few selectors, setting 200x200 thumbnail sizes, and making sure that

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<widget type="events_calendar">
<arg id="mini_cal_heat_map">true</arg>
<arg id="thumb_width">200</arg>
<arg id="thumb_height">200</arg>
<arg id="hide_repeats">true</arg>
<arg id="show_groups">true</arg>
<arg id="show_locations">false</arg>
<arg id="show_tags">true</arg>
<arg id="use_tag_classes">false</arg>
<arg id="search_all_events_only">true</arg>
<xphp content="true">
<if var="group_directory"></if><!-- LW: If we're on a group calendar page -->
<content>
<arg id="group"><xphp var="group_fullname"/></arg><!-- LW: only show this group's events -->
</content>
</xphp>
</widget>

On LiveWhale Calendar sites, this most often lives in its own file include for convenient configuration (/_ingredients/themes/global/calendar_settings.html), though it can be moved elsewhere in your theming.

In addition to adding/removing settings from the below list, you can customize your calendar views further using XPHP logic. For example:

1
2
3
4
5
6
7
<xphp content="true">
<if var="server_dirname" equals="/"/><!-- if we're on the calendar homepage, exclude certain event types -->
<content>
<arg id="exclude_category">Office Hours</arg>
<arg id="exclude_category">Meeting</arg>
</content>
</xphp>

See below for a full list of supported settings. Note: the below apply only to calendar widgets. See here for all other widget arguments.

Basic

Argument Description Examples
group show items from group(s) <arg id="group">me</arg>
<arg id="group">biology</arg>

or using the CORS widget:
group: ["Alumni","Academics"]
exclude_group don’t show items from group(s) <arg id="exclude_group">biology</arg>
default_view which view (day, week, month, all) should load first <arg id="default_view">week</arg>
exclude_view don’t include this view in the menu <arg id="default_view">month</arg>
month_view_only only show the month view <arg id="month_view_only">true</arg>
show_public show events from the Public group (default: false) <arg id="show_public">true</arg>
events_per_page number of events to show in list view before “show more” (default: 50)
Note: setting this higher than 50 is discouraged for performance reasons. Get in touch if you’d like to discuss.
<arg id="events_per_page">25</arg>

Categories

Argument Description Examples
category show items in selected category <arg id="category">lectures</arg>
exclude_category do not show items in selected category <arg id="exclude_category">Deadlines</arg>
category_mode require that items match any or all categories <arg id="category_mode">any</arg>
use_category_classes apply categories as css classes <arg id="use_category_classes">true</arg>
exclusive_categories only allow one category to be selected at a time (automatically pre-pends an “All” link) <arg id="exclusive_categories">true</arg>

Tags

Argument Description Examples
tag show items that are tagged with specific tag(s) <arg id="tag">apples</arg>
exclude_tag show items that are not tagged with specific tag(s) <arg id="exclude_tag">oranges</arg>
tag_mode require that items match any/all the specified tags <arg id="tag_mode">any
use_tag_classes apply tags as css classes <arg id="use_tag_classes">true</arg>

Filtering and Sorting

Argument Description Examples
only_starred show only starred items <arg id="only_starred">true</arg>
hide_repeats Only show next instance of a repeating/multi-day event. In LiveWhale 1.7.1+ “non_starred” hides repeats but shows them if the repeat is starred <arg id="hide_repeats">true</arg>
<arg id="hide_repeats">false</arg>
<arg id="hide_repeats">non_starred</arg>
filter_mode require items match any/all filters below <arg id="filter_mode">any</arg>
filter select one of the options below with an action and a value to filter based on your criteria <arg id="filter" name="title" action="contains">Apples</arg>
search_all_events_only any search will go to the “All” view (default: true) <arg id="search_all_events_only">true</arg>
search_all_groups
(LiveWhale 1.7.1+)
any search will ignore <arg id="group"> settings for this calendar (default: false)
Note: exclude_group settings will still be honored. We recommended this setting if your calendar homepage only shows one group.
<arg id="search_all_groups">true</arg>
display_all_day_events_last show all day events at the end of the list rather than first (default: false) <arg id="display_all_day_events_last">true</arg>
show_archived show archived events (default: false)
Note: use both to show both archived and non-archived events in your calendar. Using true will show only archived events.
<arg id="show_archived">true</arg>
<arg id="show_archived">false</arg>
<arg id="show_archived">both</arg>
home_view_combine_today_upcoming when using the home view, combine today’s featured events with upcoming featured events (max 10) into one list (default: false) <arg id="home_view_combine_today_upcoming">true</arg>

Format

Argument Description Examples
location_char_limit truncates the event location (default is 50 characters) <arg id="location_char_limit">60</arg>
thumb_width format thumb image width <arg id="thumb_width">100</arg>
thumb_height format thumb image height <arg id="thumb_height">100</arg>
image_width format event details image width (in LiveWhale 2.8+, this overrides the thumb_width in the default gallery) <arg id="image_width">600</arg>
image_height format event details image height (in LiveWhale 2.8+, this overrides the thumb_height in the default gallery) <arg id="image_height">400</arg>
gallery_width format the fullscreen gallery width when you have multiple images attached to an event (LiveWhale 2.8+ only, this overrides the image_width in the default gallery) <arg id="image_width">1000</arg>
gallery_height format the fullscreen gallery height when you have multiple images attached to an event (LiveWhale 2.8+ only, this overrides the image_height in the default gallery) <arg id="image_width">1000</arg>
format_single_image set the HTML markup of {{ image }} when only one image is attached to an event (LiveWhale 2.8+ only, this overrides format_single_image from the default gallery) <arg id="format_single_image">{image}
<span class="caption">{caption}</span></arg>
ampm_with_dots use “a.m./p.m.” instead of “am/pm” in time formats <arg id="ampm_with_dots">true</arg>
month_view_day_limit number of events shown in month view before “show X more…” link (default: 4) <arg id="month_view_day_limit">4</arg>
hide_local_timezone hides local times when user is outside the calendar’s timezone (default: false) <arg id="hide_local_timezone">true</arg>
disable_timezone removes timezone abbreviations from all times (default: false) <arg id="disable_timezone">true</arg>
show_tags populates <xphp var="lw_calendar_tags" /> with the tag selector of starred, global tags applied to events <arg id="show_tags">true</arg>
show_categories populates the category selectors for event type, audience, and campus <arg id="show_categories">true</arg>
show_groups populates <xphp var="lw_calendar_groups" /> with the group selector <arg id="show_groups">true</arg>
show_locations populates <xphp var="lw_calendar_locations" /> with the location selector <arg id="show_locations">true</arg>