Calendar Format

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.

The “outside” of your calendar (header, footer) and calendar settings (which groups/types/tags to include/exclude and other calendar widget settings) are covered in Calendar Basics.
The “inside” of your calendar (the day/week/month/event views or individual UI elements) is customizable as Calendar Components.
You can customize your calendar appearance using Calendar Styling.
More advanced customization can be done using Custom JavaScript.

Calendar Basics

Any calendar page generally includes two files:

/livewhale/theme/core/includes/calendar_head.html
This goes inside <head></head> and contains meta tags, CSS/JS, etc.
/livewhale/theme/core/includes/calendar_template.html
This goes inside <body></body> and contains the rest of your calendar.

(In some cases, there may be a single include of a main_template.html file, containing the above.)

In particular, calendar_template.html includes:

Your site header (included from calendar_header.html)
Widget arguments for your calendar (included from calendar_widget.html)
the HTML that lays out your calendar’s elements
Your site footer (included from calendar_footer.html)

Like all theme files—although you’ll see the URLs reference /theme/core, LiveWhale will check first to see if you contain files matching those names in your theme folder. So you’ll edit your main calendar templates at

/_ingredients/themes/global/includes/calendar_head.html
/_ingredients/themes/global/includes/calendar_template.html
/_ingredients/themes/global/includes/calendar_header.html
/_ingredients/themes/global/includes/calendar_widget.html
/_ingredients/themes/global/includes/calendar_footer.html

Customizing settings on a per-group basis

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_widget.html in the group that matches your theme name.

For example, in the “music” group, /_ingredients/themes/global/includes/calendar_widget.html will be overridden by /_ingredients/themes/music/includes/calendar_widget.html.

Calendar Components

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/templates/calendar/, they will override the defaults from the core theme. (For some clients, we’ve copied them already to /_ingredients/themes/global/templates/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.)

View Components

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)

Optional View Components

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.

UI Components

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

Calendar Styling

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:

/* Import core calendar styles */
@import "../../../../livewhale/theme/core/styles/calendar.less";

 /* Import core calendar mobile mixins */
@import "../../../../livewhale/theme/core/styles/calendar-mobile.less";

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:

@highlight1:  #c00; // Primary color
@highlight2:  #900; // Secondary color
@white:       #fff;
@dark-gray:   #333;
@mid-gray:    #2a3132;
@light-gray:  #eee;
@accentfont:  inherit;

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.

Using mobile mixins

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

Example usage:

 /* Import core calendar mobile mixins */
@import "../../../../livewhale/theme/core/styles/calendar-mobile.less";

// Set the mobile breakpoint
@media only screen and (max-width: 767px) {
	.mobileViewSelector(); // use the mobile view selector
	.mobileMonthViewGrid(); // use a grid of dots for month view
	.mobilePaymentsTable(); // use the mobile RSVP form
}

Custom JavaScript

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.

(function($, LW) {

	// Events:
	// calBeforeInit.lwcal   - fires after exported symbols exposed and before controller initialization
	// calInit.lwcal         - fires after first view data loads
	// calBeforeChange.lwcal - fires before loading new view data
	// calChange.lwcal       - fires after loading new view data
	// calLoad.lwcal         - fires after each view finishes loading
  
	$('body').bind('calBeforeInit.lwcal', function() {
		// do something before the calendar loads
	});

	$('body').bind('calInit.lwcal', function() {
		var lwcal = LW.lwCalendar;
		var controller = lwcal.controller;
		// do something after first data loads
	});

	$('body').bind('calLoad.lwcal', function(e, controller, data) {
		var view = controller.getView();
		if ('day' === view) {
			// do something on day view
		}
		if ('week' === view) {
			// do something else on week view
		}
		if ('event' === view) {
			// do something else on event view
		}
	});

}(livewhale.jQuery, livewhale));

Event Type and Tag Settings

By default, LiveWhale will display all your calendar event types and tags as front-end filters, using the following theme tags:

<xphp var="lw_calendar_categories"/>
<xphp var="lw_calendar_categories_audience"/>
<xphp var="lw_calendar_categories_campus"/>
<xphp var="lw_calendar_tags"/>

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:

$_LW->CONFIG['CALENDAR_GROUP_CATEGORIES_TYPE']=[];
$_LW->CONFIG['CALENDAR_GROUP_CATEGORIES_AUDIENCE']=[];
$_LW->CONFIG['CALENDAR_GROUP_CATEGORIES_CAMPUS']=[];
$_LW->CONFIG['CALENDAR_GROUP_TAGS']=[];

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:

$_LW->CONFIG['CALENDAR_GROUP_CATEGORIES_TYPE']=[
	123 => ['Athletics', 'Exhibitions', 'Performances', 'Lectures'],
	456 => ['Athletics', 'Performances', 'Lectures'],
	789 => ['Exhibitions', 'Performances', 'Lectures']
];

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.