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.

Blog New Events

When you create a new event, automatically cross post it to your blog as a post.

Enable Blog New Events by checking ‘Copy new events as posts’

Blog New Event Settings

Settings for templating & timing your blog posts.

The settings for blogging new events are all about mapping your event data to become a post.

Blog Post Content: What content from your event should get submitted as the post content? Options include the event description alone, the entire event content, or custom text entered at event creation.

Blog Post Excerpt: What to create as the post excerpt.

Blog Post Title: Use the event title, or pass a custom format (that can include a template tag for the event title.)

Custom Title Format: A custom format to post to your blog, e.g. “Event Scheduled: {title}”

Custom Post Excerpt or Content: A custom format to post to your blog including template tags from the event, but with original formatting or copy included.

Blog Post Author: Customize the author used for the post.

Blog Post Status: Publish immediately, or post as in an unpublished format for further editing.

Use post permalink for Event URL: Set the link in the Event settings to this blog post.

Post Type: Publish as a post type other than a blog post.

Post publish date: Manipulate the date of the post in relation to the event.

Custom Post Time: Sets a specific time for the post that’s different from the event’s published date. (E.g., if you want an event on your calendar immediately, but want the post published at a scheduled time the next day.)

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.

Event Submissions Settings

General Submissions form settings

Review pending events: By default, events submitted via the public submission forms are assigned “Pending” status, and require approval for publication. This link points to the My Calendar Events Management screen with ‘Pending’ events shown.

Create a submissions form: Although a basic shortcode is automatically created when you in-stall the plug-in, you may want to customize it. This link goes to the shortcode generator so that you can more easily configure the settings for your submission form.

View Event submissions form: Links to your currently defined submissions form. It’s not required to use the primary submissions form, but if you’re offering front-end event editing, then you will need this form to support all of the front-end eligible fields. Set the ID for your event submissions form page in the “Event Submission Page ID” field.

View event editing form: Event submissions can also be edited on the front-end if your users are logged-in. Event editing is not available for users without a log-in. Set the ID for your event editing form page in the “Event Editing Page ID” field.

Date Format hint: What date format is used in the My Calendar date selector.

Time format hint: What time format is used in the My Calendar time selector.

Prevent Conflicting Events: If checked, My Calendar: Submissions will reject event submissions that conflict with a previously scheduled event (in the same location, when location information is being submitted as well.)

Copy submitted locations into locations tables: If a user submits a new location, it will be copied into the location table for other users to choose.

Allow public event submitters to upload images: If checked, submitters will be able to upload images to your site for their event image when that field is included in your form. Otherwise, they must provide a URL to the image.

Automatically publish submitted events: Normally, all events are expected to go through approval. If you want them to just go immediately to the calendar, however, you can allow all events to be automatically approved.

By default, any events submitted by users who already have permission to post events to the calendar will be automatically approved. E.g., if you publish an event from the front-end form while logged-in as an administrator, that event will be immediately published.

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.

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.

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 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.

Manual Entry Payments

Manual payments allow you to accept payments via any method – cash, check, crypto, or alternative online payment – and use those payments to provide event keys. You can also use them to grant free keys at any time, to any user.

Manual payment entry form

Quantity: How many events can be submitted using this key. Each event submitted will reduce this value by one.

Price Paid: The total price paid for this key. There’s no enforcement of a relationship between the price of a key and the number of usages it allows; this value is purely for your own tracking.

Name/Email: Required to send information about the new purchase to the recipient.

Transaction Date: Defaults to today’s date, but doesn’t have any direct impact on the use of the key. A transaction dated in the future will still be usable today.

Multilingual Events

My Calendar Pro ships with support for multilingual event listings. If you’re offering events in more than one language, you can mark the language for each event. This is primarily about screen reader accessibility; when an event is marked as being in an alternate language, the output HTML will be wrapped in a container with the lang attribute set to the chosen language, so screen readers will pronounce the change in language correctly.

This feature is automatically turned on if your site has more than one language installed.

Additional language packs may not be installed if you’re not supporting a fully-translated multilingual site or don’t have any site users using alternate languages for the admin. If so, you can install any WordPress language pack by going to WordPress > Settings > General and changing the Site Language to the desired language. Once the language is installed, you can switch back to your preferred language, but the additional language will remain available.

WordPress Site Language selector, showing English active and Spanish installed.
Selecting a site language.

Once all desired languages are installed, you have the option to choose the site language for your events.

Language selector, showing available languages to choose for an event.
Select an event listing language

Payments Reporting

Table showing keys and usage information.

My Calendar Pro produces a simple report showing sales, dates, and how many times a given key has been used. As a key is used, the remaining uses will be shown.

You can edit any payment to grant additional event licenses or adjust information about the payment:

Editable fields for editing payments

Quantity: The number of event submissions currently available on the event key.

Submissions Purchased: The total number of submissions allowed on this key.

You cannot change the event submissions key once it has been granted.

Search Payments

Searchable fields for payments

Name/Email: Name and email as provided.

Transaction ID: The transaction ID provided from the payment gateway. (Not shown.)

Payment Key: Their event submission key.

After/Before: Get all payments within a date range.

Status: Get payments having a specific status.

Search results

Search results showing results, totals shown, and search limits applied.

Earnings Summary

Summary of payments made

My Calendar Pro provides a brief summary of the current month, current year, previous month, previous year, and all time sales totals.

Public Event Management

Logged-in users can be given access to view and edit events that they submitted to your site.

Event management for public users

The front-end event manager uses the same default sorting as the admin event manager. It can be access using the [submitted_events] shortcode.

[submitted_events]
Display a message to users who don't have access to edit events.
[/submitted_events]

Logged-in users can filter events by location or category, can view their events from the lists, or can edit or delete an event. Deletion is not instantaneous, and will require confirmation:

Pre-deletion warning in editor.

Required Fields

Checkboxes to set specific event fields as required.

By default, no event fields are required except for the start date. If you require additional information from your visitors, you can uses these checkboxes to set some fields as required.

Making any field required will make it required on all public submission forms. If you have excluded a required field from a form, it will be automatically added back in.

Requiring Payments

Event submission is a free service by difficult. There are many membership plugins that can be used to control access to your site or to pages of your site for a fee, but if you simply want to grant a variety of users access to pay to submit events, My Calendar Pro allows that.

Enable payments for Event submissions.

Check the box ‘Require payment to submit an event’ under the ‘Payments’ tab to require payments.

Payment settings are broken into four areas:

  1. Payment Settings
  2. New purchase settings
  3. Pricing
  4. Payment Gateways
  5. Configure a Sale

Payment Settings

  • Set your payment gateway into testing mode.
  • Payment required message.

New Purchase Settings

New purchase notification settings.

Predictability enough, My Calendar Pro sends a message to the administrator and to the purchaser following a new purchase. These fields accept a handful of template tags for dynamic values:

  • {first_name}, {last_name} – as provided by the purchaser.
  • {blogname} – Your site title as configured at WordPress > Settings.
  • {price} – The total amount paid.
  • {key} – The new event submission key the user should use to submit an event.
  • {quantity} – If allowing multiple purchase, how many event submissions this key is good for.
  • {receipt} – Link to the purchase receipt.

Pricing

Pricing options

Each event submission has a base price, which is the default price charged for any event submission.

To more finely configure options, you can set a unique price for each user role and/or set a percentage discount for logged-in members, that will apply to all members.

This is also where you’d set the currency you’re processing payments in.

Payment Gateways

Configure payment gateways

At this time, My Calendar Pro only supports PayPal basic payments. Set your primary PayPal email (this must match the primary email as configured in your PayPal account settings), and add your merchant ID.

Configure a Sale

Set a temporary sale

Configure a special sale or limited-time discount period by entering a start and end date and a percentage discount. My Calendar Pro only supports one sale at a time, and it applies equally to all purchasers.

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.)

Shortcode Generator

The My Calendar Submissions Form shortcode generator

The shortcode generator allows you to generate a heavily customized form with My Calendar’s event fields. You can use the up and down arrows to modify the order of fields, customize labels, set default category or location, and choose which fields are included.

Some types of fields don’t support custom labeling through shortcodes. These fields (registration and recurring settings) are compound fields, and the section of the form you enable with that setting includes multiple form inputs, rather than just a single input.

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.

Submission Notifications

General settings

Set options for event notifications
  • Set whether the submitter should be notified about their submission.
  • Set whether the administrator should be notified about new submissions.
  • Enable HTML notifications (text-only email by default.)
  • Define sending email address.

Messages sent to administrators

Settings for administrator notifications

There are two types of notifications that are sent: one for newly submitted events, and a second if a submitted event is edited. Each option has a separate subject and message text.

The new event notification is sent whenever an event is posted using the front-end submissions form.

The edited event notification is sent whenever an event is edited using the front-end editing form. It is not sent for edits in the admin Event Manager.

Message sent to submitters

Settings for email notifications sent to submitters.

There are three notifications sent to submitters following submission.

  1. Message sent following a new submission.
  2. A message sent if the event is edited by an administrative user in the Event Manager.
  3. A message sent to notify the user that their submission has been published.

Submission Permissions

Set the user group allowed to submit events.

As of version 2.1.0, the submission form requires users to be logged-in to submit events as a default. Previously, it was open to the general public by default.

The third setting allows finer control over who has the ability to add events to your calendar. The ‘Add Events’ capability is configured in the My Calendar Permissions Settings.

Use the [submit_event] shortcode to display a custom message to users without sufficient permissions:

[submit_event]
Hey, you can't submit events! Create an account to submit an event.
[/submit_event]