My Calendar – API

The My Calendar exports API is enabled at My Calendar > Settings > General. This API allows you to generate a CSV, JSON, or iCal formatted export of My Calendar event data.

My Calendar > Settings > General

The API is not enabled by default. Once enabled, you can access it using URL parameters on your site:

http://www.example.com/?my-calendar-api=json&from=2021-02-01&to=2022-01-31

The my-calendar-api parameter is used to set the export format, and accepts json, csv, and ical as options.

Parameters

  • my-calendar-api: format to return, ‘json’, ‘csv’, ‘ical’
  • from: starting date to retrieve, YYYY-MM-DD (default: current date.)
  • to: end date to retrieve, YYYY-MM-DD (default: 7 days from today.)
  • mcat: Category ID to limit by.
  • ltype: Location type to restrict to (keywords: ‘name’, ‘city’, ‘state’, ‘zip’, ‘country’, ‘region’)
  • lvalue: Location value to match against location field type
  • author: Events by author ID
  • host: Events by host ID.
  • search: text search query terms.

Private events are automatically excluded from exports.

Once enabled, the export API is public by default. You can restrict access to the API using your own program logic using the filter mc_api_key.

/**
 * Check for and validate access to the My Calendar exports API.
 *
 * @return bool False to block; true to allow.
 */
function your_api_key() {
	$valid = false;
	// This example assumes the addition of an additional request parameter. However, any logic could be used here.
	if ( isset( $_REQUEST['mc_api_key'] ) ) {
		$valid = your_validate_key( $_REQUEST['mc_api_key'] );
	}

	return $valid;
}
add_filter( 'mc_api_key', 'your_api_key' );

Settings – Display

Display Settings is located under My Calendar > Settings > Display.

Main Display Settings: view titles, fields shown in different views.

Grid

Event title (Grid) {time}: {title}

Example with adding in the word “Event Title” into the Event title (Grid) field.
I added shortcode: {time} Event Title: {title}

Frontend view:

My Calendar > Settings > Text > Event title (Grid). Frontend view.


Single

Event title (Single) {title}

Example with adding in the word “Event Single Title: ” into the Event title (Single) field. I added the shortcode: Event Single Title: {title}

Frontend view:

My Calendar > Settings > Text > Event Title (Single). Frontend view.


List

Event title (List) {title}

Example with adding in the word “Event List Title” into the Event title (List).
I added the shortcode: Event List Title: {title}

Frontend view:

My Calendar > Settings > Text > Event title (List). Frontend view.

These are the changes I made:

My Calendar > Settings > Text - Templating fields.
My Calendar > Settings > Text – Templating fields.

Event Display Fields

The series of check boxes gives you the ability to display or hide a variety of different fields directly in the frontend for Single Event, Calendar Popup/List View, and Mini Calendar Popup.

Settings for Single Event, Main View (Popup or List) and Mini Calendar Popup.

Choose fields to show in the various frontend views. Adjusting the templates can override these settings. Unclicking/Unsetting all the values will bring back the default values.

Single Event

My Calendar > Settings > Display – Event Display Fields – Single Event

Default frontend fields for the Single Event.

My Calendar > Settings > Display – Event Display Fields – Single Event. (Theme: Twenty Twenty One.)

Main View (Popup or List)

My Calendar > Settings > Display – Event Display Fields – Main View (Popup or List)

Default frontend view for the Main View: Popup.

My Calendar > Settings > Display – Event Display – Main View – Popup. (Theme: Twenty Twenty One.)

Default frontend view for the Main View: List.

My Calendar > Settings > Display – Event Display Fields – Main View – List (Theme: Twenty Twenty One.)

Mini Calendar Popup

My Calendar > Settings > Display – Event Display Fields – Mini Calendar Popup

Default frontend view for the Mini Calendar Popup.

My Calendar > Settings > Display – Event Display Fields – Mini Calendar Popup. (Theme: Twenty Twenty One.)

Clicking the event the Mini Calendar Popup.

My Calendar > Settings > Display – Event Display Fields – Mini Calendar Popup is open. (Theme: Twenty Twenty One.)

Calendar Navigation

Update calendar layout
Define a default layout for calendars. Use the arrow icons to move fields up or down or use drag and drop to rearrange the order these are seen in. Click the eye to hide fields. These settings will be overridden if you customize the field settings in the My Calendar shortcodes.

My Calendar > Display > Calendar Links and Update calendar layout

Default Frontend view containing one event:

My Calendar > Settings > Display. Viewing default calendar layout on frontend. (Theme: Twenty Twenty One.)

View Options

How many months of events to show at a time: Sets how many months will be shown at one time by the main calendar shortcode in list, grid, and mini view. Also configurable via the shortcode.

Grid Options

Calendar Links

Open links as a pop-up
Opens a pop-up card and one can click “Read more” to continue to the single event view.

Open event links in single event view
Bypasses the pop-up card and goes straight to the single event. Improves performance with large numbers of events.

Disable calendar links
This option will disable all event links in the main calendar. Useful for a minimal-information view.

Mobile View: Adjusts how the calendar will be rendered on mobile devices. It can switch to list view, switch to mini calendar view, or have no change.

Show Weekends on Calendar: If enabled, Saturday and Sunday (weekend days) will be included in the calendar grid.

List Options

Show the first event’s title and the number of events that day next to the date. In the list view, the toggle to expand events for a day is normally just the current date. Use this to show more information.

Show all event titles next to the date. Instead of just showing the first event, show all event titles for the date.

Mini Calendar Options

Target link for mini calendar dates – This URL is the destination you want links from the mini calendar to use.

Link action for mini calendar: Event pop-up, daily view page (above), in-page anchor on main calendar page (list), in-page anchor on main calendar page (grid).

My Calendar > Settings > Display – Grid Options – List Options – Mini Calendar Options.

Next: My Calendar > Settings > Input.

Settings – General

General Settings is located under My Calendar > Settings > General.

My Calendar > Settings > General

My Calendar Management

Calendar Page Location

“My Calendar” is the title automatically added to the page that is created to display the calendar. You can edit this page as a normal page at Pages > All Pages.

Default sort order for Admin Events List

The Events screen columns can be ordered by Event ID, Title, Date/Time, Author, Category and Location. One can also directly reorder the Event list by clicking the column headings on the Events screen.

Default sort direction

Descending (Z-A) or Ascending (A-Z).

Checkbox clicked: for Pretty Permalinks will show a similar slug to this example. https://example.com/mc-events/a-new-event/?mc_id=1

Website name / events base / event title / event ID.

Checkbox not clicked: not showing pretty permalinks will show a similar slug to this example. https://example.com/my-calendar/?mc_id=1

It will not use the events base in the slug.

With pretty permalinks enabled, single event views are rendered using your theme’s single.php template file. Otherwise, single event views are rendered by the My Calendar shortcode on your calendar page.

Go to Settings > Permalinks to change the base URL for events and locations.

My Calendar WordPress plugin. Setting Permalinks for Events and Locations.


The following example in changing mc-events to concerts with pretty permalinks activated: https://example.com/concerts/a-new-event/?mc_id=4

Advanced section

Get data (events, categories and locations) from a remote database.

This option allows you to share data between multiple sites if they all need matching calendars.

  1. It requires you to enable remote database access on the source site as a hosting option in the hosting control panel or by contacting your host.
  2. Once you enable the option, you will need to add code to your theme’s functions.php file to make the remote connection work.
function mc_remote_db() {
        $mcdb = new wpdb('DB_USER','DB_PASSWORD','DB_NAME','DB_ADDRESS');
        return $mcdb;
}

Replace the above placeholders with the host-site database information. The two sites must have the same WordPress table prefix. While this option is enabled, you may not enter or edit events through this installation.

Enabling a remote data connection will disable Adding and Managing Events, Locations, and Categories, as all that data will be drawn from the remote database. Scripts, settings, and styles are still managed from the local installation.

Example:
You own two movie theaters, and they show the same movies at the same times. Rather than enter every event twice, you can remotely access the database for theater 1 so that both theaters display exactly the same event information. The two sites can have completely different designs, and show calendars in different ways, but share the same events.

Enable external API

Enable to acquire custom event data in JSON, CSV, or iCal (.ics). When you enable the External API, the URL for requests to your API will be displayed. This API does not use the WordPress REST API.

A REST API is available for My Calendar if you have My Calendar Pro activated. Read more about the Enable external API.

Drop MySQL tables on uninstall

Check this option prior to uninstalling My Calendar to also delete all event data.

Delete plugin settings on uninstall

Check this option prior to uninstalling if you wish to delete all the settings you have configured.

Import & Export Settings

Exporting your settings will allow you to download a JSON file with your site’s current settings. You can then import those settings again after making changes or into another site.

There’s a JSON copy of the My Calendar default settings available as defaults.json in the root of the My Calendar plugin directory.

Settings on other screens

Settings > Permalinks: Events permalink slug (mc-events)
Settings > Permalinks: Location permalink slug (mc-locations)
Settings > General: First day of the week

My Calendar: Setting Permalinks for Events and Locations.

General WordPress settings

There are two important settings controlled outside the plugin:
the time zone events are displayed in and the day of the week the calendar starts on. These options are set from the WordPress general settings: Dashboard > Settings > General.

Next: My Calendar > Settings > Text.

Settings – Input

Calendar Input Settings is located under My Calendar > Settings > Input.

My Calendar > Settings > Input

Calendar Input Fields

Event editing fields to show
Restrict your event authors from using certain fields, or reduce the number of fields you see when creating or editing events, use these options to remove the fields you do not plan to use.

Example: Uncheck Categories and Event Location. Click Save Input Settings. Go to create a new (add) Event or open an existing event. Notice Categories and Event Location inputs have been removed. This will remove Categories and Event Locations for all users.

An alternative method is to use Screen Options in the Add Event or existing event screen to hide fields. Example: Categories and Event Location for all events. This will remove Categories and Event Locations just for my user.

Event: Screen Options. Event editing fields to show.

Notice the two different approaches. Output Settings will removes a field for all users. Screen Options removes it just for yourself.

Location Controls

With Location Controls we can define the values one can select when adding a new location. Save custom values to change location text fields into dropdowns. One field per line. Format: saved_value,Displayed Value

We can add adjustments to the following Input Settings Location Controls Fields:

  • Name of Location.
  • City
  • State/Province
  • Postal Code
  • Region
  • Country

Changing any of the above name/value pairs will also change the name (value) seen in the Location fields, but does not change previously saved data.

Here is an example: Adding Montana – MT, Minnesota – MN and Maine – ME to the location controls for State/Province.

My Calendar > Settings > Input > Location Controls

The Add New Location screen.
We will see a dropdown in the State/Province field. Because of the above adjustment.

My Calendar > Add New Location > State/Province drop down

Being able to control the Location Controls gives us the opportunity to finetune the setup when adding a new location. As we can limit various fields one is able to insert.

Next: My Calendar > Settings > Permissions.

Settings – Multisite

The following Multisite screen will be seen if you have the Multisite Network setup activated. My Calendar > Settings > Multisite.

My Calendar > Settings > Multisite

Multisite configuration – input

Site owners may only post to their local calendar.
Site owners have access to post only to their own sub site calendar.

Site owners may only post to the central calendar.
Site owners can only post to the primary sub site calendar.

Site owners may manage either calendar.
Site owners can manage their own sub site and the primary (sub) site calendars.

Multisite configuration – output

Sub-site calendars show events from their local calendar.
Show events from only the sub site calendar.

Sub-site calendars show events from the central calendar.
Show events from the primary sub site calendar.

Settings – Notifications

Calendar Notifications Settings is located under My Calendar > Settings > Notifications.

My Calendar > Settings > Notifications

It can be useful for notifications to be sent out when new events are submitted or created by lower-level subscribers, as these events might need administrative approval to be posted to the calendar.

Calendar Email Settings

Email Notifications

Send Email Notifications when new events are added.

Send HTML email
If you select this option you can include your complete HTML template within the Message Body Field.

Notification messages are sent to:
If you wish to send notifications to multiple email addresses, you can enter them separated by commas.

My Calendar Pro version
The plugin will send notifications when events are submitted from the public interface. Those are a separate set of messages. Both notifications will be sent; but they do not need to be sent to the same person.

Notification messages are sent from:
BCC on notifications (one per line):

Email subject – subject line of email
Message Body – message sent (template tags available.)

Settings – Permissions

Calendar Permissions Settings is located under My Calendar > Settings > Permissions.

My Calendar > Settings > Permissions

My Calendar Permissions

Permissions in My Calendar are granular, so you can provide user roles with access only to specific portions of My Calendar. It supports custom roles, as well, so you can grant permissions to any role you create or that is created by a membership plugin.

The administrator role has all capabilities, and you can not remove these in My Calendar.

Event Editing Permissions

  • Add Events: Grants users access to enter new events as drafts
  • Approve Events: Grants users the ability to publish events added by other users.
  • Publish Events: Grants the ability to publish your own events.
  • Manage Events: Grants full access to editing and publishing events.

Next: My Calendar > Settings > Notifications.

Settings – Text

Text Settings is located under My Calendar > Settings > Text.

My Calendar configurable text output fields. About 20 text fields usable to customize text shown in My Calendar views.

Text Settings

My Calendar gives control over a number of text fields via this section of settings. These are not the only elements of text that can be controlled; almost any element of event and date output can be modified.

Templating

In My Calendar 3.4.0, templating settings were moved to the ‘Display’ tab.

Main Calendar View

My Calendar > Settings > Text > Main Calendar View

My Calendar provides adjustable forward and backward navigation link text.

Previous events link – Previous
Next events link – Next

Here is an example of adding {date} to Previous {date} and Next {date} to indicate what month and year is being navigated to.

The frontend will show the Previous and Next links along with the month and year.

My Calendar > Settings Text > Previous and Next with Date shortcode. Frontend view.

Week view caption.

The default caption is “Week of” and the date.

Week view. It only supports the template tag for {date}. Here is an example of adding {date} and the words “Week view caption” to the Week view caption field. This is the template I set: Week view caption {date}. On the frontend we can see the caption followed by Monday’s date.

My Calendar > Settings Text > Week View Caption. Frontend view.

We can also adjust the date format by adding this shortcode: {date format=""}
Example F j,Y so we get Week view caption {date format="F j, Y"} the result would be:

My Calendar > Settings Text > Week View Caption date format. Frontend view.

The bottom of the Text settings we get an overview of the Date/Time Formats.

Extended caption.

Extended caption. Add text if you want additional information than month and year in your calendar heading. Here is an example of adding the words “This is the extended caption” to the calendar heading.

My Calendar > Settings Text > Extended caption. Frontend view.

Single Event View

My Calendar > Settings > Text > Single Event View

Label for all-day events All day can be changed in two places. Through the Text settings or when creating a new event or editing an event.

Changing it through Text settings will change all of the “Label for all-day events” labels. Changing it while creating an event or editing an event will only change the label for the individual event.

Hosted by Hosted by
Posted by Posted by
Buy tickets Buy tickets
Event Accessibility Heading Event Accessibility
View full calendar View full calendar
Read more text Read more

Here is an example of a single event where one can see most of the text that can be modified.

My Calendar > Settings > Text > various options. Frontend view.

More Information text More information
Browser tab title element template {title} » {date}

Date/Time formats

Primary Date Format F j, Y
Time Format g:i a
Month Format (calendar headings)
Date in grid mode, week view M j, ‘y

Date formats

F = month
M = first 3 letters of the month
j = day
Y = Year

Time formats

g = hour
i = minutes
a = am/pm

For additional information: Date formats use syntax from the PHP date() function. See the My Calendar documentation for more information about Event Template tags.

Next: My Calendar > Settings > Display.