The appearance of your LiveWhale Calendar (or calendar widget in the LiveWhale CMS) is controlled by a number of widget settings and templates from your theme.
Your LiveWhale Calendar homepage likely starts off by including a main_template.html file:
1 | <widget type="file"> |
Editing this file (_i is short for _ingredients) you can start organizing and theming your calendar. main_template.html typically includes:
(Older installations might instead include a calendar_head.html and calendar_template.html from the core theme directly into index.php, but all the same rules of Theme Inheritance still apply.)
In this main_template file (or any file includes you add), you can add/remove and rearrange the main calendar elements. You’ll need <xphp var="lw_calendar_view_menu"/>
to display the day/week/month/all view selector, as well as <xphp var="lw_calendar"/>
for the body of the calendar.
Beyond that, you can choose from the following sidebar elements, and customize them further with their individual components (below).
Sidebar Element | Tag | Required settings in calendar_settings.html |
---|---|---|
Search box | <xphp var="lw_calendar_search"/> |
none |
“Subscribe” button | <xphp var="lw_calendar_subscribe"/> |
none |
Mini-cal date picker | <xphp var="lw_calendar_mini_cal"/> |
none |
Drop-down calendar group navigation | <xphp var="lw_calendar_calendars"/> |
none |
Filter by group | <xphp var="lw_calendar_groups"/> |
<arg id="show_groups">true</arg> |
Filter by event type | <xphp var="lw_calendar_categories"/> |
<arg id="show_categories">true</arg> |
Filter by campus | <xphp var="lw_calendar_categories_campus"/> |
<arg id="show_categories">true</arg> |
Filter by audience | <xphp var="lw_calendar_categories_audience"/> |
<arg id="show_categories">true</arg> |
Filter by tags | <xphp var="lw_calendar_tags"/> |
<arg id="show_tags">true</arg> |
Filter by locations | <xphp var="lw_calendar_locations"/> |
<arg id="show_locations">true</arg> |
In general, the above filters will show all starred, global options (e.g. starred global tags, starred event types, etc.) on the front-end displays. Learn more about customizing those filters.
You may want to exclude a certain tag or event type from one group’s calendar, for instance. You can do this by creating a custom calendar_settings.html in the group that matches your theme name.
For example, in the “music” group, /_ingredients/themes/global/includes/calendar_settings.html will be overridden by /_ingredients/themes/music/includes/calendar_settings.html.
You can also add XPHP logic to the global calendar_settings.html include instead. More info and examples.
While the above includes manage the things around your calendar, you’ll edit your calendar’s components to tweak the appearance and functionality of individual pieces of the calendar, like the event view, day view, date selector, and more.
If you copy/edit any of the following to /_ingredients/themes/global/components/calendar/, they will override the defaults from the core theme. (For some clients, we’ve copied them already to /_ingredients/themes/global/components/move_to_calendar_to_customize/ as a courtesy.)
(Note for existing clients: You may be on a legacy setup where the below components are combined into calendar.html and calendar_components.html files. Contact Support to discuss moving to this new setup in your next upgrade.)
Component | Description |
---|---|
lw_cal_all.html | The “all upcoming events” view |
lw_cal_day.html | The “day” view |
lw_cal_event.html | An individual event listing in the day/week/all views |
lw_cal_event_detail.html | An individual event page |
lw_cal_month.html | The “month” view |
lw_cal_month_day.html | An individual day in the month view |
lw_cal_week.html | The “week” view |
lw_cal_list.html | A list of events (used in week/all views) |
Component | Description |
---|---|
lw_cal_feature.html | Featured event listing <div id="lw_cal_feature"></div> |
lw_cal_feature_item.html | An individual event in the featured listing |
lw_cal_feature_top.html | The first event in the featured listing |
lw_cal_feed_builder.html | Tool for building subscription feeds (view/feed_builder ) |
lw_cal_feed_selector.html | Individual selector in the feed_builder tool |
lw_cal_home.html | The “home” view (view/home ) |
lw_cal_home_event.html | An individual event listing in the home view |
Note: Your calendar installation might not support or have styling for the above optional views. Contact Support if you’re interested in enabling the home, featured, or feed_builder views.
Component | Description |
---|---|
lw_cal_calendars.html | “Calendar:” drop-down navigation pointing to all your group calendars |
lw_cal_categories.html | “Show Only:” checkbox menu for filtering by Event Type |
lw_cal_categories_audience.html | “Show Only:” checkbox menu for filtering by Event Type: Audience |
lw_cal_categories_campus.html | “Show Only:” checkbox menu for filtering by Event Type: Campus |
lw_cal_date_selector.html | Drop-down navigation for jumping to a nearby date or date range |
lw_cal_event_images.html | Image, caption, and credit for all event images |
lw_cal_event_related_content.html | Links to all content related to an event |
lw_cal_event_share_icons.html | Social media sharing icons |
lw_cal_groups.html | “Calendar:” checkbox navigation for filtering by group |
lw_cal_header.html | Header containing scroll_link, date_selector, header text, and “currently showing” text |
lw_cal_locations.html | “Location:” checkbox menu for filtering by location |
lw_cal_mini_cal.html | Mini calendar |
lw_cal_no_results.html | Text that appears when no events are found |
lw_cal_scroll_link.html | Previous/next arrows |
lw_cal_search.html | Search header and input |
lw_cal_subscribe.html | Subscribe button |
lw_cal_subscription_menu.html | Subcribe button pop-up |
lw_cal_tags.html | Menu for filtering by tags |
lw_cal_timezone_menu.html | Pop-up menu to change your timezone |
lw_cal_view_selector.html | Menu for day/week/month/all views |
When editing the above components, you can start off by rearranging the options provided in the core component. You’ll see variables being added in double-curly brackets:
1 | {{ title_link }} |
As well as some simple JavaScript logic using curly-and-square brackets, where variables are prefixed with obj.
:
1 | {[ if (obj.is_repeating) { ]} |
Note: In LiveWhale 2.0+, variables inside of {[ ]}
must be prefixed with obj.
in order to be included in your event results. This is due to performance optimizations that provide the event list and event details views with only the variables you are using in your component. See below for a list of the available variables in those components.
These are the variables available when customizing the Event List (lw_cal_event.html) and Event Details (lw_cal_event_detail.html) components.
Variable Name | Description | Example |
---|---|---|
id | Event ID | 123456 |
href | Details URL | /event/123456-my-event-title |
title | Title | My Event Title |
title_link | Event List Only: Title wrapped in link to event details | <a href="/event/123456-my-event-title">My Event Title</a> |
summary | Summary | <p>This is my event summary.</p> |
group_title | Public name of the event’s group (use group_fullname to get the system name) |
Department of Biology |
add_to_google | Add to Google Calendar URL | https://www.google.com/calendar/event?action=… |
ical_download_href | Add to iCal URL | //calendar.myschool.edu/live/ical/events/id/123456 |
is_canceled | True when event has been marked canceled | 1 |
cost_type | Event cost type (Free, Event Cost, Suggested Donation, or blank for Other) | Event Cost |
cost | Event cost amount | $15 |
description | Event Details Only: Description | <p>Full HTML of event details...</p> |
contact_info | Event Details Only: Contact Info | John Smith, jsmith@myschool.edu |
Variable Name | Description | Example |
---|---|---|
date_title | Formatted start date | Mon<span>day</span>, Jun<span>e</span> 20<span>, 2022</span> |
time | Full HTML of time display, includes date range if event repeats or spans multiple days (the same value can be called using the date_time variable in Event Details component) |
<span class=\"lw_start_time\">9:00am</span> - <span class=\"lw_end_time\">10:30am</span> <span class=\"lw_start_date\">Jun<span>e</span> 20</span> - <span class=\"lw_end_date\">Jun<span>e</span> 21</span> <span class=\"lw_cal_tz_abbrv tz_editable\">EDT</span> |
repeats | How often does event repeat (daily, weekly, monthly, yearly, M-F, M/W/F, T/TH) | weekly |
repeats_start | Date of first repeating event | June 20 |
repeats_end | Date of last repeating event | June 29 |
is_all_day | True when event is all day | 1 |
is_multi_day | True when event spans multiple days | 1 |
is_first_multi_day | Event List Only: True on the first encountered instance of a multi-day event | 1 |
Variable Name | Description | Example |
---|---|---|
date_start | Start date (MM/DD/YYYY) | 06/20/2022 |
date_start_day | Start date (day) | 20 |
date_start_day_of_week | Start date (day of week) | Monday |
date_start_month | Start date (month) | June |
date_start_month_short | Start date (abbreviated month) | Jun |
date_start_year | Start date (year) | 2022 |
datetime_start | Start date (datetime) | 2022-06-20T00:00 |
date_end | End date (MM/DD/YYYY) | 06/21/2022 |
date_end_day | End date (day) | 21 |
date_end_day_of_week | End date (day of week) | Tuesday |
date_end_month | End date (month) | June |
date_end_month_short | End date (abbreviated month) | Jun |
date_end_year | End date (year) | 2022 |
datetime_end | End date (datetime) | 2022-06-21T10:30 |
ts_start | Start date/time (Unix timestamp) | 1655730000 |
ts_end | End date/time (Unix timestamp) | 1655730000 |
time_start | Start time | 9:00am |
time_end | End time | 10:30am |
tz | Timezone area (as defined by PHP) | America/New_York |
tz_abbrv | Timezone abbreviation | EDT |
tz_offset | Start time timezone offset | -14400 |
tz2_offset | End time timezone offset | -14400 |
user_abbrv | Timezone abbreviation of site visitor | EDT |
user_offset | Timezone offset of site visitor | -14400 |
Variable Name | Description | Example |
---|---|---|
image_raw | Event List Only: Full HTML markup of image | <picture class="lw_image">... |
image | Event Details Only: The markup of a single image or gallery (see below) | <picture... |
images | Event Details Only: An array of images used to generate the slideshow markup | […] |
image_src | The Image URL | https://… |
thumb_width | The image width | 200 |
thumb_height | The image height | 200 |
custom_remote_image_url | If pulling from a Linked Calendar, the URL of the image | https://… |
custom_remote_image_caption | If pulling from a Linked Calendar, the caption of the image | My image caption |
When using {{ image }} in your Event Details component, the image or slideshow that’s provided (depending on if the event has one or multiple images attached) is provided by the default gallery in LiveWhale 2.0+.
You can fully customize the default gallery to change the way that {{ image }} appears, or you can override certain settings just for the calendar in your calendar widget settings.
Variable Name | Description | Example |
---|---|---|
has_map | True when a map is present | 1 |
location | Location name | University Library |
latitude | Location Latitude | 41.821943 |
longitude | Location Longitude | -71.416989 |
Variable Name | Description | Example |
---|---|---|
is_online | True when event is online | 1 |
online_url | Event web address | http://zoom.us/123456 |
online_button_label | Join Event button text | My Button Text |
online_instructions | Special instructions? | My special instructions |
online_type | Online only or Hybrid | Online only |
Variable Name | Description | Example |
---|---|---|
tags | Array of starred tags | [‘Humanities’, ‘Arts & Sciences’] |
tag_links | HTML list of links to each starred tag (called tags_calendar or tags_starred_calendar on Event Details View) | <a class=\"lw_cal_app_link\" href="all/tags/Humanities">Humanities</a>, <a class="lw_cal_app_link" href="view/all/tags/Arts%20%26amp%3B%20Sciences">Arts & Sciences</a>" |
tag_classes | All starred tags formatted as CSS class names | lw_tag_humanities lw_tag_arts_sciences |
Variable Name | Description | Example |
---|---|---|
categories | Array of event types | [‘Student Events’, ‘Admissions’, ‘Arts & Performance’] |
categories_audience | Array of audience event types | [‘Students’, ‘Faculty’, ‘Alumni’, ‘Prospective Students’] |
categories_campus | Array of campus event types | [‘Main Campus’] |
category_links | HTML list of links to each event type | <a href=\"all/categories/Student%20Events\">Student Events</a>, <a href=\"all/categories/Admissions\">Admissions</a>, <a href=\"all/categories/Arts%20%26amp%3B%20Performance\">Arts & Performance</a> |
category_audience_links | HTML list of links to each audience event type | <a href=\"all/categories/Students\">Students</a>, <a href=\"all/categories/Faculty\">Faculty</a>, <a href=\"all/categories/Alumni\">Alumni</a>, <a href=\"all/categories/Prospective%20Students\">Prospective Students</a> |
category_campus_links | HTML list of links to each campus event type | <a href=\"all/categories/Main%20Campus\">Main Campus</a> |
category_classes | All event types formatted as CSS class names | lw_category_student_events lw_category_admissions lw_category_arts_performance lw_category_students lw_category_faculty lw_category_alumni lw_category_prospective_students lw_category_main_campus |
If you’d like to format the event types using your own markup, you can use code like this to loop over the array:
1 | {[ _.each(obj.categories, function(category) { ]} |
You can also link to more events of that type by linking to /all/categories/Category Name
. Note, you’ll need to include class="lw_cal_app_link"
anytime you create a link tag from inside of another event component that’s meant to refresh the main calendar view.
1 | {[ _.each(obj.categories, function(category) { ]} |
Your calendar page will render and load /_ingredients/themes/global/styles/calendar.less on every view by default.
If you have a different or additional theme set (say, a custom “music” theme for the “music” group), it will also load the associated /_ingredients/themes/music/styles/calendar.less, if one exists.
You’ll notice your calendar.less begins with something like this:
1 | /* Import core calendar styles */ |
This is very important— including these styles and mobile mixins allow you to build on top of the existing core calendar styles from LiveWhale, rather than starting from scratch. It also means that the next time you are upgraded, any changes to the core theme/UI will filter down into your theme with minimal work.
There are also a few default variables you’ll inherit from the core theme, but can override in your own calendar.less should you choose:
1 | @highlight1: #c00; // Primary color |
At minimum, we recommend setting your school color(s) to the @higlight1
and @highlight2
variables in /_ingredients/themes/global/styles/calendar.less. You may want to do more hands-on styling of individual elements, but this will do a first-pass at matching the various UI elements to your chosen colors.
The calendar-mobile.less include doesn’t generate any rendered CSS, but rather provides a few mixins that you can choose to include in your own style, to allow for custom mobile breakpoints and styling.
Mobile Mixin | Description |
---|---|
.mobileMonthViewList() |
Display month view as a list of events |
.mobileMonthGridList() |
Display month view as a grid of dots |
.mobilePaymentsTable() |
Display RSVP form in a single column |
.mobileViewSelector() |
Display pared-down view selector |
1 | /* Import core calendar mobile mixins */ |
If you create a /_ingredients/themes/global/scripts/calendar-custom.js, it will be loaded in every view of your front-end calendar. This can be used to implement additional JavaScript or jQuery customization on top of the default calendar behavior.
The below template for calendar-custom.js aliases the livewhale.jQuery object for you to use as $
. Note also, there are several JavaScript triggers you can bind to, in order to run custom code at particular times or for particular views.
1 | (function($, LW) { |
When you create a new group in LiveWhale Calendar, you have the option to give it a URL. Visitors to that URL will see the “group calendar,” which uses a special template group_calendar.php. In most cases, your group_calendar.php is probably the same as your main /index.php — that is, individual group calendars look like your calendar homepage.
In LiveWhale 1.7.1 and before, the group calendar template was located at
In LiveWhale 2.0+, the new supported locations for the group calendar template are
And if no group_calendar.php is found, LiveWhale 2.0+ will fall back to your calendar homepage /index.php.
By default, LiveWhale will display all your calendar event types and tags as front-end filters, using the following theme tags:
1 | <xphp var="lw_calendar_categories"/> |
Event types will only show up after they’ve been applied to events (same with starred tags)—so, if your Athletics calendar doesn’t have any “Performance” events, that event type won’t show up in the filter list on the Athletics calendar.
However, there may be times when you want to control the front-end display of event types and tags more granularly. Since LiveWhale 1.7, you can do so by adding the following settings in /livewhale/client/public.config.php:
1 | $_LW->CONFIG['CALENDAR_GROUP_CATEGORIES_TYPE']=[]; |
Each of those arrays takes the same format: first, the group ID, then a sub-array of all event types allowed to be displayed in that group. For example:
1 | $_LW->CONFIG['CALENDAR_GROUP_CATEGORIES_TYPE']=[ |
These act as filters on top of the default behavior: so, in the example settings above, group 123 will still only show “Athletics” in the filter list if there are events with that type in the group. However, group 789 will not show the filter “Athletics,” even if there are Athletics events in the group.