Groundplan comes with four pre-built responsive event calendars that display all your events.  There are a number of arguments you can include to customize the functionality of this calendar.


Calendar Shortcode

For quick testing purposes, you can include the Groundplan events calendar using a shortcode in any WYSIWYG field.


Example Shortcode Usages 


Monthly Calendar

[gp-calendar type="all" sold_out_message="Call box office"]


Mini Calendar with date details wrapper

[gp-calendar type="mini" wrapper_class="my-calendar-skin" detail_container="#date-details" show_days="90" ]
<div id="date-details"></div>


Mini Calendar for event detail page - with date details and event post ID

[gp-calendar type="mini" wrapper_class="my-calendar-skin" detail_container="#date-details" show_days="90" event_ids="{$post->ID}" ]
<div id="date-details"></div>




Adding Calendars to theme templates

For most installations, you'll want to use the XDGPCalendar class in your templates to configure the calendar exactly how you want.

To create one page per event, add a single-mc_event.php file to your theme folder and paste and modify the following code:


Example Usage - PHP Class



$argsarray(
    'month_format'=> 'F Y',
    'week_start'=> 0,
    'show_genre'=> true,
    'genre_taxonomy'=> 'xdgp_genre',
    'genre_nav_style'=> 'click_to_show',
    'wrapper_class'=> 'xdgp-calendar-main-skin--archetype',
    'wrapper_id'=> 'xdgp-calendar-1',
    // 'first_date' => false,
    // 'last_date' => false,
    'hide_if_single'=> true,
    'show_all'=> true,
    // 'event_post' => false,
    'type'=> 'single'// 'single', 'all', or 'agenda'
    // 'pad' => false,
    // 'show_days' => false,
    'enable_add_to_calendar'=> false,
    'buy_text'=> 'Buy',
    'fast_forward'=> true,
    'priority'=> 'tickets'// can be 'tickets' or 'details'
    // 'perfs' => false,  //override perfs array
    'sold_out_message'=> 'Call For Waitlist',
);
 
 
$calendar new XDGPCalendar($args);
echo $calendar->xdgp_display_calendar();
?>





Configuration Arguments

Swap out the items in the shortcode with these terms below to customize your shortcode. You can pass the following arguments to Groundplan calendars either as shortcode or class arguments.  


General Configuration

 

type

Type of calendar to display.
default: 'all'

"all": monthly with all events in system
"single" : weekly calendar for a single event. Displays only the number of weeks (1 or more weeks) to cover the duration of the event
"agenda": all performances displayed in a vertical list sorted by start time
"mini" : Monthly "widget" style with click interactivity to show performances for the selected date.
"dropdown" : a select menu of all performances in the calendar scope, ideal for tours and events scheduled many times per day. SINCE 0.6.1
"grid": Hourly "Festival" style calendar, organized by venue and day.


wrapper_class(text) Class that wraps the entire calendar.  Use this to apply your own custom skin to a Groundplan Calendar.
wrapper_id
SINCE 1.1.2
(text) ID that wraps entire calendar


Date Configuration


month_format(text)
default: "F Y" for most events, "l, F j, Y" for Grid Calendar
PHP Date format of Month / Heading Labels in Calendar
week_start(int)

default: 0 (Sunday)

Numeric value of first day of week (equal to date('w',$date))
week_end(int) Calculated final day of week
pad'month'
'week'.
Determines length of date padding around current month. Certain calendar types force this value to 'month' or 'week'.
show_days(int) Number of days to show in the calendar range (e.g. for Agenda or Mini Calendar view).  
If show_all is set to true, will display full run of the shows loaded.
fast_forward(boolean) If true, fast forward the calendar to the next performance, if false display the current month even if there are no performances.
paginate_by'month', 'week' or (integer) number of days, or false if not paginated.  Date ranges to split calendar pages into (currently only used by mini calendar, which is set to 'month')
display_date
SINCE 1.1.3
(text) Date in text format (e.g. "December 2017" or "MM/DD/YYYY").  Allows you to request a specific start date for a calendar (e.g. Monthly calendars).  Note that certain modes like fast_forward and available performances may override this setting.  Only used for monthly, agenda, grid, and mini calendars.
display_timezone
SINCE 1.5.5
(boolean) if true, display Time Zones in calendar in short format where times appear (e.g. EDT).  Default is set to the Display Time Zone in Dates? setting in Groundplan >> Settings.


Filter Configuration


show_genre(boolean) If true, show the genre filters at the top of the calendar. Disabled with mini calendars.
genre_taxonomy(text / array)

default: 'xdgp_genre', the built-in Groundplan genre

Taxonomy slug or array of slugs to associate with Genre. Each item in array generates a separate filter on the calendar.
show_venue_filters(boolean) If true, display the venue filters. Disabled with mini calendars.
hide_venue_ids(array) Array of specific venue IDs to hide in venue filters
genre_nav_style'exclude' (default): filters are subtractive, allowing you to exclude events from clicked genres.
'click_to_show': filters will only show chosen genre when clicked.
'dropdown': filters will be arranged in a dropdown menu.


Event Data Configuration


performances(array) Not available with Shortcode. Array of performance objects to display in the calendar. Overrides the automatically generated query.

Warning: Advanced Feature.
In most cases you'll want to use the event_ids and show_days arguments to limit to specific events instead of this argument.  When you don't set this argument, the calendar class automatically loads the performances in the scope you provide. If you don't properly form each performance data object including mc_event and mc_venue attributes, it can break certain elements when displaying the calendar.  
convert_utc(boolean, default true)
true : convert all dates from UTC to local time (the WP Local timezone).
false : do not convert dates from UTC to local time.


suppress_hidden_events
SINCE 0.6.0 



(boolean, default false for single calendar, default true for all other calendars)
true : events hidden using the "Hide this event from the general calendar" setting are removed from this calendar
false : events hidden using the "Hide this event from the general calendar" hidden events are shown in this calendar


event_ids
SINCE 0.7.1



(array | int)
Specify an array of event post IDs to display.
Use with a WP Query to limit calendar to a specific scope of events, e.g. past events or a taxonomy / genre / series / season / venues.
This value is overridden when the $_GET variable 'event' is set in the URL. 


Event Block Configuration


priority

default: 'tickets'
'tickets' : Toggles the links in the event block to click through to Ticket checkout first for all links.
'details' : click to the event detail page when clicking on show image or title.
SINCE 1.1.0 On the grid calendar, priority details suppresses all buy tickets links and instead displays "Details" buttons.


group_performances(boolean). Option for "All" type.
true: Performances of the same event on the same day will be grouped together in a single event block.
false : Each performance is separated into separate event blogs.

Set to true for film festivals or other events where there are many show times in a single day.


enable_add_to_calendar
SINCE 0.8.0 



(boolean). default: false.

Available for calendars of type all, single, agenda, and mini.

true: display iCal and gCal buttons for each performance next to buy buttons
false: do not display iCal & gCal buttons in the calendar.
show_performance_venue(boolean).  default: false
For multi-venue companies.
true: display the venue name in the event block
false: do not display the venue name
performance_type_position
SINCE 1.2.17
default: 'button'
'button': The performance type appears inside the .action__buy button
'before': The performance type appears before the .action__buy button
'after': The performance type appears after the .action__buy button
'top': The performance type appears before the event instance time, at the top of the block.


Monthly Calendar Configuration

Options for the Monthly Calendar type 


month_navigation
SINCE 1.2.16
true: Show a dropdown menu by the current month allowing the user to navigate forward up to 1 year.
false: Do not show the dropdown menu, only the current month.


Single Calendar Configuration

Options for the Single Calendar type 


hide_if_singletrue: hide the calendar when there is a single performance.
false: always show the calendar
show_alldefault: true
true: show all performances for the run in the view
false: display only the next two weeks of performances.
event_post(object). Not available with shortcode.
Specify an event to display with the calendar.



MIni Calendar Configuration

Options for the MIni Calendar type 




detail_container
SINCE 0.8.2 



(text)
When set, disables "hover" mode in the mini calendar and replaces the functionality with a sidecar "date detail" layout. detail_container should be a unique DOM element selector (e.g #date_details) in your theme where the mini calendar will populate performance details for each date that is clicked. (details are hidden on page load by default)


months_per_page
SINCE 0.8.2 



(int) default: 1
Number of months displayed per page. Currently Disables navigation between months. show_days must also be set and exceed this value.


Festival / Hourly Grid Calendar Configuration

Options for the Grid Calendar type 


show_detail_popup
SINCE 1.1.0
(bool) default true
Whether to display an event details popup - including trailer or calendar image, byline and short description.


grid_hour_height
SINCE 1.1.0 



(int) default 84
Pixel count of each hour block height, adjustable to calculate animation JS.  Defaults to match the default skin height.


grid_hour_width
SINCE 1.1.0 



(int) default: 150
Pixel count of each hour block width, adjustable to calculate animation JS.  Defaults to match the default skin width.


grid_venues_height
SINCE 1.1.0 



(int) default: 56
Pixel count of each venue label height, adjustable to calculate animation JS.  Defaults to match the default skin height.


grid_max_venues
SINCE 1.1.0 



(ind) default: 5
Number of venues to display before switching to a horizontal scroll.  Does not apply to mobile.
grid_venue_sort
SINCE 1.1.0 
(text) 'density', 'menu_order' or 'abc', default 'density'
Method of sorting venues within the grid.
density: busiest venues are sorted to the left.
abc: venues are sorted alphabetically.
menu_order: Venue menu_order is honored, which can be modified with reorder plugins.



Education Plugin Calendar Configuration




event_template_taxonomy
SINCE 1.1.17



(boolean)
When set, displays a calendar filter by event template type (e.g. "Class" or "Event")


event_template
SINCE 1.1.17





(string | array)
Limit event results by event template type.
(e.g. "class" or "default")


Language Configuration


buy_text(text)
default: 'BUY'
Text for "buy" buttons.
buy_text_class
(Education Add-On)
(text)
default: 'Register'
Text for calls to action on Classes
sold_out_message
(text)
default: 'Sold Out'
Text to display when a performance is sold out.



URL Parameters

The following arguments can be passed as URL parameters to the page on which the calendar displays to modify calendar features like date range.


?event={post_id}
?event[]={post_id_1}&event[]= {post_id_2}


(int | array) ID number of a single mc_event post. Limits the display of performances to only that event.
Supports arrays of events SINCE 0.7.1


?exclude={array}
?filter={array}
?exclude_venue={array}
?filter_venue={array}
(array slugs, separated with spaces) Used by filters to hide (exclude) and show (filter) events belonging to specific venues or genres.
Note that for dropdown filters, there should only be one specified filter or filter_venue in the array
?month={month+year}(text) specify a specific month for the calendar to display.  (Same argument as display_date)
Usage: http://example.com/calendar?month=December+2016



Calculated Calendar Attributes

These parameters cannot be configured, they contain information generated by Groundplan based on calendar type.


config(array) Arguments passed to the calendar for use in filters.
pad_weeks(boolean) if true, load performances to the beginning and end of actively displayed weeks.  True by default, but set to false in Agenda view and views like it.
days_order(array) Sequence of days, using php integer format (see docs for date() function)
starttime(timestamp) beginning of requested date range.  Does not include Padded time.
endtime(timestamp) end of requested date range.  Does not include Padded time.
calendar_starttime(timestamp) beginning of currently active calendar range.  Includes Padded time. For paginated calendars, this is the start of the first calendar range.
calendar_endtime(timestamp) end of currently active calendar range.  Includes Padded time. For paginated calendars, this is the end of the last calendar range.
date_range(array) Array of date timestamps (and with some calendars, performances) ranging from $calendar_starttime to $calendar_endtime. Not paginated.
events_by_date(array) (array) Array of arrays of groups of dates and performance information. Organized into pages for paginated calendars that can be navigated without a page reload.
first_performance(MCEventPostType object) $post of First Performance returned.  Used to check for presence of performances within a date range.
grid_venues(array) Venues included in a Grid Calendar
grid_days(array) Dates included in the scope of events in a Grid Calendar
grid_min_hour(integer) date('H') format, e.g. '03'. Start time for each day within the grid calendar.
grid_max_hour(integer) date('H') format, e.g. '03'. End time for each day within the grid calendar.