Import Events from My Calendar

If you need to import events from another site running My Calendar, you can do this using the My Calendar event export API with the My Calendar Pro importer. This requires the My Calendar export API to be enabled from the source site, which it is not by default.

Once the external API is enabled on the source site, you can use the normal My Calendar Pro imports to fetch events.

The URL you’ll need to use will follow a predictable pattern:

https://www.yourdomain.com/?mc-api=csv&from=YYYY-MM-DD&to=YYYY-MM-DD

All of the available parameters are documented in the My Calendar external API documents; you can import any set of events you choose from within those specifications, with a couple of exceptions:

  • Private events are always excluded from exports.
  • Drafts and trashed events are excluded from exports.
  • Archived events will be included.

If the source site makes heavy use of recurring events, then there will be a significant mismatch between the number of events the importer tells you it’s importing and what it actually imports. The number of events it starts with is simply the number of rows in the CSV file; My Calendar Pro has not yet processed the events in any way.

During processing, My Calendar Pro will only import one of any given recurring event, and use that event to generate the recurring series – all other events in the series will be discarded.

If you select a date period that includes recurring events, the recurring events will be propagated from the time the recurring event started, and will not be limited to within the period imported.

REST API Client

Settings for REST API Clients

If your site is a client, then the REST API is not enabled, but the user interface for adding your events to other site’s is enabled. You will have an interface for adding endpoints, or URLs that this site can attempt to send events to.

Settings

The API key entered for endpoints must be that provided by the API server. This is the default API key; if you’re using multiple endpoints, each endpoint can have a unique API key.

URL: The home URL for the My Calendar server.

Label: The label that will be displayed in the user interface for selecting where to send events.

Author: The author ID that should be sent as the author on the remote site. This will probably not be an author ID that exists in your site, so you will need to be provided with an appropriate author for the target site.

Key: The API key for the target API server. If left blank, queries will use the API key set globally.

Cross Posting Events

Cross posting events to remote sites

When the site is a client, any configured servers will be shown in the admin ‘Add Events’ interface as options to select for target. The events will always also be added to the current site.

Cross posting is not available from the public submissions form.

REST API Server

REST API Server settings

For sites operating as an API server, you have to configure the clients that you are allowing access to post events. Only clients that match these client URLs and pass the API key you define will be allowed to post events.

Settings

API Key: You can set the API key for your site. This is an API key that any other site will need to have entered in their Endpoint settings in order to be allowed to post events on your site.

URL: The home_url() value of a site that you are granting permissions to post events to your site.

Label: How that site will be labeled when it is shown on your site as an event source or when filtering events.

Display on Calendar: Whether the display of events from these clients should default to ‘on’ or ‘off’. If ‘off’, the events will be hidden by default. They are still available, just not visible by default.

Widget/Shortcode

When your site is operating as a server, the My Calendar API Filters widget or [my_calendar_api_sources] shortcode can be used to display controls for enabling and disabling events from the various sources (similar to the category filtering in the default calendar.)

Event Sharing with the REST API

REST API Configuration options: disabled, server, or client.

Any site with My Calendar Pro installed can be set up to share events with another site that has My Calendar Pro installed. For security purposes, there are a number of controls in place to restrict how that works.

You can enable the REST API from the My Calendar Pro settings. By default, the REST API is fully disabled, and there’s no access to it. You can either enable My Calendar to act as a REST API server or as a REST API client.

Import Events from CSV

A .csv file, or comma separated values file, offers a significantly more flexible way of importing events than the standardized iCal format (.ics). While .ics files are standardized, they’re also quite limited in how they’re structured and what information can be included.

The only absolutely required fields are event_title and event_begin, but you can also automatically generate categories and locations from your CSV import file.

Your CSV file must have a header row that includes the field names as listed below, e.g. “event_id,event_title,event_begin”. The header row will be used to map values to My Calendar’s data structures.

Supported CSV Fields

  • event_title: Title
  • event_begin: Starting Date
  • occur_begin: Starting Date
  • event_end: Ending Date
  • occur_end: Ending Date
  • event_time: Starting Time
  • event_endtime: Ending Time
  • content: Description
  • event_desc: Description
  • event_short: Excerpt
  • event_link: External event URL
  • event_link_expires: Link expiration
  • event_recur: Recurring frequency period: S – single, D – day, E – weekdays, W – weekly, M – month/date, U – month/day, Y – year.
  • event_repeats: Number of repetitions or date to repeat until. 4 = event repeats 4 times, for a total of 5 occurrences. 2022-05-25 means “repeats until May 25th, 2022”.
  • event_every: Recurrence frequency multiplier. D + 3 == every 3 days, 2 + W == every two weeks.
  • event_image: Event Image URL
  • event_allday: Event is all-day
  • event_author: Author ID
  • event_approved: Publishing status
  • event_category: Category Name or ID
  • category_color: Category Color
  • category_icon: Category Icon
  • category_private: Category Privacy status
  • event_fifth_week: Omit week 5 recurrences
  • event_holiday: Cancel on Holidays
  • event_group_id: Event Group ID
  • event_span: Event spans multiple days
  • event_hide_end: Hide end date
  • event_status: Event Status
  • event_flagged: Event Flagged as Spam
  • event_tickets: Event Tickets Link
  • event_registration: Event Registration Info
  • event_host: Event Host ID
  • event_access: Event Accessibility Data
  • location_preset: Location ID
  • event_label: Location Label
  • event_street: Location Street
  • event_street2: Location Street (2)
  • event_city: Location City
  • event_state: Location State
  • event_postcode: Location Postcode
  • event_region: Location Region
  • event_country: Location Country
  • event_url: Location URL
  • event_phone: Location Phone Number
  • event_phone2: Alternate Location Phone
  • event_longitude: Location longitude
  • event_latitude: Location latitude
  • event_zoom: Map zoom level
  • event_location: Location ID in locations table
  • mc_copy_location: Copy location into DB
  • UID: Unique event ID. If an event exists with this UID already, it will be updated instead of added.
  • event_added: Date this event was added to source calendar

Import Events

Event import user interface. Upload file or input URL.

Import Settings

Restrict event import by time: If you have an import file that contains a wide range of events, you can restrict your import to a subset of those events based on date.

  • Ignore events in the past
  • Ignore events more than a month in the past
  • Ignore events more than a year in the past

Remote import frequency: When importing events by URL, you can set a regular import schedule. This is useful for importing from sources that update periodically. As long as the import source includes a unique ID field, you won’t have to worry about importing duplicate events.

The import frequencies are based on your existing cron schedules, so they may vary, but the default frequencies are:

  • One time import
  • Once Weekly
  • Once Monthly
  • Once Hourly
  • Twice Daily
  • Once Daily
Import to category setting when importing .ics URLs

Import to Category: If you’re importing an iCal source from a URL, you can assign the events from this URL to a specific category in your calendar. The iCal format doesn’t include any native data that can be used as a category.

Scheduled Imports

An import scheduled weekly.

When you schedule an event import, the first automatic import will be scheduled for the future at the end of the current interval. To get the current events, complete the import in the same way you would for a one-time import. If you do not complete the one-time import, the schedule will still be established.

Individual scheduled imports can be deleted, but not edited.

Shortcodes

My Calendar Pro includes six shortcodes:

[advanced_search]

Outputs the advanced search form.

Attributes:

  • date – ‘false’ to exclude date parameters from search.
  • author – ‘false’ to exclude author parameters from search.
  • host – ‘false’ to exclude author parameters from search.
  • category – ‘false’ to exclude categories from search.
  • location – ‘false’ to exclude locations from search.
  • home – integer ID attribute used to generate the target URL for searches (used to render searches on a page other than the current page.)

API Sources

[my_calendar_api_sources]

When you’re using the REST API to allow external sites to send events to your calendar, this shortcode is used to output a list of external sites that are registered to send events. The list contains buttons for each source and is used along with the main calendar widget to enable and disable events from a given source on the calendar.

Attributes: none.

Submit Payment

[submit_payment]

When payments are enabled, the ability to purchase payment keys are automatically added at the top of the Event Submission form. The submit payment shortcode provides a payment mechanism that’s independent of the event submissions form, so that you can invite users to purchase submission keys in a more compact context.

Attributes: none.

Geolocate

[geolocate]

Generates a map of all My Calendar locations within a given distance of a specified latitude and longitude. Requires loading a geolocation database (not included in standard package due to size, but available on demand.), and enabling via filter.

Attributes:

  • latitude – Centering latitude. If not provided, the map will attempt to source from the user’s IP.
  • longitude – Centering longitude. As above.
  • radius – Radius to search within in kilometers.
  • limit – Maximum number of locations to return.

Submit Event

[submit_event]

Form to submit events to the calendar. This is a highly complicated shortcode, and using the shortcode generator is the recommended way to build these shortcodes.

Attributes:

  • fields – Comma separated list of field IDs to include in form.
  • categories – 1 to include categories form, 0 to exclude.
  • locations – ‘either’ (select form and enter new location), ‘enter’ (new locations only), ‘none’, or ‘choose’ (select an existing location).
  • category – Integer for the default category a form should submit.
  • location – Integer for the default location a form should use.
  • location_fields – Comma separated list of location field IDs to include in form.
  • form_id – Unique ID to represent this form.

Submitted Events

[submitted_events]

A table of events that the current logged-in user is allowed to edit.

Attributes

  • orderby – Default ordering. Table is sortable by the user, so this is just how it appears by default.
  • order – ‘desc’ or ‘asc’
  • past – Include events from the past. Defaults to ‘false’; ‘true’ to include.

Advanced Search

Advanced Search Form

The search form shows all the configured options from the Advanced Search settings screen. The Type of location search will toggle between different input types (select or free text) depending on the type of information being searched.

Search results

The default output is simple, but customizable. After searching, you will be shown the results of your search followed by a search form set to your previous search parameters.

Advanced Search Settings

The event search available in My Calendar is a simple text search, with no filtering or bonus search tools. My Calendar Pro adds options for a richer search that makes it easier to narrow down what a user is looking for.

Advanced Search Settings

The advanced search has a dedicated Page on your site that will be added when you save the search settings.

In advanced search, you can enable searching by:

Dates: Set a start and end date to search within a range.

Author/Host: Search only for events by a specific event publisher.

Category: Limit search to events in a given category.

Location: Limit search to events matching specific location characteristics.

Location searches can search by the location name, city, state, country, postal code, or region.

“Region” is not a formal location structure; this is a field in My Calendar locations that you can use to separate groups of locations by a more generalized grouping. For example, this field could be used for neighborhoods, service areas, or any other abstract grouping.

Search Results Template

Search results are displayed in a list format by default, but the structure of the resulting information in that list can be customized using the same model the rest of My Calendar’s templating uses.

Events From Posts

The reverse of “Blog new events”, this feature allows you to generate a calendar event while creating other post types.

Enable event creation from posts by checking “Post events from posts”

Event from Posts Settings

Choose post types & event status

Support post types: All public post types are available; check the post types where you’d like to be able to create new events.

Events are drafts: Check ‘Events from Posts are always created as drafts.’ to default all new events as drafts.

Creating Events in Posts

My Calendar Pro adds a meta box with a slightly reduced version of the My Calendar “Add Event” form on enabled post types.

My Calendar Pro event meta box in the block editor

The events metabox includes most of the same fields available in the My Calendar user interface.

Featured Images: My Calendar events created here will use the featured image set on the post.

Copy events: You can’t create multiple copies of an event from a post; only single or recurring events.

The form is used only for creating new events; once the event is created, it should be edited in the My Calendar event manager. Events are only created if the event title field is not empty.

Meta box showing the event created.

After posting an event, the metabox will link to the event page associated with the new post.