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.
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.
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.
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 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.
When you create a new event, automatically cross post it to your blog as a post.
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.)
My Calendar supports custom fields to collect event information that isn’t natively supported by My Calendar. Since My Calendar Pro 3.0.0, you can create your custom fields directly in the admin.
Custom field types supported include text, email, number, date, time, url, tel, select, checkbox, radio, textarea, and hidden fields.
Custom fields can also be defined in PHP for more advanced configuration or defined in a JSON file called mc-custom-fields.json, stored in your plugins/my-calendar-custom directory or in your theme directory. An example JSON definition file is in the plugin’s root folder.
All custom fields will be listed in the custom field editor, though PHP and JSON fields can’t be modified in the editor.
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.
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.
Event submissions page: 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.
Event editing page: 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.
Create new submissions forms: Although a basic shortcode is automatically created when you install the plug-in, you may want to customize it. This link goes to the shortcode generator so that you can configure the settings for your submission form.
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.
Use AJAX form submission: As of My Calendar 3.0.0, submitting dynamically using AJAX is the default. If you wish to disable this, you can do so. If you’ve upgraded from an earlier version, you can enable AJAX here.
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.)
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.
The reverse of “Blog new events”, this feature allows you to generate a calendar event while creating other post types.
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.
My Calendar Pro adds a meta box with a slightly reduced version of the My Calendar “Add Event” form on enabled post types.
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.
After posting an event, the metabox will link to the event page associated with the new post.
The My Calendar submissions form builder allows you to generate heavily customized forms 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.
Any custom fields created in the Custom Field editor will automatically be added to the fields manageable in the form builder. Labels for custom fields are only managed in the custom field editor.
The form builder generates a shortcode in the format [submit_event form_id="test-form"]. Selecting and editing that form in the form builder will change the view of that form with no need to change the shortcode.
You can also create additional forms with different data to collect and different requirements. In the front-end event editor, links to edit events from a specific form ID are sent to the form that created that event for editing.
Some fields can be configured as required fields for all submission forms. When enabled, any form created will automatically have these fields added and made required for submission.
By default, no event fields are required except for the start date. If you require additional information from your visitors, use 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.
You can use the form builder to make form fields selectively required for a specific form.
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.
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:
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.
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.
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.
event_title: Titleevent_begin: Starting Dateoccur_begin: Starting Dateevent_end: Ending Dateoccur_end: Ending Dateevent_time: Starting Timeevent_endtime: Ending Timecontent: Descriptionevent_desc: Descriptionevent_short: Excerptevent_link: External event URLevent_link_expires: Link expirationevent_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 URLevent_allday: Event is all-dayevent_author: Author IDevent_approved: Publishing statusevent_category: Category Name or IDcategory_color: Category Colorcategory_icon: Category Iconcategory_private: Category Privacy statusevent_fifth_week: Omit week 5 recurrencesevent_holiday: Cancel on Holidaysevent_group_id: Event Group IDevent_span: Event spans multiple daysevent_hide_end: Hide end dateevent_status: Event Statusevent_flagged: Event Flagged as Spamevent_tickets: Event Tickets Linkevent_registration: Event Registration Infoevent_host: Event Host IDevent_access: Event Accessibility Datalocation_preset: Location IDevent_label: Location Labelevent_street: Location Streetevent_street2: Location Street (2)event_city: Location Cityevent_state: Location Stateevent_postcode: Location Postcodeevent_region: Location Regionevent_country: Location Countryevent_url: Location URLevent_phone: Location Phone Numberevent_phone2: Alternate Location Phoneevent_longitude: Location longitudeevent_latitude: Location latitudeevent_zoom: Map zoom levelevent_location: Location ID in locations tablemc_copy_location: Copy location into DBUID: 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 calendarIf 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.
Enable the API at My Calendar > Settings > General:
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:
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 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.
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.
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.
Once all desired languages are installed, you have the option to choose the site language for your events.
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:
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.
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.
My Calendar Pro provides a brief summary of the current month, current year, previous month, previous year, and all time sales totals.
Logged-in users can be given access to view and edit events that they submitted to your site.
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:
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.
Check the box ‘Require payment to submit an event’ under the ‘Payments’ tab to require payments.
Payment settings are broken into four areas:
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.
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.
Set your primary PayPal email (this must match the primary email as configured in your PayPal account settings), and add your merchant ID.
Stripe payments are a more secure method of handling payments.
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.
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.
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.
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.
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.
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.
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.)
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.)[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]
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]
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]
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]
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.
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.
There are three notifications sent to submitters following submission.
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]