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
|
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_single | true: hide the calendar when there is a single performance. false: always show the calendar |
show_all | default: 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. |