# Events Manager Documentation > The complete user documentation and tutorials for Events Manager, the free WordPress plugin for event calendars, registration, bookings and ticketing, and for Events Manager Pro, its paid add-on for payments, custom booking forms, coupons, PDF tickets, check-in and automation. One Markdown file for AI assistants and language models. Each page lists its canonical URL on wp-events-plugin.com. Generated 2026-09-18 from the documentation source. Shorter overview: https://wp-events-plugin.com/llms.txt. REST API reference (not included here): https://wp-events-plugin.com/documentation/api/. Product site: https://wp-events-plugin.com/. Pro licenses and support: https://eventsmanagerpro.com/. # Documentation ## Documentation URL: https://wp-events-plugin.com/documentation/ ### Installation and Setup For those of you new to Events Manager, we highly recommend you check out our [getting started](https://wp-events-plugin.com/documentation/getting-started/ "Getting Started") page, which gives a quick overview of how to get up and running. ### First Steps - [Installation and Upgrades](https://wp-events-plugin.com/documentation/installation/) - [Getting Started](https://wp-events-plugin.com/documentation/getting-started/ "Getting Started Guide") - [Introduction to Settings](https://wp-events-plugin.com/documentation/introduction-to-settings/ "Introduction to Events Manager Settings") ### Basic Settings - [Using Widgets](https://wp-events-plugin.com/documentation/wordpress-event-widgets/) - [Mail Settings](https://wp-events-plugin.com/documentation/mail-settings/) - [Configure Automated Emails](https://wp-events-plugin.com/documentation/automated-emails/ "Automated Emails") - [Booking Options](https://wp-events-plugin.com/documentation/booking-options/) ### Advanced Setup - [Multisite Installations](https://wp-events-plugin.com/documentation/multisite/ "Multisite") - [Buddypress Installations](https://wp-events-plugin.com/documentation/buddypress/ "Buddypress Setup") - [User Permissions (Capabilities)](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities") - [Privacy & GDPR Compliance](https://wp-events-plugin.com/documentation/data-privacy-gdpr-compliance/) - [WooCommerce Integration](https://wp-events-plugin.com/documentation/woocommerce/) ### Payments Setup Pro - [Custom Booking Forms](https://wp-events-plugin.com/documentation/custom-booking-forms/) - [Payment Gateways Overview](https://wp-events-plugin.com/documentation/payment-gateways-overview/ "Payment Gateways Overview") - [PayPal](https://wp-events-plugin.com/documentation/events-with-paypal/) - [Stripe Payments](https://wp-events-plugin.com/documentation/payment-methods/stripe/checkout/) - [Offline Payments](https://wp-events-plugin.com/documentation/offline-event-payments-bookings/) - [Authorize.net AIM](https://wp-events-plugin.com/documentation/event-bookings-with-authorize-net-aim/ "Event bookings with Authorize.net AIM") ### Your Events Once you've installed Events Manager, it's time to start adding event and locations! Here's some handy links to help you along the way. ### Events - [Create and Edit Events](https://wp-events-plugin.com/documentation/creating-and-editing-events/ "Creating and Editing Events") - [Recurring Events](https://wp-events-plugin.com/documentation/recurring-events/) - [Group Events with Categories](https://wp-events-plugin.com/documentation/event-categories/) - [Accept User-Submitted Events](https://wp-events-plugin.com/documentation/user-event-guest-submissions/ "Accepting User-Submitted Events") - [Manage User-Submitted Events](https://wp-events-plugin.com/documentation/event-approval/) - [Event Calendars](https://wp-events-plugin.com/documentation/calendars/ "Using Template Files") - [Sharing Events with iCal](https://wp-events-plugin.com/documentation/event-ical-feeds/ "Using the iCal Feeds") ### Bookings - [Set Up Event Bookings](https://wp-events-plugin.com/documentation/set-up-event-bookings/) - [Allow Bookings Without Accounts](https://wp-events-plugin.com/documentation/no-user-bookings/) - [Manage Bookings](https://wp-events-plugin.com/documentation/manage-attendees/) - [Multiple Bookings at Once](https://wp-events-plugin.com/documentation/multiple-booking-mode/) Pro New - [Manual Bookings](https://wp-events-plugin.com/documentation/manual-bookings/ "Manual Bookings") Pro - [Coupons](https://wp-events-plugin.com/documentation/coupons/ "Coupons") Pro - [Custom Booking Emails](https://wp-events-plugin.com/documentation/custom-booking-email-templates/) Pro New ### Locations - [Create and Edit Locations](https://wp-events-plugin.com/documentation/creating-and-editing-locations/ "Creating and Editing Locations") - [Google Maps](https://wp-events-plugin.com/documentation/google-maps/) - [Zoom Meetings, Webinars and Rooms](https://wp-events-plugin.com/documentation/location-types/zoom/) ### Advanced Usage _**Requires knowledge of HTML.**_There are several ways of showing your events throughout your site. Here are some of the basics. Each way has its advantages and offer varying levels of flexibility. If you are a developer wishing for more flexibility, it's advised you check out the developer docs too. - [Placeholders](https://wp-events-plugin.com/documentation/placeholders/) _\- change event page information/layouts_ - [Conditional Placeholders](https://wp-events-plugin.com/documentation/conditional-placeholders/) _\- placeholders that display on conditions being met_ - [Shortcodes](https://wp-events-plugin.com/documentation/shortcodes/) _\- for pages/posts_ - [Event Search Attributes](https://wp-events-plugin.com/documentation/event-search-attributes/) _\- add filters and options to shortcodes_ - [Event and Location List Grouping](https://wp-events-plugin.com/documentation/event-search-attributes/event-location-grouping-ordering/) _\- powerful grouping logic for your lists, such as showing first upcoming event in each town_ - [Custom Event/Location Fields](https://wp-events-plugin.com/documentation/event-attributes/) _- Add custom fields to your events_ - [Importing and Exporting](https://wp-events-plugin.com/documentation/importing-exporting/) New - [Optimization Recommendation](https://wp-events-plugin.com/documentation/optimization-recommendations/ "Optimization Recommendations") _- plugin-specific tips to speed up your website_ - [General Optimization Recommendations](https://wp-events-plugin.com/documentation/general-optimization-recommendations/ "General Optimization Recommendations") _- more tips to speed up your website_ - [Upgrading to Dev-Versions](https://wp-events-plugin.com/documentation/upgrade-dev-version/) _- Get the latest and greatest!_ - [WP Cron](https://wp-events-plugin.com/documentation/wp-cron/) _- Recommended setup of scheduled tasks_ ### Developer Docs & Tutorials If you have some experience using PHP and editing wordpress themes or plugins, you may find the more advanced features useful, as they provide a very high degree of flexibility and power, which you can use in your own  theme customization. - [Tutorials](https://wp-events-plugin.com/tutorials/) - a comprehensive set of walkthroughs for customizing Events Manager - [Using Template Files](https://wp-events-plugin.com/documentation/using-template-files/) - [Template Tags](https://wp-events-plugin.com/documentation/template-tags/) - [Hooks and Filters](https://wp-events-plugin.com/documentation/hooks-and-filters/) - [Advanced Usage](https://wp-events-plugin.com/documentation/advanced-usage/) - [Translating](https://wp-events-plugin.com/documentation/translating/) ### Finding Help If after reading the documentation you get stuck, there's a lot of places to find help. We do recommend you read the documentation though, there's a good chance the answer is there already! - [Troubleshooting](https://wp-events-plugin.com/documentation/troubleshooting/) - _regularly updated with recently common issues_ - [FAQ](https://wp-events-plugin.com/documentation/faq/) - _regularly updated with recently common issues_ - [Community Forum](https://wordpress.org/support/plugin/events-manager) _\- a lively community, visited regularly by the team_ - [Pro Support Forum](https://eventsmanager.com/support/) _\- for faster support, monitored regularly mon through fri_ ## Getting Started URL: https://wp-events-plugin.com/documentation/getting-started/ This tutorial will point you to some of the important features of Events Manager to get you up and running quickly, easily and with the ability to change your events to suit the look of your site. Let's begin firstly by [installing events manager](https://wp-events-plugin.com/documentation/installation/ "Installation and Upgrades"), if you haven't done so already. Usually everything should go without a hitch, but in case you do run into any issues, there's a few places where you should go to for help: - Make sure you're on the latest versions of WordPress and Events Manager (and Pro). This may have already been fixed. - View our [Troubleshooting](https://wp-events-plugin.com/documentation/troubleshooting/) page for common issues. These are regularly updated with recently known issues. - Visit the WordPress [support forums](http://wordpress.org/tags/events-manager?forum_id=10) as others may be experiencing the same issues as you. Pro users can also use our [member forums](https://eventsmanagerpro.com/support/) which are monitored regularly on a daily basis. ### Setting up Events Manager Once installed and activated, you'll notice a new "Events" menu item within your Wordpress admin area. This contains all the pages concerning your events. The first page you want to visit is Settings, which has all the options for changing the way Events Manager works and looks. #### Set Up Pages and Lists By default, Events Manager will create various pages on your site and overrides the page content with event, location and category lists, as well as a page for previous bookings. EM should automatically create three pages with this structure: - **Events** - Contains a list of upcoming events and a search form. - **Categories** - Contains a list of event categories. - **Locations -** Displays the list of locations on your site. - **My Bookings** - Displays a user's booking history and cancellation options. These pages can be reassigned or disabled from the _Pages_ tab in the _Events > Settings_ page in your admin area. [Image: Set up your events pages in the Pages tab.] If you don't see an Events page, verify that there is one in your Pages menu, that the right page is selected in your settings page. If you do not want pages, you can also allow WordPress to create default archive pages for both Events and Locations, much like posts. You will have the option to enable archives if you select \[No Events Page\] or \[No Locations Page\], as well as ordering options. #### Overriding Formats You will notice that for single pages and lists you have an option to override with formats. This means that your settings within the _Formats/Templates_ tab will override the default content output by a custom post type - see Displaying Events further down for more information. By default Events Manager will override with formats to provide more information about events. #### Using Pages or Posts? Since locations and events are custom post types, you can modify the templates used for each type. WordPress assigns custom post types the post template, when often a normal page template would suit it better. If you would like Events Manager to override your default template and treat events like a normal WordPress page, select 'Page' in these cases. Should you wish, you could also create a _single-event.php_ or _single-location.php_ file in your theme and override this feature completely with PHP. #### Other Important Settings Events Manager is set up to pretty much run from get go with no initial setup. However, there may be times where installations didn't go correctly or things aren't working as expected ### Creating your First Event To create your first event, simply go to Events > Add New and start filling out the fields. Note that you may want to set up locations and categories beforehand, although you are able to enter basic location information as you enter events too, or select a previously used location. #### Recurring Events With recurring events, the start date represents the first instance (or the first date a recurrence can start on, depending on recurrence setting) a recurrence can occur, and the end date is the last day an event can occur. So, if you had a weekly recurring event with start and end dates of a month, you would have four events during the selected month. #### Bookings To enable bookings in your event, provided bookings are enabled on the settings page (enabled by default) you should check the enable bookings box and edit/add appropriate tickets. If you are using bookings, you certainly want to view the Booking and Ticketing Options, Booking Email Templates and [Email Settings](https://wp-events-plugin.com/documentation/mail-settings/ "Mail Settings"). ### Displaying Events You'll notice the word "Format" in many options on the settings page. This is the word we use for snippets of html templates for how bits of information about Events Manager should be displayed. Using [placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders"), you can easily create customized formats by changing the default html and placeholders. With [conditional placeholders](https://wp-events-plugin.com/documentation/conditional-placeholders/ "Conditional Placeholders"), you can also show and hide certain information depending on whether a certain condition is true, e.g. if an event has bookings, you would want to show some more event information. [Image: An example of how you could use placeholders to display tabular HTML information in the settings page.] It may be that you want to show events elsewhere, such as within your posts, pages, or sidebars. This is possible with [widgets](https://wp-events-plugin.com/documentation/wordpress-event-widgets/ "WordPress Event Widgets") and [shortcode](https://wp-events-plugin.com/documentation/shortcodes/ "Shortcodes"). ### Further Development If you know PHP and are comfortable editing WordPress themes/plugins, there are more advanced ways of editing the looks of your events and website using [template tags](https://wp-events-plugin.com/documentation/template-tags/ "Template Tags"), [template files](https://wp-events-plugin.com/documentation/using-template-files/ "Using Template Files") and [advanced php](https://wp-events-plugin.com/documentation/advanced-usage/ "Advanced Usage"). If you would like to further customize Events Manager event more on your blog or site, this is totally possible, as we use various ways to allow programmers to override EM and change the way it behaves and looks. We recommend you check out the [Advanced Usage](https://wp-events-plugin.com/documentation/advanced-usage/ "Advanced Usage") page for a quick coder's overview of Events Manager, but this is still work in progress, the best place to dive right in is probably our [series of tutorials for creating a full add-on](http://wp-events-plugin.com/tutorials/creating-a-events-manager-add-on-a-complete-walkthrough/ "Creating an Events Manager Add-On : A Complete Walkthrough") for events manager ## Installation and Upgrades URL: https://wp-events-plugin.com/documentation/installation/ Before we begin, we must stress that making backups before installing/updating any WordPress plugins or WordPress itself is highly recommended. Wordpress makes installing and updating plugins very easy. In case you are not familiar with installing/updating plugins ([as explained on wordpress](http://codex.wordpress.org/Managing_Plugins#Manual_Plugin_Installation)), here are a few ways: - [Events Manager](#em) - [Events Manager Pro](#em-pro) ### Events Manager Installation There are three ways you can install Events Manager.[](#) #### Automatic Install via Wordpress (Recommended) 1. Go to your admin page and go to Plugins > Add New 2. Search for 'events manager' 3. Find Events Manager and click install 4. Add your FTP details if requested and let the plugin install 5. Activate it from the installation page or your Plugins page #### Adding via Zip file 1. [Download Events Manager](https://wp-events-plugin.com/pricing/ "Download Events Manager") 2. Go to Plugins > Add New in your admin area 3. Click Upload 4. Choose the zip file you just uploaded and click Install Now 5. Add your FTP details if required, install 6. Activate it from the installation page or your Plugins page #### Uploading via FTP 1. [Download Events Manager](https://wp-events-plugin.com/pricing/ "Download Events Manager") 2. Connect to your blog via FTP 3. Extract the zip file you downloaded, and upload the events-manager folder to your wp-content/plugins folder 4. Visit your Plugins page in the admin area. 5. Activate the plugin ### Updating Events Manager The best way to update is via the WordPress automatic updater. It will automatically inform you of new updates and will install them for you after confirmation. However, if this isn't possible, you can do it the same way as adding via zip file. Bear in mind that you should deactivate and delete the plugin before replacing it with the new one.  No events or settings are deleted in this process (the only time events are deleted is if you click uninstall, and even then you must confirm again before anything gets deleted by EM). Once uploaded reactivate and the update should happen in the background. Again, remember to back up your database before updating and installing plugins! This is something you should do for any upgrades you make, including (if not especially) the WordPress core. ## Pro Installation Since Pro is an add-on to Events Manager, you must install Events Manager beforehand. ### Installing 1. [Download Events Manager Pro](http://eventsmanagerpro.com/downloads/ "Download Events Manager") 2. Go to Plugins > Add New in your admin area 3. Click Upload 4. Choose the zip file you just downloaded and click Install Now 5. Add your FTP details if required, install 6. Activate it from the installation page or your Plugins page 7. Visit the Events > Settings page and click on the Licenses tab, then click the 'Activate' button for Events Manager Pro. 8. Once activated, you should see some new options within the _Events_ menu, such as _Forms Editor_ and/or _Gateways_ ### Updating You can update three ways: 1. Enter your [license key](http://eventsmanagerpro.com/account/) for our [auto-update feature](https://wp-events-plugin.com/documentation/auto-updating/ "Auto Updating"). Then just update via your admin menu with the WordPress automatic updater. 2. Do as you would install, but deactivate and delete the plugin before installing the new one. No events or settings are deleted in this process. 3. Deactivate the plugin, replace it with the new version via FTP, and reactivate. ### Activating your Pro license Once installed for the first time, you will be asked to activate your Pro license to make Pro features available. This step is required whether or not you still have access to pro updates and support. You will see an admin notice asking you to activate your plugin license. Click on this and you will be redirected to our site, where you will need to log in (if not already logged in) and confirm the activation of a license on your site. You can also view and manage your licenses from within your WordPress Dashboard > Events > Settings > Licenses tab or from our [account licenses](https://eventsmanagerpro.com/account/licenses/) page. ## Getting Started / Troubleshooting Once you've installed Events Manager, it's time to start adding events! We strongly recommend you check out the [getting started guide](https://wp-events-plugin.com/documentation/getting-started/ "Getting Started") and our [documentation section](https://wp-events-plugin.com/documentation/). If you run into problems with either Events Manager or Events Manager Pro there are various places to find help: This page is only a small portion of the event documentation which is here for quick reference. If you're just starting out, we recommend you visit the following places for further support: 1. Browse the other [documentation pages](https://wp-events-plugin.com/documentation/) and [tutorials](http://wp-events-plugin.com/tutorials/). Many questions we answer are already there. 2. View the [FAQ](https://wp-events-plugin.com/documentation/faq/) for general questions and [Troubleshooting](https://wp-events-plugin.com/documentation/troubleshooting/) for common issues. These are regularly updated with recently common issues users may be experiencing. 3. Rather than trying to contact us directly, we request you use the [support forums](http://wordpress.org/tags/events-manager?forum_id=10) as others may be experiencing the same issues as you. Pro users should use the [pro forums](http://eventsmanagerpro.com/support/) for faster support. ## Auto Updating URL: https://wp-events-plugin.com/documentation/auto-updating/ As of Events Manager Pro 1.3, auto-updating is now possible, just like a normal wordpress.org plugin. Once you have [installed Events Manager Pro](https://wp-events-plugin.com/documentation/installation/ "Installation and Upgrades"), all you need is your membership key. #### Your Membership Key When you install Events Manager Pro, you will be asked for a membership key which is used to notify you of updates to the plugin, and download the latest version right from your WordPress admin area. [Image: If unfilled, or if your key is not valid/expired, the pane will turn red] You should enter this key at the bottom of your settings page. If all goes well, the pane will turn a normal grey, otherwise it will remain red. [Image: A valid entry would show a normal gray pane with your key.] If you have any validation issues due to server errors, you will also see a descriptive error there (none for invalid/expired keys). Below is an example which could be solved by [David Walsh's post](http://davidwalsh.name/php-ssl-curl-error) (or if on managed hosting, ask your hosting support and point them to this link). [Image: auto-update-errors] If for some reason your server cannot communicate with ours (e.g. you are on a local dev server) and you just want to remove the notice, you need to insert the following into your [wp-config.php](http://codex.wordpress.org/Editing_wp-config.php) file: ```php defined(‘EM_DISABLE_API_REMINDER’,true); ``` Your membership key is located from within your [profile page](http://wp-events-plugin.com/wp-admin/profile.php). #### Development Version If you'd like to use the latest development version of Events Manager Pro, it's now easier than ever! All you have to do is add this line of code to your [wp-config.php](http://codex.wordpress.org/Editing_wp-config.php) file. ```php define(‘EMP_DEV_UPDATES’,true); ``` Then, just force a recheck of plugin updates. #### Forcing a plugin update check Wordpress checks for plugin updates every 12 hours. If you go to Dashboard > Updates and click the 'check now' button, this should happen immediately. As of 3.2.1 I notice that clicking "Check Now" within your Updates dashboard will not recheck plugins immediately (a delay of 5 mins in some occasions). One reliable way of doing this is deleting the _\_site\_transient\_update\_plugins_ option from your wp\_options table and refreshing your plugin/update page. You should see a new record re-appear when you do. ## How to Upgrade to the Dev Version URL: https://wp-events-plugin.com/documentation/upgrade-dev-version/ Running the Developer version of Events Manager and Events Manager Pro means you'll get access to updates and new features a little sooner than regular users. Sometimes Events Manager support will suggest upgrading to the Dev version, especially if it contains bug recent fixes that relate to a problem you've reported. Here's how to switch to using the Dev version. Go to _Events > Settings > General_ and click open the _Admin Tools (Advanced)_ tab. You'll see there are two options for getting the Dev version. Clicking the _Check Dev Versions_ button will perform a one-time check for a Dev version update. If one is available, you'll see it appear as plugin update as normal. [Image: Enabling Check Dev Versions] The second option - setting _Enable Dev Updates_ to yes - allows you to permanently monitor for newer Dev versions. [Image: Enable Dev Updates] If you enable this option, Events Manager will check for updates based on the Dev version, rather than the regular version. ### Why can't I see any updates available? If you know there's an update available but you're not seeing it listed on your Plugins page, click the _Re-Check Updates_ or _Check Dev Versions_ button under the Admin Tools panel and then try refreshing the Plugins page a few times until you see the updated listed. ## Getting the Latest Stable Version Sooner URL: https://wp-events-plugin.com/documentation/installation/latest-stable/ WordPress.org now holds every plugin release back from automatic updates for up to 24 hours (its "Protect the Shire" review window). During that window the new version can be installed manually, but the normal update check on your site will not show it yet, so you can be left waiting a day for an important fix to appear. Events Manager can look up the latest stable release directly from WordPress.org and show it on your Plugins and Updates screens straight away, so you can update by hand without waiting for the rollout. #### Turning it on Go to _Events > Settings > General_ and open the _Admin Tools (Advanced)_ tab. Under _Development Versions & Updates_, set _Always check the latest stable version?_ to _Yes_ and save. From then on, whenever a newer stable release exists that WordPress.org has published but not yet rolled out to your site, Events Manager shows it on your _Plugins_ and _Dashboard > Updates_ screens as a normal available update. If you would rather check just once, use the _Re-Check Updates_ button in the same section. It performs a single direct check and shows any newer stable release immediately. #### Manual updates only, by design A release surfaced this way is only ever offered for a **manual** update. It is deliberately excluded from unattended automatic updates, so enabling the option does not defeat the 24 hour review window for auto-updates. Your plugin continues to show "auto-updates enabled" as normal, and a genuinely rolled-out release still auto-updates when WordPress.org distributes it. In short, the option lets you choose to update sooner; it does not make your site auto-update sooner. #### Forcing automatic updates If you run your own sites and want held-back releases to install automatically as well, rather than just showing them for a manual update, add this constant to your `wp-config.php`: ```php define( 'EM_AUTO_UPDATES', true ); ``` With this defined, Events Manager auto-updates to the latest stable release as soon as it is published, without waiting for the 24 hour rollout. This is a deliberate, code-level choice rather than an admin setting, because it opts you out of the safety window the delay provides. Leave it undefined (the default) to keep the safe, manual-only behaviour. #### Development versions This works alongside the _Enable Dev Updates_ option, which checks for the very latest in-development build rather than the latest stable release. See [How to Upgrade to the Dev Version](https://wp-events-plugin.com/documentation/upgrade-dev-version/) for more on that. ## Introduction to Events Manager Settings URL: https://wp-events-plugin.com/documentation/introduction-to-settings/ ### Setting Up Events Manager Now you know your way around, let's take a look at some of the main settings that you may want to adjust before creating your event. To adjust the settings navigate to **Events > Settings**. #### General Settings The General Settings tab has options for enabling different functionality in the Events Manager plugin. For example, you can enable categories and tags, event attributes and custom fields. Edit these to suit your needs. They can be adjusted at any time. [Image: turn on and off functionality] You may wish to set the default country for when you create your locations. You'll find this underneath **General Options.** [Image: the default location can be changed under default options] #### Pages The Pages tab gives you greater control over your event content. Some of the things you may wish to adjust in this section: - Your events and locations can either display as a Post or a Page. Displaying as a Post will have data such as post date and post author displayed with it. If you don't wish to display this information select to display as a Page. - Change your archive pages. These are the default pages that are created when you activate Events Manager. - Enable/disable event search. #### Formats/Layouts You can adjust the layouts and formats of your different pages. This lets you decide how your event pages are displayed. You will need basic HTML knowledge to edit the display. #### Booking Options The booking options control how people register for your event. You can enable cancellations, allow guest bookings or require pre-approval. You can also set the pricing options here. You should ensure that your currency and your currency formatting are set correctly. You can also add a tax rate to your tickets. [Image: the pricing options] #### Email Adjust your [email settings](https://wp-events-plugin.com/documentation/mail-settings/ "Mail Settings") and the [automated emails](https://wp-events-plugin.com/documentation/automated-emails/ "Mail Settings") that are sent when someone registers for your event. ## Buddypress Setup URL: https://wp-events-plugin.com/documentation/buddypress/ Events Manager allows BuddyPress users to manage their events from the front-end your website. Aside from this, your users also can create group events and manage these together. When both plugins are installed, users will see a new Events menu automatically added to their BuddyPress profile menus. What options they see depends on the permissions they have assigned to their user role from _Events > Settings > User Capabilities_ in the admin area. [Image: Users with limited capabilities will only see relevant menu items.] ### User Event Management **My Profile** Available to all users, and is the only public page accessible by other members/guests. Shows a list of events the user is hosting, as well as events they may be attending. [Image: Events Dashboard/Profile page on Buddypress installations] **Events I'm Attending** This is the same interface as non-buddypress installations use for logged in users e.g. httpx://yoursite.com/events-page/my-bookings/ [Image: Events I'm Attending page on Buddypress installations] **My Events (Add/Edit Events)** This is the equivalent to the Add/Edit Events interface in the admin area. You can add a new event by clicking the 'add new' link next to the page title. Note that admins will only see events they own, and not all user events like in the admin area. When an event is published, the event will also appear on the main Events Page (unless you are filtering events). [Image: My Events page on Buddypress installations] **My Locations** This is equivalent to the Add/Edit Locations interface in the admin area. Note that admins will only see their locations and cannot view other user locations in this interface, unlike in the admin area. [Image: My Locations page on Buddypress installations] **My Event Bookings** This is equivalent to the Add/Edit Locations interface in the admin area. Note that admins will only see their locations and cannot view other user locations in this interface, unlike in the admin area. [Image: My Event Bookings page on Buddypress installations] ### Group Events Group admins can attach events to their group, allowing other group admins to also manage the event and bookings (if allowed). Creating a group event is just like creating a normal event, except that you will have the option of choosing a group to assign the event to. [Image: Group Events page on Buddypress installations] Once you attach an event to a group, it cannot be unattached. Other group admins will also see the event in their event management panels. ### Activity Stream and Notifications When a user books a place at an event, cancels it, or creates an event, the activity stream is updated. When someone books or cancels a booking for your event, you will also have a notification within the standard buddypress notifications area. [Image: An activity stream of a user using Events Manager] ### Modifying Page Layouts All Buddypress page layouts can be modified using [template files](https://wp-events-plugin.com/documentation/using-template-files/ "Using Template Files"), which means you can modify the look from your theme folder and not directly modify the plugin. These folders/files are used by EM in BuddyPress: - _templates/buddypress/ -_ all these files represent pages in buddypress - _templates/templates/my-bookings.php -_ used in the "Events I'm Attending" screens - _templates/forms/event-editor.php -_ the add/edit event screen - _templates/forms/location-editor.php -_ the add/edit locations screen ## Mail Settings URL: https://wp-events-plugin.com/documentation/mail-settings/ If you intend to have notifications sent when an event is booked, you should ensure that email is correctly configured for your server in the events settings page, which is located under the emails tab of your [events settings page](https://wp-events-plugin.com/documentation/introduction-to-settings/ "Introduction to Events Manager Settings"). [Image: email-settings] ### Sender Settings Some email servers may not use the same email address you'd like users to see in their inbox. You can change the sender details of this email by modifying the _Notification sender name_ and _Notification sender address_ options in your email settings. Note that some email servers will not allow you to change the sender details and will always override it with the default mailbox address/name. ### Mail Sending Method By default, Events Manager will attempt to use the default PHP mail function. However, there are various other options you can use: **WP Mail _(default - recommended)_** Uses the same method used by Wordpress to send emails. Along with recommending this setting, we also recommend you take two extra steps to ensure higher email deliverability: - Use a dedicated mail handling plugin, such as [WP Mail SMTP](https://pxlink.cc/smtp) _(recommended)_ or [Post SMTP](https://wordpress.org/plugins/post-smtp/). - Use a mail delivery service, such as SendGrid or Mailgun (which can be set up with the [WP Mail SMTP](https://pxlink.cc/smtp) plugin above). - Alternatively, if you do not send large volumes of emails, Gmail is often a good option, which again should be set up via one of the above mailing plugins rather than SMTP, if possible. **SMTP** Use another service to send emails, e.g. gmail or a private email server. See below for further required settings for SMTP **PHP Mail** Uses the PHP mail() function. If this does not work, please contact your hosting provider. **Qmail** For those who have qmail installed on your server and prefer to use that instead. **Sendmail** For those who have sendmail installed on your server and prefer to use that instead. ### SMTP Settings - Gmail Example _**Warning -** The following example is just that, an example. Recent announcements from Google indicates the eventual deprecation of support for SMTP. We recommend OAuth connection method rather than SMTP via a plugin such as [WP Mail SMTP](https://pxlink.cc/smtp) and selecting WP Mail as your sending method._ _If you do use SMTP make sure you [enable the use of 'less secure apps'](https://support.google.com/accounts/answer/6010255?hl=en) in your Google page._ If you run into issues with your local email settings, you could always try using another email server, such as Google Mail or Apps accounts. If your site sends a high volume of emails regularly it's recommended you get a dedicated email server, or use a transactional email sending service (mentioned further up) to prevent possible problems due to abuse of Google's SMTP servers. Following the Google example, here is what you would need to set up a GMail account. - **Notification sender address** - Should be the same as your gmail/apps address (may cause problems if not). - **Mail sending port****\-** 465 - **Mail sending method** - SMTP - **Use SMTP authentication?** -  Yes - **SMTP Encryption -** TLS - **AutoTLS -** Yes - **SMTP Host** -  smtp.gmail.com - **SMTP username -** your full acount username (e.g. user@gmail.com or user@appsdomain.com) - **SMTP password** - your google account password ### Test Your Setttings Once you've added your settings, you can test these settings before saving by clicking the 'Test Email Settings' button. A test email will be sent to your account email. Be sure to check your spam folder if you don't receive anything. If you still don't receive anything, yet you're getting a successful result, try using another mail transport that you can be sure is reliable, such as SMTP and Gmail. ### Configure Your Automated Emails Now that you've successfully set up your emails, you can [configure the content of the emails](https://wp-events-plugin.com/documentation/automated-emails/ "Automated emails") sent by Events Manager. ## Data Privacy and GDPR Compliance URL: https://wp-events-plugin.com/documentation/data-privacy-gdpr-compliance/ Events Manager 5.9.3 includes various features to help you comply with international and national data protection and privacy laws, such as the EU GDPR laws which is enforced as of May 25th 2018. Since the GDPR will affect most of the world, we'll refer to data privacy/protection laws as GDPR for the purposes of this document. _It's important to understand that these features do not automatically make you GDPR (or any other data protection law) compliant. Everyone's site is different and therefore is subject to different consideration when coming up with a data privacy and protection plan. The purpose of this document is to explain the features available to you that will **assist you** with compliance. Please see our [overview of GDPR considerations](https://wp-events-plugin.com/documentation/data-privacy-gdpr-compliance/guidelines-for-gdpr-compliance/) you should take into account when making your site compliant with GDPR and other data protection laws you may be subject to._ The main areas you need to deal with when it comes to GDPR involve: - **Privacy policy** - providing clear information about what you do with personal data obtained by your site. - **Consent** - obtaining permission to use personal data submitted to you in accordance with your privacy policy. - **Right to erasure** \- users have the right to request their data to be removed from your site. - **Data access and portability** \- users can request for a digital copy of all their personal information stored on your site. ### Privacy Policy The first area is the part that requires the most input from you, since you need to create your own Privacy Policy. We integrate with WordPress' Privacy Policy tool to provide you with an example of information you could include in your Privacy Policy, which describes how and why Events Manager collects data from the user. This sample (at the time of writing) is: > _We use Google services to generate maps and provide autocompletion when searching for events by location, which may collect data via your browser in accordance to Google's [privacy policy](https://policies.google.com/privacy)._ > > _We collect and store information you submit to us when making a booking, for the purpose of reserving your requested spaces at our event and maintaining a record of attendance._ > > _We collect and store information you submit to us about events (and corresponding locations) you would like to publish on our site._ > > _We may use cookies to temporarily store information about a booking in progress as well as any error/confirmation messages whilst submitting or managing your events and locations._ ### Privacy Settings You will see a _Privacy_ section on our settings page under the _General_ tab, which will look like this: These settings provide you with fine grain control over the next few areas of the GDPR you need to comply with. #### Consent We provide you with an easy way to automatically add a consent checkbox to the bottom of your booking event/location submission forms. With this checkbox present, it must be checked for users to proceed with submitting their data. The first option,  _Consent Text_, allows you to edit the specific wording used for the checkbox description. _Remembering Consent_ allows you to decide whether to display these checkboxes more than once to registered users. When a form is submitted containing this consent checkbox, the date of consent is saved to the user profile, and gets updated when they consent again. Because of this, you can choose whether or not to keep showing this checkbox to users that consented, and whether to pre-fill the box as well. The following options allow you to decide whether or not to show these consent checkboxes, and if so, whether to show them only to guests regardless of whether the registered user had previously consented or not. #### Export / Erase These two sections provide the same sort of options, and deal with the "right to erasure" and "right to data access" requirements of the GDPR. Events Manager integrates with the personal data export/eraser tools provided by WordPress, and the following options provide you with fine-grained control on what to specifically include in data exports, and what to delete when requested. One important point to note is that WordPress does not delete user accounts when erasing personal data. When you delete a user account, you are given the option to delete all their content, or transfer it to another user. This applies to events and locations too. Bookings belonging to a user, including payment transaction history, will get deleted along with the account. As of May 25th 2018, the new [EU GDPR](http://ec.europa.eu/justice/smedataprotect/index_en.htm) laws are enforced and affect anyone that runs a website which is served to anyone in the EU. ## Guidelines for GDPR Compliance URL: https://wp-events-plugin.com/documentation/data-privacy-gdpr-compliance/guidelines-for-gdpr-compliance/ > **Info:** This page will be updated shortly with some general guidelines which may help you in your site privacy policy and strategy, including more information about what our plugin does and how it stores/processes data. Please check back over the next few days._ ## Right of Withdrawal (EU 'Widerrufsbutton') URL: https://wp-events-plugin.com/documentation/compliance/right-of-withdrawal/ > **Warning:** This is not definitive legal advice This page explains Events Manager features that can help you meet the EU right-of-withdrawal rules. It is **not legal advice** and does **not** make your site automatically compliant. The rules differ by country, change over time, and depend on what you sell and to whom. Always confirm your specific obligations with a qualified lawyer before relying on any setup described here. ### The law, in brief From **19 June 2026**, Germany's new **§ 356a BGB** requires online businesses to provide an easy-to-use electronic **right-of-withdrawal button** (the *Widerrufsbutton*) wherever consumers can conclude distance contracts online and a statutory right of withdrawal exists. This is not Germany-only. It implements **Article 11a of the EU Consumer Rights Directive** (2011/83/EU, as amended by Directive (EU) 2023/2673), so equivalent rules apply across the EU under each country's own transposition. In short, the function must be: - **Prominent and permanently available**, and reachable **without logging in**. - A **two-step** process: the consumer declares the withdrawal, then confirms it on a separate page. - **Data-minimised** — it may only require the consumer's name, something to identify the contract, and an electronic contact for the reply. - Followed by an **acknowledgment of receipt** on a durable medium (email) that reproduces the declaration and records the exact date and time it was received. ### Does it affect you? The button is only required where a **statutory right of withdrawal exists**, so this matters a great deal for event organisers: - **Tickets for fixed-date events are generally exempt** (§ 312g Abs. 2 Nr. 9 BGB — leisure services tied to a specific date). Many organisers selling dated tickets do **not** need a withdrawal button. - It **does** typically apply to non-dated services, courses or memberships without a fixed date, digital content/downloads, and physical goods. If your site sells **any** withdrawal-eligible item, the function is expected to be reachable **site-wide**. - It follows the **consumer, not your location.** If you target consumers in Germany or the EU (language, currency, shipping, marketing), the rules can apply even if your business is based elsewhere (Rome I Regulation, Article 6). Where it applies, ignoring it carries real risk: German law allows fines up to **€50,000 or 4% of annual turnover**, plus cease-and-desist actions from competitors and consumer associations. A valid withdrawal also triggers a **refund duty** — the full amount, within 14 days, with no cancellation fee (§§ 357/357a BGB). That is separate from the contractual cancellation terms (*Stornobedingungen*) you are free to set for exempt, fixed-date events. ### How Events Manager helps Events Manager includes an **optional, guest-accessible Right of Withdrawal flow** that provides the *mechanism* the law expects. You still supply your own legal wording. It is **off by default**, so dated-ticket sellers are unaffected unless they switch it on. When enabled it adds: - An **`[em_withdrawal_form]`** page with the two-step, no-login flow, offering two ways in: - **By reference** — the consumer enters their booking reference and email. - **By email** — if they don't have the reference, they enter only their email and receive a secure, time-limited link to choose the booking. - A legally-shaped **acknowledgment email** to the consumer (the declaration reproduced verbatim plus the exact receipt timestamp, worded as confirmation of *receipt only*), and a **notification to you** for review. - An optional, prominent **footer link** so the function is reachable from every page. - **Locale-aware default labels** (for example German on German sites), all editable. - A field to paste **your own** withdrawal policy and model withdrawal form. It records each declaration against the booking. It does **not** auto-cancel the booking or issue refunds — you review whether the withdrawal is valid and process any refund through your normal workflow. #### Self-service withdrawal by email link The email path is built so attendees can withdraw on their own, with minimal work for you: 1. On your withdrawal page the attendee enters **just their email address** — no booking reference, no account, no login. 2. Events Manager looks up bookings for that email and emails a **secure, time-limited link** (valid 24 hours). The page shows the same neutral "if a booking exists, we've sent a link" message either way, so it can't be used to probe which emails have bookings. 3. The attendee clicks the link and sees a **list of their own bookings** to choose from. 4. They pick one and confirm. Events Manager then automatically: - emails them the **acknowledgment of receipt** (the declaration plus the exact date and time it was received), and - sends **you a notification** containing the booking, the statement, the timestamp, and whether it arrived inside the withdrawal window. For event planners, this is where the time savings are. Attendees identify and select their own booking, the legally-required acknowledgment goes out automatically, and you simply receive a notification to review and action (cancel and refund) on your own terms — no looking up bookings by email or chasing confirmations by hand. Attendees who already have their booking reference can skip the email step and go straight to confirmation by entering the reference and email instead. ### Setting it up 1. Go to **Events → Settings → Bookings → Right of Withdrawal (EU)** and switch it on. 2. Create a page (for example "Withdraw from a contract") containing the **`[em_withdrawal_form]`** shortcode, then select it as the **Withdrawal page**. 3. Set the **withdrawal period** (14 days by default) and the **admin notification** email address. 4. Paste your lawyer-provided **withdrawal policy / model withdrawal form** into the policy field. 5. Leave the labels and acknowledgment email blank to use the built-in defaults, or customise them. #### Where to place the link The law expects the function to be **continuously and easily reachable**, so don't bury it. We recommend: - The built-in **footer link** (enable *Show footer link*) so it appears site-wide. - A link in your **booking confirmation email** and on the **My Bookings** page. - A link from your **terms** or **withdrawal policy** page. Keep the label unambiguous — "Withdraw from contract" / "Vertrag widerrufen". Avoid vague wording such as "Cancel", which German guidance treats as insufficient. ### What this feature does not do - It does **not** provide legal text. You must supply your own withdrawal policy (*Widerrufsbelehrung*) and model withdrawal form. - It does **not** judge whether a withdrawal is valid, cancel bookings, or issue refunds automatically. You review each request and act on it. - It does **not** replace advice from a qualified lawyer for your particular situation. ## Creating and Editing Locations URL: https://wp-events-plugin.com/documentation/creating-and-editing-locations/ Locations can be created from two places, the add location form or the location form within an events form. This page will focus on editing events in your WordPress admin area. However, you can also create public pages on your actual website for users to submit and manage locations either by installing BuddyPress or selecting submission pages within _Events > Settings > Pages > Other Pages._ ### Creating New Location To create a new location, visit the _Events > Locations_ and then click on the _Add Location_ button ### Managing/Editing Locations When viewing the _Events > Locations_ page in your admin area, you will see a list of your locations. [Image: View and manage your locations in the admin area] To edit a location, click on the location name. ### Creating locations along with new events If you have disabled _Use dropdown for locations?_ in _Events > Settings > General Options_ in the admin area (disabled by default), a slimmed down version of the locations form will be used, which also has an auto-complete function for filling in previous location information. [Image: Add a new location or select a previously created one when adding an event] You cannot edit a location from within the edit event page. The available options are to use another location or create a new one. ## Creating and Editing Events URL: https://wp-events-plugin.com/documentation/creating-and-editing-events/ This page will focus on editing events in your WordPress admin area. However, you can also create public pages on your actual website for users to submit and manage events and locations either by installing BuddyPress or selecting submission pages within _Events > Settings > Pages > Other Pages._ ### Creating An Event Events can be created by clicking on the _Events > Add Event_ link in the admin menu. Alternatively, you can also click on the add new button on the events list in the admin area. [Image: You can add Events by clicking the menu, or any location, event or recurring event by clicking the Add New button when viewing the relevant list pages.] The minimum information required for an event is a name, start date and location. You are also required to add a time, although a default 12AM is already inserted. ### Managing/Editing Events The events admin page is where you can view all of the events in the system. Bear in mind that the default view is FUTURE events, meaning that some events might be 'missing' if they are past events. You can view past or all events by selecting the right scope in the filter pulldown above the events table. From this page you can also go to the events booking page, delete and duplicate events. [Image: Manage your events from the events admin page.] Editing an event is just like adding an event. You can edit an event by finding it in the events list page in your admin area (click on the _Events_ menu item) and clicking on the event title. [Image: Event Editor] ### Recurring Events You can also create recurring event patterns, please see our [recurring events documentation](https://wp-events-plugin.com/documentation/recurring-events/) page for more information. ## Editing in the Classic and Block Editor URL: https://wp-events-plugin.com/documentation/events/editor/ Events Manager works with both the WordPress Classic Editor and the Block Editor (Gutenberg). You can choose which one you use for editing events and locations, and when you use the Block Editor you can also choose how the event panels are arranged. ### Which editor should I use? For most sites we still recommend the Classic Editor for events. Events are more data focused than content focused: dates, times, locations, bookings and attributes matter more than long-form page content, and the Classic Editor presents all of that on a single, familiar screen. That said, we are committed to supporting the Block Editor and are making continuous improvements to the experience. If your workflow is built around blocks, or you want event content to sit alongside richer page content, the Block Editor is a good choice and gets better with each release. You can switch between the two at any time without losing data, so it is worth trying both and using whichever suits you. ### Choosing your editor Go to _Events > Settings > General_ and set the Editor option to either Classic Editor or Block Editor (Gutenberg). The choice applies to both events and locations across your site. If a developer has defined the `EM_GUTENBERG` constant in your `wp-config.php`, that takes precedence and the setting is locked to match it. ### The Classic Editor The Classic Editor shows every part of an event on one screen: the When panel (dates, times and recurrences), Bookings, Where (the location and map), Attributes, and anything added by your add-ons. Everything is visible at once, which suits the data-entry nature of events. If you have used Events Manager before, this is the layout you already know. ### The Block Editor (Gutenberg) In the Block Editor your event description is edited as blocks, the same as a normal post or page. The event's data panels (When, Bookings, and so on) are presented separately, and you can choose how they are arranged with the Block editor layout option in _Events > Settings > General_. There are three layouts to choose from. #### Canvas tabs The main event panels are shown as a set of tabs inside the editing area, near the top, so the most-used fields (When, Bookings, Attributes, and add-on panels such as automated emails) stay close to where you write. A few panels work better in the standard WordPress layout and are shown as their own panels below the content instead. The location and map (Where) is one of these, so that the map behaves correctly. Canvas tabs is the default for new installations. #### Tabbed metaboxes The same panels are grouped into a single tabbed box in the standard panel area below your content. This uses WordPress's native forms throughout, so every panel, including ones added by add-ons, behaves exactly as it does in the Classic Editor, only organised into tabs rather than stacked. #### Stacked metaboxes Each panel is shown as its own box, stacked one after another below your content. This is the arrangement closest to the Classic Editor while still using the Block Editor for your content, and it is the default for sites that have upgraded from an earlier version. ### Locations The location editor is simpler, as its main content is the address and map. In the Block Editor the location panels are always shown in the standard panel area rather than the canvas, so the map works reliably. They follow your tabbed or stacked choice; if you have selected canvas tabs for events, locations use the stacked layout instead. ### Switching at any time The editor and the layout can both be changed whenever you like from _Events > Settings > General_. The choice is site-wide and does not change your saved events or locations, so you can move between them freely and settle on whatever fits your workflow best. ## Recurring Events URL: https://wp-events-plugin.com/documentation/recurring-events/ Recurring events are events that occur more than once in regular intervals. Recurring events are useful if you want to create many single-day events using the same information once. Recurring events are enabled by default, but you can activate/deactivate this feature within your _Events > Settings  > General > General Options_ settings area. Recurring events are handled in a separate area to normal events, which can be found in _Events > Recurring Events_ of your admin menu. You can add recurring events by clicking the _Add Recurring Event_ button on this page. Editing recurring events is much the same as a normal event, however, you will see extended options for recurrence patterns when choosing event dates and times. There are a few important differences between single and recurring events. Here's a list of them: - When a recurring event is created, the start and end dates become the starting and ending dates where an event can occur, according to the recurrence options used. - Each recurrence is treated as a separate event. - If a person makes a booking at a recurring event, they are booked for the specific day, not the whole recurring set (more options on the way). - If you attempt to edit a single recurrence of an event, only that event will be modified. - You can detach an event from a set of recurrences by clicking the 'detach' link when editing an event or viewing the admin events list. - If you reschedule a recurring event, all information pertaining to attached recurrences (e.g. bookings, etc.) is deleted and recreated as a new event. - Deleting a Recurring Event will delete attached recurrences. To reschedule an event, you can either click on the reschedule link from a single event editing page, or also click on the reschedule link next to a recurrence within the admin events list. To edit a single recurrence, click on the event name itself, like when editing a normal single event. ## Timezone Support URL: https://wp-events-plugin.com/documentation/timezone-support/ Events Manager is timezone aware as of version 5.8.2. You can create events in different timezones around the world and these events will not appear under upcoming events lists if the events have passed, wherever they may be in the world. iCal feeds will also include Timezone information which can be parsed by calendar/email clients. From a user perspective, event admins and site visitors may notice some subtle changes. Site admins will see an option to select a timezone whilst creating and editing events, and will also be able to output timezone information with new placeholders. Event creators and admins will also notice that when viewing events in the admin area, any event that is not in the same timezone as your blog (which is found in _WP Dashboard > General > Settings_) will show a little information icon with a tip showing the timezone of that specific event. Every event will now have its own timezone. If you would like to have a different timezone for your events (for example, if you never had paid attention to timezones when creating your first events), you can do so from _Events > Settings > Admin Tools_. Do bear in mind, however, that this will overwrite ALL events, even those with custom timezones. ### Transitioning from earlier versions of Events Manager All events created prior to 5.8.2 will adopt the blog local timezone. Future events will default to the default setting in _Events > Settings > General > General Options_, which will by default be the same timezone as the local blog timezone. See further up for information on changing your event timezones in bulk, in case you hadn't set your blog timezone to a local time. ### Developer Information For developers, the way we store and access date-related information has changed. Most notably, we have introduced two new classes called EM\_DateTime and EM\_DateTimeZone, and also added three new database fields into the wp\_em\_events table. #### Database Changes Three new fields are introduced to the _wp\_em\_events_ table, which are _event\_start_, _event\_end_ and _event\_timezone_. These first two fields are mysql DATETIME values representing UTC equivalent start/end date/times for the event. These two fields will be used for searching by date when using past and future scopes, so that an event that happened in Auckland at 10am won't still show on a blog with a London timezone at 10am that same day. Date-specific searches such as by month or specific date ranges will still use local dates to search. _event\_timezone_ represents the timezone of that specific event, in the format of an Olson timezone or UTC manual offset (as used by WordPress) These fields are also included in the _wp\_postmeta_ tables for each event, and whilst _\_start\_ts_ and _\_end\_ts_ are still there, they will not be used anymore and eventually will be deleted. Additionally, we have added _\_event\_start\_local_ and _\_event\_end\_local_ which are DATETIME representations of the start and end of the event in local time, which is used for sorting and filtering in the admin area and for WP\_Query lookups where timezone isn't a consideration for lists. #### Code Changes Our new classes are extensions of the default PHP DateTime and DateTimeZone classes with some added improvements allowing for shorter method building and also support for manual UTC offsets as supported by WordPress. Dates and times stored by Events Manager within the Event, Booking and Ticket objects should now be accessed using functions which return a valid EM\_DateTime object in the relevant timezone of the event. We recommend developers take a look at these new classes, stored in `classes/em-datetime.php`, which are fully documented inline. We will go through each of these objects and highlight how certain class properties previously used throughout the plugin and likely in your code, and how to modify them for our new standards. The general rule is this: 1. The EM\_DateTime properties should ALWAYS be used for reference, display and comparison. 2. The only exceptions to 1) is if you are specifically after raw mysql date/time value and do not intend on manipulating that information for anything else. 3. Checking if a value is set such as via empty() is acceptable in certain situations, but we recommend retrieving the EM\_DateTime object and checking its _valid_ property instead. 4. If you need to change the value of a property (for example, if you are updating an event to the database), you can still directly set these properties. Note that all these properties do have a fallback and will still output data as previously expected, internally though, it will be providing that information via their respective EM\_DateTime objects. ##### EM\_Event (and EM\_DateTime examples) Previously, the following object properties were used in almost every way with regards to referencing and displaying event start and end information: - _event\_start\_date_ - _event\_end\_date_ - _event\_start\_time_ - _event\_end\_time_ - _event\_rsvp\_date_ - _event\_rsvp\_time_ - _start_ - _end_ - rsvp\_end It was common to compare dates to see if events were on the same day, or use the start/end properties to pass onto date() functions for formatting dates. This isn't necessary anymore and instead all this information can be obtained by the _start()_, _end()_ and _rsvp\_end()_ functions. These objects all work the same way, and we'll provide some initial examples with respect to this: ```php $EM_Event->start()->getDate(); //can be used instead of: $EM_Event->event_start_date; // and $EM_Event->end()->format(‘d/m/Y’); //should be used instead of: date(‘d/m/Y’, $EM_Event->start); ``` #### Notes about timestamps It's also important to note that timestamps are now real UTC timestamps. Previous versions of Events Manager would generate timestamps with offsets relative to blog timezones so that they could be used when displaying formatted dates using the timezone unaware date() and date\_i18n() functions. Previously, you would want to check if an event is past like this: ```php if( $EM_Event->start > current_time(‘timestamp’) ) ... ``` Whereas now you would do this: ```php if( $EM_Event->start()->getTimestamp() > time() ) …. ``` Whilst the earlier line of code will still work, because EM\_Event will still return 'start' as an offset timestamp, we still recommend switching over. #### Accessing new properties and saving old ones Finally, the new UTC times stored in _wp\_em\_events_ and loaded as properties _event\_start_, _event\_end_ and _event\_timezone_ are protected properties and cannot be accessed or manipulated directly. If you would like to get or set the timezone of an event, you can use the following: ```php $EM_Event->getTimezone()->getName(); //getTimezone() returns an EM_DateTimeZone object $EM_Event->setTimezone(‘America/New_York’); //you can supply a string, EM_DateTimeZone or DateTimeZone object. ``` If you would like to get the UTC-equivalent end time of an event, you would simply do this: ```php $EM_Event->start(true)->getDateTime(); //passing true to start() returns the object in UTC timezone ``` If you change the time of an event via _EM\_Event->event\_start\_time_, or change the timezone of an event the UTC date/time value will be reset and recreated relative to the new time should you wish to save that event. So, for example, for an event in London time during DST (i.e. UTC + 1 hour) ```php $EM_Event->start()->getDateTime(); //currently 2017-07-01 13:00:00 or 12:00:00 UTC time $EM_Event->event_start_time = 15:00:00; $EM_Event->start(true)->getTime(); //UTC time will return 14:00:00 $EM_Event->setTimezone(‘Europe/Madrid’); //Local time remains 15:00:00 but Madrid DST timezone is now UTC+2 $EM_Event->start(true)->getTime(); //UTC time will return 13:00:00 $EM_Event->save(); //event_start time will now be saved as 13:00:00, and event_end time will also be changed relative to new timezone ``` ##### EM\_Ticket Tickets have start and end times for when they are available for sale: - _ticket\_start_ - _ticket\_end_ These times are represented as local time for the event. Setting and getting these objects will still produce the same result as before. They should, however, now be accessed via the start() and end() methods which behave exactly the same as the EM\_Event methods, the only difference being the timezone is obtained from the event the ticket belongs to. You can use these EM\_DateTime objects to check availability irrespective of timezone, such as: ```php if( $EM_Ticket->start()->getTimestamp() > time() && $EM_Ticket->end()->getTimestamp() < time() ) …. //tickets are on sale right now, now check space availability ``` ##### EM\_Booking Bookings have a booking date associated with them marking the date it was made, stored as _booking\_date_. This is stored as a UTC date, and can be retrieved by the date() method and will return a EM\_DateTime object with a timezone belonging to the event it was booked. In this case, it may be useful to show the booking date and time relative to the blog timezone. So, an event with a New York timezone was booked at 9am on a London-based blog for example. You may want to show UK time like so: ```php $EM_Booking->date()->setTimezone(‘Europe/London’)->format(‘d/m/Y H:i’); ``` ## Translating URL: https://wp-events-plugin.com/documentation/translating/ Events Manager is capable of being translated into any language using the [standard wordpress localization methods](http://codex.wordpress.org/WordPress_in_Your_Language). Translations are [provided by volunteers](http://wp-events-plugin.com/about/) from around the world. You can also contribute in your own language and appear on our credits page! Please visit our translation hub and learn [how to start contributing](http://translate.netweblogic.com). Since late 2015, WordPress plugins hosted on the public repository (like Events Manager) are using the GlotPress translation system hosted on [translate.wordpress.org](https://translate.wordpress.org/projects/wp-plugins/events-manager), which enables collaborative translations from many users, as well as automatic updates for language files independently of the plugin itself. This is still in transition stages, and languages not fully translated are still provided/updated by us within the plugin folder. We have created our [own translation hub](https://translate.netweblogic.com) which provides helpful information on translating our plugin, translation-related news about our plugins as well as hosting GlotPress for [translation for Events Manager Pro](https://translate.netweblogic.com/go/projects/em-pro/) and any other future premium projects. All language files are located within the _langs_ within Events Manager Pro. ## Wordpress Event Widgets URL: https://wp-events-plugin.com/documentation/wordpress-event-widgets/ Wordpress widgets are a convenient way for users to add and manage content on various areas of your website without the need of inserting complex code. You may have already used these in your current theme for adding things like category lists, latest posts lists, login forms, twitter feeds, etc. Widgets are extremely easy to use and to add with a decent wordpress theme. Events Manager comes with three wordpress event widgets: - _**Events**_ - Displays a list of events (e.g. upcoming events) - _**Events Locations -**_ Displays a list of event locations (e.g. locations with upcoming events) - _**Calendar -**_ Displays an AJAX-driven calendar with occurring events. To add these widgets to your sidebar, go to your admin dashboard and visit Appearance > Widgets [Image: widgets] Then search for the Events Manager widgets from the Available Widgets panel, and drag it into one of the widget areas on the right column. Depending on your theme, you could have one or more areas to insert widgets, you can add these to any of them. To remove the widget, drag the widget out of the right column back to the available widgets panel. These wordpress event widgets are also available via [Shortcodes](https://wp-events-plugin.com/documentation/shortcodes/ "Shortcodes") for inserting inline with your content such as pages or posts. ## Using Event Calendars URL: https://wp-events-plugin.com/documentation/calendars/ Once you create your events, you can display event calendars on your site. There's various options and ways to insert a calendar into your site, we'll go trough them here. ### Calendar Types Unless stated, these calendars take up the whole width of their container, meaning that if you add a calendar in your sidebar, it'll take up the whole width of the sidebar, if you add it to a page, it'll take up the whole page width, etc. #### Full-Sized Calendars Full-Sized calendars display a list of events in a list-style fashion. You can choose how many events to show, and style what each event list item contains in your settings page, which we'll look at further down. [Click here for a demo of this calendar](http://demo.wp-events-plugin.com/calendar/normal-calendar/) #### Small Calendars Small calendars are similar to full-sized calendars, but do not contain lists of events within the calendar dates. Each calendar date which has events will be a link to a page showing the list of events that day. Use the [calendar_event_style](https://wp-events-plugin.com/event-search-attributes/#calendar_event_style) option to change how eventful days are marked, for example a coloured ring around the date (the default at this size) or coloured dots beneath it: | Default | Dots style | | --- | --- | | [Image: Small calendar, default style] | [Image: Small calendar, dots style] | [Click here for a demo of this calendar](http://demo.wp-events-plugin.com/) #### WP FullCalendar (seperate plugin) _This is a seperate plugin created by us_, which is freely available on the WordPress plugins repo, meaning you can install it straight from your dashboard. Search for "wp fullcalendar". [Click here for a demo of this calendar](http://demo.wp-events-plugin.com/calendar/) FullCalendar is a jQuery script that generates a beautiful AJAX-powered calendar, offering various styling possibilities. This behaves much in the same way as calendars with regards to displaying them with shortcodes, settings, widgets, etc. Please note that due to the way that FullCalendar works, certain features available in the native calendars may not be the same for FullCalendar and vice-versa. ### Calendar Display Options All calendar display options are located within the _Calendar format_ panel within the the Events > Settings > Formats/Layouts tab of your admin dashboard. These options will enable you to: - Change how/what event information is shown on eventful calendar days. - Decide how many events to show within on calendar per day. - How to link out to calendar day and event pages from the calendar. One important option when displaying Small and Full Calendars is _Long Events_, this just means that events spanning more than one day will be shown on each day it occors. If not enabled, then it'll only be shown on the starting date. #### Event Display Styles You can control how events appear on each eventful calendar day with the **calendar_event_style** option. Set it site-wide under _Events > Settings > Formats/Layouts > Calendar_ (the _Default event style_ setting), or override it per calendar via the shortcode, widget, block or PHP. The available styles are: - **Pills** (`pill`, the default) — each event is shown as a labelled pill/bar with its title. - **Single dot** (`dot`) — a single coloured dot beneath the date number. No overflow indicator is shown, no matter how many events fall on that day. - **Multiple dots** (`dots`) — one coloured dot per event, up to the per-day events [limit](https://wp-events-plugin.com/event-search-attributes/#calendar-limit), then a `+` for any beyond it. - **Rings** (`ring`) — a coloured ring drawn around the date number. Dots and rings take their colour from each event's first category colour, falling back to your default category colour. With the `dots` style, the number of dots (and the `+` overflow) honours the same per-day events _limit_ as the other calendar styles, which you can set in the calendar settings or per calendar. These styles work everywhere a calendar is shown: the `[events_calendar]` shortcode (e.g. `calendar_event_style="dots"`), the _Events Calendar_ widget (the _Event Style_ and _Events per day_ options), the _Events Calendar_ block (the _Event style_ and _Events per day_ inspector controls), and `EM_Calendar::output()`. ### Displaying Calendars On Your Site #### Main Events Page If you would like to show the Full Calendar on your main event page, you should go to the _Events > Settings > Pages_ tab in your admin dashboard and then open the _Events List/Archives_ panel. You'll see an option called _Display calendar in events page?_ If you are using the WP FullCalendar plugin then you'll see a section for FullCalendar in the General Tab, which provides the  _Override calendar on events page?_ option. #### Widgets There is a calendar [widget](https://wp-events-plugin.com/documentation/wordpress-event-widgets/ "WordPress Event Widgets") which you can use to display the Small Calendar in various widget areas of your theme. To add a calendar widget, visit your Appearances > Widgets page in your admin dashboard, and drag the widget called _Events Calendar_ to your desired sidebar. #### Shortcode You insert one single [shortcode](https://wp-events-plugin.com/documentation/shortcodes/ "Shortcodes") into your post and page content to display a calendar, here is an example: ```[events_calendar full="0" long_events="1"]``` This shortcode would create a calendar exactly like the calendar above, however, depending on where you inserted this it may stretch to fit the full-width. If you want to restrict the size of this calendar (for example, 250 pixels), you can wrap it in a div html element like so: ```html [events_calendar full="0" long_events="1"] ``` #### PHP Code _Requires knowledge of PHP and HTML._ You can directly insert calendars using PHP into your theme files. Here's an example equivalent to the sortcode and widget examples in PHP: ```php echo EM_Calendar::output(array(‘full’=>0, ‘long_events’=>1)) ``` ### Advanced Customization _Requires knowledge of PHP and HTML._ If you want to make some changes to the structure of the calendar. You can do this by overriding the default calendar templates within your theme. The files you'll want to move are: - _templates/templates/calendar-full.php_ - The Full Calendar - _templates/templates/calendar-small.php_ - The Small Calendar ## Event Categories URL: https://wp-events-plugin.com/documentation/event-categories/ Event categories are useful for grouping your events. You might want to divide parties from conferences, and lessons from gym sessions. It’s easy, just create a number of categories and assign each event to its own group. ### Activation By default, Categories are activated. To enable or disable event categories you can do this from the Settings page. ### Adding and Editing Categories To manage categories, ensure that your user role has the _edit\_event\_categories_ [capability](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities"). Categories are inserted through the _Events > Event Categories_ menu in your admin area. This will open a dedicated page where you can add, edit and remove categories. [Image: Add, edit and delete your categories from this page.] Once added one or more event categories, you’ll be allowed to select any of these categories for each event, through a box appearing on the right sidebar of the new/edit event page. Users with the _edit\_event\_categories_ [capability](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities") will also be able to quickly add new categories. ### Advanced Settings - Pages You can also edit category page and permalink details by visiting the _Events > Settings > Pages_ in your admin area, which should look like this: [Image: Choose whether to have a category page in your events settings 'Pages' tab] #### Event Category Page Since categories are a custom taxonomy, WordPress already creates archive pages for each category automatically, however these are usually very rigid templates and require you to have coding knowledge to modify. Events Manager allows you an easier way to override these pages and use [placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders") and basic html directly in your settings page (under the _Formats/Templates_ tab) to format how a category page looks. To enable this, select the _Override with Formats_ option in _Events > Settings > Pages > Event Categories_ in your admin area and proceed to the _Formats/Templates_ tab to style your category lists and pages. The default link structure for these pages are _mysite.com/events/categories/my-category/_. The _events/categories_ bit is controlled in the Permalink Slugs section in the above screenshot. The _my-category_ slug can be modified by editing the individual category. #### Event Categories Page If you would like a page that displays a list of categories, you can assign one of your pages as a categories page in your settings page, as shown above.  Alternatively, you can also use [shortcodes](https://wp-events-plugin.com/documentation/shortcodes/ "Shortcodes") such as _\[categories\_list\]._ By default, you should have a categories page created automatically which is a child of your default events page (also created automatically). This is optional, and should you prefer, you can delete this page and choose to not have a category page. You can change the layout and format of this page by using  [placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders") in your settings page (under the _Formats/Templates_ tab). ## Event Locations URLs URL: https://wp-events-plugin.com/documentation/location-types/urls/ Event Location URLs are a simple way to attach a URL to your event, in situations where you may want to link out to the event organizer for more information, or if the event is being held online in some form. > _Check our other location types for integrations with webinar platforms, such as [Zoom](https://wp-events-plugin.com/documentation/location-types/zoom/)_ Once enabled as per our location types documentation, simply select the URL location type in the location settings, and you'll be presented with two fields: - URL - The actual URL/address to link to. - Link Text - The text used when creating an HTML link. ### Displaying URL Information We have included some [placeholders](https://wp-events-plugin.com/documentation/placeholders/) and [conditional placeholders](https://wp-events-plugin.com/documentation/conditional-placeholders/) to help you display your meeting information on your event formats. We recommend wrapping this information in conditional placeholders so that non-URL events will not attempt to display it. #### Conditional placeholders _\{has\_event\_location\_url}...\{/has\_event\_location\_url}_ Displays the ... contents only if the event has a URL as the event location. _\{no\_event\_location\_url}_..._\{/no\_event\_location\_url}_ Displays the ... contents if the event specifically does NOT have an event location URL. #### Placeholders You can use the following bits of information with the following placeholders: - _**#\_EVENTLOCATION**_ - An HTML link, opens in a new tab. - **_#\_EVENTLOCATION\{url}_** - Just the URL - **_#\_EVENTLOCATION\{text}_** - Just the Link Text - **_#\_EVENTLOCATION\{\_self}_** - Regular HTML link - **_#\_EVENTLOCATION\{\_parent}_** - HTML link with target="\_parent" - **_#\_EVENTLOCATION\{\_top}_** - HTML link with target="\_top" #### Filtering URL events The _location\_type_ search attribute will support the value _zoom\_meeting_ for filtering events with Zoom Meetings, and zoom\_webinar for Zoom Webinars. For example: > \[_events\_list location\_type="zoom\_meeting"_\] Will only show events that have a Zoom Meeting associated with it. You can also use commas to filter multiple types, such as _zoom\_meeting,zoom\_webinar_ . ## Event and Location Approval URL: https://wp-events-plugin.com/documentation/event-approval/ If you [allow users to submit their events and locations](https://wp-events-plugin.com/documentation/user-event-guest-submissions/ "Accepting User-Submitted Events"), you probably don't want to allow them to directly publish their event. With [User Capabilities](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities") you can prevent specific user types from publishing these to your site. Events and Locations have three specific statuses (when not deleted and in the trash). - **Published** \- Events and location with the published status can be seen on your website. - **Pending -** Pending events and locations are not visible on your website, and are ready for you to approve and publish. The number of events and locations pending approval will also be displayed within your admin menu (see screenshot below). - **Draft -** Some required information is missing from your event or location and therefore cannot be published. If you disable the _publish\_events_ and/or _publish\_locations_ capability from a specific user role, users will not be able to directly publish their events to your site without your pre-approval. Also, should they update it their event or location goes back into pending mode. ### Publishing Events and Locations To publish, either click on 'Quick Edit' on an event or location: [Image: Hover over an event or location and click 'Quick-Edit' to edit basic information such as status.] Or change the status of the event or location when editing it directly: [Image: Change the status of your event or location by clicking the 'Edit' link next to the status.] When you publish an event, if this event also has a corresponding unpublished location, it will automatically attempt to publish that location as well. ### User Notification When an event is published, the event owner will be notified by email that their event has been published. You can modify the email template by visiting _Events > Settings > Emails > Event Email Templates_ in your admin area. ## Accepting User-Submitted Events URL: https://wp-events-plugin.com/documentation/user-event-guest-submissions/ With Events Manager you can let users submit events themselves. Although you can allow user submitted events to be published immediately, it's more likely you'll want events to be saved as Pending so that you can moderate them before publishing. Events Manager uses [user capabilities](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities") to control publishing privileges, which you can also fine-tune to suit your own needs. Capabilities are already assigned to the default WP roles when you first install Events Manager. By default, users at the subscriber level are only able to add, edit and delete their own events, recurring events and bookings. They're not able to publish events [without prior approval from admins](https://wp-events-plugin.com/documentation/event-approval/ "Event and Location Approval") or to access other features of Events Manager. _Note: When a user edits / resubmits an event, the status is changed to Pending meaning it will no longer be visible on the site until it's re-approved._ To extend or reduce the capabilities of users, go to _Events > Settings > User Capabilities_. For example, it you wanted to let users publish any kind of events instantly - without their events being put into Pending status - you'd make sure _publish\_events_, _publish\_recurring\_events_ and _publish\_locations_ were all checked. See more detailed information about [User Capabilities](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities") and [approving submitted events and locations](https://wp-events-plugin.com/documentation/event-approval/ "Event and Location Approval"). ### Interface options There are two choices of interfaces available when enabling user submissions. The first option is for submitters to use WordPress Admin, the second is to let them use pages on the front-end of your site. Although the interfaces are different, the feature set is exactly the same. #### Option 1 - WordPress Admin With this option, users edit events using the standard WordPress Admin Dashboard - minus access to those areas that are not enabled for their user level. You can see from the screenshot below that this version of the Add New Event form is the same as that used by admin users. This option is always activated by default, though you may want to also enable the front-end forms option. #### Option 2 - Front-end Forms With Events Manager you can also let users add events through the front-end your site. This is a good option if you want visitors to have a consistent user experience because they can add, edit and manage bookings on pages that have the same design as the rest of your site. To use this option, you first need to choose which pages will be displayed for the _edit events_ page, _edit locations_ page and the _manage bookings_ page. Before you can assign pages, you need to create them with the usual WordPress _Pages > Add New_ option. Because these are placeholder pages for dynamic content created by Events Manager, there's no need to add any content to these pages. Just publish an empty page with the page title you want to use and Events Manager will add the necessary content. Once you've created the pages, go to _Events > Settings > Pages > Other Pages_. In the lower half of the panel you'll see a heading called Front-end management pages. Under that heading there are three drop-downs for you to select which page is used to display each form. Select the three pages you just created and click _Save Changes_. You can also include the event submission form on other pages of your site by using the _\[event\_form\]_ shortcode within posts and pages or the _em\_event\_form()_ PHP tag within your theme templates. What users see on those pages depends on whether or not they are logged in. For example, logged in users going to the submit your event page will see this: This page lists all previous events the user has submitted. In fact, from this one page they can easily add, edit or delete any of their events. Unless you've enabled anonymous submissions (see the next section to learn how), users who aren't logged in will be prompted to login to see the event submission form: ### Anonymous Event Submissions This feature allows you to accept event submissions from users without them needing to create an account beforehand. Bear in mind that users submitting events in this way won't be able to view or edit their submissions afterwards. It's also important to remember there needs to be an internal user account associated with anonymous submissions, even though the user will be unaware of it. We recommend creating a separate dummy user account just for these types of submissions. Make the user level "subscriber" and choose a safe, non-dictionary password. You can enable anonymous submissions by going to _Events > Settings > General_ and clicking open the _Events Submission Forms_ panel. Scroll down to the _Allow anonymous event submissions?_ option and set it to Yes. From the _Guest Default User_ dropdown select the dummy account you created. You can also customize the _Success Message_ which users see after submitting an event. if you want, you can use Event Related and Location Related [placeholders](https://wp-events-plugin.com/documentation/placeholders/) within the message. The event submission page will look something like this: Notice how this version of the form includes _Name_ and _Email_ fields at the top. These allow you to send an email to the user when their event is approved. **Edit Locations page** Logged in users see the locations page, allowing them to add, edit and delete locations. Bear in mind that users can also add new locations when submitting a new event too, unless you force them to choose a currently submitted location via your settings page under the _General (tab) > General Options > Use dropdown for locations?_ Users who aren't logged in will be prompted to login. **User managed bookings** If the user selected _Enable registration for this event_ under the _Bookings/Registration_ section of their submitted event, they can view and edit all their bookings via the _Manage Bookings_ page. #### Fine-tuning the Events Submission form Head over to _Events > Settings > General > Event Submission Forms_. Here you'll find options to activate the visual editor (making it easy for users to add formatting like bold and italics to their submission) and allow anonymous submissions. You can also customize the messages users see when they submit an event and when an event is updated. ### Email Notifications As an Administrator, you can choose to receive an email when users submit an event. To activate the feature, go to _Events > Settings > Emails > Event Submission Templates_. Add the email address you want to send notifications to in the _Administrator Email_ field. You can add more than one address by separating them with a comma. If don't want to receive notifications, leave the box empty. Under the _Administrator Email_ field, there are templates that control which information is included in emails sent to administrators. Whenever an event is submitted by a non-admin users, Events Manager will send out the appropriate emails. Below the Admin email templates, you'll see more email templates under the heading _Event Submitter Emails_. These govern the format for emails sent to the user who submitted the event. Both sets of email templates can use the standard Events Manager [placeholders](https://wp-events-plugin.com/documentation/placeholders/). ## User Capabilities URL: https://wp-events-plugin.com/documentation/user-capabilities/ Wordpress user authentication works under the [User Roles and Capabilities](http://codex.wordpress.org/Roles_and_Capabilities) model, which means users of a certain Role has certain Capabilities. For example an Administrator (role) can Activate Plugins (the activate\_plugins capability). Events Manager uses the same principle, and you can allow specific permissions to certain users, such as only administrators and editors can publish an event. User Capabilities for Events Manager can be found in the settings page. If you are using MultiSite, this would be located in your network admin area. [Image: User Capability Settings] On this screen you can check or uncheck the relevant boxes to change what different user levels can and can't do. Below is an explanation of each capability. ### Event Capabilities **read\_private\_events** Events can be marked as private, in these cases, only users with this role will be able to access these events and view them in event lists. **edit\_events** Users can access the event registration forms and can view the events option in the admin area. They will be able to register and manage their events (not delete). Note that _publish\_events_ is needed to actually publish the event on the site. **delete\_events** Allows the user to delete their own created events. **edit\_others\_events** Allows users to edit other users events. This also allows the user to change the owner of the event, a drop-down menu of users will appear in the event registration forms. **delete\_others\_events** Allows user to delete any event. **publish\_events** User can publish events. Users without this privilege will have their events set to pending status, and will require a user with this capability to [approve it](https://wp-events-plugin.com/documentation/event-approval/ "Event Approval"). Note that any time an event detail is modified by a user without this capability, the event will always go back into pending mode. ### Recurring Event Capabilities Recurring events are very similar to normal events, but allow users to create many events at once. For this reason, creation and modification of event templates can be controlled seperately. Individual recurrences created by recurring events are managed by the individual event capabilities. **edit\_recurring\_events** User can create and edit recurring events. Bear in mind that the _edit\_events_ capability must be checked for users to edit the individual recurrences. _publish\_recurring\_events_ must also be checked for users to publish the events. **delete\_recurring\_events** User can delete recurring events (individual recurrences also get deleted). **edit\_others\_recurring\_events** User can edit recurring events owned by another user, and change ownership of these events. **delete\_others\_recurring\_events** User can delete recurring events owned by another user.  Individual recurrences also get deleted. **publish\_recurring\_events** User can publish recurring events. Users without this privilege will have their events set to pending status, and will require a user with this capability to [approve it](https://wp-events-plugin.com/documentation/event-approval/ "Event Approval"). Note that any time an event detail is modified by a user without this capability, the event will always go back into pending mode. When initially created, the event recurrences are not created. Once an event is published for the first time, the recurrences will be created. If a recurring event is edited, individual recurrences will not be modified until the recurring event is re-approved. ### Location Capabilities **read\_others\_locations** Locations are owned by their creators too, it is possible to use other people's locations for their event by enabling this capability, and users will be granted read-only access to all other locations. **read\_private\_locations** Locations can be marked as private, in these cases, only users with this role will be able to access these locations and view them in location lists. **edit\_locations** Locations can be created by the user. They can create and edit (not delete) their own locations. **delete\_locations** Allows users to delete their own locations. **edit\_others\_locations** User can edit locations owned by other users and reassign ownership. **delete\_others\_locations** Allows user to delete any location. **publish\_locations** User can publish locations. Users without this privilege will have their locations set to pending status, and will require a user with this capability to [approve it](https://wp-events-plugin.com/documentation/event-approval/ "Event Approval"). Note that any time a location detail is modified by a user without this capability, the location will always go back into pending mode. ### Category Capabilities **edit\_event\_categories** Allows users to add and edit categories (there is no ownership of categories). If unchecked, the users will not see a category link in the events menu, but will still be able to assign categories to events. **delete\_event\_categories** User can delete categories. ### Booking Capabilities **manage\_bookings** User can allow bookings on their events and can also manage bookings made for their events. Requires _edit\_events_ enabled as well to work. **manage\_others\_bookings** Bookings for events owned by other users can be managed by the user. Does not require _edit\_others\_events_ to work. ### Other Capabilities **upload\_event\_images** User can upload a featured image for their event and location. ## Set Up Event Bookings URL: https://wp-events-plugin.com/documentation/set-up-event-bookings/ There are many options you can set to change the way bookings are handled on your site. Here are a few important steps to take. ### Activating/Enabling bookings By default, bookings are already enabled, but you can disable or enable them via the admin dashboard on the _Events > Settings_ page. On this page, under the _General Options_ panel, set the option _Enable bookings?_ to yes or no. ### Enabling bookings for an event To set up bookings, you need to check the _Enable registration for this event_ checkbox. When you do this, you will see a list of tickets which you can modify. [Image: bookings] ### Setting up event tickets Events can have one or more tickets, each ticket can have certain restrictions or conditions: - _Price_ \- The price of this booking. - _Min/Max_ - Setting either or both of these will set an lower and/or upper limit of tickets a person must book to apply for this ticket type. - _Start/End_ \- Add opening and/or closing dates for this ticket, such as the early bird special! - _Available Spaces_ - Assign a maximum number of this ticket you want to sell. By default, an open free ticket is created with a maximum of 10 spaces available, but you can edit this by clicking any of the edit buttons. You can also delete tickets, but only if newly created or if there are no bookings associated with it. When you open your event for editing, the red square should turn green if the ticket is considered as available by Events Manager. [Image: bookings-ticket-form]  Once you have saved your events, it may look something like this in the admin area followed by the public page: [Image: Bookings enabled with three tickets for an upcoming event.] ### Displaying a bookings form By default, a booking form should automatically display if your event has bookings enabled. To display a bookings form on your event pages, you need to add a #\_BOOKINGFORM [placeholder](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders") to your formats, in _Events > Settings > Templates/Formats_. If there are no bookings for this event, the form will not be displayed. If the event has bookings enabled but is full, a message will say this in place of the booking form. You can also use [conditional placeholders](https://wp-events-plugin.com/documentation/conditional-placeholders/ "Conditional Placeholders") within your formats to hide information based on whether this event has bookings or not. The conditional placeholders relevant to bookings are _has\_bookings_ and _no\_bookings._ [Image: A sample booking form with three tickets] ### Single ticket mode The default setting for Events Manager is the use of multiple tickets for an event. It is possible limit users to providing and selling one ticket for that event. To do this, see the [booking options](https://wp-events-plugin.com/documentation/booking-options/ "Booking Options") page. ## Multiple Bookings Mode URL: https://wp-events-plugin.com/documentation/multiple-booking-mode/ Please take a look at our [MB Mode Demo Site](http://demo.wp-events-plugin.com/mb/) for an example of how this feature will work from the customer point of view. It is now also possible to enable 'Multiple Bookings Mode', which essentially turns your event bookings flow into one similar to a shopping cart. At this point, users will be able to book many events in one go and pay once for all of them. ### How it Works (What's different) The flow will generally work like this: 1. User chooses an event to book 2. User fills out attendee information and any booking-specific information in your custom form. - Any custom forms you use for events at this point will be stripped of user fields, these fields are only used on the checkout page and will apply to all bookings. 3. User submits booking, booking gets added to a cart. 4. If you have added a booking cart widget to your sidebar, this should automatically be updated and would look similar to this: [Image: mb-booking-cart-widget] 5. User can repeat steps 1-4 multiple times. 6. When a user is ready to pay, they proceed to the checkout to review and finalize their bookings, where they will see a total price to be paid. [Image: mb-cart-checkout-1] [Image: mb-cart-checkout-2] [Image: mb-cart-checkout-3] 7. Users will be able to enter a coupon code at this point to apply a discount 8. User enters information requested by your checkout custom booking form, minimum requirement is an email. 9. User selects payment method and proceeds with payment the same way as with a normal single booking. #### Booking Emails Multiple Bookings will work much the same way as a single booking, with some subtle differences. When automated emails are sent to the users and admins, one single email will be sent for all the bookings to the site administrators  rather than one email per single booking, which can contain some new summarizing placeholders. In these emails, single event placeholders e.g. dates, event name, etc. will not work as expected, since the booking can contain one or more event. You do have the option to additionally send individual emails for every event (instructions on setting up emails are further down), which will go out to the event owner. #### Managing Multiple Bookings When viewing the admin area, you will still see individual bookings as you would in normal booking mode. You can still manage bookings independently from each other as usual such as changing status, resending emails, modifying information etc.  When doing so, the normal single event booking emails would be sent to users (if applicable). You will also be able to manage them altogether in a separate Multiple Bookings admin window. You should see a warning when viewing/editing a single booking with a link to the master booking. Here you can view all the bookings made at once, add notes and payments for this booking, as well as modify their status in bulk, which would result in the Multiple Booking email being sent to the person who booked rather than individual booking emails. [Image: mb-booking-edit-single] #### Coupons When you turn on Multiple Bookings Mode, all [coupons](https://wp-events-plugin.com/documentation/coupons/ "Coupons") immediately become site-wide coupons, meaning they are available to any booking being made. Additionally, coupon discounts are not applied to individual events but to the booking as a whole. ### Caveats & Limitations This feature makes some significant changes to how bookings are made. There are some inevitable changes to how bookings work and should be considered when you're deciding whether or not to use this feature: #### Booking Confirmation Emails One booking confirmation email is sent for all events booked, therefore you cannot make use of single event placeholders (even if there is only one event booked). The new summarizing placeholders available to you must be used instead. The only times single event booking emails are sent is if you manually alter the booking status of that single event booking and also choose to send the relevant confirmation email when doing so. #### Events belonging to different users Since people can book many events at once if you allow multiple users to submit events with bookings enabled, it is highly likely that at one point someone will book two events belonging to different users. Unless they have the manage\_others\_bookings [capability](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities"), they will not be able to view information submitted on the checkout page form. They will still be able to view any [user fields you created in our form editor](https://wp-events-plugin.com/documentation/custom-booking-forms/ "Custom Booking Forms"). #### #\_BOOKINGBUTTON Placeholder #\_BOOKINGBUTTON functionality doesn't change, it still registers a single event/ticket booking. ### Enabling/Setting Up Once you have [installed and set up Events Manager and Events Manager Pro](https://wp-events-plugin.com/documentation/getting-started-guide/ "Getting Started Guide"), you can proceed with these additional steps to enable Multiple Bookings Mode. #### Create Pages You need to create two normal WordPress pages, which you can name whatever you want, but will serve the purposes of: - Checkout - Where users will view their bookings, fill out relevant user information (if not logged in) and then proceed with a selected payment method. - Cart - Users can view their booking information and proceed to the checkout. #### Create a custom checkout form The checkout page can contain a unique custom booking form, which will be used to obtain any user information (minimum being an email, like with a single booking), as well as any additional information you may want to obtain for the booking as a whole. If you don't want to reuse a form you already have, or to make sure you clearly distinguish forms from each other, create a new [custom booking form](https://wp-events-plugin.com/documentation/custom-booking-forms/). #### Enable Multiple Bookings To enable this feature, you need to enable this from your dashboard - _WP Admin > Events > Settings > Bookings (Tab) > Multiple Bookings Mode_ [Image: mb-booking-settings] When you select 'yes' to enable this feature, you will be able to assign the Cart and Checkout pages you created earlier, as well as the checkout custom form you'd like to use. You will also see some options to specific certain lines of text, such as a message that is shown when a booking is added to the cart, or of no bookings have been added yet. At this point, you need to save your settings to enable further Multiple Bookings settings to appear. #### Configure Emails Once enabled, you can configure a new set of email templates which are sent instead of individual booking templates when dealing with a Multiple Booking. You can find this in _WP Admin > Events > Settings > Emails (Tab) > Multiple Booking Email Templates._ [Image: mb-booking-settings2] There will already be some preconfigured templates for you to start with, but you can edit these to your specific needs. The types of email templates that you can modify are the same types you can modify for single bookings, which are still available in the same tab under _Booking Email Templates_ ### Widget and Shortcode When enabled, you will have a new widget and shortcode available to you for displaying the cart contents. When bookings are added to the cart, this widget is automatically updated without the need for a page refresh. [Image: mb-booking-cart-widget-setting] The Widget is called 'Event Bookings Cart', which contains some custom settings: - _List Item Format_ - the format for listing each event booked, which can contain any [booking placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders"), if not supplied a default will be used, if blank, no events will be listed. - _Loading Text_ - When an event is booked, this text will be shown whilst the cart contents are refreshed - _No Bookings Text_ - shown if no bookings have been made yet You can also use this in shortcode form, called **_\[em\_cart\_contents\]_** and can also contain these arguments: - format - the format for listing each event booked, which can contain any [booking placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders"), if not supplied a default will be used, if blank, no events will be listed. - cart\_text - the text link which points to the cart page - checkout\_text- the text link which points to the checkout page - no\_bookings\_text - shown if no bookings have been made yet - loading\_text - when an event is booked, this text will be shown whilst the cart contents are refreshed ### Placeholders When using [placeholder formats](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders") (e.g. in a confirmation email) to display information about a multiple booking, you are displaying information about a group of individual bookings. Due to this, certain placeholders available in single booking formats will not provide useful information as it is limited to showing a single piece of information, for example: - Any event, location, category placeholders such as #\_EVENTNAME, #\_LOCATIONNAME, etc. - Any booking placeholders referring to specific ticket information, such as \_BOOKINGTICKETNAME However, any placeholders specific to bookings, such as #\_BOOKINGSPACES, #\_BOOKINGPRICE, etc. will be available and will contain the total sum, such as total price and spaces in these cases. These new placeholders can be used in your new email templates to show information about the individual event bookings. - _#\_BOOKINGTICKETS_ - Shows a list of all tickets booked. - _#\_BOOKINGSUMMARY_ - Shows a list of all events booked, broken down by ticket type and price/spaces - _#\_BOOKINGATTENDEES_ - Shows a list of attendee information filled per event and by ticket type ### Developers & Custom Gateways We've tried to make this new move as painless as possible, however, it is inevitable that some changes have to be made to custom Gateways, just like we had to make some small changes to the gateways included in Pro. By default, your gateway will not be available for usage once Multiple Booking Mode is enabled. This is a safety feature so that things don't work unexpectedly. To enable your gateway for activation, you simply have to add this property to your extending gateway class: ```php var $supports_multiple_bookings = true; ``` Before you do that though, there's two things you should be aware of: - In PayPal, the only change we had to make along with the above is change any instantiation of an EM\_Booking object (in our case, one line) like so: ```php $EM_Booking = new EM_Booking($id); //change this to: $EM_Booking = em_get_booking($id); //done, now you will get either a EM_Booking or EM_Multiple_Booking object! ``` - If you are hooking into specific booking filters, particularly em\_booking\_get\_post, em\_booking\_validate, and em\_booking\_save you should check what mode you're in and use the variations of these filters, which are em\_multiple\_booking\_get\_post, em\_multiple\_booking\_validate and em\_multiple\_booking\_save respectively. Here's what we did in our Authorize.net gateway: ```php if( get_option(‘dbem_multiple_bookings’) ){ add_filter(’em_multiple_booking_save’, array(&$this, ’em_booking_save’),2,2); }else{ add_filter(’em_booking_save’, array(&$this, ’em_booking_save’),2,2); } ``` In a nutshell, a multiple booking is an extended class of the original EM\_Booking class, but is now called EM\_Multiple\_Booking, which overrides certain parent functions to provide the extra functionality needed. You can check your booking object when using the new em\_get\_booking() function to see if the result is a EM\_Multiple\_Booking class like so: ```php if( get_class($EM_Booking) == ‘EM_Multiple_Booking’ ){ //This is a Multiple Booking object } ``` ## Manage Attendees URL: https://wp-events-plugin.com/documentation/manage-attendees/ You can manage your bookings from within your Events admin area or if you have BuddyPress enabled you can manage bookings for events you created from within your profile pages. If you have disabled booking approvals from the [booking options](https://wp-events-plugin.com/documentation/booking-options/ "Booking Options") then bookings will automatically be confirmed and there will never be any pending booking screen messages like with the screenshot on the right. This page shows a bookings table for upcoming event as well as a list upcoming events with bookings enabled. If booking approval is enabled then this will show pending bookings by default. ### Booking Admin Pages There are various pages which you will encounter when managing your bookings. These include: - **Dashboard** - Main bookings page, shows all bookings and events - **Event** - Single event and bookings for that event - **Ticket** - View all bookings which have a specific ticket - **User** - View all bookings belonging to a user Each page shows bookings using the same booking table (see below), but restricts the types of booking shown according to the above. ### The Bookings Table Our bookings table provides a uniformed way of viewing and navigating your bookings in a quick loading and easy to use fashion. [Image: The bookings admin table allows you to view and manage all the relevant bookings quickly.] #### Booking Links and Actions The bookings table contains a useful 'Actions' column which is shown by default and contains various useful shortcuts. Aside from a link to edit the booking, depending on the booking status, the Actions column will contain links to Approve, Reject, Unapprove, Confirm and Delete the booking. For some actions (e.g. Approve, Cancel, Reject), clicking on these will automatically send a corresponding email to the attendee. #### Filter Bookings There are various options for filtering your bookings which can be used in combination: - **Event Scope** _(only when viewing bookings for all events)_ - You can choose to whether to view bookings for future/past/present events, and various other time ranges. - **Rows -** Decide how many rows to show at once. - **Status -** The status of the bookings #### Show/Hide Columns You can choose which columns to display and in whatever order you choose. There are many columns to choose from, including custom fields you created in your form editor. [Image: Click on the cog of a bookings admin table to choose your columns and other default values.] To add/remove columns, drag the ones you want to see to the left yellow column, and move unwnted ones back into the grey columns. You can arrange the order of columns by dragging them up and down. ##### Displaying Custom Fields From Pro If you create custom fields in your booking forms or user fields, you should see these columns available on the right. #### Exporting to CSV Often you'll want to export booking information into a spreadsheet. CSV files can be read by most common spreadsheet applications including Office, Google Docs and Open Office. When exporting, you'll have a similar choice of fields as when showing/hiding columns. There is one difference, which is whether you check the _Split bookings by ticket type_ box. When you click this, more fields will be made available such as _Ticket Name_ and _Ticket Price,_ which are not relevant to an entire booking. [Image: bookings-table-admin-csv] When you click the _Export Bookings_ button, you should be offered a file to download. If you have exported bookings then you will see one row for each booking. If you are exporting bookings split by ticket type, you will see one row for each ticket type in each booking, and certain columns pertaining to the whole booking will repeat themselves (e.g. Name, Total Price, etc.). One useful column to include in ticket exports is the booking id, which links tickets to a single booking. ### Edit Bookings Page When you click on the _view/edit_ link on a bookings table, you'll be taken to a page where you can view all the details about that specific booking, and edit details about the booking. This page contains various sections: #### #### Event Details and Personal Details These two sections are purely for informational purposes. These sections also provide links to view all bookings for this event as well as all bookings for this specific user. To edit the user information, you should visit that user profile in the _Users_ menu of your admin dashboard. #### Booking Details and Editing The _Booking Details_ meta box is the central area for this form, as it contains booking-specific information and is also where you would edit the booking itself. The first line shows the status of the booking as well as two buttons; one allows you to change the status of the booking, the other allows you to resend the booking status email (e.g. if cancelled a cancellation email will be resent). Next is the tickets table, which breaks down the booking by tickets, and shows values such as taxes, coupons, etc. If you click on individual ticket names, you can view all bookings which are using this ticket in a new page. Below the tickets table are the fields from the booking form, minus the user fields. To edit this and the ticket quantities, you must first click the Modify Booking button, which will convert all the values into input fields: #### Booking Notes Booking notes allow event admins to add private notes about that specific booking, and this information will only be seen by users who have permission to manage bookings for that event. When you add a new note, it'll appear above the comments box: [Image: Add private notes to your booking for future reference] #### Add Offline Payment (pro) If your attendees pay you offline, e.g. via the phone, check etc., then you may want to record these payments within your bookings. The offline payment form allows you to add partial or full payments as well as refunds (negative numbers). To add an offline payment, simply enter the quantity, an optional comment and click the _Add Offline Payment_ button. If your payment amount is equal to or more than the pending amount for this booking then it will be automatically approved. If you provide a refund (or partial refund), bookings will not automatically revert to Pending. When you add payments in this way, they will appear in the transaction history as an offline payment, despite whether or not the Offline gateway is enabled on your booking form. #### Transaction History (pro) If you're using Gateways, then you can also view payment history for this specific booking. More information about the transaction history table can be found in the [Payment Gateways Overview](https://wp-events-plugin.com/documentation/payment-gateways-overview/ "Payment Gateways Overview"). ## Add Bookings Manually URL: https://wp-events-plugin.com/documentation/manual-bookings/ Bookings can also be added manually. You can add a booking via any event bookings managment page. There should be an "Add Booking" button next to the page title: [Image: bookings-add-bookiong-button]Adding a booking is much like the going in with a different browser and booking as a different user, but with two major differences. 1. You have the option of selecting a current user from the dropdown, or create a new one. 2. You decide whilst booking whether the user has fully paid or provided partial payment. If you enter a quantity paid, or mark the booking fully paid, then a corresponding offline transaction record will also be created. If fully paid, the booking will be marked as paid and confirmed, along with sending a user a confirmation email, opposed to a pending mail if the booking is not fully paid, and it will be marked as awaiting payment. [Image: A typical manual booking form][](http://wp-events-plugin.com/wp-content/uploads/2011/05/gateways-offline-booking.png) ## Allow Bookings Without Creating User Accounts URL: https://wp-events-plugin.com/documentation/no-user-bookings/ Events Manager automatically creates an account for each new user that books a space at an event. The benefits of this are that users can return to the site, log in, and view their booking details, cancel, and opens the possibility to much more customer interaction. There are various occasions where site owners do NOT want to allow users to create accounts on their website. Due to an overwhelming number of requests for this possibility, we created a workaround called _No-User Booking Mode_. ### How It Works What happens in this mode is that bookings are still attributed to a user account, but in No-User Booking mode, ALL bookings not belonging to a registered user will be assigned to a 'dummy' user. All the personal information about that person who made the booking will be stored within the booking database tables rather than the user tables. When bookings belonging to this dummy user are loaded for viewing or processing, the personal information of the attendee is loaded and replaces the dummy user. You can still use the normal user bookings in this mode, because registered users will still have to log in because their email is already being used. In these cases, bookings will be attributed to the logged in user and they'll be able to access their booking information as normal. ### Activating No-User Bookings To Activate No-User Bookings, visit your _Events > Settings > Booking Options_ tab in your admin dashboard, and there you'll see the _No-User Booking Mode_ panel where you can set _Enable No-User Booking Mode?_ to yes. In the same settings panel you can also choose to allow logged-out users to supply emails belonging to registered users, but bear in mind that bookings made using registered emails whilst the user is logged out will still be treated as a 'no-user' booking which won't appear in the history of bookings for that specific user. ### Disadvantages of No-User Bookings - Users cannot log in and view their previous and current bookings. - Event Admins cannot view the history of a single user. - Event admins cannot search for specific users to bring up booking information. ## Custom Booking Forms URL: https://wp-events-plugin.com/documentation/custom-booking-forms/ Events Manager Pro adds a high degree of flexibility to your booking forms by allowing you to add various types of fields and gather specific information from your attendees. You can edit your forms from within the Events > Forms Editor in your admin area. ### The Form Editor Each form editor contains a set of fields which you can add/remove/edit. You can also drag these fields in order to change the ordering. Each row in the editor represents a single field and can have the following columns: - **Label -** _This is what your users will see next to the input fields_ - **Field ID -** _Automatically generated, useful if using placeholders like #\_BOOKINGFORMCUSTOM\{field\_id}_ - **Type -** _Determines what type of field this is, for further information on types, see further down._ - **Required -** _Is this field required?_ - **'Options' Link -** _The options link expands the row to show advanced options for your chosen field type._ - **'Remove' Link -** _Remove the field from the form._ To add another field to the form, click the _Add booking field_ button. This will add a new, blank field row to the bottom the form. How you fill it in and the settings you apply to it depends on the kind of information you want to collect. You can also delete a field by clicking the remove link, or change the order of form fields by dragging the icon with four arrows on the left of each panel. #### Creating a new field : Example Let's suppose you want ask for a phone number. Under _Label_, type in the name you want the text field to have when it appears on your website - "Phone Number", for example. Next, click in the _Field ID_ box. You'll notice Events Manager automatically creates an ID for you based on the Label you added. So the Label "Phone Number" will be given a Field ID of _phone\_number_. Unless you have a particular reason to change the generated Field ID, it's best to leave it as it is. Next, from the _Type_ dropdown select _Text_. Three extra options will appear under the dropdown. [Image: Type Text selected] All three fields are optional but here's how you can use them to enhance your form. _Tip Text -_ Add something like "Please leave your full number with area code". _Regex -_ To limit users to using only numbers you could use the regular expression: _^\[0-9\]+$_ _Error Message -_  Give a meaningful error message if the regex above doesn't match, such as 'Please use numbers only'. ### The Forms #### Booking Form This is the form shown to users below where ticket quantities are selected. The information collected from this form will be stored on a per-booking basis and will be requested on every booking. [Image: An example custom booking form] The above image is an example default custom booking form. When you first activate Events Manager Pro, custom booking forms will be enabled and the default name/email/address/comments structure will be used. You can start editing immediately, or if you just want to leave things the way they are, that's fine too. The only required field here is the user email, which is a default registration field used to create a user account and email the user information about their booking. This field will not appear on your booking form when users are logged in, since we already know the user email from their account. #### User Fields You can define custom user fields which are stored along with other user account information when users make a booking for the first time on your site. Once created here, they are available as new field types in your booking form editor. All user fields you add here will be available when viewing and editing user profiles within your WP admin area. You can see this by clicking on _Users > Your Profile_. User fields are created the same way as creating a booking form field, you assign it a label, decide on the type of field (e.g. text, checkbox, etc.), and add any extra options relevant to that field type. [Image: The user fields editor looks just like the booking form editor and works much the same way.] If a user is logged in, these fields disappear on your booking forms, however, you can choose whether to display the values and/or make them editable by visiting your Settings > Booking Options tab : [Image: Custom booking form options in your Settings page under the Booking Options tab.] #### Attendee Form This form is used to collect information for every space a user books. If your guests want to book two spaces, then two forms will be shown requesting information about each attendee. If the user chose two spaces for two different ticket types, then four forms are shown in total. Attendee forms do not collect any user account information, these fields are requested on a per-booking basis and this information is stored as part of the booking. [See our guide for adding an attendee form.](https://wp-events-plugin.com/documentation/how-to-add-an-attendee-form/ "How to add an Attendee Form") #### Common User Fields for Gateways Since many payment gateways require personal information from users (e.g. for address verification), Events Manager provides a way to associate your custom User fields with a set of commonly used fields. Using this method, all gateways that accept extra user information can access this information regardless of what you actually call your user fields. [Image: Assign common gateway fields from your custom user fields ] You will find your common user fields at the bottom of the Form Editor page, below your booking form and user fields editors. By default, Events Manager Pro should automatically create these common user fields and associate them. In many cases you could leave these as is. One thing to bear in mind is that if your gateway does require these address fields, you may want to consider adding them to your booking form to ensure that new users enter this information. ### Customizable Field Types Below is a list of all available custom field types and their subsequent options. Here's the reformatted markdown: #### html Enter HTML into this field type to add custom information to your forms. Click the arrow to view options for each type. - `Content` - The html to be displayed #### checkbox Shows a single checkbox item, which results as Yes/No whether filled or not. - `Checked by default?` - Force the box to be checked by default. - `Error Message` - Shown if this field is required and not checked (e.g. you must agree to our terms and conditions). - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### text Simple text input, used for things like names, phone numbers, etc. - `Regex` - This accepts regular expressions, e.g. `^[A-Z]+$` would only accept capital letters. See [Regular Expressions Quick Start](http://www.regular-expressions.info/quickstart.html) for more info on regular expressions. - `Error Message` - This error is shown when the above regex fails. - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### textbox A multiple lined textbox, suitable for longer texts such as comments or a list of names. - `Regex` - This accepts regular expressions, e.g. `^[A-Z]+$` would only accept capital letters. See [Regular Expressions Quick Start](http://www.regular-expressions.info/quickstart.html) for more info on regular expressions. - `Error Message` - This error is shown when the above regex fails. - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### checkboxes Multiple checkboxes where you can select more than one option, e.g. interests. - `Options` - A list of available options, one per line. - `Error Message` - Shown if this field is required and not checked (e.g. you must agree to our terms and conditions). - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### radio Multiple options, but only one can be chosen. - `Options` - A list of available options, one per line. - `Error Message` - Shown if this field is required and not checked (e.g. you must agree to our terms and conditions). - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### select A single drop down menu can be shown with a list of given values. Users can choose one of these options. - `Options` - A list of available options, one per line. - `Use Default?` - If checked, the first value in the options list above will be pre-selected. Supercedes default text. - `Default Text` - If you want to have a default value that can't be used as a value (e.g. "please choose from this list") you can enter this here. - `Error Message` - Shown if this field is required and a value is not selected. - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### multiselect Much like a select box, but larger and allows users to select more than one field by keeping the Ctrl key (or command key in macs) pressed whilst choosing. - `Options` - A list of available options, one per line. - `Use Default?` - If checked, the first value in the options list above will be pre-selected. Supercedes default text. - `Default Text` - If you want to have a default value that can't be used as a value (e.g. "please choose from this list") you can enter this here. - `Error Message` - Shown if this field is required and a value is not selected. - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### captcha This field helps prevents spammers from successfully filling your form. This uses Google's [reCaptcha](http://www.google.com/recaptcha) service, which is free to sign up for and requires API keys from when you register your domain [on their website](https://www.google.com/recaptcha/admin/create). This field is always required. - `Private/Public Keys` - The keys provide to you by Google. - `Error Message` - Shown when the CAPTCHA is incorrectly entered. #### country This is essentially a pre-populated select field with the list of countries. - `Error Message` - Shown if this field is required and a value is not selected. - `Tip Text -` This text will appear as a tool tip when users hover over the label of a field. #### signature Captures a legally-meaningful signature for waivers, consent forms, medical/photo releases, or terms and conditions, backed by a full audit trail (exact wording signed, signer identity, timestamp, IP address, and tamper detection). See the dedicated [Signature Fields](https://wp-events-plugin.com/forms/fields/signature/signature) guide for its full set of options and how signing works on the front end. #### Registration Fields Registration fields are fields already available to WordPress user accounts. These field types are only available to your booking forms. All registration fields are considered to be text fields and correspond directly with the native WordPress user profile values. For this reason we will only explain some specific registration fields available to you: **Email** This is the only required field in the form. This is because we need to have an email to send event information to and create an account with so users can access their booking information. **Name vs First/Last **Name**** You can only use one or the other, as using Name with the other two may cause unpredictable behaviour. The name field is the equivalent of using the first and last name fields, and the name is split into first/last by the first space. This means that "John James Smith" would have first name "John" and last name "James Smith". **Username Login** By default if this field is not used a username is created for new registrants automatically based on their email address. You can allow users to select their own username with this field. #### Custom Registration Fields These field types are the user fields you created using the [User Fields Form Editor](#user-fields), described further up. These field types are only available to your booking forms. ### Accessing/Viewing Booking Information Once a booking has been made, these field values are stored along with the other booking information and can be accessed by viewing a single booking. To view a single booking, visit the bookings dashboard or a single event booking management page and click the 'view/edit' link next to the relevant booking. You will see the booking information within the Booking Details window. Note that registration information isn't shown here as it is available on the user information fields. ### Displaying your custom forms If you create more than one form, the default form will be used unless you specifically tell an event to use a different booking or attendee form. After your form is created, you'll be able to include it with any event by selecting it from the dropdown select under _Booking Form_ in the _Bookings/Registration_ panel that appears on every event page in WordPress admin. [Image: Selecting Attendee forms] ## Upload Field URL: https://wp-events-plugin.com/documentation/forms/fields/upload/ ## Upload Fields for Custom Forms – Documentation ### Overview Events Manager Pro 3.5 introduces **Upload Fields** for booking, attendee, and user forms. This feature allows you to collect images, documents, or other files from attendees during the booking process, with file previews and upload restrictions built in. Upload fields can be added to: - **Booking Forms:** Files uploaded apply to the entire booking. - **Attendee Forms:** Each attendee can upload their own files. - **User Forms:** Files uploaded by registered users are stored in their profile and persist across bookings. ### Enabling the Visual Uploader Before adding upload fields, ensure the **Visual Uploader** is enabled: 1. Navigate to **Events > Settings > General > Uploads**. 2. Enable **Visual Uploader**. 3. Set **default upload size limits** and **image dimension limits** (optional). *(Screenshot Placeholder)* These defaults can be customized for each upload field later. ### Adding an Upload Field You can add upload fields to booking, attendee, and user forms. #### Booking Forms 1. Go to **Events > Booking Forms**. 2. Select the **form you wish to edit**. 3. Click **Add Field** and select **Upload Field**. 4. Configure the field: - **Label:** Display name for the field. - **Allowed File Types:** E.g., images, PDFs, or custom extensions (e.g., `.jpg, .png, .pdf`). - **Max File Size:** Individual file size limit. - **Max Uploads:** Limit the number of files that can be uploaded. - **Image Dimensions (Optional):** Set maximum width and height for images. 5. Click **Save Form**. *(Screenshot Placeholder)* #### Attendee Forms 1. Go to **Events > Attendee Forms**. 2. Follow the same steps as the **Booking Forms** section. 3. Uploaded files will be specific to each attendee. *(Screenshot Placeholder)* #### User Forms 1. Go to **Events > User Forms**. 2. Follow the same steps as the **Booking Forms** section. 3. Files uploaded by users will be stored in their profile and automatically attached to future bookings. *(Screenshot Placeholder)* ### Making a Booking with Upload Fields 1. Navigate to an event with a form containing upload fields. 2. Complete the form and upload the requested files: - Supported files will display a **preview** (images, PDFs). - Unsupported files will be rejected based on your settings. 3. Submit the booking. *(Screenshot Placeholder)* ### Managing Uploads in the Admin Area 1. Go to **Events > Bookings**. 2. Open a booking with uploaded files. 3. Uploaded files will be displayed with **file icons** and **previews**. 4. You can: - **Preview Files** (images, PDFs). - **Delete Files** (with the option to undo before saving). - **Upload New Files** (adhering to field restrictions). 5. Click **Save Changes**. *(Screenshot Placeholder)* ### Managing User Uploads 1. Go to **Users > All Users** in WordPress. 2. Select a user with uploaded files. 3. You will see their uploaded documents associated with **User Forms**. 4. You can **add new files**, **remove files**, or **replace files**. 5. Changes will be reflected in **all future bookings made by this user**. *(Screenshot Placeholder)* ### Important Notes - **File Upload Limits:** Maximum file size and types depend on your server configuration (e.g., PHP settings). Ensure your hosting environment supports the limits you wish to apply. - **Undo File Deletion:** If you remove a file during editing, you can **undo** the deletion before saving. - **Previews:** Supported previews include **images (JPEG, PNG)** and **PDFs**. Other file types will display as a generic icon. ### Common Use Cases - **ID Verification:** Request attendees upload a scan of their ID. - **Waivers/Forms:** Collect signed documents before the event. - **Photos:** Require attendees to upload images for badges or promotional material. ### Troubleshooting **[Insert any error messages or edge cases you’d like covered. Please confirm common issues during testing.]** ### Frequently Asked Questions **[List any common questions or points of confusion raised during beta testing. Please confirm with support team.]** ### Related Documentation - [Booking Forms Overview] - [Attendee Forms Overview] - [User Forms Overview] ### Final Review Needed **Please confirm the following:** - **Error messages or common issues during upload process.** - **Supported file types beyond images and PDFs.** - **Any known browser limitations or compatibility issues.** - **Server configuration requirements (e.g., PHP upload limits).** --- Once finalized, this documentation will serve as a comprehensive guide to the new Upload Fields feature. Let me know if you’d like me to start refining any sections further. ## Signature Fields (Waivers & Consent) URL: https://wp-events-plugin.com/documentation/forms/fields/signature/ Events Manager Pro includes a **signature** field type for booking, attendee, and user forms. Use it to collect a legally-meaningful signature for liability waivers, medical or photo consent, terms and conditions, or any situation where you need proof that a specific person agreed to specific wording at a specific time. Each signature is stored with a full audit record: the exact wording that was signed, the signer's name and email, a timestamp, their IP address and browser, and confirmation that they agreed to sign electronically. If the record is ever altered, Events Manager will detect it and flag it as tampered. > **Warning:** This is not legal advice Events Manager gives you the mechanism to capture and verify a signature. It does not tell you what your waiver should say, and it does not guarantee that an electronic signature is sufficient for your activity, jurisdiction, or insurer. Always have your waiver wording reviewed by a qualified lawyer. ### Adding a signature field Signature fields can be added to **booking forms**, **attendee forms**, and **user (registration) forms** from **Events → Forms Editor**. For a waiver, the attendee form is usually the right place — it captures a separate signature for every person on the booking, not just the account holder. Add a new field, give it a label, and choose **signature** as the type. This reveals a dedicated options panel: [Image: The signature field type in the Forms Editor, showing its options panel] - **Consent Text** — the waiver or consent wording shown to the signer. Basic HTML is allowed, and placeholders such as `#_EVENTNAME`, `#_EVENTDATES` and `#_LOCATIONNAME` are supported. - **Document Version** — a version label (a date works well) stored with every signature, so you can prove exactly which wording someone signed. Bump this whenever the consent text changes. - **E-Sign Acknowledgement** — the wording shown next to the mandatory tick-box confirming the signer agrees to sign electronically. Leave blank to use the default wording. - **Require Acknowledgement Checkbox** — when enabled (the default), the signer must tick that box before they can apply their signature. - **Signature Mode** — *Draw or type*, *Draw only*, or *Type only*. - **Signature Display** — *Modal* (a pop-up opens when clicked), *Modal with consent text* (the wording appears inside the pop-up), *Inline* (the pad sits directly in the form), or *Sign later* (see below). - **Tip Text** / **Error Message** — the usual per-field tooltip and required-field error message. ### What the visitor sees By default the field shows a "Click to sign" box on the form: [Image: An unsigned Liability Waiver field on the front-end booking form] Clicking it opens the signing pad. If **Signature Mode** allows drawing, the visitor can sign with a mouse, trackpad, or finger: [Image: The signing modal in Draw mode, showing the consent text and signature pad] If typing is allowed, the visitor can type their name instead and choose from a few handwriting-style previews: [Image: The signing modal in Type mode, showing a typed signature preview] Once they tick the e-sign acknowledgement and apply the signature, the field shows a preview of what was signed, with an edit icon to redo it before submitting: [Image: The Liability Waiver field showing a completed signature] If the field is marked **Required**, the booking form cannot be submitted until it's signed. ### Verifying a signed booking Every signed field on a booking shows its full audit record in the admin booking screen, under **Advanced information**: [Image: The signature certificate shown on a signed booking, including signatory, timestamp, method, and integrity check] This includes the signatory's name and email, the UTC timestamp, whether they drew or typed their signature, the document version they signed, their e-sign consent, IP address, and user agent. The **Integrity** row re-verifies the record every time the page loads — if any of the stored data has been altered since signing, it will show as failed rather than verified. A downloadable PDF certificate is also generated for each signature. If a required signature hasn't been provided yet, the same spot shows **Not signed** with a **Sign now** link instead. ### Signing after booking ("Sign later") Some waivers are easier to complete after checkout rather than holding up the payment flow — for example, a long attendee-form waiver for each guest on a group booking. Setting **Signature Display** to **Sign later** hides that field from the initial booking or attendee form entirely; it isn't required to complete the booking. Instead, use the `#_BOOKINGSIGNATUREURL` placeholder in your booking confirmation email (or the booking/my-bookings page) to send the signer a secure link where they can complete every outstanding signature on their booking in one place. Wrap it in the conditional tags so the link only appears when something is actually outstanding: ``` {booking_has_unsigned_signatures} Please complete your waiver before the event: #_BOOKINGSIGNATUREURL {/booking_has_unsigned_signatures} ``` The placeholder resolves to nothing once every signature on the booking has been completed, so it's safe to leave in a template permanently. ### Signature emails Under **Events → Settings → Emails**, the **Signature Emails** section lets you attach signed signature images to the booking confirmation email (sent to the registrant), the admin notification email, or both, and lets you customise the subject and body of the dedicated "signature completed" emails sent to each. ### Signing through DocuSign or Dropbox Sign If your insurer or legal team wants a certificate of completion from a recognised e-signature provider, or you already run DocuSign, a signature field can be collected by DocuSign or Dropbox Sign instead of the built-in pad. Signing then happens after checkout, by email from the provider, and the booking is held pending until it is done. See [Signing with DocuSign or Dropbox Sign](providers.md). ### What this feature does not do - It does not supply waiver or consent wording — you write and maintain that yourself. - It does not judge whether an electronic signature is legally sufficient for your activity or location. - Retention/auto-delete of the signature image (keeping the audit record but discarding the image after a set number of days) is an advanced capability that isn't exposed by default; it's off until a site enables it at the code level. ## How to add an Attendee Form URL: https://wp-events-plugin.com/documentation/how-to-add-an-attendee-form/ Attendee forms can be created the same way other [custom booking forms](https://wp-events-plugin.com/documentation/custom-booking-forms/ "Custom Booking Forms") are created, and are available via your settings page. When activated, the Attendee Form will be shown for every space booked. Because the Attendee Form isn't activated by default, the first step is to go to _Events > Form Editor > Attendee Form_, and set _Enable Attendee Forms_ to _Yes_ and click _Save_. Once the page has refreshed, you'll see the Attendee Form tab now looks this: [Image: Attendee Form] To create your first form, type a name for it in the text box and click the _Add New_ button. This will generate the default form, which looks like this: [Image: Default Attendee Form] The default Attendee Form only asks the user for a Title and Name, so you may well want to add fields to it or to create a completely customized version. See the [custom booking forms](https://wp-events-plugin.com/documentation/custom-booking-forms/ "Custom Booking Forms") documentation page for more information on creating new fields in your Form Editor. > **Tip:** You'll notice that the first field is an [HTML field](https://wp-events-plugin.com/documentation/custom-booking-forms/#field-types "Custom Booking Forms"), containing the text _'Attendee #NUM#'_. When displayed in booking forms, #NUM# gets replaced by a number depending on how many forms are shown. So, if you choose 3 spaces, the third space will have a heading of _Attendee 3_. ## Booking Options URL: https://wp-events-plugin.com/documentation/booking-options/ The main options for bookings are located withing the Booking Options tab within _Events > Settings_ of your admin area. This tab affects how bookings are handled within your site. The Emails tab also contains a bookings section allowing you to customize the emails that go out to people when they have booked an event and when the status of their bookings change. [Image: Booking options have their own tab, for email templates click the Emails tab.] Let's go through the different sections and options: ### General Options Contains settings specific to the whole booking and how bookings are accepted on your site, mainly to do with event spaces and approval of bookings. Each field has an explanatory tip. _**Booking Approvals**_ Bookings will not be confirmed until the event administrator approves it. When someone makes a booking, they will receive an email advising them that their booking is pending confirmation and that they will receive an email when the booking is confirmed. If booking approvals are turned off, attendees will receive the confirmation email immediately after booking and you will not see any new booking notifications in the admin area (i.e. like in the first screenshot). If you are using payment gateways with the Pro add-on, bookings will always be considered as 'pending confirmation' or 'awaiting payment' until payment is made. ### Pricing Options Currently, Events Manager accepts one currency for the whole site (unless using MultiSite, sub-sites can have different currencies). You can also choose to add a tax rate, as well as whether to add tax to the ticket prices. **_Add tax to ticket price?_** If you select yes, users will not see the tax as an extra cost in their bookings (unless you choose to show them this within their emails using booking [placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders")). If you select No, you will see tax broken down when viewing individual bookings in the admin area, and if users are paying with a Gateway such as PayPal, they should see tax added separately to their totals. ### Booking Form Options Choose display options for your booking form, as well as modifying the default messages returned by the booking form. _**Guest Bookings**_ If you allow guest bookings, logged out users will also see registration fields which are used to create their account on your site when they book their first event. By default they will see Email, Name and Phone number fields, which will be saved to their user profile. If you have Events Manager Pro, you can also use the [booking form editor](https://wp-events-plugin.com/documentation/custom-booking-forms/ "Custom Booking Forms") to request extra registration fields such as username, First/Last names, and more. [Image: A sample booking form from a guest point of view (With guest bookings enabled)] The next time that user logs in to book for an event, they will not see these registration fields because they have already supplied you with this information the first time round. _**Feedback Messages**_ Once a booking request is submitted by a user and processed by Events Manager, a feedback message is returned depending on whether the booking was successful or not. You can customize the messages sent by modifying the settings in this section. ### Ticket Options **Single ticket mode** In single ticket mode, users can only create one ticket per booking, and will not see options to add more tickets. This is useful if you'd like to keep things simple for your users or you just don't want users to create more than one ticket per event. [Image: Booking admin area in single ticket mode] You can also choose how single tickets are displayed on your event form. If you set _Show ticket table in single ticket mode?_ to Yes, users will always see a ticket table instead of a single field (and price if applicable) and drop-down for selecting quantity: [Image: An event with a single ticket and option 'Show ticket table in single ticket mode?' set to no.] ### No-User Booking Mode If you do no want users to have an account created for them, this is possible, although the drawback of this is that your users will not be able to log in and see their previous bookings or request cancellations automatically. One advantage of this feature is that users with an account on your site will still be able to book and manage their bookings without filling in registration fields each time such as name, email etc. so you can have a mix of the two. When you enable no-user bookings, you must choose a user to 'assign' these bookings to. This user should be a random account that nobody uses, which can be a subscriber. When a guest books, their personal information will be stored along with the booking, but the booking will 'belong' to this user you assigned. Guests will never know the user login, but when viewing that booking their information will be displayed instead. ### Booking Email Templates and Settings In the _Emails_ tab of your settings page you can also modify the format of emails sent to users at certain stages of the booking process, as well as options about email administrators and event contacts. You can make use of [placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders") in these emails to create personalized templates. ## Custom Booking Email Templates URL: https://wp-events-plugin.com/documentation/custom-booking-email-templates/ The Events Manager Custom Booking Email Templates feature lets you fine-tune the messages sent to attendees, event owners (for user-submitted events) and admin users. You can customize emails at the individual event level or by payment gateway. This feature allows you to do things like send instructions for getting to a particular event, give customers extra information about payments, notify admins to review bookings, and so on. ### Enabling Custom Booking Email Templates If you're upgrading from Events Manager Pro version 2.3.5.4 or below you'll need to enable the feature by going to _Events > Settings > Emails > Custom Booking Email Templates_ and setting _Enable Custom Booking Email Templates?_ to Yes. For new installations of Events Manager Pro, Custom Booking Email Templates are enabled by default. When the feature is enabled, you'll see four sub-options in the Custom Booking Email Templates tab under _Events > Settings > Emails_. [Image: email-template-options] Here’s an explanation of what each option does. _Allow custom emails for events?_ Lets admin users and event owners customize the email templates used for individual events. _Allow custom admin email addresses for events?_ Allows custom email addresses to be added for notifications for individual events. _Allow custom emails for gateways?_ Lets admin users create custom emails specific to each payment gateway. _Allow custom admin email addresses for gateways?_ Let admin users add additional admin email addresses for gateways via the Payment Gateways settings page. ### The Email Template Editor The email template editor looks the same when editing events or gateways. It consists of a group of emails that can be expanded to show specific emails for that group. We’ll explain the basics for all cases first. If you have already enabled any custom email templates, those sections will open automatically when you load that page with the previous values. We will explain the relevant options within each group of emails: #### Also Send Event Owner Emails To If you have enabled this in your settings page (described further up), the first option under each email group lets you add additional recipients of the Event Owner emails. To add multiple email addresses, separate each with a comma. [Image: default-free-emails] #### Custom Email Templates Like other areas of Events Manager, custom email templates can include dynamic information like event names, locations, dates, etc. by using [Placeholders](https://wp-events-plugin.com/documentation/placeholders/). For a guide to the different types or emails that Events Manager can send out, see our documentation on [Automated Emails](https://wp-events-plugin.com/documentation/automated-emails/) [Image: event-owner-emails] The next two sections allow you to enable, disable or use the default email templates for event admins and the attendees. These options will do the following: - _Enable_ - Override the default email template with a custom subject and message. - _Disable_ - Prevent this email from being sent. - _Default_ - Uses the email templates from your [default booking email settings](https://wp-events-plugin.com/documentation/automated-emails/). ##### Event Owner Emails Clicking the Event Owner Emails heading will display options to customize templates which are sent to event owners and additional admins, depending on your [default booking email settings](https://wp-events-plugin.com/documentation/automated-emails/) and any additional emails you added in the setting above. ##### Attendee Emails These sets of emails will be sent to the person who made the booking. ### Event-based Custom Email Templates You can customize the templates used for individual events via the _Custom Automated Emails_ tab on the Add / Edit Event page in WordPress admin. In this tab you'll see one or more headings, depending on how many gateways you have enabled. Click on any of them to display the associated options. [Image: gateway-options] _Default or Free Gateway Emails_ are the templates used for emails sent out if a gateway isn't used or if the booking total is free ($0). Depending on which gateways you activate, you’ll also find headings and options for _PayPal_, _Offline,_ _Authorize.net AIM_ and any other custom _Gateway Emails_ you may have added. These work the same way and allow you to customize the recipients and messages for each of these payment options. ### Payment Gateway Emails When custom email booking email templates are enabled, default templates can be set for each gateway. To do this, go to _Events > Payment Gateways_ and select the gateway you want to edit. #### Multiple Booking Email Templates If you’re using Events Manager in [Multiple Bookings Mode](https://wp-events-plugin.com/documentation/multiple-booking-mode/), there are a few differences to the above: - Whilst you can still edit individual event emails these don't get sent out to attendees because they instead receive a Multiple Booking email template which summarizes the booking for multiple events. You can still opt to send individual event owner email in your settings page under _Emails > Multiple Booking Email Templates_ - Individual event emails only get sent when you modify individual bookings within a multiple booking (e.g. changing statuses or resending emails) - Extra template options for each payment gateway appear under the Multiple Booking Email Templates headings. When enabled, these will supersede the templates at _Events > Settings > Emails > Multiple Booking Email Templates_ ### Examples #### Customizing an Event Email - How to get there In this example, we're going to send instructions to attendees of a specific event when their booking is confirmed. To open the correct template, go to the Edit Event page for the event in WordPress admin. In the _Custom Automated Emails_ tab click open the _Default or Free Booking Emails_ heading, and then the _Attendee Emails_ heading. Next, select _Enabled_ from the _Confirmed booking email_ dropdown - this will display the default email template for confirmed bookings. Any changes you make to the template here will only be used when emailing attendees of this event. Here's an example template that uses the standard [Events Manager placeholders](https://wp-events-plugin.com/documentation/placeholders/) for dynamic information. > Hi #\_BOOKINGNAME, > > We've just reserved your tickets for #\_EVENTNAME. Here are the details of your booking: > > When : #\_EVENTDATES @ #\_EVENTTIMES Where : #\_LOCATIONNAME - #\_LOCATIONFULLLINE Spaces booked : #\_BOOKINGSPACES > > IMPORTANT: Because of the closure of Bridge Street, the main entrance is now in Kentish Road, off Church Square. > > Look forward to seeing you at #\_EVENTNAME. > > #\_CONTACTNAME #### Creating Default Gateway Emails - Offline Payment Instructions In this example we’ll add a custom email that tells user how to pay when they book any event using the offline payment gateway. From your WordPress admin area, click on _Events > Payment Gateways > Offline_ and visit the _Booking Email Templates_ section. Click on the _Attendee Emails_ heading to open it. From the _Awaiting Offline Payment_ dropdown select _Enabled_. This template is used for the email sent to attendees who have made a booking and have to pay for this event. Here's an example template you could use: > Hi #\_BOOKINGNAME, > > Thank you for your booking of #\_BOOKINGSPACES space/spaces for #\_EVENTNAME on #\_EVENTDATES (#\_EVENTTIMES) at #\_LOCATIONNAME. > > To confirm your booking, please transfer #\_BOOKINGPRICEWITHTAX to the following bank account: > > \[your bank account info here\] > > We'll be in touch as soon as the funds arrive, usually within 3 working days. > > Thank you. #\_CONTACTNAME ## Coupons URL: https://wp-events-plugin.com/documentation/coupons/ Coupons are a great way to promote your events with discount codes. You can create coupons that will be applied to specific events, all your events, or all events your website (if you are an admin). ### Creating/Editing Coupons Only users with the manage\_others\_bookings [capability](https://wp-events-plugin.com/documentation/user-capabilities/ "User Capabilities") are able to create and manage coupons. You can create and manage your coupons from within the Events > Coupons menu in your admin area. You should then see your previously created coupons and a link to add a new coupon - "Add New" [Image: Coupons Admin Area] You can then enter your coupon information and settings. Here are some important settings: **Event-Wide Coupons** Event wide coupons will be automatically applicable to any event owned by the creator of the coupon. This is useful if you're an event organizer and want to make a coupon for all your events. _This is not available if you are using [Multiple Bookings Mode](https://wp-events-plugin.com/documentation/multiple-booking-mode/ "Multiple Booking Mode")._ **Site-Wide Coupons** If all the events on your site belong to one user, or you want to create a coupon that works for any event on the site, check this. _This is not available if you are using [Multiple Bookings Mode](https://wp-events-plugin.com/documentation/multiple-booking-mode/ "Multiple Booking Mode") and all coupons are by default site-wide coupons when using this feature._ **Registered Users Only?** You can limit guests from being able to use coupon codes by checking this box. **Fixed Amount Discounts** If you enter a fixed amount and the booking total is equal to or smaller than this discount, the booking will be free. ### Applying Coupons Once you create your coupons, you should see these within your booking settings when editing an event, underneath your ticket information. Site-wide and event-wide coupons will be shown for information purposes. You can choose the single coupons you would like applied to this specific event by checking the boxes next to each coupon. [Image: coupons-admin-event] ### Using Coupons Once you have applicable coupons for an event, the coupon field should appear in your booking form. When users enter the code and move away from that field, the form will check the Coupon code and confirm the discount type, or inform the user of an invalid coupon code. [Image: coupons-front] ## Safely Saving Gateway API Credentials URL: https://wp-events-plugin.com/documentation/safe-encryption-api-keys/ Events Manager gateways such as PayPal and Authorize.net need API credentials to communicate with their servers to verify whether or not a booking has been paid for, specifically before deleting bookings automatically. This allows to take payments, verify bookings and more. API Credentials are particularly sensitive bits of information which can give access to your payment processor account, and therefore must be stored safely. For this reason, we prevent API information from being displayed or stored via unencrypted admin pages. If your site does not support SSL, you will need to store this information in another way. ### Recommended Solution - Get SSL! This may seem obvious, and we appreciate that not everyone can enable SSL on their hosting environment. However, if you can, we strongly suggest you consider doing this! Not only will your credentials be safely transferred between your browser and your site, but everything else will be too, such as your WordPress username and password! You can force your whole admin area to use SSL simply by adding this line to your wp-config.php file: ``` define('FORCE_SSL_ADMIN', true); ``` Please see the WordPress official documentation for [enabling SSL in your admin dashboard](https://codex.wordpress.org/Administration_Over_SSL). ### One Exception - Sandbox Credentials If you have your gateway Mode set to ‘Test Mode (Sandbox)’ or similar in your settings, then you will see the option to show your API credential fields allowing you to view and store them. We still don’t show them to you by default, just in case you’ve stored real API credentials in there and just switched to sandbox mode. We STRONGLY advise against switching to ‘Test Mode’ and choosing to show and/or store your real API keys when not using SSL. ### Install via PHP Script Some technical knowledge is required here, but it’s the only ‘convenient’ and ‘safe’ alternative. If you cannot enable SSL on your admin area, and you want to add API credentials to your Events Manager settings, you could upload a file to your site via secure FTP or via your host control panel. Many hosts these days enforce secure FTP connections to your site files, or alternatively allow you to edit files via their control panels which are over HTTPS. This way, you can securely upload a script that saves your API information directly to your database, and then delete it. If you can do the above, then it’s pretty straightforward. Copy [this snippet of code](https://pastebin.com/rRQXa80K) into a new .php file, and upload it to /wp-content/mu-plugins folder, [as indicated in our tutorial](http://wp-events-plugin.com/tutorials/how-to-safely-add-php-code-to-wordpress/). Make sure you replace YOUR USERNAME, YOUR PASSWORD and YOUR SIGNATURE with the relevant information. Once you upload this, visit your gateway settings page and you should see the first and last letters of each bit of information. That’s it! When you’re done, delete that file. ## Stripe Checkout Setup URL: https://wp-events-plugin.com/documentation/payment-methods/stripe/checkout/ For more information about Stripe in general, please see our [Stripe FAQ](https://wp-events-plugin.com/payment-methods/stripe/) page. This page will help you set up the Stripe Checkout payment method. Once you have signed up for a Stripe account. Setting up Events Manager to receive payments is fast and straightforward in 4 simple steps! ### 1\. Install Events Manager Pro Stripe plugin You can download the Events Manager Pro Stripe plugin from the [downloads](https://eventsmanagerpro.com/downloads/) page. From here, you would install it [just like you installed Events Manager Pro](https://wp-events-plugin.com/documentation/installation/), via the Plugins > Add New > Upload Plugin area. Once installed and activated, you should see Stripe as a payment method under your _Dashboard > Events > Payment Gateways_ admin area. Click on the Stripe gateway to access the settings. ### 2 . Obtain and save your API credentials _At this point, make sure you're in Test Mode, or Live Mode, both your API credentials and Webhooks further down are different in live and test mode, and you'll need to repeat these steps when moving from testing to production._ Log into your Stripe Dashboard, and access _Developers > API Keys_ from the left-hand menu. From there, you'll have access to your standard API keys, as shown below. Copy and paste these into the _Stripe Checkout Credentials_ section of your settings page. ### 3\. Create a Webhook This will allow your website to immediately be aware of when a booking payment is completed, or if any refunds or chargebacks were initiated. Still on the Stripe Dasbhoard, click on _Developers > Webhooks_ and you'll see the following page. Click on the '+ Add Endpoint' button. You will then be able to fill this form to create a new webhook. The endpoint URL you need to use will be displayed in the Stripe Gateway settings page on your site, under the  _Stripe Checkout Credentials_ section. The _Version_ you should choose is currently **_2019-09-09_** at the time of writing. You should also make sure to add these three events: - checkout.session.completed - charge.refunded - charge.dispute.created Your form should look similar to the one below: Once you've submitted this, you'll be shown information about your new webhook. Click the 'click to reveal' button in the Signing Secret section and copy your Signing Secret key, which you'll then paste just below your API keys in your Stripe settings page of your website. If you're in test mode, one final step is to make sure your website is listening for these webhooks is to send a test webhook, a button will appear on the top-right of the page allowing you to do so. You'll receive this for any test webhook that was successful: ```js { "message": "This is a webhook test response, which means the endpoint is correctly configured." } ``` ### 4\. Complete your settings page The three steps above are enough to start accepting payments already, but there are various other options that you may find useful. Whilst most are quite self-explanatory, we'll highlight one that is often useful for reserving spaces during the booking process. #### "Delete Bookings Pending Payment" and prevent double bookings When a user starts the payment process, a booking is already created and given the 'awaiting online payment' status. During this time, users are redirected to Stripe.com and enter their payment information there. You can hold booking spaces during this process (you can choose for how long just above this setting), to avoid double bookings if two users are interested in the last ticket. If payment is not completed in your set amount of time the reserved space is freed, the booking is deleted and the user payment will not go through for that checkout session. ### 5\. Activate the Gateway and make a test payment Once you're done with the settings page, you should go back to the Gateways page (Events > Payment Gateways) and activate the payment method, which you can do when hovering over the Stripe payment gateway. We always suggest you try and make a test payment for an event, [see here for test card numbers](https://stripe.com/docs/testing). Once you have made the booking, and verified that the booking has been marked as approved automatically after payment, you can also refund that payment and see that the booking will also get cancelled automatically. ## Set up Square for Events Manager Pro URL: https://wp-events-plugin.com/documentation/payment-methods/square/ ## Set up Square Events Manager Pro can take card payments through Square in two ways, and you can use either or both: - **Square Web Payments** — buyers enter their card on a form built into your booking page and never leave your site. - **Square Checkout** — buyers are sent to a secure Square-hosted page to pay, then returned to your site. Both use the same Square account, so you only enter your details once. ### Before you start - **Events Manager Pro** installed and active. - A **Square account** — [sign up free](https://squareup.com/signup). You can build and test everything in Square's free sandbox before taking real payments. - Your site running over **HTTPS** for live payments (Square requires it for the embedded card form). ### Step 1 — Get your Square credentials You need three things from Square: an **Application ID**, an **Access Token**, and a **Location ID**. 1. Go to the [Square Developer Dashboard](https://developer.squareup.com/apps) and sign in. 2. Click **+ Add application**, give it a name (e.g. *My Website*), and open it. 3. In the sidebar open **Credentials**, and make sure the toggle at the top is set to **Sandbox**. 4. Copy the **Application ID** (it starts with `sandbox-sq0idb-`) and the **Access token** (click *Show* first). 5. Open **Locations** in the sidebar and copy the **Location ID**. 3. In the sidebar open **Credentials**, and switch the toggle at the top to **Production**. 4. Copy the **Application ID** (it starts with `sq0idb-`) and the **Access token** (click *Show* first). 5. Open **Locations** in the sidebar and copy the **Location ID** for the location that should receive these payments. > **Caution:** Keep your access token private Your live access token can take real payments. Don't share it or post it anywhere public. If it's ever exposed, click **Rotate** in Square and update Events Manager with the new value. ### Step 2 — Add your credentials to Events Manager 1. Go to **Events → Payment Gateways** and click **Square Web Payments** (or **Square Checkout** — the credentials are shared, so either is fine). 2. Open the **[Test] API Keys/Notifications** tab for sandbox details, or **[Live] API Keys/Notifications** for live details. 3. Paste in your **Application ID**, **Access Token**, and **Location ID**. 4. Click **Save Changes**. Events Manager sets up Square's payment notifications for you automatically when you save — you'll see a green "verified" message once it's done. You don't need to configure anything in the Square dashboard yourself. ### Step 3 — Turn on a gateway Open the gateway you want — **Square Web Payments** and/or **Square Checkout** — and on its **General Options** tab: - Set **Active** to **Yes**. - Set **Test Mode** to **Yes** while testing with sandbox credentials, or **No** for live payments. - Set the **Gateway Title** your customers will see (e.g. *Pay by card*). A couple of gateway-specific options: - **Square Checkout** lets you choose whether your ticket prices already include tax (otherwise tax is shown separately on the Square page), and whether to ask the buyer for a shipping address. - **Square Web Payments** keeps the card form simple — Square collects the billing postcode itself as part of the card form, where it's needed. Save your changes. ### Step 4 — Test it With **Test Mode** on, open a paid event on your site and book a ticket: 1. Choose your Square payment option. 2. Enter a Square test card — number `4111 1111 1111 1111`, any future expiry (e.g. `12/30`), any CVV (e.g. `111`), and any postcode if asked. 3. Complete the booking. You should land on your confirmation page, and the booking should show as **Approved** under **Events → Bookings**. Square's [full list of test cards](https://developer.squareup.com/docs/devtools/sandbox/payments) lets you try declines and other scenarios too. ### Step 5 — Go live 1. Paste your **live** credentials (from the *Live* tab in Step 1) into the **[Live] API Keys/Notifications** tab and save. 2. On the gateway's **General Options** tab, set **Test Mode** to **No**. 3. Make one small real booking to confirm everything works — you can refund it from your Square dashboard afterwards. ### Troubleshooting **The card form doesn't appear, or is blank.** Make sure your site is served over **HTTPS**. Square won't load the embedded card form on an insecure (`http://`) page. **"Could not set up Square notifications" when saving.** Your site needs to be reachable from the internet so Square can send payment notifications. This is normally only an issue on local or offline development sites. **A booking stays pending after payment.** Square notifies your site when a payment completes; if that's delayed, Events Manager automatically double-checks with Square when the booking's payment window expires, so it resolves on its own shortly. If it keeps happening, confirm your credentials saved correctly (the green "verified" message in Step 2). **Refunds aren't showing on the booking.** Refund the payment from your Square dashboard and Events Manager records it against the booking for you. If nothing updates, re-save your credentials so notifications are re-checked. ### Need help? If you're stuck, post on the [Events Manager support forum](https://eventsmanagerpro.com/support) with the event and a description of what you're seeing. ## Xero URL: https://wp-events-plugin.com/documentation/payment-methods/xero/ The **Events Manager Pro – Xero** add-on turns a booking into a proper Xero invoice. When someone books a paid event, the add-on creates an authorised invoice in your connected Xero organisation and then either sends the customer to Xero's hosted payment page or emails them the invoice to pay from their inbox — your choice. When the invoice is paid, Xero notifies your site automatically and the booking is confirmed. This guide walks you through connecting your site to Xero and raising your first invoice. There's no code involved. > **Info:** What you'll need - **Events Manager Pro** installed and activated (the Xero add-on requires it). - A **Xero account** you can sign in to. The same login works at [developer.xero.com](https://developer.xero.com), where you'll register a free app. - A few minutes. ### How it works - A customer books a paid event and chooses **Pay via Xero Invoice** at checkout. - Your site creates an invoice in Xero for that booking. - Depending on your settings, the customer is either **redirected to Xero's online invoice** to pay by card, or **emailed the invoice** to pay later. - When the invoice is paid, Xero sends your site a secure **webhook** and the booking is automatically marked as confirmed. You connect to Xero once, using a free "app" you register in Xero's developer portal. That app is what lets your website talk to your Xero organisation securely — let's set it up. ### 1. Create a Xero app Your website connects to Xero through an **OAuth 2.0 app** that you register once. This is free. Sign in at [developer.xero.com](https://developer.xero.com), go to **My Apps**, and click **New app**. [Image: The Xero developer My Apps page, with the New app button top-right] Fill in the form: - **App name** — anything that identifies your site, e.g. *"My Events Website"*. Your customers will see this name on the Xero consent screen. - **Integration type** — choose **Web app**. - **Company or application URL** — your website address. - **Redirect URI** — this is the one value you need to copy from your site. Open your gateway settings (see Step 2), copy the **Redirect URI** shown on the *Xero Connection* tab, and paste it here. [Image: The Xero New app form filled in — app name, Web app, company URL and redirect URI] Once the app is created, open its **Configuration** page. Here you'll find your **Client id** and a button to **Generate a secret**. You'll copy both into your website in the next step. [Image: The app's Configuration page showing the Client id and the Generate a secret button] > **Caution:** Keep your secret safe Your **Client Secret** is shown only once and works like a password — don't share it or post it anywhere public. If you ever lose it, just generate a new one. ### 2. Connect your site to Xero In your WordPress admin, go to **Events → Payment Gateways** and click **Xero Invoice** to open its settings. You'll land on the **Xero Connection** tab. [Image: The Xero Connection tab: App ID and App Secret fields, and your site's redirect URI] 1. Copy the **Redirect URI** shown here into your Xero app (Step 1) if you haven't already. 2. Paste your **Client ID** and **Client Secret** from Xero into the matching fields. 3. Click **Save Changes**. 4. Click **Connect to Xero**. You'll be taken to Xero to approve the connection — pick the organisation you want to use and click **Allow**. After you approve, you're returned to the Xero Connection tab, which now shows you're connected. [Image: The Connection tab showing the connected Xero organisation and a Disconnect option] > **Tip:** The Client Secret field stays blank For your security, the secret is never displayed back to you. Once saved, the field shows a placeholder — leave it blank when saving again to keep your existing secret. ### 3. Set up the webhook The webhook is how Xero instantly tells your site when an invoice has been paid, so bookings are confirmed without you lifting a finger. On the same **Xero Connection** tab you'll find a **Webhook** section with a **Delivery URL** and a **Webhook signing key** field. [Image: The Webhook section: the Delivery URL and the Webhook signing key field] 1. In Xero's developer portal, open your app and go to **Webhooks**. 2. Set the **Delivery URL** to the one shown on your site, and subscribe to the **Invoices** event. 3. Xero will show you a **signing key** — copy it, paste it into the **Webhook signing key** field on your site, and click **Save Changes**. > **Note:** One delivery URL and signing key cover both Test and Live — you only set this up once. ### 4. Choose your organisation and account code Xero has separate **Test** and **Live** modes, shown as the **[Live]** and **[Test]** tabs. Each mode points at a connected Xero organisation, so you can safely trial everything against Xero's free **Demo Company** before going live. On the **[Live]** tab, choose the organisation invoices should go to in live mode, and enter your **Sales account code** — the revenue account from your Xero Chart of Accounts that invoice lines post to (for example `200`). [Image: The Live tab: the Organisation dropdown and the Sales account code field] On the **[Test]** tab, do the same for testing. A great choice here is Xero's **Demo Company**. You can also restrict test mode to specific people or IP addresses using the standard Limited Test Mode options. [Image: The Test tab: the Organisation (e.g. Demo Company) and the Sales account code] > **Caution:** Match your tax rates to Xero Xero works out the tax on each invoice from the **account code** you choose, so make sure your Events Manager tax rate matches the tax rate set on that Xero account. The invoice total always matches the booking total — but if the rates differ, the net/tax breakdown will follow Xero's account. Keep them in sync to avoid confusion. ### 5. Gateway options The **Gateway Options** tab has a few useful settings: [Image: The Gateway Options tab: pay online, booking status, due days, email invoice and branding theme] - **Pay online (redirect)** — *Yes* sends the customer to Xero's hosted invoice to pay immediately; *No* simply emails them the invoice to pay from their inbox. - **Booking status while awaiting payment** — whether unpaid bookings sit as *Awaiting Online Payment* (best for the pay-now flow) or *Awaiting Payment* (best for an emailed, pay-later invoice). Either way the space is held until payment is confirmed. - **Days to Pay** — how many days until the invoice is due. - **Email invoice from Xero** — when redirecting to pay online, you can *also* email the customer their branded invoice. - **Branding Theme ID** — optionally apply a specific Xero branding theme to invoices. ### 6. Activate and make a test booking Finally, go back to **Events → Payment Gateways** and **activate** the Xero Invoice gateway (hover over it to find the Activate link). We always recommend a test run first: 1. Make sure you're in **Test** mode and that your Test tab points at the **Demo Company**. 2. Book a paid event on your site and choose **Pay via Xero Invoice**. 3. Check that the invoice appears in your Xero Demo Company, pay it (or mark it as paid in Xero), and confirm the booking flips to **Confirmed** on your site automatically. [Image: An invoice raised in Xero from a test booking — the event name appears as the reference] Once you're happy, switch the gateway to **Live** mode and you're ready to take real bookings. ### Troubleshooting - **"Not connected" notice** — open the **Xero Connection** tab and click **Connect to Xero**. If you've just changed your Client ID or Secret, save first, then connect. - **The customer wasn't redirected to pay** — the online-payment redirect needs your Xero organisation to have online invoice payments enabled. Xero's **Demo Company** and trial organisations don't return an online-payment link, so during testing the invoice is emailed instead. This is a Xero limitation, not a fault on your site. - **Bookings aren't being marked as paid** — double-check that the webhook **Delivery URL** and **signing key** in Xero match your site, and that you subscribed to the **Invoices** event. - **The invoice tax looks different from the booking** — see the tax note above, and align your Events Manager tax rate with the Xero account's tax rate. Still stuck? [Get in touch with our support team](https://wp-events-plugin.com/support/) and we'll be happy to help. ## Offline Event Payments URL: https://wp-events-plugin.com/documentation/offline-event-payments-bookings/ Events Manager Pro allows for offline payments to be entered in by Event owners. It also allows for owners to add manual payments to the booking, and if paid in full bookings are confirmed. ### Enabling Offline Payment Button You can allow users to pay offline by [activating the offline payments gateway](https://wp-events-plugin.com/documentation/payment-gateways-overview/#activate "Payment Gateways Overview"). At this point the option allowing users to pay offline will appear on your booking form. [Image: gateways-paypal-purchase] When a user successfully enters the correct information into your form, the user will have a booking awaiting payment, which you must manually confirm when paid. You can customize the text of this button, or use an image instead by visiting the offline gateway settings, which is located under Events > Payment Gateways and then clicking on the settings link : [Image: pro-gateways] Events awaiting offline payment are located in the bookings dashboard (Events > Bookings in admin area) and also within a event bookings management area. You can get to event booking management pages in various ways: - click 'manage bookings' when editing an event - click 'bookings' under the relevant event when viewing events lists in event admin areas. - from the bookings dashboard, click on the relevant event name within the 'Events with Bookings Enabled' list. You can leave this disabled to only allow event owners/admins to add offline payments and manual bookings. ### Offline Payments (Partial and Full Payments) Once you've activated Pro, a new offline payment form will appear when viewing an individual booking in the admin area (when viewing bookings, click the 'view/edit' link next to the desired booking). You can simply add a numerical amount and this will be added to the transaction history and payment total. [Image: gateways-offline-payment] If you add partial payments, this will still appear in the [transaction history](https://wp-events-plugin.com/documentation/payment-gateways-overview/#transactions "Payment Gateways Overview") shown on all booking info pages and contribute towards a full payment. When the payment amount exceeds or matches the amount pending, the booking will be automatically marked as confirmed and a confirmation email will be sent. Note that you can also create a full payment by manually approving a booking as usual. ## Testing PayPal in Sandbox / Test Mode URL: https://wp-events-plugin.com/documentation/paypal-sandbox-mode/ By setting Events Manager to run in PayPal Sandbox / Test mode, you can extensively test the gateway without needing worry about having to keep refunding test payments. In Sandbox mode, the PayPal gateway functions exactly the same as in Live Mode except transactions do not involve real money. To run sandbox mode you'll need a developer account from [https://developer.paypal.com](https://developer.paypal.com/). If you already have a PayPal account you should be able to login with your normal username and password. Once logged in, go to _Applications > My Apps > Sandbox Accounts_. [Image: sandbox1] On the _Create test account_ screen, you'll be asked to fill in the information used to populate your test account. As well as an email address and password, you can choose things like whether the test account should be treated as a verified account and decide how "money" should be in the account balance. You'll also be asked to choose the type of account - Personal or Business. [Image: sandbox3] To fully test the Events Manager PayPal Gateway, you'll need to create both a Personal and Business account. This will allow you to test transactions are working correctly from both the customer and merchant point-of-view. #### Logging in to your Sandbox accounts Even though sandbox accounts are created through the Developer website, you need to **login via the Sandbox site below** to check payments and transactions and make other changes. This applies to both your business and personal sandbox accounts. After you've created the accounts via the Developer site, Sandbox accounts are accessible at [https://www.sandbox.paypal.com](https://www.sandbox.paypal.com/). Before you can begin testing, login into the PayPal Sandbox site using your test business account and set it up to receive payments exactly as if it were a live account. To do this, choose _Profile > My Selling Tools_. [Image: sandbox4] On the next page, scroll down to _Instant payment notifications_ and click _Update_. [Image: sandbox5] On the next screen, click _Choose IPN Settings_. Under _Notification URL_, paste in the _IPN return url_ that you'll find in Events Manager under _Events > Payment Gateways > PayPal > PayPal Options_. Make sure _Receive IPN messages_ is checked and click Save. [Image: sandbox6] #### Setting a return URL In most cases, you'll want to bring users back to your site automatically after the transaction. To set where users are sent, go to _Profile > Selling Tools_ again and click _Update_ next to _Website preferences_. On the next screen set _Auto Return_ to on and _Return URL_ to the page you want users to be taken back to. **Note**: When a _Return URL_ is set but _Auto Return_ is off, users will see a PayPal thank you page with a manual link to the return url. [Image: sandbox7] **Important**: Although you can redirect to any page on your site, PayPal requires that the page makes it clear to users that the payment has been made and the transaction is complete. When you're done, remember to logout of this account so that you can test the Events Manager payment gateway using your **personal** sandbox account later. #### Setting Up PayPal Sandbox Mode in Events Manager In Events Manager, go to _Events > Payment Gateways > PayPal_. Under _PayPal Options_, set _PayPal Email_ to the email address of your **business sandbox account**. You'll also need to change _PayPal Mode_ underneath to _Test Mode (Sandbox)_. [Image: sandbox8] Now you're ready to a make a test payment through an event page on your site by using the email address of your **personal** sandbox account. #### IMPORTANT Once you've finished testing, don't forget to go back to _Events > Payment Gateways > PayPal_ and set the _PayPal Email_ to the correct email address for live transactions and to switch Sandbox mode back to Live mode. ## PayPal and Displaying Taxes URL: https://wp-events-plugin.com/documentation/events-with-paypal/paypal-displaying-taxes/ For PayPal Standard, you have the option in our gateway settings to show taxes separately on the PayPal payment page or include them in the itemized billing prices. This setting is called _Include Taxes In Itemized Prices_ Whilst this may not apply to everyone, if you are pricing your tickets with more than two decimals we generally recommend you NOT display prices on PayPal. The reason for this is because PayPal requires us to submit individual per-space prices of tickets which contain only two decimals. When you multiply that by the spaces booked, then the taxes apply, there's the possibility for errors in prices. Here's an example: > _We have an event with a tax rate of 19% where the desired ticket price INCLUDING taxes is $49, which makes a tax-exclusive ticket price of $41.1764 rounded to four decimals._ > > _If we were to use two decimals when calculating the price of one ticket, $41.18 plus 19% makes $49.0042 which will work for one ticket when rounding to two digits, but ten tickets will amount to $490.04 when rounded, that's four cents off._ Herein lies the problem with allowing PayPal to calculate your prices if you're using ticket prices containing more than 2 decimals. Should you want to let PayPal calculate the taxes, we can only supply to PayPal three bits of information,  the price of one space rounded to two decimals, spaces booked, and tax rate. With special prices like the example above, you will see slight discrepancies in total prices. A lot of the time, the price will round correctly, but it's important to understand that some unique prices like the example above may not, and if you choose to show your taxes as a separate item in PayPal, be aware of what could happen. On the other hand, if prices are calculated by Events Manager, the four digits are used to calculate the price WITH tax and that is then passed onto PayPal for correct calculation according to spaces booked. ## Event bookings with Authorize.net AIM URL: https://wp-events-plugin.com/documentation/event-bookings-with-authorize-net-aim/ Our Autorize.net AIM gateway allows you to charge users who enter their card details on your site. Events Manager submits this information to Authorize.net for processing and approves the booking if successful. In this case, the user never has to leave your site. If you want to test Authorize.net without using real cards and payments, please view our [Authorize.net Sandbox tutorial](https://wp-events-plugin.com/documentation/event-bookings-auhtorize-net-sandbox/ "How to Set Up and Test an Authorize.net Sandbox"). ### Important Notes It's important to note that since you are accepting Credit Card information over the internet, it's absolutely necessary that you have valid SSL certificates on your site, otherwise, this will not work! Events Manager will always force an HTTPS connection when a booking form accepting Authorize.net **in live mode** is used. When using sandbox mode, we do not impose any SSL requirements since you're not using real payment information. We do not force the event page or any other page showing a booking form to be over HTTPS, we do however always force the destination where the form data is sent to be an HTTPS address, ensuring all data is safely transmitted. If you want to force event pages or any other specific pages to use SSL, consider using a WordPress SSL plugin such as [Really Simple SSL](https://wordpress.org/plugins/really-simple-ssl/), [WordPress HTTPS](https://wordpress.org/plugins/wordpress-https/), or alternatively use a [PHP snippet we created](http://pastebin.com/NXqz3mUF). Since this gateway requires extra fields to be filled in, this gateway cannot be used with single quick pay buttons (e.g. paypal and offline payments). ### Setting Up Authorize.net Account Once you've registered for your authorize.net account, there's three important pieces of information you need to obtain/set up. These are your: - [API Login ID](https://support.authorize.net/s/article/How-do-I-obtain-my-API-Login-ID-and-Transaction-Key) - [Transaction Key](https://support.authorize.net/s/article/How-do-I-obtain-my-API-Login-ID-and-Transaction-Key) - [Signature Key](https://support.authorize.net/s/article/What-is-a-Signature-Key) (optional for notifications) All three can be obtained from your authorize.net control panel under Account > Settings > API Credentials & Keys, we recommend you check out [Authorize.net's instructions](https://support.authorize.net/s/article/How-do-I-obtain-my-API-Login-ID-and-Transaction-Key) for further clarification. You will need to request both the transaction and signature keys, if you haven't previously generated them before, you will need to do so now and store them in a safe place unless you want to regenerate them from scratch (regenerating keys will invalidate previous ones). ### Set Up Gateway Now you need to enter the key information from before into the gateway settings page. Bear in mind that you need to select the right type of mode you are in. If you are using a sandbox, make sure you choose a sandbox mode, or vice versa. Now that you have saved the necessary information, you are ready to activate and set up the gateway. First things first, visit Events > Payment Gateways in your admin area and click 'activate' beneath the Authorize.net AIM gateway. [Image: Activate Gateway] There's many more settings for you to choose from on this page with helpful explanations. Here are some specific that may interest you: - **Manually approve completed transactions? -** If selected, successfully paid bookings will be marked as 'Pending' rather than 'Confirmed' - **Email Customer (on success) -** This sends the user sends the default authorize.net confirmation email, you can add additional information above and below it with the following input fields. #### Passing On Address/Personal Information If you would like to pass on common personal/address information for usage in the Address Verification Service (AVS) or to provide further information in your transaction reports, you need to [associate address fields with user fields](https://wp-events-plugin.com/documentation/custom-booking-forms/#user-address-fields "Custom Booking Forms") in your form editor. ### Set Up Refund/Reversal Notifications Refunds must be initiated from your Authorize.net control panel. You can set up Events Manager Pro to track refunds and automatically cancel a booking payment that has been refunded or voided. If you would like to track refunds and voided transactions on authorize.net, you need to first have obtained your [Signature Key](https://support.authorize.net/s/article/What-is-a-Signature-Key) and saved it in your settings during the initial setup instructions above. Once that's saved you can proceed to activate [Webhooks](https://support.authorize.net/s/article/How-do-I-add-edit-Webhook-notification-end-points) and/or [Silent Posts](https://support.authorize.net/s/article/Silent-Post-URL). We strongly recommend setting up Webhooks, as Silent Posts will likely be deprecated by authorize.net in the not too distant future. Firstly, visit your Authorize.net settings page in Events Manager via your _WordPress Dashboard > Events > Payment Gateways._ There, under the _Payment Notifications_ section, you'll find the URLs you'll need to enter into either Webhooks or Silent Post settings on Authorize.net Once you've obtained your desired url notification destination url, copy it and visit either of the settings page. Silent Posts simply require you to paste the URL and save. Webhooks have a couple more options but are also very straightforward. Copy your Webhooks endpoint, which will be similar to _http://yoursite.com/wp-json/events-manager/v1/gateways/authorize\_aim/notify_ and then click the 'Add Endpoint' button in the Authorize.net Webhooks settings page. Paste your url into 'Endpoint URL' field , provide a meaningful name (if any) and make sure it's selected to be active. Finally, ensure you checked the _net.authorize.payment.refund.created_ and _net.authorize.payment.void.created_ options. Your settings will look very similar to the screenshot below. That's it! You've set up notifications. You can even set both up if you wish, although as recommended by Authorize.net we recommend going with Webhooks. ### Finishing Up That's it! You're now ready to process payments. If you visit an event page, you should now see an option to pay with this gateway. If you have more than one gateway enabled, this will be available from the gateways drop-down list (which can be renamed from within the same options page as above). If this is the only gateway available, the credit card fields will be shown with no gateway choice. ## Multisite URL: https://wp-events-plugin.com/documentation/multisite/ Events Manager works with [WordPress MultiSite](http://codex.wordpress.org/Create_A_Network) and allows you various 'modes' in which you can run the plugin across your network sites. The first decision to make is on which sites/blogs on your network you want to make the plugin active. After this, you can decide how your events are inter-related between these blogs. ### Installation Firstly, install Events Manager and Events Manager Pro as instructed in the installation instructions, however you have two options when activating Events Manager and Pro in multisite mode. #### Network Activate _WordPress Plugins that are also stored in the plugins directory can be activated across the entire network by the super admin. Once 'Network Activated' plugins will become active in all sites. 'Network Activated' plugins will hide their activate/deactivate menu options to individual site administrators. Only super admin can deactivate a 'Network Activated' plugin on a site by site basis. - [WP Codex](http://codex.wordpress.org/Create_A_Network#Step_6:_Network_Admin_Settings)_ If you would like Events Manager to be available on every single site/blog on your network then you Network Activate both Events Manager and Events Manager Pro. To do this: 1. Log in as an administrator and click on the My Sites > Network Admin option on your WP Admin Bar (on WP < 3.3 it's on the top right) 2. Click on the Plugins menu item on the left 3. Click 'Network Activate' for both Events Manager and Pro (if applicable) [Image: Network Activate Events Manager and Pro together.] #### Site Specific Activation **Important:** Certain plugin settings will always remain in the network admin area and editable by superusers only. For this to work you must activate Events Manager on your root blog, whether you use it there or not. _WordPress Plugins to be activated or deactivated by an individual blog owner are stored in the plugins directory. You need to enable the Plugins page for individual site administrators from the Network Admin's Settings -> Network Settings menu. Specific site administrators can then toggle optional plugin activation. _- [WP Codex](http://codex.wordpress.org/Create_A_Network#Step_6:_Network_Admin_Settings)__ Activating Events Manager on single blogs on your network is the same as activating any normal plugin on a single site, which you can do from the normal site plugins menu. #### What's the difference between these two methods? In terms of functionality, none. This purely depends on how you want to set up your site. We recommend you check out the [WP Multisite Codex](http://codex.wordpress.org/Create_A_Network#Step_6:_Network_Admin_Settings) for a great introduction to understanding Multisite. ### Updating When updating Events Manager, you should also visit _Events Manager > Update Blogs_ in your Network Admin as this will automatically run the update script of Events Manager on each blog (The default Update Network feature of WordPress does not) ### Configuration When in WordPress Multisite mode, certain settings are made available/restricted to only super admins. These extra options are located on the network admin area. [Image: MultiSite Network Admin] #### Multisite Options (Event Information Sharing) Found near the top of the settings page, this panel concentrates on how events are connected within your site. The most important one of these is the _Enable global tables mode?_ option. [Image: Global Tables Mode Enabled (Not all options will show depending on your settings chosen)] #### Global Tables Mode By default, Events Manager is installed as an independent plugin on each site, minus a few shared settings which Network Admins control. This means events created there are exclusive to that site, and so are locations, booking information, etc. These cannot be shared. Enabling global tables will make event, location and category index information save in the main site event tables. This allows you to share events across different blogs, such as showing events in your network whilst allowing users to display and manage their events within their own blog. **Where information is stored** Categories are shared across all blogs, and is controlled in the main blog. Note that your main blog admin area will not count events using shared categories when counting event category useage. Front-end lists (i.e. public pages, widgets, shortcodes, etc.) will though. Since Events and Locations are custom post types in WordPress, the actual posts will still reside in the corresponding blog posts tables (locations can be forced to save in the main blog, see Global Mode Options below). **Important** You must ensure that Events Manager is installed on the root blog for this to happen, as all events are saved on to the root blog's table along with information on which blog created it. Bear in mind that activating this will mean old events created on the sub-blogs will not be accessible anymore, and if you switch back they will be but new events created during global events mode will only remain on the main site. It's recommended you decide this when first installing Events Manager, as changing back and forth will produce unexpected results. #### Global Mode Options When enabled, you have further options available to you for modifying the way Events and Locations are shared. **Global Event Options** _Display global events on main blog?_ Displays events from all sites on the network by default. You can still restrict events by blog using [shortcodes](https://wp-events-plugin.com/documentation/shortcodes/ "Shortcodes") and [template tags](https://wp-events-plugin.com/documentation/template-tags/ "Template Tags") coupled with the _blog_ [search attribute](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). _Link sub-site events directly to sub-site?_ When displaying global events on the main site you have the option of users viewing the event details on the main site or always direct them to the sub-site. If you select 'No', then a duplicate events page will be created and attached to your Events Page (must be enabled on your main blog for this to work). So for example, if your events page is _mysite.com/my-events/_, then a sub-site event might be _mysite.com/my-events/event/a-subsite-event/_, yet main site events will still have the format of _mysite.com/events/main-site-event/_ This is important if you expect users to have separate gateway information such as paypal addresses on their sub-site, if so you should enable this, so that booking payments aren't made to the main blog gateway accounts _(more interoperability with PayPal and sub-sites is planned for the near future)_. _Global event slug_ If you have chosen to display sub-site events on your main blog, you can modify the slug appended to your events page, so instead of _mysite.com/courses/event/a-subsite-event/_, you could modify this and have it be _mysite.com/courses/course/a-subsite-event/_ **Global Location Options** _Locations on main blog?_ If you would prefer all your locations to belong to your main blog, users in sub-sites will still be able to create locations, but the actual locations are created and reside in the main blog. This means that the actual WordPress post object will belong to the main blog, and a slightly different interface will be shown in the admin area (similar to the public location forms or those used with BuddyPress). Subsequent options will not be considered if this is chosen. _Display global locations on main blog?_ Displays locations from all sites on the network. You can still restrict locations by blog using [shortcodes](https://wp-events-plugin.com/documentation/shortcodes/ "Shortcodes") and [template tags](https://wp-events-plugin.com/documentation/template-tags/ "Template Tags") coupled with the _blog_ [search attribute](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). _Link sub-site locations directly to sub-site?_ See _Link sub-site events directly to sub-site?_ above, same principle but instead of using the events page, it uses the locations page. _Global location slug_ As with the global event slug, if you are displaying sub-site locations on your main site, a slug is appended to your locations page e.g. _mysite.com/locations-page/location/sub-site-location/_, you can modify the _location_ slug here. ## Custom Event and Location Fields URL: https://wp-events-plugin.com/documentation/event-attributes/ Aside from the usual fields Events Manager offers, you may find the need for extra fields that would contain specific information about your events. For example, you may host evening events and require a dress code or minimum age. You could be hosting classes and want to include teacher names. There's two ways to add custom information events and locations, the traditional WordPress way which uses [Custom Fields](http://codex.wordpress.org/Custom_Fields#Advanced_Techniques_for_Custom_Fields), or using our custom attributes feature. ### Custom Attributes vs. WP Custom Post Fields Custom attributes **ARE** custom fields. Custom fields with events work the same way as with WordPress post or pages, custom attributes are simply a way of imposing certain restrictions which custom fields do not: - each attribute can only be used once per event/location - only attributes created by admins can be used - a choice of pre-determined values can be provided Which one to use really depends on your specific needs. If you don't have a preference or you need to force specific fields and nothing more, try custom attributes (enabled by default). You can always go back and forth using custom fields, because the data is stored in the same place. ### Enabling/Activating To use event attributes or custom fields you must first enable them in the Settings page. #### Events Go to the _Events > Settings_ page in your admin dashboard and open the _General Options_ panel. You will see these two options, choose which features you'd like to use. #### Locations A little further down from the event attributes are the equivalent options for locations: ### Creating Custom Attributes Now we need to define our attributes by giving them names and possible values. Attributes are defined by either adding them to your attributes box in the same settings page where you activated attributes above, or entering them directly into your formats on the settings page. Events Manager will detect that there is a new attribute and generate the right form fields on the event or location registration page. In this example, I want to show the name of the speaker at my event, and the dress code. `Speaker` is the name of my speaker Key, this is what will as the label name for entering Speaker information on the event registration forms. I will also add a Dress Code attribute with some pre-defined values. The syntax used to create attributes is as follows. - `#_ATT{Field Label}` - Text event attribute, no default value if not defined. - `#_ATT{Field Label}{Default Value}` - Text event attribute, with a default value if not defined. - `#_ATT{Field Label}{Default Option|Option 1|Option 2|etc.}` - Select from one of the options, seperated by a pipe | character. If not defined, the first option is considered the default option. So, using the earlier example, this is what we would see in our event registration page: #### Location Attributes Location attributes work exactly the same way as Event attributes, with some slight differences: - They have a different placeholder, instead of `#_ATT` use `#_LATT`. - They can be used on event and location formats alike. - There is a seperate location attributes box if you're not adding your attribute directly into a format. #### Managing default values and preset values in attributes As you can see in the attribute examples above, the second page has a select box, which shows the options that were seperated by the | character. This makes things really easy for the people registering their events and also prevents misspellings or unwanted values from being entered. **If I have the same attribute in multiple places and need to add one more option, where do I add it?** This will undoubtedly be a common question, and fortunately there's an easy solution. In the first screenshot, you'll see a text box for event attributes. Using the example above, we could just use `#_ATT{Dress Code}` throughout the formats and add `#_ATT{Dress Code}{Informal|Smart|Casual Smart}` to that text box and it will apply to all the other attributes with the same name. **What about old attributes that I would like to add preset values to?** That is not a problem, but bear in mind that when converting an old attribute, if your event attribute values don't appear in the list of options, the default option will be used for that event. ### Creating Custom Fields If you decide to use custom fields, you'll see a section in your event/location submission forms similar to this: You'll be able to assign previous field keys and new values, add new custom fields with a new field key, or add a field more than once. ### Displaying Custom Fields and Attributes The easiest way to display custom fields and attributes is using the `#_ATT` and `#_LATT` placeholders for events and locations respectively. In our example above for creating an event attribute, the `#_ATT` placeholder was used to output Speaker and Dress Code information. If this was a custom field with the same key name, it would have been displayed instead. Since attributes are custom fields, you can also retrieve field and attribute values as custom fields [using WordPress custom field functions](http://codex.wordpress.org/Custom_Fields#Advanced_Techniques_for_Custom_Fields) within your theme files. ## General Optimization Recommendations URL: https://wp-events-plugin.com/documentation/general-optimization-recommendations/ Whilst we're regularly working on ways to improve the plugin in terms of performance (see our [optimization recommendations](https://wp-events-plugin.com/optimization-recommendations/) for further plugin-specific recommendations), there's a few things you can also do to speed up your page load times. This particularly becomes important when hosting hundreds (or more) events and also if you are running the plugin on websites with high levels of traffic. Even if you're not running a large events or high traffic website, optimization can still dramatically reduce the load time of your site which will benefit your users, reduce loads on your server, and even increase SEO rankings. Below are some recommendations which will allow you to speed up Events Manager as well as other areas of your website. ### Use Google Libraries WordPress and various other plugins make use of [jQuery](http://jquery.com) and the [jQuery UI](http://jqueryui.com/) library, which add various fancy effects to your site and generally improve the user experience. This is what powers things like our datepickers, booking ajax and calendars. One drawback with WordPress is that it includes the jQuery UI library broken up into various files. The concept is that you only load the specific components needed, however, when you need to use many of these components (as EM does) it can amount to 10+ files that need to be individually loaded by your visitors browsers, which is far from ideal. [Use Google Libraries](http://wordpress.org/extend/plugins/use-google-libraries/) plugin does two very helpful things. 1. It loads the correct scripts from the Google CDN servers, which not only is very fast, but also completely removes the burden on your server from these requests. 2. (And possibly more importantly) It magically requests ONE minified jQuery UI file, meaning you'll only ever download 2 jQuery files per request resulting in significantly faster load times! Given that other plugins and themes are likely to use these libraries, they'll benefit from the use of this plugin too. ### Use a Caching Plugin Caching plugins can do a number of very useful things, including - Caching certain pages, alleviating your server from repeatedly creating the same page over and over again. - Hosting external files such as images, scripts and stylesheets on a CDN (such as [Amazon CloudFront](http://aws.amazon.com/cloudfront/) or [MaxCDN](http://www.maxcdn.com/)), further unburdening your server from unnecessary loads. Whilst there's various other great caching plugins (notably [WP Super Cache](http://wordpress.org/extend/plugins/wp-super-cache/)) we currently recommend [W3 Total Cache](http://wordpress.org/extend/plugins/w3-total-cache/), simply because it provides more options for tailoring what gets cached when. See our basic [tutorial for setting up W3TC with EM](http://wp-events-plugin.com/tutorials/setting-up-w3-total-cache-for-events-manager/ "Setting up W3 Total Cache for Events Manager") ### Example in Action We use W3TC paired with the CloudFront CDN along with performance tweaks described in our [optimization recommendations](https://wp-events-plugin.com/optimizaion-recommendations/) for our [demo site](http://demo.wp-events-plugin.com/). The result? Page loads originally over 4 seconds brought down to ranges of **less than a second** up to 2 seconds, as shown on these Pingdom Tools results: [Image: pingdom-demo-site-example] ## Event and Location Grouping and Ordering URL: https://wp-events-plugin.com/documentation/event-search-attributes/event-location-grouping-ordering/ As of version 5.8, it is possible to easily group up events and locations by specific values using the _groupby_, _groupby\_orderby_ and _groupby\_order_ search attributes, and display only one item per group in a list along with other ungrouped items. This is a complex feature because of the many possible applications for it, but when applied to a specific situation it becomes easier to understand. The term 'Grouping' in this context is not to be confused with grouping events via categories/tags, BuddyPress Groups (i.e. the _group_ attribute) or the _events\_list\_grouped_ shortcode which outputs event lists grouped by day, week, month or year. ### What is grouping? We should start with a commonly used example. In a scenario where you have various daily recurring events, and a few one-off events, your list will look very repetitive if you showed every upcoming daily recurrence, and it'd be hard for people to see the important one-off events you may have within that list. If you would like to display all your upcoming events, but only display the first recurrence for each recurring event set, Grouping is what you're after. By using these grouping attributes, you can display the first item of each group, which can be useful in many circumstances such as if you wanted to display a list of: - All upcoming events, but showing only the first recurrence of an event in each set of recurring events. - Locations showing the first location within each state of a specific country. - The next upcoming event in each city, state or country. - Locations where the next upcoming event will occur for each blog you have in a MultiSite environment (with our Global Tables feature enabled) The possibilities of grouping are endless, but we'll give you a few shortcode examples of the above further down to show you the possibilities. ### Working example Whilst we explain each attribute, we'll work off the example below where we're trying to show the next upcoming event at each location, as well as any other upcoming events without locations. However, we'll display our final list of events in alphabetical order (just to highlight the different attributes and how they affect the final result): > \[_events\_list_ groupby="location\_id" orderby="event\_name" order="ASC" groupby\_orderby="event\_start\_date, event\_start\_time" groupby\_order="DESC" scope="future"\] In PHP it'd look like this: ```php echo EM\_Events::output('groupby'=>'location\_id', 'orderby'=>'event\_name', 'order'=>'ASC'...); ``` Here's a diagram we hope will help clarify how the final result is obtained: Notice how the final result (the purple box) has a list of events in alphabetical order and non-sequential dates, containing only one event per location as well as events without locations. This is because _order_ is set to _event\_name_ which is what determines the order of the final list. In the diagram, the shortcode doesn't include _scope="future"_ and _order="ASC"_ as these two arguments are the default values in Events Manager (unless changed in our settings page). ### Understanding each grouping attribute and how to use it Let's go through each attribute and break down the meaning and use: #### _groupby_ - What to group by _groupby_ is the main argument and is required for the other two to take effect. This attribute defines what fields you want to group your results by, and accepts any field name from the wp\_em\_events and wp\_em\_locations tables (just like _orderby_). In our working example, we have set _groupby_ to _location\_id_ which allows you to group events by location, and display one event from each location. Note, that in situations where an event or location does not have a value for what is being grouped by, those items are not grouped and shown separately. In our example above, you'll see two events without locations showed up in the final list. You can use other attributes provided by EM to filter your results further. If we wanted to only show events with locations, we'd also add the _has\_locations="1"_ attribute to the shortcode above. #### _groupby\_orderby_ - What is used to choose each result in each group _groupby\_orderby_ defines on what basis we decide to choose the event/location that ends up on our final list. This also accepts a comma-separated list of event or location table field names, just like _groupby_ and _orderby_. In our shortcode example above, we have chosen the event based on when it begins. You should use '_event\_start\_date, event\_start\_time'_ to order by the start date **and** then the time, we chose '_event\_start\_date'_ in our example just to shorten the shortcode length for display purposes. #### _groupby\_order_ - How to sort what you're using to choose in each result in each group _groupby\_order_ will sort the list within each group of events/locations in ASCending or DESCending order, and accepts either ASC or DESC as a value (or lowercase asc/desc). Since the first item is what is chosen to be used in the final list of events/locations, the order of sorting will determine whether you will obtain the first or last item within each group as sorted by _group\_orderby_. In our example, you'll be getting the **latest** event starting at each location, because _groupby\_order_ value is DESCending order for a list sorted by start date in _group\_orderby_. If it was ASCending, you'd get the earliest event. Also, note that here, we're not choosing the next **upcoming** event here, we're getting the **earliest** or **latest** event within the _scope_ we've chosen, which in this case is future events. ### Further considerations Now that you have an understanding of how grouping works, it's important to note that grouping simply defines what you're grouping by, and which item to choose within each group. _order_ and _orderby_, whilst similar in terms of accepted values, will order the final list of events and has no impact on what happens within the list of items within each group. Grouping can (and should) be paired with your usual attributes to limit the what's chosen within each group, and in the final result. For example, _scope_ will let you choose the time span from which to choose your events, _has\_location_ allows you to only show events that have a location, or _eventful_ will let you only show a list of locations that have an event associated with it. Another situation where people may get confused is grouping by location, categories and tags. If you would like to show a list of upcoming events, but grouped by location, but show more than one event per location, this isn't the right solution for you. In that sort of situation, you're actually displaying a list of locations, and within each location you would want to display upcoming events by using #\_LOCATIONNEXTEVENTS. The resulting shortcode may look like this: > \[locations\_list scope="future" eventful="1"\] ### #\_LOCATIONNAME #\_LOCATIONNEXTEVENTS\[/locations\_list\] **However,** here's a great example of how you **can** still use grouping show a list of upcoming events at one location (the first location alphabetically) per country for example! > \[locations\_list scope="future" eventful="1" groupby="location\_country" groupby\_orderby="location\_name"\] ### #\_LOCATIONNAME #\_LOCATIONNEXTEVENTS\[/locations\_list\] As you can see, the combinations are endless! ### More real-world examples We hope this article has given you a better understanding of how to leverage this powerful new feature. We'll finish off by providing an example shortcode for each of the initial scenarios we presented at the beginning. We'll make some assumptions here, to keep the shortcodes shorter. The default scope and ordering would look like this in each shortcode: > _scope="future" orderby="event\_start\_date, event\_start\_time" order="asc" groupby\_order="asc"_ Depending on your settings, you may need to add one or more of these to produce the right results. **All upcoming events, but showing only the first recurrence of an event in each set of recurring events.** > \[events\_list groupby="recurrence\_id" groupby\_orderby="event\_start\_date,event\_start\_time"\] **Locations showing the first location alphabetically within each state of a specific country.** > \[locations\_list groupby="location\_country" groupby\_orderby="location\_name" orderby="location"\] **The next upcoming event in each town/city.** > \[events\_list groupby="location\_town" groupby\_orderby="event\_start\_date, event\_start\_time"\] **Locations where the next upcoming event will occur for each blog you have in a MultiSite environment (with our Global Tables feature enabled)** > \[events\_list has\_location="1" groupby="blog\_id" groupby\_orderby="event\_start\_date, event\_start\_time"\]#\_LOCATIONNAME\[/events\_list\] > > _In this last example, we use events\_list rather locations\_list because we're looking for locations based on upcoming events, which we can obtain from the event via placeholders as well as information about the specific event if needed._ ## Template Tags URL: https://wp-events-plugin.com/documentation/template-tags/ ### Template tags If you're into theming, you should probably use the template tags provided by Events Manager. The following tags insert event-related elements into your templates. At least a basic knowledge of PHP and wordpress [template tags](http://codex.wordpress.org/Template_Tags) is needed to use these. Here are some basic tags that you may find useful for displaying certain information from Events Manager. > **Tip:** For advanced users, we suggest you check out the `em-template-tags.php` file, and see the underlying functions used within these template tags. Whilst the functionality is ultimately the same, you can get finer control using root functions. For example, `em_calendar()` is the same as `EM_Calendar::output()`. ### Display Event Information Events Manager was made with flexibility in mind, especially for developers, so if you know what you’re doing and want to do more with Events Manager, see our [advanced useage](https://wp-events-plugin.com/documentation/advanced-usage/) page. > **Info:** All of these functions below the $args variable can be an array or [query-string](http://codex.wordpress.org/How_to_Pass_Tag_Parameters#Tags_with_query-string-style_parameters) with any event [accepted arguments](https://wp-events-plugin.com/documentation/event-search-parameters/). > **Tip:** If you change the function names below from `em_` to `em_get_`, the function will return the value rather than immediately display it. #### `em_events()` #### ```php em_events( $args ) ``` Displays a list of events with fine-grained control over the events shown and their format. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | *required* | Array of [general](https://wp-events-plugin.com/event-search-parameters/#general-parameters), [event](https://wp-events-plugin.com/event-search-parameters/#event-parameters) and [location](https://wp-events-plugin.com/event-search-parameters/#location-parameters) [accepted arguments](https://wp-events-plugin.com/documentation/event-search-parameters/). | #### `em_calendar()` #### ```php em_calendar( $args ) ``` Displays an HTML calendar populated with events that match the given arguments. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | *required* | Array of [calendar](https://wp-events-plugin.com/event-search-parameters/#calendar-parameters), [general](https://wp-events-plugin.com/event-search-parameters/#general-parameters), [event](https://wp-events-plugin.com/event-search-parameters/#event-parameters) and [location](https://wp-events-plugin.com/event-search-parameters/#location-parameters) [accepted arguments](https://wp-events-plugin.com/documentation/event-search-parameters/). | #### `em_locations()` #### ```php em_locations( $args ) ``` Displays a list of locations that match the given arguments. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | *required* | Array of [general](https://wp-events-plugin.com/event-search-parameters/#general-parameters) and [location](https://wp-events-plugin.com/event-search-parameters/#location-parameters) [accepted arguments](https://wp-events-plugin.com/documentation/event-search-parameters/). | #### `em_events_list_grouped()` #### ```php em_events_list_grouped( $args ) ``` Prints a grouped list of events by year, month, week, or day. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | *required* | Array of [general](https://wp-events-plugin.com/event-search-parameters/#general-parameters), [event](https://wp-events-plugin.com/event-search-parameters/#event-parameters) and [location](https://wp-events-plugin.com/event-search-parameters/#location-parameters) [accepted arguments](https://wp-events-plugin.com/documentation/event-search-parameters/). | ### Links #### `em_link()` #### ```php em_link( $text = '' ) ``` Creates and prints an HTML link to the events page. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$text` | `string` | `''` | Optional link text. | #### `em_rss_link()` #### ```php em_rss_link( $text = 'RSS' ) ``` Creates and prints an HTML link to the RSS feed. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$text` | `string` | `'RSS'` | Optional link text for the RSS feed. | ### Forms > **Tip:** If you change the function names below from `em_` to `em_get_`, the function will return the value rather than immediately display it. #### `em_event_form()` #### ```php em_event_form( $args = [] ) ``` Outputs the event submission form for guests and members. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | `[]` | Optional array of arguments to customize the form. | #### `em_events_admin()` #### ```php em_events_admin( $args = [] ) ``` Outputs a table of events belonging to the user. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | `[]` | Optional array of arguments to customize the display.| #### `em_event_search_form()` #### ```php em_event_search_form( $args = [] ) ``` Outputs the event search form. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | `[]` | Optional array of arguments to customize the search. | #### `em_location_form()` #### ```php em_location_form( $args = [] ) ``` Outputs the location submission form for guests and members. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | `[]` | Optional array of arguments to customize the form. | #### `em_locations_admin()` #### ```php em_locations_admin( $args = [] ) ``` Outputs a table of locations belonging to the user. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | `[]` | Optional array of arguments to customize the display.| #### `em_location_search_form()` #### ```php em_location_search_form( $args = [] ) ``` Outputs the location search form. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$args` | `array` | `[]` | Optional array of arguments to customize the search form, see [search form parameters][/search-form/parameters/] for more options. | ### Conditional Tags > **Info:** Conditional tags all return a `boolean` value, these are useful in `if` statements. Each of these functions may accept parameters to customize the behavior of the conditional check. #### `em_is_event()` #### ```php em_is_event( $data, $object_required = false ) ``` Returns whether the given `$data` represents an event. | **Parameter** | **Type** | **Default** | **Description** | |--------------------|-------------|--------------|------------------------------------------------------| | `$data` | `mixed` | *required* | The data to be checked. accepts a number (assumed Post ID), `EM_Event`, `WP_Post` or subclass of `EM_Object` with the `post_type` matching an event post type, | | `$object_required` | `boolean` | `false` | Specifies if an EM Event-type object is required, such as `EM_Event`. | #### `em_is_location()` #### ```php em_is_location( $data, $object_required = false ) ``` Returns whether the given `$data` represents a location. | **Parameter** | **Type** | **Default** | **Description** | |--------------------|-------------|--------------|------------------------------------------------------| | `$data` | `mixed` | *required* | The data to be checked. accepts a number (assumed Post ID), `EM_Location`, `WP_Post` or subclass of `EM_Object` with the `post_type` matching a location post type, | | `$object_required` | `boolean` | `false` | Specifies if an EM Event-type object is required, such as `EM_Location`. | #### `em_are_events_available()` #### ```php em_are_events_available( $scope = 'future' ) ``` Returns `true` if there are any events available in the given `$scope`. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$scope` | `string` | `future` | The scope of events to check. | #### `em_is_events_page()` #### ```php em_is_events_page() ``` Returns `true` if the page currently being displayed is the events page. #### `em_is_event_page()`{#em_is_event_page} #### ```php em_is_event_page() ``` Returns `true` if the page currently being displayed is a single event page. #### `em_is_calendar_day_page()` #### ```php em_is_calendar_day_page() ``` Returns `true` if the page currently being displayed is a single calendar day page. #### `em_is_category_page()` #### ```php em_is_category_page( $category = false ) ``` Returns `true` if the page currently being displayed is a single category page. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$category` | `mixed` | `false` | Optional category or categories to check against. Accepts an `array` of term IDs and/or slugs, or a single term ID or slug | #### `em_is_categories_page()` #### ```php em_is_categories_page() ``` Returns `true` if the page currently being displayed is a categories list page. #### `em_is_tag_page()` #### ```php em_is_tag_page( $tag = false ) ``` Returns `true` if the page currently being displayed is a single tag page. | **Parameter** | **Type** | **Default** | **Description** | |---------------|-----------|---------------|------------------------------------------------------| | `$tag` | `mixed` | `false` | Optional tag/tags to check against. Accepts an `array` of term IDs and/or slugs, or a single term ID or slug | #### `em_is_location_page()` #### ```php em_is_location_page() ``` Returns `true` if the page currently being displayed is a single location page. #### `em_is_locations_page()` #### ```php em_is_locations_page() ``` Returns `true` if the page currently being displayed is a locations list page. #### `em_is_my_bookings_page()` #### ```php em_is_my_bookings_page() ``` Returns `true` if the page currently being displayed is the user's bookings page. #### `em_is_event_rsvpable()` #### ```php em_is_event_rsvpable() ``` Returns `true` if the current event is RSVPable. ## Using Template Files URL: https://wp-events-plugin.com/documentation/using-template-files/ Events Manager was built on the principle of being as flexible as possible. Whilst you can modify the look and feel of almost any output event information, it is sometimes necessary to use more complex code or integrate some PHP from your theme or another plugin. Whatever the reason, it is now possible to simply insert specific files into your theme which will override certain aspects of Events Manager. Events Manager uses templates from within the plugin folder to format things like calendars, event pages, event registration forms, etc. and therefore, when it calls these templates, it first checks to see whether it should use the same one from your theme instead. This folder is called _templates:_ To override any of these files, you should place the file you want to modify within the same folder structure in one of these folders **starting from, not including** the first templates folder: - wp-_content/plugin-templates/events-manager_ - _wp-content/themes/parent-theme/plugins/events-manager_ - _wp-content/themes/child-theme/plugins/events-manager_ The above also shows the order of precedence, so if you override the same file in multiple places, the file in your child theme will take precedence over the parent theme and the plugin-templates folder respectively. Here's a visual example: If these folders don't exist in your theme or the wp-content folder, create them. #### Example - Overriding the Calendar HTML We'll give you a common example, using the above folder structures,  which override the calendar. This file is located at _wp-content/plugins/events-manager/templates/templates/calendar-day.php._ Rather than editing this file directly, copy it to _wp-content/plugin-templates/events-manager/templates/calendar-day.php_ and edit it there, as it will not be overwritten when you update Events Manager. Note that Events Manager has two _template_ folder levels, the one inside contains common templates, but other folders within the parent templates folder can be overridden. If you're copying over a file from templates/templates, that'll need to go within a templates folder in the overriding folder destination, as per the screenshot above. ### Pro Templates Events Manager Pro also makes use of templates for its own features. In this case, the concept is exactly the same, except you need to refer to the folder in _events-manager-pro/templates_ to find the templates you're after, and put them in a separate folder at the same level as the _events-manager_ folder you've created as per the examples above. Note that you're creating a new folder aside from _events-manager_ here, you don't put the events-manager-pro folder inside the _events-manager_ folder; they remain alongside each other (assuming you have an _events-manager_ folder, not required) ### Which folder should I choose? This largely depends on your needs, but generally speaking, we recommend putting it in the _wp-content/plugin-templates/events-manager_ folder. The reason is that if you ever update your theme, your changes don't get overwritten, whereas this folder doesn't get overwritten by any updates to any part of your installation. If you're designing a theme from scratch or a child theme and Events Manager theming is integrated within your theme, then it may make sense to add it to your theme folder. If you previously had your overriding files in one place, you can move it at any time to any of the possible template locations without consequence. Just remember that you should move it, because if you copy over your files from your theme to the _wp-content/plugin-templates_ folder, EM will still use the files from your theme. ### **More Common Mistakes** **Wrong folder path -** Files within the templates folder are not put within _wp-content/themes/your-theme/plugins/events-manager/**templates**/templates/_ - note the extra templates folder in this path compared to the previous one. **Don't copy all the files -** whilst we do our utmost to keep changes on the templates to a minimum, we're regularly adding features that sometimes require us to change the default templates slightly to allow this new functionality. If you copy files you don't need to modify, they will unnecessarily override potentially updated files in the plugin folder and cause conflicts. ## WP Cron and Events Manager URL: https://wp-events-plugin.com/documentation/wp-cron/ ### What is Cron and WP\_Cron? [Image: Time] Cron is a Linux scheduling utility which enables a server to run tasks automatically at preset times, without user intervention. Common tasks that use Cron include things like automated backups, which might be scheduled to run daily in the middle of the night. Each scheduled task is called a cron job and they can be run as frequently as every minute or as far apart as once a year. Many core WordPress features - like checking for theme and plugin updates - are run as scheduled tasks. The trouble is, because Cron is a server command (and not all WordPress sites are run on Linux), WordPress can't add tasks directly to Cron. Instead, it uses its own version called _WP\_Cron_. ### How WordPress Crons Work Every time a page is loaded in admin or on the front-end of your site, WordPress calls W_P\_Cron_. This function checks for scheduled tasks and runs any that are found. This takes place as a background process so that page loading isn't held up while tasks are running. Events Manager uses WP\_Cron to send event email reminders. When you set up reminder emails under _Events > Settings > Emails > Event Email Reminders_, you're effectively creating a cron job to run every day to check for event reminders. In fact, Events Manager uses two crons - one to create the mail queue daily and another to process the queue every minute and send out emails in batches (if there are any to send). ### Potential problems with WordPress Cron The problem with using _WP\_Cron_ that if your site traffic is relatively low, you may not get a visitor until some time after a cron job was due to run - leading to delayed event email reminders. Sites with lots of traffic can experience problems too, with simultaneous page loads causing _WP\_Cron_ to run more than once. In some cases, this can lead to more than one reminder being sent to a user as a second call to _WP\_Cron_ re-processes the mail queue before the first _WP\_Cron_ has had time to delete it. This means automatic triggering of _WP\_Cron_ isn't always the most reliable solution - especially for time-sensitive content like events. The answer is to set up a "real" cron job on the server to call _WP\_Cron_ at the exact time, only once, without needing to be triggered by visitors on your site. ### Setting up 'real' cron jobs The first step is to prevent WordPress from running _WP\_Cron_ automatically. To do that, open up your wp-config.php file (found in the top level folder of your WordPress install) in a text editor and add this line: `define('DISABLE_WP_CRON', 'true');` Now you're ready to add a server side cron job. We're recommending two ways, the 'right' way and the 'easy' way, both should have the same result. #### The 'right' way: Set up a server cron job The exact steps / screens will vary between web hosts, but the general process is similar no matter which company you use. The steps and screenshot below show how to do it using cPanel which is used by Bluehost, Hostgator and many other hosting companies. After logging in to your cPanel / admin area, go to the _Advanced_ area and click the _Cron jobs_ icon. On the _Add new cron job_ page you'll need to configure both a time for the cron and the script you want to run. For optimum running of all WordPress and Events Manager scheduled tasks, schedule a cron to run once every minute. Many admin panels - including cPanel - have a preset selector for "Every minute". If not, add an asterisk (\*) under the minute option to denote "every minute". Make sure other options like Day and Month also have an asterisk so that the cron runs every day and every month. [Image: add-cron] In the _Command_ field, paste the line below making sure you change yoursite.com to your own domain: `wget http://www.yoursite.com/wp-cron.php?doing_wp_cron=1 > /dev/null 2>&1` On some systems, you may need to use a curl function instead: `curl -s http://www.yoursite.com/wp-cron.php?doing_wp_cron=1 > /dev/null` #### The 'easy way': use a monitoring service If setting up server cron jobs isn't your cup of tea, there's an easy alternative. There's loads of monitoring services out there that ping your site to make sure it's working. You can use these to do the same thing you'd do via a cron job, which is simply visiting the wp-cron.php file on your site every minute. The downside is that most services will charge for minute-by-minute checks which is the recommended frequency. [EasyCron](https://pxlink.cc/easycron) is a service dedicated to doing cron jobs. They even have a free account offering crons every 20 minutes and have a tutorial specifically for Events Manager. [Pingdom](http://pingdom.com) is a robust service mainly aimed at checking whether your site is up, but is also capable acting as a cron job, simply set up an HTTP request every minute to _http://www.yoursite.com/wp-cron.php?doing\_wp\_cron=1_ (remember to change www.yoursite.com to your domain). ### Checking cron is running Some admin panels allow you to specify a notification email that's sent each time the cron script is run. That can be handy, but make sure you remove the email once you know it's working, unless you like getting lots of email :) Alternatively, try the [WP Crontrol](https://wordpress.org/plugins/wp-crontrol/) plugin which lets you view scheduled tasks to make sure they're being run as they should. ### Cron on WordPress Multisite If you're running a WordPress network, remember the method above will only run _WP\_Cron_ for one site only - you'll need to add an additional cron for each site in the network. ### Additional resources Another plugin that may be useful is [WP-Cron Control](https://wordpress.org/plugins/wp-cron-control/) by Automattic, which lets you specify a secret key that must be used when calling WP\_Cron. This is another way to prevent multiple calls to WP\_Cron. Photo credit: [Βethan](https://www.flickr.com/photos/beth19/4721798240/) ## PHP Development URL: https://wp-events-plugin.com/documentation/advanced/php/ Events Manager uses an Object Oriented approach to handling events. This opens up lots of possibilities for developers as you can now easily change the way events are displayed on your website with much less code and in a much more upgrade-safe manner. As time permits, we'll update this page with a more comprehensive documentation highlighting the full extent of Events Manager's power and flexibility. Here are a few basic commands to get you started. ##### `EM_Events::output( $args )` This will print out a list of events. The $args variable should be an array with any event [accepted arguments](https://wp-events-plugin.com/documentation/event-search-attributes/). This is a very powerful function as you have a fine grained control of what events are shown, what format to show them in, etc. Example: ``` if ( class_exists('EM_Events') ) { echo EM_Events::output( array('limit' => 10,'orderby' => 'name') ); } ``` ##### `EM_Calendar::output( $args )` Will return an html calendar string, populated with the events that match the given arguments in $args, which should be an array with any calendar [accepted arguments](https://wp-events-plugin.com/documentation/event-search-attributes/). Example: ``` if ( class_exists('EM_Calendar') ) { echo EM_Calendar::output( array('long_events'=> 1, 'location' => '1') ); } ``` ##### `EM_Locations::output( $args )` Will return a list of locations, that match the given arguments in $args, which should be an array with any calendar [accepted arguments](https://wp-events-plugin.com/documentation/event-search-attributes/). Example: ``` if ( class_exists('EM_Locations') ){ echo EM_Locations::output( array('limit' => '10','orderby' => 'name') ); } ``` ## Shortcode Security Suggestions URL: https://wp-events-plugin.com/documentation/advanced/security/shortcode-security/ > **Important:** This page contains important information about how shortcodes work, and will work in future versions. If you use shortcode **with custom formats**, this is of particular importance to you! Prior to version `6.4.8`, shortcodes behaved slightly differently by decoding html entities on all supplied formats. This included wrapped content like `[shortcode]content[/shortcode]` and the parameters such as [`format`](https://wp-events-plugin.com/event-search-attributes/#format), [`format_header`](https://wp-events-plugin.com/event-search-attributes/#format_header) and [`format_footer`](https://wp-events-plugin.com/event-search-attributes/#format_footer). This left shortcodes exposed to potential vulnerabilities since any users with publishing capabilities could potentially supply harmful HTML content through these shortcode formats. We received a report from the WordFence security team, who had discovered a vulnerability, which was fixed in `6.4.8`. The end result is that some websites that legitimately supplied html entity-encoded formats within shortcodes would end up with unexpected results. Check this short gif video for a demonstration on how this can be confusing on editors once running `6.4.8` or higher: Ultimately, on the classic editor, or on Gutenberg, if you're using a visual editor and you see raw HTML, then that's what you'll get on the front-end because what you're really outputting to your visitor is this: ```html [events_list]<p>#_EVENTNAME</p>[/events_list] ``` Which will look exactly like this on the page: ```html Event XEvent Y ``` Previously, EM would decode and display the content as one may have *hoped*. This, in reality, is the wrong approach. Entity-encoded HTML cannot be reliably sanitized and becomes a security risk once you allow users into your site to submit content that gets published. ### The Ideal Solution > **Tip:** The majority of users these days will likely be doing it this way. You'll know you're 'doing it wrong' if you see the the HTML format in an editor, whilst other parts of that editor or block may be bold or formatted. Ideally, you will use shortcode as intended, and supply HTML via the HTML or shortcode blocks in Gutenberg, or in 'text' mode via the Classic Editor. This ensures that any submitted content is correctly sanitized by WordPress itself, allowing only the HTML the submitting user is permitted to use. In the video further up, we show you how to achieve this with the Classic Editor, Shortcode, and HTML blocks. Paragraph blocks are not recommended if using formatting. ### Intermediate Solutions and Risks #### Risks This is particularly of importance if you allow untrusted users to submit content on your site. This includes MultiSite instances, site admins are also not considered 'trustworthy' as they are still submitting content to your network. If you trust all your users, or you have only limited user(s) that can publish content, then the risk is significantly lower. However, we still recommend transitioning at some point, since if a hacker does manage to inject content into your site somehow, they could leverage this risk. #### Solutions > **Important:** These solutions are included in the `6.4.11` release, which is not yet released at time of writing. You can [upgrade to dev version](https://wp-events-plugin.com/upgrade-dev-version/) `6.4.10.2`, which does include these fixes. Alternatively, you can implement the code snippet provided further down, which will work on `6.4.9` and later. If you have been using Events Manager for some time, then it's very possible you've unknowingly added shortcode throughout your pages and received a shock updating to `6.4.8` or later. Version `6.4.11` introduces a few important settings you can adjust in your settings page to temporarily rectify this. You will find the following options under *Events > Settings > Admin Tools > HTML Escaping Options* : ##### Decode shortcode content? If you have shortcode like this: ```html [events_list]<p>#_EVENTNAME</p>[/events_list] ``` Then enabling this option will display your content as expected, Event names, one per line/paragraph. We recommend going through your content and modifyng it accordingly. In most cases, it's a copy/paste job. Copy the desired HTML whilst in visual mode, switch to text and paste/replace the entity-encoded content. ##### Sanitize shortcode content? If the above setting is enabled, then we recommend leaving this setting on too, as it will pass all decoded content through `wp_kses()` each time it is displayed so only specific allowed HTML will pass through, and any malicious content is removed. > **Warning:** Shortcode-Specific Sanitization `wp_kses()` is a more resource-intensive function than other escaping methods used during output, and is intended for when saving content. This may impact server performance to some degree particularly for high-traffic websites. ##### Allow format shortcode parameters? Format parameters [`format`](https://wp-events-plugin.com/event-search-attributes/#format), [`format_header`](https://wp-events-plugin.com/event-search-attributes/#format_header) and [`format_footer`](https://wp-events-plugin.com/event-search-attributes/#format_footer) ideally should not be used in shortcode. These formatting parameters should be added within, before and after the shortcode, in respective order. > **Warning:** Shortcode-Specific Sanitization If enabled, all three format parameters are run through `wp_kses()` each time the containing page is displayed. This is more resource intensive, but necessary for security and there is no option to disable this behaviour. ##### Decode shortcode format parameters? If enabled, you can opt not to decode these format parameters, this is certainly a safer option, however we will always sanitize via `wp_kses()` each time (see above setting). ### Transitioning Forward At some point in the future, we will completely remove the above options, and cease to allow format parameters in shortcode or entity-decode the content supplied within shortcode. If you do use entity-escaped content and still wish to use it, then your only option is to use some PHP to reverse the transition. You can add the following code as per these instructions, and you will always be able to use format parameters and entity-encoded text on your shortcode. ```php function legacy_em_clean_shortcde_args ( $args, $format, $supplied_args = array() ){ // re-enable format params if they were removed if( !empty($supplied_args['format']) && empty($format) ){ $args['format'] = $supplied_args['format']; } if( !empty($supplied_args['format_header']) ){ $args['format_header'] = $supplied_args['format_header']; } if( !empty($supplied_args['format_footer']) ){ $args['format_footer'] = $supplied_args['format_footer']; } // html_entity_decode all three format array items in $args if( !empty($args['format']) ) $args['format'] = html_entity_decode($args['format']); if( !empty($args['format_header']) ) $args['format_header'] = html_entity_decode($args['format_header']); if( !empty($args['format_footer']) ) $args['format_footer'] = html_entity_decode($args['format_footer']); // wp_kses() the format content global $allowedposttags; if( !empty($args['format']) ) $args['format'] = wp_kses($args['format'], $allowedposttags ); if( !empty($args['format_header']) ) $args['format_header'] = wp_kses($args['format_header'], $allowedposttags ); if( !empty($args['format_footer']) ) $args['format_footer'] = wp_kses($args['format_footer'], $allowedposttags ); // return the params return $args; } add_filter('em_clean_shortcode_args', 'legacy_em_clean_shortcde_args', 10, 3); ``` ## Placeholders URL: https://wp-events-plugin.com/documentation/placeholders/ Events Manager has a templating syntax that lets you customise events information in the events list and pages. You can use this syntax both in the Events Manager Settings page and in the template tags or shortcodes that you might insert in your theme templates or pages/posts. The syntax is quite simple, just write your html code in the usual way, then you can add a number of placeholders corresponding to the information you want to show. See the bottom of this page for a few examples. ### Event Related Placeholders When you’d like to show information pertaining to events, you can choose from the following. In all cases, you should also be able to call location related placeholders. #### Event Details | Placeholder | Description | |-------------|-------------| | `#_EVENTID` | Shows the event ID number in the wp_em_events table. | | `#_EVENTPOSTID` | Shows the event corresponding Post ID in the wp_posts table. | | `#_EVENTNAME` | Displays the name of the event. | | `#_EVENTNOTES` | Shows the description of the event. | | `#_EVENTEXCERPT` | If an excerpt has been added to the event, it will be used. If you added a [more tag](http://en.support.wordpress.com/splitting-content/more-tag/) to your event description, only the content before this tag will show. | | `#_EVENTEXCERPT{words,...}` | If an excerpt has not been added to the event you can use this format `#_EVENTEXCERPT{10,...}`, where `10` is the number of words to show and `...` is what is used at the cut-off point. | | `#_EVENTEXCERPTCUT` | [`#_EVENTEXCERPT`](#_EVENTEXCERPT) (and also accepts the `{words,...}` arguments) but will also cut excerpts as well as post content. Default word limit is 55 and cut-off is `[...]` | | `#_EVENTIMAGE` | Shows the event image, if available. | | `#_EVENTIMAGE{x,y}` | Shows the event image thumbnail, x and y are width and height respectively, both being numbers e.g. `#_EVENTIMAGE{100,100}`. If 0 is used for either width or height, the corresponding dimension will be proportionally sized | | `#_EVENTCATEGORIES` | Shows a list of category links this event belongs to. | | `#_EVENTCATEGORIESLINE` | Displays all event categories in a single, comma-separated line, or the default no categories message defined in settings. | | `#_EVENTCATEGORIESIMAGES` | Shows a list of category images this event belongs to. Categories without an image will be ignored. | | `#_EVENTTAGS` | Shows a list of tag links this event belongs to. | | `#_EVENTLOCATION` | Displays information about the event location, which is different from a physical location. [See our documentation](https://wp-events-plugin.com/documentation/location-types/) for more information. | | `#_EVENTSTATUS` | A textual representation of the event status, such as `Active` or `Cancelled` | | `#_EVENTTAGSLINE` | Displays all event tags in a single, comma-separated line, or the default no tags message defined in settings. | #### Recurring Events Events which are recurrences can output information about the recurring pattern or recurring event itself (a template for all recurrences). > **Tip:** Combine this with the [`{is_recurrence_}`](https://wp-events-plugin.com/conditional-placeholders/#is_recurrence) conditional placeholder to display in lists where some events are not recurring. | Placeholder | Description | |-------------|-------------| | `#_RECURRINGDATERANGE` | A range of dates from when the recurrences start and end. | | `#_RECURRINGID` | The recurring ID, which all recurrences share. This is equivalent to the Event ID of the recurring event. | | `#_RECURRINGPATTERN` | Textual representation of the recurrence pattern, such as `Saturday every 3 weeks` | #### Date and Times These are shortcut placeholders for pre-formatted dates and times. See the Custom Date/Time Formatting section below for more refined formatting placeholders. | Placeholder | Description | |-------------|-------------| | `#_24HSTARTTIME` | Start time in a 24 hours format (e.g. 16:30). | | `#_24HENDTIME` | End time in a 24 hours format (e.g. 18:30). | | `#_12HSTARTTIME` | Start time in a 12 hours format (e.g. 4:30 PM). | | `#_12HENDTIME` | End time in a 12 hours format (e.g. 6:30 PM). | | `#_EVENTSTARTDATE` | Start date of the event | | `#_EVENTTIMES` | Displays either a single time, time-span, or "All Day" depending on your event times. Format is taken from your Events Manager settings page. | | `#_EVENTDATES` | Displays either a single date or a date range depending on your event dates. Format is taken from your Events Manager settings page. | ##### Custom Date/Time Formatting Events Manager allows extremely flexible date formatting by using [PHP date syntax format characters](http://www.php.net/manual/en/function.date.php) along with placeholders. | Placeholder | Description | |-------------|-------------| | `# or #@` | Prepend `#` or `#@` before a valid PHP date syntax format character to show start and end date/time information respectively (e.g. `#F` will show the starting month name like "January", #@h shows the end hour). | | `#_{x} or #@_{x}` | You can also create a date format without prepending # to each character by wrapping a valid php date() format in `#_{}` or `#@_{}` (e.g. `#_{d/m/Y}`). If there is no end date (or is same as start date), the value is not shown. This is useful if you want to show event end dates only on events that are longer than one day, e.g. `#j #M #Y #@_{ \u\n\t\i\l j M Y}`. | #### Timezones, Date and Times Events can have their own timezones, so that events held in various parts of the world are recorded according to their real local time. You can display timezone information in your event formats too. > **Info:** Timezone Formats Timezone formats are [provided by WordPress](https://developer.wordpress.org/reference/functions/wp_timezone_string/) which use [PHP Timezone names](https://www.php.net/manual/en/timezones.php), which can also include manual UTC offsets. Local user timezones are derived via Javascript from the user browser and adheres to the [same formatting](https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones) as PHP | Placeholder | Description | |-------------|-------------| | `#_EVENTTIMEZONE` | Event timezone with spaces instead of underscores, such as `America/New York` | | `#_EVENTTIMEZONERAW` | Event timezone *without* spaces instead of underscores, such as `America/New York` | | `#_EVENTTIMEZONELOCAL` | The local timezone of the viewing user, this using Javascript to determine browser location and timezone. | ##### Site Timezone Date/Times These placeholders are extensions of the default Date/Time placeholders, but instead will display the time of the event relative to your WordPress timezone rather than the local time of the event itself. > **Tip:** Timezone Settings Your WordPress site timezone is found in your **Dashboard > Settings > General** settings page. > **Warning:** Important Dates and times may differ according to timezones, for example an event near midnight in USA would show up as next day, early morning in Europe. | Placeholder | Description | |-------------|-------------| | `#_12HSTARTTIME_SITE` | [`#_12HSTARTTIME`](#_12HSTARTTIME) relative to your site timezone. | | `#_12HENDTIME_SITE` | [`#_12HENDTIME`](#_12HENDTIME) relative to your site timezone. | | `#_24HSTARTTIME_SITE` | [`#_24HSTARTTIME`](#_24HSTARTTIME) relative to your site timezone. | | `#_24HENDTIME_SITE` | [`#_24HENDTIME`](#_24HENDTIME) relative to your site timezone. | | `#_EVENTDATES_SITE` | [`#_EVENTDATES`](#_EVENTDATES) relative to your site timezone (dates can be different for events near midnight in a different timezone). | | `#_EVENTTIMES_SITE` | [`#_EVENTTIMES`](#_EVENTTIMES) but displays times relative to your site timezone. | | `#__{x} or #@__{x}` | Same as [`#_{x}`](#_) or [`#@_{x}`](#@) relative to your site timezone. | ##### Viewer Timezone Date/Times These placeholders are extensions of the default Date/Time placeholders, but instead will display the time of the event relative to the visitor timezone rather than the local event start time. > **Info:** We use [moment.js](https://momentjs.com/) Javascript to output local times, which is shipped with WordPress core. This time is based on the user browser settings and JavaScript, so this may not always be accurate if a visitor is travelling and does not update their browser timezone, or if they have disabled JS on their browser. > **Warning:** Important Dates and times may differ according to timezones, for example an event near midnight in USA would show up as next day, early morning in Europe. | Placeholder | Description | |-------------|-------------| | `#_12HSTARTTIME_LOCAL` | [`#_12HSTARTTIME`](#_12HSTARTTIME) in user local time. | | `#_12HENDTIME_LOCAL` | [`#_12HENDTIME`](#_12HENDTIME) in user local time. | | `#_12HTIMES_LOCAL` | [`#_12HTIMES`](#_12HTIMES) in user local time. | | `#_24HTIMES_LOCAL` | [`#_24HTIMES`](#_24HTIMES) in user local time. | | `#_24HSTARTTIME_LOCAL` | [`#_24HSTARTTIME`](#_24HSTARTTIME) in user local time. | | `#_24HENDTIME_LOCAL` | [`#_24HENDTIME`](#_24HENDTIME) in user local time. | | `#_EVENTTIMES_LOCAL` | [`#_EVENTTIMES`](#_EVENTTIMES) in user local time. | | `#_EVENTTIMES_LOCAL{...}` | [`#_EVENTTIMES_LOCAL`](#_EVENTTIMES_LOCAL) but displays custom format by replacing `...` with [documented Moment JS formatting syntax](https://momentjs.com/docs/#/displaying/). | | `#_EVENTDATES_LOCAL` | [`#_EVENTDATES`](#_EVENTDATES) relative to your site timezone (dates can be different for events near midnight in a different timezone). | | `#_EVENTDATES_LOCAL{...}` | [`#_EVENTDATES_LOCAL`](#_EVENTDATES_LOCAL) but displays custom format by replacing `...` with [documented Moment JS formatting syntax](https://momentjs.com/docs/#/displaying/). | #### Links/URLs | Placeholder | Description | |-------------|-------------| | `#_EVENTIMAGEURL` | Shows the event image url, if available. | | `#_EVENTURL` | Simply prints the event URL. You can use this placeholder to build your own customised links. | | `#_EVENTLINK` | Displays the event name with a link to the event page. | | `#_EDITEVENTLINK` | Inserts a link to the admin or buddypress (if activated) edit event page, only if a user is logged in and is allowed to edit the event. | | `#_EDITEVENTURL` | Inserts a url to the admin or buddypress (if activated) edit event page, only if a user is logged in and is allowed to edit the event. | #### Custom Attributes Events Manager allows you to create dynamic attributes to your events, which act as extra information fields for your events (e.g. "Dress Code"). For more information see [our online documentation](http://wp-events-plugin.com/documentation/event-attributes/) for more info on attributes. | Placeholder | Description | |-------------|-------------| | `#_ATT{key}` | This key will appear as an option when adding attributes to your event. | | `#_ATT{key}{alternative text}` | This key will appear as an option when adding attributes to your event. The text in the second braces will appear if the attribute is not defined or left blank for that event. | | `#_ATT{key}{option 1\|option 2\|option 3\|etc.}` | This key will appear as an option when adding attributes to your event. The second braces are optional and will use a select box with these values as input. If no valid value is defined, the first option is used. | #### Bookings These placeholders will only show if bookings are enabled for the given event and in the events manager settings page. Spaces placeholders will default to 0. | Placeholder | Description | |-------------|-------------| | `#_BOOKINGFORM` | Adds a booking forms for this event. | | `#_BOOKINGBUTTON` | A single button that will appear to logged in users, if they click on it a booking will be made. This button will automatically book the first available ticket if more than one ticket exists for the event, and will also circumvent any payment requirements. Use in combination with conditional placeholders such as is_free to avoid unpaid bookings. | | `#_BOOKINGSCUTOFF` | The cut-off date and time, at which point bookings can't be made for the event. | | `#_BOOKINGSCUTOFFDATE` | The cut-off date for bookings of the event. | | `#_BOOKINGSCUTOFFTIME` | The cut-off time for bookings of the event. | | `#_AVAILABLESPACES` | Shows available spaces for the event. | | `#_BOOKEDSPACES` | Shows the amount of currently booked spaces for the event. | | `#_PENDINGSPACES` | Shows the amount of pending spaces for the event. | | `#_UNAVAILABLESPACES` | Shows number of confirmed and reserved spaces, any booked spaces that affect capacity. | | `#_RESERVEDSPACES` | Shows the amount of pending (non-confirmed) spaces that affect capacity for the event. | | `#_SPACES` | Shows the total spaces for the event. | | `#_ATTENDEES` | Shows the list of user avatars attending the event. | | `#_ATTENDEESLIST` | Shows the list of people attending the event. | | `#_ATTENDEESPENDINGLIST` | Shows the list of people with a pending booking for the event. | | `#_BOOKINGSURL` | Shows the url to the admin, front-end or buddypress (if activated) bookings management page for this event. Only shown if user is logged in and able to manage bookings. | | `#_BOOKINGSLINK` | Shows a link to the admin, front-end or buddypress (if activated) bookings management page for this event. Only shown if user is logged in and able to manage bookings. | | `#_EVENTPRICERANGE` | Shows a "maximum - minimum" price range for available tickets at the time of display, or a single price if there is no range. Once bookings are closed this will show a 0 value, if you have enabled 'Show unavailable tickets' in your booking settings these will be included. Price is formatted according to currency formatting in your settings page. | | `#_EVENTPRICERANGEALL` | Like `#_EVENTPRICERANGE` but shows all tickets price range whether or not bookings or individual tickets are available. | | `#_EVENTPRICEMIN` | Shows the lowest available ticket price for this event. Will display a value of 0 if no ticket is available. | | `#_EVENTPRICEMAX` | Shows the highest available ticket price for this event. Will display a value of 0 if no ticket is available. | | `#_EVENTPRICEMINALL` | Shows the lowest ticket price for this event, whether available or not. | | `#_EVENTPRICEMAXALL` | Shows the highest ticket price for this event, whether available or not. | ##### Event RSVP Policies [Pro](http://wp-events-plugin.com/features/) ##### Event RSVP Policies [Pro Feature](http://wp-events-plugin.com/features/) Events Manager Pro allows for setting RSVP policies and endpoints for users to visit and quickly confirm their attendance. > **Tip:** Conditional Placeholders Display this information based whether an event has RSVP enabled via the [`{has_rsvp_policy}`](https://wp-events-plugin.com/conditional-placeholders/#has_rsvp_policy) and similar [RSVP-related conditional placeholders](https://wp-events-plugin.com/conditional-placeholders/#rsvp). | Placeholder | Description | |-------------|-------------| | `#_EVENT_RSVP_DEADLINE_DATE` | Represents the deadline date for an event RSVP, at which point RSVP policy is enforced. | | `#_EVENT_RSVP_DEADLINE_TIME` | Shows the deadline time for an event RSVP, at which point RSVP policy is enforced. | | `#_EVENT_RSVP_DEADLINE_TIMEZONE` | Displays the timezone associated with the event RSVP deadline. | | `#_EVENT_RSVP_POLICY_TYPE` | Type ID of RSVP policy applicable to the event RSVP, such as `open`,`strict`,`flexible`. | | `#_EVENT_RSVP_POLICY_NAME` | Displayable RSPV policy name governing the event, such as `Open`, `Strict`, `Flexible`. | | `#_EVENT_RSVP_POLICY_DESCRIPTION` | Description of the policy applied to the event RSVP. | ##### Waitlists [Pro](http://wp-events-plugin.com/features/) ##### Waitlists [Pro Feature](http://wp-events-plugin.com/features/) Some events may have waitlists enabled, with varying policies, and events fully booked may be displaying waitlist information. > **Tip:** Conditional Placeholders Display this information only if an event has Waitlists enabled via the [`{has_waitlist}`](https://wp-events-plugin.com/conditional-placeholders/#has_waitlist) and similar [RSVP-related conditional placeholders](https://wp-events-plugin.com/conditional-placeholders/#waitlists). | Placeholder | Description | |-------------|-------------| | `#_WAITLIST_EXPIRY` | Represents the number of hours an approved waitlisted booking keeps available spaces reserved. | | `#_WAITLIST_SPACES` | Indicates the maximum number of spaces available to be waitlisted. | | `#_WAITLIST_BOOKING_LIMIT` | The maximum number of spaces per booking allowed on the waitlist for an event. | | `#_WAITLIST_WAITING` | Displays the number of people currently waiting on the waitlist (not including those approved but not yet booked). | | `#_WAITLIST_AVAILABLE` | Shows the number of spaces left to reserve on the waitlist, indicating 'Unlimited' if no limit is set. | | `#_WAITLIST_SPACES_RESERVED` | The number of spaces already reserved under a booking on the waitlist. | | `#_WAITLIST_SPACES_APPROVED` | The number of approved spaces on the waitlist that have not yet been booked. | #### Contact Details The values here are taken from the chosen contact for the specific event, or the default contact in the settings page. | Placeholder | Description | |-------------|-------------| | `#_CONTACTNAME` | Name of the contact person for this event (as shown in the dropdown when adding an event). | | `#_CONTACTUSERNAME` | Contact person's username. | | `#_CONTACTEMAIL` | E-mail of the contact person for this event. | | `#_CONTACTURL` | Website of the contact person for this event. | | `#_CONTACTPHONE` | Phone number of the contact person for this event. Can be set in the user profile page. | | `#_CONTACTAVATAR` | Contact person's avatar. | | `#_CONTACTPROFILELINK` | Contact person's "Profile" link. Only works with BuddyPress enabled. | | `#_CONTACTPROFILEURL` | Contact person's profile url. Only works with BuddyPress enabled. | | `#_CONTACTID` | Contact person's WordPress user ID. | | `#_CONTACTMETA` | Display any user meta of a WordPress account by including the meta key, e.g. `#_CONTACTMETA{dbem_phone}` | #### iCal/Calendar Every event has a unique URL which can be used to add to calendar apps or clients. Most calendar apps will accept the standard iCal format. | Placeholder | Description | |-------------|-------------| | `#_EVENTADDTOCALENDAR` | Displays an 'Add To Calendar' dropdown which users can select from different formats such as iCal, Google, Outlook etc. | | `#_EVENTICALURL` | Displays the URL of the event ical feed (ics file format). | | `#_EVENTICALLINK` | Displays an html link to the event ical feed (ics file format). | ##### 3rd Party Calendars We also have specific links for popular 3rd party apps such as Google Calendar, Office 365 and Outlook Live. | Placeholder | Description | |-------------|-------------| | `#_EVENTGCALURL` | Displays URL which would take the user to Google Calendar and pre-fill their add new event form. | | `#_EVENTGCALLINK` | Displays a button which would take the user to Google Calendar and pre-fill their add new event form. | | `#_EVENTOFFICE365LINK` | Office 365 add-to-calendar link to event, with 'Office 365' link text. | | `#_EVENTOFFICE365URL` | Office 365 add-to-calendar url. | | `#_EVENTOUTLOOKLIVELINK` | Outlook Live add-to-calendar link to event, with 'Outlook Live' link text. | | `#_EVENTOUTLOOKLIVEURL` | Outlook Live add-to-calendar url. | | `#_EVENTWEBCALURL` | [`#_EVENTICALURL`](#_EVENTICALURL), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | | `#_EVENTWEBCALLINK` | [`#_EVENTICALLINK`](#_EVENTICALLINK), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | #### Imported Events Pro #### Imported Events [Pro Feature](http://wp-events-plugin.com/features/) | Placeholder | Description | |-------------|-------------| | `#_EMIOEVENTURL` | The URL of the external imported event. | | `#_EMIOBOOKINGSURL` | Provides a URL where bookings for the event can be made or viewed. | | `#_EMIOBOOKINGSPRICE` | Displays the price for bookings, formatted according to site settings for currency symbols and decimal places. | | `#_EMIOCURRENCY` | Represents the currency used for event bookings, showing the full currency name. | | `#_EMIOCURRENCYSYMBOL` | Shows the currency symbol used for event bookings. | | `#_EMIOSPACES` | Indicates the total number of spaces available for bookings, as provided by the imported data. | | `#_EMIOAVAILABLESPACES` | Displays the number of spaces still available for booking at the current time of import. | | `#_EMIOBOOKEDSPACES` | Shows the number of spaces that have been confirmed as booked at time of import. | ### Location Related Placeholders If an event has a physical location, or if you are showing a location directly the following placeholders can be used. > **Tip:** If you have combinations of events with physical and virtual events, you can make use of our conditional placeholders, such as [`{has_location}`](https://wp-events-plugin.com/conditional-placeholders/#has_location) #### Location Details | Placeholder | Description | |-------------|-------------| | `#_LOCATIONID` | Shows the event ID number in the wp_em_locations table. | | `#_LOCATIONPOSTID` | Shows the location corresponding Post ID in the wp_posts table. | | `#_LOCATIONNAME` | Displays the location name. | | `#_LOCATIONNOTES` | Shows the location description. | | `#_LOCATIONEXCERPT` | If an excerpt has been added to the location, it will be used. If you added a [more tag](http://en.support.wordpress.com/splitting-content/more-tag/) to your location description, only the content before this tag will show. | | `#_LOCATIONEXCERPT{words, ...}` | If an excerpt has not been added to the location, only a specific length is shown, e.g. `#_EVENTEXCERPT{10,...}` where 10 is the number of words to show and ... is what is used at the cut-off point. | | `#_LOCATIONEXCERPTCUT` | [`#_LOCATIONEXCERPT`](#_LOCATIONEXCERPT) (and also accepts the `{words,...}` arguments) but will also cut excerpts as well as post content. Default word limit is 55 and cut-off is `[...]`. | | `#_LOCATIONIMAGE` | Shows the location image. | | `#_LOCATIONIMAGE{x,y}` | Shows the location image thumbnail, x and y are width and height respectively, both being numbers e.g. `#_LOCATIONIMAGE{100,100}`. If 0 is used for either width or height, the corresponding dimension will be proportionally sized. | | `#_LOCATIONIMAGEURL` | Shows the location image url, if available. | | `#_LOCATIONFULLLINE` | Shows a comma-separated line of location information, omitting blanks (format of address, town, state, postcode, region). | | `#_LOCATIONFULLBR` | Shows a line-break (br tag) separated location information, omitting blanks (format of address, town, state, postcode, region). | #### Address Information | Placeholder | Description | |-------------|-------------| | `#_LOCATIONADDRESS` | Displays the address. | | `#_LOCATIONTOWN` | Displays the town. | | `#_LOCATIONSTATE` | Displays the state/county. | | `#_LOCATIONPOSTCODE` | Displays the postcode. | | `#_LOCATIONREGION` | Displays the region. | | `#_LOCATIONCOUNTRY` | Displays the country. | #### Maps and Coordinates | Placeholder | Description | |-------------|-------------| | `#_LOCATIONLONGITUDE` | Displays the longitude, used for locating in Google Maps. | | `#_LOCATIONLATITUDE` | Displays the latitude, used for locating in Google Maps. | | `#_LOCATIONMAP` | Displays a google map showing where the location is located (Will not show if maps are disabled in the settings page). | | `#_LOCATIONMAP{x,y}` | [`#_LOCATIONMAP`](#_LOCATIONMAP) with width and height, in pixels. Height is optional and it also accepts percentages such as `#_LOCATIONMAP{100%,300}` for a full-width map with 300px height. | #### Custom Attributes Events Manager allows you to create dynamic attributes to your locations, which act as extra information fields for your locations (e.g. "Dress Code"). For more information see [our online documentation](http://wp-events-plugin.com/documentation/event-attributes/) for more info on attributes. | Placeholder | Description | |-------------|-------------| | `#_LATT{key}` | This key will appear as an option when adding attributes to your location. | | `#_LATT{key}{alternative text}` | This key will appear as an option when adding attributes to your location. The text in the second braces will appear if the attribute is not defined or left blank for that location. | | `#_LATT{key}{option 1\|option 2\|option 3\|etc.}` | This key will appear as an option when adding attributes to your location. The second braces are optional and will use a select box with these values as input. If no valid value is defined, the first option is used. | #### Links | Placeholder | Description | |-------------|-------------| | `#_LOCATIONURL` | Simply prints the location URL. You can use this placeholder to build your own customised links. | | `#_LOCATIONLINK` | Displays the location name with a link to the location page. | | `#_EDITLOCATIONLINK` | Inserts a link to the admin or buddypress (if activated) edit location page, only if a user is logged in and is allowed to edit the location. | | `#_EDITLOCATIONURL` | Inserts a url to the admin or buddypress (if activated) edit location page, only if a user is logged in and is allowed to edit the location. | #### Related Events You can show lists of other events that are being held at this location. The formatting of the list is the same as a normal events list. | Placeholder | Description | |-------------|-------------| | `#_LOCATIONPASTEVENTS` | Will show a list of all past events at this location. | | `#_LOCATIONNEXTEVENTS` | Will show a list of all future events at this location. | | `#_LOCATIONALLEVENTS` | Will show a list of all events at this location. | | `#_LOCATIONNEXTEVENT` | Will show a link to the next event at this location, or the no events message. | #### iCal/RSS Feeds | Placeholder | Description | |-------------|-------------| | `#_LOCATIONICALURL` | Displays the URL of the location ical feed (ics file format) which shows all events happening at that location. | | `#_LOCATIONICALLINK` | Displays an html link to the event ical feed (ics file format) which shows all events happening at that location. | | `#_LOCATIONWEBCALURL` | [`#_LOCATIONICALURL`](#_LOCATIONICALURL), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | | `#_LOCATIONWEBCALLINK` | [`#_LOCATIONICALLINK`](#_LOCATIONICALLINK), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | | `#_LOCATIONRSSURL` | Displays the URL of an RSS feed showing all upcoming events happening at this location. | | `#_LOCATIONRSSLINK` | Displays an html link to an RSS feed showing all upcoming events happening at this location. | ### Booking Related Placeholders In most cases you should also be able to use event and location placeholders when able to use these, which will show the event and corresponding location that has been booked for. #### Individual Booking Information When a specific booking is displayed (on screen and on email), you can use these placeholders to show specific information about the booking. Event and Location placeholders are also available in these cases. | Placeholder | Description | |-------------|-------------| | `#_BOOKINGID` | The unique ID number for this booking, useful if you are making your own customizations to this plugin. Consider using *#_BOOKING_UUID* to display IDs to users, since booking IDs are just auto-incrementing numbers. | | `#_BOOKING_UUID` | The [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#:~:text=A%20Universally%20Unique%20Identifier%20(UUID,Acronym) of this booking without hyphens, which serves as a more ambiguous alternative to *#_BOOKINGID*. For example, `550e8400e29b41d4a716446655440000` | | `#_BOOKINGNAME` | Name of person who made the booking. | | `#_BOOKINGEMAIL` | Email of person who made the booking. | | `#_BOOKINGPHONE` | Phone number of person who made the booking. | | `#_BOOKINGSPACES` | Number of spaces the person has booked. | | `#_BOOKINGCOMMENT` | Any specific comments made by the person who made the booking. | | `#_BOOKINGSUMMARY` | Shows a breakdown of price/quantity booked by ticket, followed by a summary of price totals, taxes, and other discounts applied. | | `#_BOOKING_STATUS` | Status of the booking, such as `Approved`, `Pending`, `Cancelled`, etc. | #### Custom Booking Forms [Pro](http://wp-events-plugin.com/features/) > **Tip:** Pro Feature These features are available as part of the Booking Form customization features available in [Events Manager Pro](http://wp-events-plugin.com/features/) | Placeholder | Description | |-------------|-------------| | `#_BOOKINGATTENDEES` | Generates a list of attendee information displaying the filled in form data for each attendee (requires individual attendee forms enabled for the event). This list is split by ticket type, then by individual attendee. | | `#_BOOKINGFORMCUSTOMFIELDS` | Generates a list of booking form custom fields that are used in the booking. | | `#_BOOKINGFORMCUSTOM{field_id}` | Shows booking form custom fields. The field_id value must match that of your custom booking form field. | | `#_BOOKINGFORMCUSTOMREG{field_id}` | Shows booking form custom fields that are used for guest user registration. The field_id value must match that of your custom booking form field. | #### Signatures [Pro](http://wp-events-plugin.com/features/) #### Signatures [Pro Feature](http://wp-events-plugin.com/features/) > **Tip:** Conditional Placeholders Wrap this in [`{booking_has_unsigned_signatures}`](https://wp-events-plugin.com/conditional-placeholders/#booking_has_unsigned_signatures) so it disappears from a template once nothing is outstanding. | Placeholder | Description | |-------------|-------------| | `#_BOOKINGSIGNATUREURL` | A secure link where the signer can complete every outstanding [signature field](https://wp-events-plugin.com/forms/fields/signature/signature) on the booking — booking form and each attendee — in a single visit. Resolves to an empty string once nothing is outstanding, so it's safe to leave permanently in a confirmation email or my-bookings template. Requires [Events Manager Pro](http://wp-events-plugin.com/features/). | #### Pricing Display formatting of prices is decided by your settings in *Settings > Bookings > Pricing Options* | Placeholder | Description | |-------------|-------------| | `#_BOOKINGPRICE` | Displays booking total price (tax inclusion depends on your booking settings). | | `#_BOOKINGPRICETAX` | Displays booking total tax. | | `#_BOOKINGPRICEWITHOUTTAX` | Displays booking total without tax. | | `#_BOOKINGPRICEWITHTAX` | Displays booking total with tax. | #### Tickets > **Info:** Important Single ticket placeholders (all below except [`#_BOOKINGTICKETS`](#_BOOKINGTICKETS)), will select the first available ticket in the event of a booking with multiple tickets. | Placeholder | Description | |-------------|-------------| | `#_BOOKINGTICKETS` | Shows a breakdown of tickets and pricing, defined in the `emails/bookingtickets.php` template. (See [Using Template Files](http://wp-events-plugin.com/documentation/using-template-files/) for more information) | | `#_BOOKINGTICKETDESCRIPTION` | Shows the description of the first ticket booked. | | `#_BOOKINGTICKETNAME` | Name of the ticket booked. Useful in single ticket mode, if multiple tickets are booked a random ticket is used. | | `#_BOOKINGTICKETPRICE` | Shows the price of the first ticket booked, tax inclusion depending on your booking settings. | | `#_BOOKINGTICKETPRICEWITHOUTTAX` | Shows the price excluding tax of the first ticket booked. | | `#_BOOKINGTICKETPRICEWITHTAX` | Shows the price including tax of the first ticket booked. | | `#_BOOKINGTICKETTAX` | Shows the tax of the first ticket booked. | ##### QR Codes [Pro](http://wp-events-plugin.com/features/) ##### QR Codes [Pro Feature](http://wp-events-plugin.com/features/) > **Note:** These placeholders can only be used in custom code or overriding templates, when you are looping through bookings and individual ticket spaces. QR codes are automatically output in PDF ticket attachments. | Placeholder | Description | |-------------|-------------| | `#_TICKETBOOKING_QR` | Displays a QR code `img` html element for the ticket booking. | | `#_TICKETBOOKING_QR_URL` | Provides the URL to the QR code image for the ticket booking. | | `#_TICKETBOOKING_BASE64` | Encodes the QR code image for the ticket booking into a Base64 string, suitable for embedding directly into web pages or emails. | #### RSVP > **Tip:** Conditional Placeholders Display this if event has RSVP enabled via the [`{has_rsvp_policy}`](https://wp-events-plugin.com/conditional-placeholders/#has_rsvp_policy) and similar [RSVP-related conditional placeholders](https://wp-events-plugin.com/conditional-placeholders/#rsvp). | Placeholder | Description | |-------------|-------------| | `#_BOOKING_RSVP_STATUS` | The RSVP status of the booking, values are `Unconfirmed`, `Attending`, `Not Attending` | | `#_BOOKING_RSVP_URL` | [Pro](http://wp-events-plugin.com/features/) URL mobile-friendly endpoint users can visit and quickly click the `Attending` or `Not Attending` checkboxes. | #### Waitlists [Pro](http://wp-events-plugin.com/features/) #### Waitlists [Pro Feature](http://wp-events-plugin.com/features/) > **Tip:** Conditional Placeholders Display this information only if an event has Waitlists enabled via the [`{has_waitlist}`](https://wp-events-plugin.com/conditional-placeholders/#has_waitlist) and similar [RSVP-related conditional placeholders](https://wp-events-plugin.com/conditional-placeholders/#waitlists). | Placeholder | Description | |-------------|-------------| | `#_WAITLIST_BOOKING_EXPIRY` | Provides the remaining time before the waitlist booking expires. | | `#_WAITLIST_BOOKING_EXPIRED` | Shows the time remaining if not yet expired or the passed since expiry. | | `#_WAITLIST_BOOKING_AHEAD` | Shows the number of people ahead of the current booking on the waitlist. | | `#_WAITLIST_BOOKING_BEHIND` | Displays the number of reservations behind the current booking on the waitlist. | | `#_WAITLIST_BOOKING_POSITION` | Represents the current booking's position in the waitlist line. | | `#_WAITLIST_BOOKING_SPACES_AHEAD` | Counts the total spaces reserved in bookings ahead of the current one on the waitlist. | | `#_WAITLIST_BOOKING_URL` | Provides the URL for managing the specific waitlist booking, allowing a user to cancel their waitlist. | #### Booking Dates These placeholders refer to when the booking was made by the customer. | Placeholder | Description | |-------------|-------------| | `#_BOOKINGDATE` | The date of the booking. | | `#_BOOKINGDATETIME` | Date and time of the booking. | | `#_BOOKINGTIME` | The time when the booking was made. | #### Links People are able to manage their bookings. Below are some placeholders which automatically provide correctly formatted URLs. | Placeholder | Description | |-------------|-------------| | `#_BOOKINGADMINURL` | URL for admins to view and manage the booking. This should only be used on admin-specific email templates. | | `#_BOOKINGADMINLINK` | HTML link for admins to view and manage the booking. This should only be used on admin-specific email templates. | | `#_BOOKINGLISTURL` | URL to page showing that users booked events. | #### Payments [Pro](http://wp-events-plugin.com/features/) #### Payments [Pro Feature](http://wp-events-plugin.com/features/) Information pertaining to specific gateways. Requires [Events Manager Pro](http://wp-events-plugin.com/features/). | Placeholder | Description | |-------------|-------------| | `#_BOOKINGTXNID` | *Online Payments Only* - Prints the transaction ID of this booking if available. | #### Coupons [Pro](http://wp-events-plugin.com/features/) #### Coupons [Pro Feature](http://wp-events-plugin.com/features/) When a booking has been made with a coupon, you can display coupon information using these placeholders. If no coupon is used, nothing will be shown. Requires [Events Manager Pro](http://wp-events-plugin.com/features/). | Placeholder | Description | |-------------|-------------| | `#_BOOKINGCOUPON` | Displays the coupon code followed by the amount/percentage discounted. | | `#_BOOKINGCOUPONCODE` | Displays the coupon code used. | | `#_BOOKINGCOUPONNAME` | Displays the name given to this coupon. | | `#_BOOKINGCOUPONDISCOUNT` | Displays amount/percentage discounted (e.g. 25% Off). | | `#_BOOKINGCOUPONDESCRIPTION` | Displays the coupon description. | ### Category Placeholders When displaying category lists, or formatting a single category page, you can choose from the following: #### Category Details You can use these when displaying categories or for showing the first available category in an event format. | Placeholder | Description | |-------------|-------------| | `#_CATEGORYNAME` | Shows the category name. | | `#_CATEGORYID` | Shows the category ID. | | `#_CATEGORYSLUG` | Shows the category slug. | | `#_CATEGORYLINK` | Category name with a link to the category page. | | `#_CATEGORYURL` | URL of the category page. | | `#_CATEGORYCOLOR` | Shows the category color (useful for inline styling), in hex format, if no color is defined the default category color from your settings page will be used. | | `#_CATEGORYIMAGE` | Shows the category image, if available. | | `#_CATEGORYIMAGE{x,y}` | Shows the category image thumbnail if available, x and y are width and height respectively, both being numbers e.g. `#_CATEGORYIMAGE{100,100}`. If 0 is used for either width or height, the corresponding dimension will be proportionally sized. | | `#_CATEGORYIMAGEURL` | Shows the category image url, if available. | | `#_CATEGORYNOTES` | Shows the category description. | #### Related Events You can show lists of other events belonging to this category. The formatting of the list is the same as a normal events list. | Placeholder | Description | |-------------|-------------| | `#_CATEGORYPASTEVENTS` | Will show a list of all past events with this category. | | `#_CATEGORYNEXTEVENTS` | Will show a list of all future events with this category. | | `#_CATEGORYALLEVENTS` | Will show a list of all events with this category. | | `#_CATEGORYNEXTEVENT` | Will show the next event with this category. | > **Info:** If you have multiple archetypes, all archetypes are included in the above placeholders. You can add an additional argument to event-listing placeholders to display events of one specific archetype, such as `#_CATEGORYNEXTEVENTS{workshops}` #### iCal/RSS Feeds | Placeholder | Description | |-------------|-------------| | `#_CATEGORYICALURL` | Displays the URL of the event ical feed (ics file format) which shows all events with this category. | | `#_CATEGORYICALLINK` | Displays an html link to the event ical feed (ics file format) which shows all events with this category. | | `#_CATEGORYWEBCALURL` | [`#_CATEGORYICALURL`](#_CATEGORYICALURL), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | | `#_CATEGORYWEBCALLINK` | [`#_CATEGORYICALLINK`](#_CATEGORYICALLINK), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | | `#_CATEGORYRSSURL` | Displays the URL of an RSS feed showing all upcoming events happening in this category. | | `#_CATEGORYRSSLINK` | Displays an html link to an RSS feed showing all upcoming events happening in this category. | ### Tag Placeholders When displaying tag lists, or formatting a single tag page, you can choose from the following: #### Tag Details You can use these when displaying tags or for showing the first available tag in an event format. | Placeholder | Description | |-------------|-------------| | `#_TAGNAME` | Shows the tag name. | | `#_TAGID` | Shows the tag ID. | | `#_TAGSLUG` | Shows the tag slug. | | `#_TAGLINK` | Tag name with a link to the tag page. | | `#_TAGURL` | URL of the tag page. | | `#_TAGNOTES` | Shows the tag description. | | `#_TAGCOLOR` | Shows the tag color (useful for inline styling), in hex format, if no color is defined the default tag color from your settings page will be used. | | `#_TAGIMAGE` | Shows the tag image, if available. | | `#_TAGIMAGE{x,y}` | Shows the tag image thumbnail if available, x and y are width and height respectively, both being numbers e.g. `#_TAGIMAGE{100,100}`. If 0 is used for either width or height, the corresponding dimension will be proportionally sized. | | `#_TAGIMAGEURL` | Shows the tag image url, if available. | #### Related Events You can show lists of other events belonging to this tag. The formatting of the list is the same as a normal events list. | Placeholder | Description | |-------------|-------------| | `#_TAGPASTEVENTS` | Will show a list of all past events with this tag. | | `#_TAGNEXTEVENTS` | Will show a list of all future events with this tag. | | `#_TAGALLEVENTS` | Will show a list of all events with this tag. | | `#_TAGNEXTEVENT` | Will show the next event with this tag. | > **Info:** If you have multiple archetypes, all archetypes are included in the above placeholders. You can add an additional argument to event-listing placeholders to display events of one specific archetype, such as `#_TAGNEXTEVENTS{workshops}` #### iCal/RSS Feeds | Placeholder | Description | |-------------|-------------| | `#_TAGICALURL` | Displays the URL of the event ical feed (ics file format) which shows all events with this tag. | | `#_TAGICALLINK` | Displays an html link to the event ical feed (ics file format) which shows all events with this tag. | | `#_TAGWEBCALURL` | [`#_TAGICALURL`](#_TAGICALURL), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | | `#_TAGWEBCALLINK` | [`#_TAGICALLINK`](#_TAGICALLINK), but using the [webcal:// protocol](https://en.wikipedia.org/wiki/Webcal), which will open up various calendar apps automatically including iCalendar, Outlook and Google Calendar. | | `#_TAGRSSURL` | Displays the URL of an RSS feed showing all upcoming events happening in this tag. | | `#_TAGRSSLINK` | Displays an html link to an RSS feed showing all upcoming events happening in this tag. | ### Conditional Placeholders For those of you asking _“I’d only like to show something IF”_, then you should read up on our [conditional placeholders](http://wp-events-plugin.com/documentation/conditional-placeholders/) too, which works much in the same way as normal placeholders. ### Examples #### Single Event Format If you look at the default events page format, which is found in Events > Settings > Formats/Layouts > Events Format in your admin area: > **Note:** This snippet is redacted to keep this short for demonstration purposes. ```html {has_image} #_EVENTIMAGE{medium} {/has_image} ... #### When #_EVENTDATES     #_EVENTTIMES #_EVENTADDTOCALENDAR ... ... ... {has_location_venue} #_LOCATIONMAP{100%,0} ... ``` this is how it appears on a single event page: [Image: Single Event Placeholder Example] #### Simple Custom Events List Here is an example where you combine shortcodes and placeholders to display customized information about events happening tomorrow. Note that this is pasted into your page content in HTML view of the editor. ```html [events_list scope=”month”]#_EVENTLINK – Dates : #_EVENTDATES, Times : #_EVENTTIMES[/events_list] ``` This is what it would look like: [Image: Placeholder example of events list shortcode with custom placeholders] ## Shortcodes URL: https://wp-events-plugin.com/documentation/shortcodes/ Shortcode is a WordPress-specific code that lets you do nifty things with very little effort. Shortcodes are in this format: ```html [events_list limit="10" location="1"] ``` Arguments are what follow “shortcode” above, where “limit” would be one of the argument names and “10” would be the value of that argument. For more information on shortcodes in WordPress, [see the codex about shortcode](http://codex.wordpress.org/Shortcode). In some cases, you can also include text within a shortcode opening and closing tag, which is used to format the output on your page, e.g. ```html [events_list limit="10" location="1"]#_EVENTNAME [/events_list] ``` Event information can also be displayed through shortcode. Just insert one of the following shortcodes into any of your posts/pages. You can even include shortcode within event and location descriptions! ### Event Shortcodes #### `[events_list]` Displays a list of events. If you enter html and placeholders within the shortcode, each event will be formatted this way (note that you should add your html using the HTML tab of the WordPress content editor). Accepts any of the event, location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). **Example:** ```html [events_list scope="tomorrow" country="US"]#_EVENTLINK will take place at #_LOCATIONLINK on #_EVENTDATES at #_EVENTTIMES[/events_list] ``` The above will display events occurring tomorrow in the United States in a paragraph format. ##### Choosing a view By default the matched events are displayed as a list, but the same search can be displayed as a grid, a map, a calendar or a grouped list by supplying the **view** attribute: | **Attributes** | `Default` | Description | | --- | --- | --- | | **view** | `list` | How the matched events are displayed.`list` - a list of events.`list-grouped` - events split into headed groups by day, week, month or year, see the **mode** and **date_format** attributes of [`[events_list_grouped]`](#events_list_grouped).`grid` - a grid of events, formatted with the grid formats in _Events > Settings > Formatting > Events_.`map` - a map of the events which have a location.`calendar` - a calendar, which also accepts the [calendar parameters](https://wp-events-plugin.com/event-search-attributes/#calendar-parameters). | | **views** | *settings* | Which views a visitor can switch between, as a comma-separated list, e.g. `list,grid,map`. Only applies when **has_search** is enabled. | | **has_search** | `0` | Set to `1` to display a search form above the events, letting visitors filter them and switch between the enabled **views**. Accepts the [search form parameters](https://wp-events-plugin.com/search-form/parameters/). | **Example:** ```html [events_list view="grid" scope="tomorrow" country="US"] ``` `[events_list_grouped]` and `[events_map]` below are shorthand for `[events_list view="list-grouped"]` and `[events_list view="map"]`. #### `[events_list_grouped]` Displays a list of events grouped by a specific time frame (e.g. daily, weekly, monthly, yearly), the equivalent of `[events_list view="list-grouped"]`. If you enter html and placeholders within the shortcode, each event will be formatted this way (note that you should add your html using the HTML tab of the WordPress content editor). Accepts any of the event, location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes") as well as the following: | **Attributes** | `Default` | Description | | --- | --- | --- | | **mode** | `daily` | Decides how to split events up, possible options are : yearly, monthly, weekly, daily. | | **date_format** | dependent on mode | PHP date formatting string for the headers (see [php date() documentation](http://php.net/manual/en/function.date.php) for reference and examples). | **Example:** ```html [events_list_grouped mode="monthly" country="US"] ``` The above will display events grouped by month occurring in the United States and may look like this: [Image: shortcodes-example-events_list_grouped] #### `[event]` Displays a single event. If you enter html and placeholders within the shortcode, the event will be formatted this way (note that you should add your html using the HTML tab of the WordPress content editor). Accepts any of the event, location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). This shortcode requires the _post\_id_ OR _event_ attribute, however, if used within an event description and none of these attributes, it will automatically use the event the description belongs to (useful for showing event placeholders within an event description). **Example:** ```html [event post_id="123"]My selected event is called #_EVENTNAME[/event] ``` This will show the event with post ID 123, and replace #\_EVENTNAME with the name of this event. #### `[event_form]` Displays a form where users can submit event and location information outside the WordPress admin area. You can also assign a page for adding events, locations and managing bookings within _Events > Settings > Pages > Other Pages_ in your WordPress admin area. #### `[event_search_form]` Displays the same search form you see on your default events page. An events page must be selected in _Events > Settings > Pages > Event List/Archives_ in order for this to work properly. #### `[events_link]` Displays a text link which links to the events page. If you add text in between opening and closing shortcode tags, it will become the link text, like so: ```html [events_link]alternate events link text[/events_link] ``` Would become [alternate events link text](#) #### `[events_url]` Displays the events page url (e.g. “http://yoursite.com/events/”). #### `[events_rss_link]` Displays a text link which links to the events RSS page. If you add text in between opening and closing shortcode tags, it will become the link text, like so: ```html [events_rss_link]alternate RSS link text[/events_rss_link] ``` Would become [alternate RSS link text](#) #### `[events_rss_url]` Displays the events RSS url (e.g. “http://yoursite.com/events/rss/”) #### `[events_map]` This is pretty much the same as `[locations_map]` except that it searches for events with locations, rather than locations. Use this instead if you're wanting to search for locations with specific event related filters such as categories, tags or locations with events that are happening during a specific time period. Accepts any of the event, location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). This is the equivalent of `[events_list view="map"]`, and also accepts the **width**, **height** and **map_style** attributes documented under [`[locations_map]`](#locations_map). ### Location Shortcodes #### `[locations_list]` Displays a list of locations. If you enter html and location placeholders within the shortcode, each location will be formatted this way (note that you should add your html using the HTML tab of the WordPress content editor). Accepts any of the event, location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). **Example:** ```html [locations_list eventful="1" scope="tomorrow" country="US"]#_LOCATIONLINK[/locations_list] ``` The above will display location links with events occurring tomorrow in the United States in an unordered list format. ##### Choosing a view As with `[events_list]`, the **view** attribute decides how the matched locations are displayed: | **Attributes** | `Default` | Description | | --- | --- | --- | | **view** | `list` | How the matched locations are displayed. Accepted values are `list`, `grid` and `map`. `[locations_map]` is shorthand for `[locations_list view="map"]`. | | **views** | *settings* | Which views a visitor can switch between, as a comma-separated list, e.g. `list,map`. Only applies when **has_search** is enabled. | | **has_search** | `0` | Set to `1` to display a search form above the locations, letting visitors filter them and switch between the enabled **views**. Accepts the [search form parameters](https://wp-events-plugin.com/search-form/parameters/). | #### `[location]` Displays a single location. If you enter html and location placeholders within the shortcode, the location will be formatted this way (note that you should add your html using the HTML tab of the WordPress content editor). This shortcode requires either the _post\_id_ OR _location_ attribute and also accepts other location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). **Example:** ```html [location post_id="123"]My selected location is called #_LOCATIONNAME[/location] ``` This will show the location with post ID 123, and replace #\_LOCATIONNAME with the name of this location. #### `[locations_map]` Inserts a map of multiple locations. Accepts any of the location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"), as well as these: | **Attributes** | `Default` | Description | | --- | --- | --- | | **width** | `450` | The width in pixels of the map. | | **height** | `300` | The height in pixels of the map. | | **map_style** | | A base64 encoded JSON map style object. See our [maps documentation](https://wp-events-plugin.com/documentation/google-maps/) for styling instructions. | **Example:** ```html [locations_map country="US"] ``` Will show events located in the US, which may look like this: [Image: Using the locations_map shortcode, the balloon appears when you click on a marker (format controlled in your Setings page)] The balloon appears once a marker is clicked on, and the content of the balloon can be configured with placeholders in _Events > Settings > Formats/Templates > Maps and Geotagging_ section of your admin area. ### Category Shortcodes #### `[categories_list]` Displays a list of event categories. If you enter html and category placeholders within the shortcode, each category will be formatted this way (note that you should add your html using the HTML tab of the WordPress content editor). Accepts any of the category and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). as well as $args available to the [WordPress WP_Term_Query](https://developer.wordpress.org/reference/classes/wp_term_query/__construct/). **Example:** ```html [categories_list hide_empty=0]#_CATEGORYLINK[/categories_list] ``` The above will display category links including those without events in an unordered list format. #### `[event_category]` Shows a specific event category. Requires the `category` parameter to define the category to be shown. **Example: ** ```html [event_category category="jazz"]The Jazz Category has these upcoming events: #_CATEGORYNEXTEVENTS[/event_category] ``` ### Tag Shortcodes #### `[tags_list]` Displays a list of event tags. If you enter html and tag placeholders within the shortcode, each tag will be formatted this way (note that you should add your html using the HTML tab of the WordPress content editor). Accepts any of the category and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes"). as well as $args available to the [WordPress WP_Term_Query](https://developer.wordpress.org/reference/classes/wp_term_query/__construct/). **Example:** ```html [categories_list hide_empty=0]#_CATEGORYLINK[/categories_list] ``` The above will display tag links including those without events in an unordered list format. #### `[event_tag]` Shows a specific event tag. Requires the `tag` parameter to define the tag to be shown. **Example:** ```html [event_tag tag="jazz"]The Jazz Tag has these upcoming events: #_TAGNEXTEVENTS[/event_tag] ``` ### Calendar Shortcodes #### `[events_calendar]` Displays a calendar. Accepts any of the [calendar](https://wp-events-plugin.com/event-search-attributes/#calendar-parameters), event, location and general [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/ "Event Search Attributes") (except for the _scope_ attribute) as well as these two: **Example :** ```html [events_calendar long_events=1 full=1 country="US" category="1,2,3,4" year="2025" month="1""] ``` Will show a full-sized calendar displaying events within the US which have a category ID of 1,2,3, or 4 that occur on February 2012 (default starting month will be 02/2012), which may look like this: [Image: Example of the events_calendar shortcode] You can also change how events appear on each calendar day with the **calendar_event_style** attribute (`pill`, `dot`, `dots` or `ring`) — see [Event Display Styles](https://wp-events-plugin.com/calendars/#event-display-styles). For example, `[events_calendar calendar_event_style="dots" limit="3"]` shows up to three category-coloured dots per day, with a `+` when a day has more. ## Search Parameters URL: https://wp-events-plugin.com/documentation/event-search-attributes/ Events Manager uses a consistent set of accepted search parameters which you can pass to various shortcodes, template tags, and core functions that search objects like events and locations. For example, when dealing with locations, you should be able to use most general parameters which are also available when dealing with events. Below is a description of specific parameters and general parameters. ### Data Type Definitions When defining the *Type* of a parameter, we use PHP definitions, and (for you non-coders) can be interpreted as such;
`int` A number
`bool` true or false, `1` or `0`
`string` text of some kind, such as `"some-text-123"`
`mixed[]` A PHP array or comma-separated list containing mixed values such as `array(1,'value',34)` or `"1,value,34"` A single value can also be supplied, such as `1` or `some-value`
`int[]` or `string[]` Same as `mixed[]` but only accepts numbers or strings.
### Parameters #### General Parameters These parameters are shared across all shortcodes and template tags that accept parameters. Some default values have different defaults when used in different contexts (e.g. for locations). For example, `[locations_list]` will obtain **format** default values from settings page `Formatting > Locations > Location List Formats`. `EM_Events::output()` would take **format** from `Formatting > Events > Event List Formats` > **Info:** Note In some contexts these parameters will not make a difference to the returned results. For example, `[event]` will accept parameters such as **format** yet it would not make use of **page**, given it is not outputting a list. | **Parameter** | **Type** | **Default** | **Description** | |-----------------------------------------------------|------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **array** | `bool` | `0` | If you supply this as an argument, the returned data will be in an array, not an object (only useful when using PHP, not shortcodes). | | **language** | `string` | *blog* | Show only items in a specific language. Only useful when combined with a supported multilingual plugin. Currently only WPML is officially supported. | | **limit** | `bool` | `0` | Limits the amount of values returned to this number. Default value may vary depending on context used. | | **no_results_msg** | `string` | *settings* | Text which is displayed in listing functions/shortcodes when there are no results to be shown.Events, locations and taxonomies will have their own default customizable text in the relevant settings page area. | | **offset** | `int` | `0` | For example, if you have ten results, if you set this to `5`, only the last 5 results will be returned. A limit higher than `0` is required for offsets to work. | | **pagination** | `bool` | `0` | When using a function or shortcode that outputs items (e.g. `[events_list]` for events, `[locations_list]` for locations), if the number of items supersede the limit of items to show, setting this to `1` will show page links under the list. | | **page** | `int` | `1` | Which page shall be shown. Requires [**pagination**](#pagination) to be set to `1` and will override the [**offset**](#offset) value if also provided. | | **page_queryvar** | `string` | `pno` | The parameter name used to figure out the page number in a url, provide a unique name if you want to display two lists on the same page with independent pagination. | ##### Display Parameters These parameters decide how matched items are displayed by shortcodes and output functions such as `[events_list]`, `[locations_list]` or `EM_Events::output()`. They do not change which items are returned, only how they are rendered. | **Parameter** | **Type** | **Default** | **Description** | |-----------------------------------------------------|------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **view** | `string` | `list` | How matched items are displayed.**Events**`list` - a list of events.`list-grouped` - events split into headed groups by day, week, month or year, controlled by [**mode**](#mode) and [**date_format**](#date_format).`grid` - a grid of events, using the grid formats from the settings page.`map` - a map of the events which have a location.`calendar` - a calendar, which also accepts the [calendar parameters](#calendar-parameters).**Locations**`list`, `grid`, `map`The `[events_list_grouped]`, `[events_map]` and `[locations_map]` shortcodes are shorthand for the equivalent **view** value. | | **views** | `string[]` | *settings* | Which views a visitor can switch between in the search form, as a comma-delimited string or PHP array, e.g. `list,grid,map`. Only applies when [**has_search**](#has_search) is enabled. See [search form parameters](https://wp-events-plugin.com/search-form/parameters/#views). | | **has_search** | `bool` | `0` | Displays a search form along with the results, letting visitors filter them and switch between the enabled **views**. Accepts the [search form parameters](https://wp-events-plugin.com/search-form/parameters/).Calendars behave differently here, see [**has_search**](#calendar_has_search) under the calendar parameters. | ##### Format Parameters These parameters can be supplied to alter the formatting when used in output functions, such as `EM_Events::output()` or `EM_Locations::output()` > **Warning:** Important Changes As of `6.4.11`, these formatting parameters will not be permitted by default with shortcode, for security purposes. We do not recommend using these for shortcode anymore, because you can included these values before, within and after the shortcode. We have covered this in a specific [shortcode security documentation](https://wp-events-plugin.com/advanced/security/shortcode-security) page. | **Parameter** | **Type** | **Default** | **Description** | |-----------------------------------------------------|------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **format_header** | `string` | *settings* | If you are displaying lists (e.g. listing events), you can supply the header html and placeholders here. | | **format** | `string` | *settings* | If you are displaying some information with the shortcode or function (e.g. listing events), you can supply the html and placeholders here. When providing a custom **format** value, **format_header** and **format_footer** will default to blank if not also provided. | | **format_footer** | `string` | *settings* | If you are displaying lists (e.g. listing events), you can supply the footer html and placeholders here.**Default value:** If the format attribute is not provided, the relevant default format will be taken from the settings page. | ##### General CPT Searches These parameters are limited to Custom Post Types, or content objects, like Locations and Events, which share similar traits such as publish status, visibility etc. When searching for locations, the parameter defined here takes precedence for locations. For example, if searching locations by [**status**](#status), locations with the status parameter will be returned, and vice-versa for events.
**Parameter** **Type** **Default** **Description**
**blog** `int[]` `false` Limit search to events/locations created in a specific blog id or ids. **Default Value:** Current blog ID being viewed, or if the main blog/site all blog events/locations are shown. > **Info:** Only works with MultiSite in [MultiSite Global Mode](https://wp-events-plugin.com/multisite/#global-tables-mode)
**groupby** `string` `null` Group events by a certain type of data. > **Note:** More Info See our [grouping docs](http://localhost:3000/documentation/event-search-attributes/event-location-grouping-ordering/) for more information and examples.
**groupby_orderby** `string[]` `null` Determine ordering of each set of grouped events when [**groupby**](#event-groupby) is set.
**groupby_order** `string` `ASC` Indicates the alphabetical/numerical order of the grouped lists defined by [**groupby**](#event-groupby). Choose between `ASC` (ascending) and `DESC` (descending).
**order** `string` `ASC` Indicates the alphabetical/numerical order of the lists. Choose between `ASC` (ascending) and `DESC` (descending).
**orderby** `string[]` *settings* Choose what fields to order your results by.**Accepted Arguments:** Database table fields, e.g. `event_name` or `location_country,location_town`
**owner** `int[]` `0` User ID(s) to filter events/locations owned by user. Supplying `me` will show events/locations belonging to logged-in user.
**post_id** `int[]` `false` Limit the search to events with the supplied post_id(s).
**private** `bool` *user* `1` includes, `0` excludes private events/locations. If undefined, private events/locations are shown to users with capability to view private events/locations.
**private_only** `bool` `0` Show private events/locations only
**search** `string` Search for events containing provided text within event name, description and location.
**status** `mixed` `publish` Search events with a specific publish status. `1` - Published `0` - Pending `-1` - Draft `null` - Trashed Also accepts : `publish`, `pending`, `draft`, `trash`, `all` *(exc. trashed)*, `everything` *(inc. trashed)*
#### Event Parameters Along with these parameters, you can also use the general parameters and location parameters for filtering by location. This applies to all event-related functions and shortcodes, e.g. [`em_events()`](https://wp-events-plugin.com/template-tags/#em_events), [`[events_list]`](https://wp-events-plugin.com/shortcodes/#events_list), `EM_Events::get()`
**Parameter** **Type** **Default** **Description**
**active** `bool` `null` `1` includes or `0` excludes events with an *Active* status.
**active_status** `mixed` `null` Accepts a single `int` or commma-seprated list of `int` event status values. Negative numbers will exclude. `1` - Active `0` - Cancelled > **Tip:** This setting is useful particularly if you have implemented custom event status types. Otherwise, you could include/exclude active or cancelled events using the [**active**](#active) and [**cancelled**](#cancelled) paremeters.
**bookings** `bool` `null` `1` includes or `0` excludes events with bookings enabled. If `"user"` is supplied, bookings belonging to the current user will be returned.
**cancelled** `mixed` *settings* `1` includes or `0` excludes events with an *Cancelled* status.
**category** `mixed[]` `0` Category IDs or slugs to **include** in the list of searchable tags. Prefix the ID or slug with a minus `-` to **exclude** that category. **Example:** `-jazz,-rock` includes everything *except* rock and jazz
**date_format** `string` *settings* Date format for headings in a grouped list (defined in [**mode**](#mode)). Accepts [PHP date formatting](https://www.php.net/manual/en/datetime.format.php) syntax.
**event** `int[]` `0` Filters list to return only the supplied Event ID(s).
**event_location_type** `string` `0` Event location type, such as `url` or `zoom`, not physical locations.
**location_status** `bool` `0` Search events with locations of a specific publish [**status**](#location-status) value.
**has_event_location** `bool` `0` Search events with non-physical locations, such as a URL or Zoom location.
**has_location** `bool` `0` Search events with a physical location
**header_format** `bool` `0` Header format for group of events in a grouped list (defined in [**mode**](#mode)). Accepts HTML and replaces #s with the date defined by [**date_format**](#date_format), for example ` ### #s `
**location_status** `bool` `0` Search events with locations of a specific publish [**status**](#status)
**mode** `string` `0` Display events in a grouped mode, such as `daily`,`weekly`,`monthly` or `yearly`
**month** `int` Month filter, such as `1`for January, `12` for December
**no_location** `bool` `0` Search events without a physical location
**recurrences** `bool` `null` `1` will only show, `0` will omit events that are part of a recurring pattern, if not set, one-off and recurring events will be shown.
**recurrence** `int` `0` Show a specific set of event recurrences, defined by `recurrence_id`
**recurring** `bool` `null` `1` will show recurring event templates. > **Info:** Important Recurring events are not actual posts/pages for publication, but a template for defining individual recurrences.
**scope** `string[]` *settings* Date or date range for which to search events by. Default value is `future` or preset by settings depending on context shown. **Preset Ranges:** `future` `past` `today`, `tomorrow`, `week`, `this-week`, `month`, `this-month`, `next-month`, `1-months`, `2-months`, `3-months`, `6-months`, `12-months`, `all` **Date Ranges:** `yyyy-mm-dd,yyyy-mm-dd` Searches between these two dates. `yyyy-mm-dd,` Searches from the start date onwards. **Single Dates** `yyyy-mm-dd` Searches a specific date. > **Tip:** You can [create your own event scope](https://wp-events-plugin.com/tutorials/create-your-own-event-scope/) and use it here as well!
**tag** `int` `0` Category IDs or slugs to **include** in the list of searchable tags. Prefix the ID or slug with a minus `-` to **exclude** that category. **Example:** `-jazz,-rock` includes everything *except* rock and jazz
**timezone** `string[]` `false` Events in one or more timezones, for example: `Europe\London`or `Europe\London,Europe\Madrid`. Defaults to the current blog timezone.
**year** `int` *today* Filters events during defined year, defaults to current year, such as `2024`.
#### Location Parameters Along with these parameters, you can also use the general parameters and event parameters for filtering locations according to events. This applies to all location-related functions and shortcodes, e.g. [`em_locations()`](https://wp-events-plugin.com/template-tags/#em_locations), [`[locations_map]`](https://wp-events-plugin.com/shortcodes/#locations_map), `EM_Locations::get()` > **Warning:** Important - Geographical Searches All geographical parameters such as `country`,`town`,`state`,`region` and `postcode` accept comma-delimited or a PHP array of searchable values. Additionally, you can supply negative values (using a minus `-` sign before a value) to exclude items from returned results. For example: `state="NY,FL"` - Searches New York and Florida `country="-DE,-GB"` - Searches all countries **except** Germany and United Kingdom If you mixed positive/negative values in the same search, negatives are ignored, for example; `country="DE,-GB"` - Searches locations in Germany only. Aside from `country`, which is stored in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format, these values are searched as stored in the database, so if you use abbreviations for states, like `NY` for `New York`, search for `NY`
Parameter Type Default Description
**country** `string[]` `false` Filter by locations in supplied country(ies) using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format. Accepts country codes like `US`,`DE` or full names as per blog language, such as `Spain` in an English site. Additionally accepts *negative* exclusions, so for example `-DE,-GB` will show all locations not in Germany and United Kingdom. > **Note:** More Info See our [geographical search notes](#geographical-parameters) above for more info.
**event_status** `bool` `0` Search locations with events of a specific publish [**status**](#status) value.
**eventful** `bool` `0` Locations that have an event associated with it.
**eventless** `bool` `0` Locations without events, [**eventful**](#eventful) takes precedence.
**location** `int[]` `0` Filter by location with the supplied Location ID(s).
**near** `float[]` `0` Latitude, longitude coordinates, supplied like so: `123.123,321.321`
**near_distance** `int` *settings* Numerical distance from [**near**](#near) coordinates, the unit type (kilometers or miles) is defined by [**near_unit**](#near_unit)
**near_unit** `mixed` *settings* Distance unit (`mi` or `km`) defined by [**near_distance**](#near_distance)
**postcode** `string[]` `false` Search locations with or without the supplied postcode(s) > **Note:** More Info See our [geographical search notes](#geographical-parameters) above for more info.
**region** `string[]` `false` Search locations in or not in the supplied region(s) > **Note:** More Info See our [geographical search notes](#geographical-parameters) above for more info.
**state** `string[]` `false` Search locations in or not in the supplied state(s) > **Note:** More Info See our [geographical search notes](#geographical-parameters) above for more info.
**town** `string[]` `false` Search locations in or not in the supplied towns/cities. > **Note:** More Info See our [geographical search notes](#geographical-parameters) above for more info.
#### Category/Tag Parameters Aside from general parameters for lists, see the [WordPress get_terms() Codex](http://codex.wordpress.org/Function_Reference/get_terms) for a list of possible search parameters/arguments. These would be used in shortcodes such as [`[categories_list]`](https://wp-events-plugin.com/shortcodes/#categories_list), [`[tags_list]`](https://wp-events-plugin.com/shortcodes/#tags_list) or PHP functions like `EM_Categories::get()` #### Calendar Parameters Calendar searches are generally used for display purposes, and most of the arguments specific to calendars surround intentions of display. This applies to all calendar-related functions and shortcodes, e.g. `em_calendar()`, `[events_calendar]`, `EM_Calendar::output()`. Some of these search parameters may come in handy in advanced usages too, such as `EM_Calendar::get()` which returns the array of data used to populate a calendar. Along with these parameters, you can also use the [general](#general-parameters), [event](#event-parameters), and [location](#location-parameters) parameters to refine the displayed events on a calendar. > **Info:** There are certain parameters below already described in other sections, however they behave differently for calendars and detailed here. | **Parameter** | **Type** | **Default** | **Description** | |------------------|----------|-------------|------------------------------| | **calendar_size** | `string` | `auto` | Displays calendar in a fixed size if provided a value of `large`, `medium` or `small`, if not defined the calendar will be responsive. | | **has_search** | `bool` | `0` | Displays a search form trigger button, which opens up an advanced search modal. Use **show_search** to display a search form above the calendar. | | **show_search** | `bool` | `0` | If **has_search** is enabled, the search form will be displayed above the calendar, respecting default search form settings unless overriden by [search form parameters](https://wp-events-plugin.com/search-form/parameters/). | | **calendar_event_style** | `string` | `pill` | Choose how events are shown on eventful calendar days.**Accepted Values**`pill` - each event is shown as a labelled pill/bar (default).`dot` - a single coloured dot beneath the date number, with no overflow indicator.`dots` - one coloured dot per event up to the **limit**, then a `+` for any beyond it.`ring` - a coloured ring around the date number. | | **calendar_dates_height** | `string` | `apsect` | Control how rows of dates on the calendar grid auto-adjust height based on content within the whole calendar. **Accepted Values**`even` - height of each row will adjust to match tallest cell/row in entire table.`aspect` - height will match width of cell, unless there is more content and then that row will match tallest cell.`auto` - no restriction, each cell in a row will adjust height to tallest cell in that row. | | **calendar_preview_mode** | `string` | `modal` | Determines how events are previewed when clicking on a specific event in a calendar. Accepted values are `modal`and `tooltips` | | **calendar_preview_mode_date** | `string` | `modal` | Eventful dates will display a modal by default with the list of events, if set to `none` clicking on a date will go straight to event date page with a list of events. | | **calendar_nav** | `bool` | `true` | Displays the navigation elements at the header of the calendar, including month picker, next/previous month and today links. | | **calendar_month_nav** | `bool` | `true` | Displays the month picker at the header of the calendar. Requires **calendar_nav** to also be `true`. | | **calendar_nav_nofollow** | `bool` | `true` | Adds `rel="nofollow"` to the calendar navigation links to prevent unnecessary search engine indexing. | | **limit** | `int` | *settings* | Number of events to return per date, rather than total number of events returned. | | **long_events** | `bool` | `1` | Displays events that span more than one day on each calendar cell where it's active if set to `1`. | | **month** | `string` | | Choose the starting month being displayed on page load, default is today's month, or the first date defined in **scope** | | **number_of_weeks** | `int` | *auto* | Number of weeks to return, if not defined, determined by the month and number of days in the month, this is usually `5`or `6` to allow the weekdays before and after the current month being displayed. | | **scope** | `string` | | Different to the regular [scope](https://wp-events-plugin.com/event-search-attributes/#scope) argument, it only accepts a comma-separated set of dates, or `future`.`future` will default to display the current month with events starting from today. | | **year** | `string` | | Same as **month** but for the year. | | **full** | `bool` | `false` | Shortcut for `calendar_size = "large"` if set to `true`, this paremeter is not recommended anymore and documented for posterity, use **calendar_size** instead. | #### Booking Parameters Booking parameters can be provided specifically to booking PHP functions, such as `EM_Bookings::get()`. There are no shortcodes that expose these parameters due to privacy/security reasons.
**Parameter** **Type** **Default** **Description**
**array** `mixed` `0` If you supply this as `1`, the returned data will be in an array, not an object (only useful when using PHP, not shortcodes) > **Note:** You can also supply an array of column names from the `wp_em_events` and `wp_em_bookings` table to return back, such as `booking_id`, `event_name` etc.
**owner** `int` *conditional* Search by person's bookings > **Warning:** Use with caution, as this can expose confidential data. If not defined, the owner will default to the currently logged in user if the user cannot edit other user events.
**person** `int` `0` Search for bookings belongs to a specific person with their WordPress User ID.
**rsvp_status** `int` `0` Filter by RSVP status of booking, accepts the following values: **Accepted Values** `0` - Not Confirmed `1` - Confirmed `2` - Not Attending
**status** `int` `0` Status of booking, such as confirmed or pending payment. **Accepted Values** `0` - Pending `1` - Confirmed `2` - Rejected `3` - Cancelled `4` - Awaiting Online Payment `5` - Awaiting Offline Payment `6` - Waitlisted
**ticket_id** `int` `0` Filter bookings containing this ticket ID
### Examples This is a shortcode showing a paged list of 10 events that occur tomorrow: ``` [events_list scope=’tomorrow’ limit=10 pagination=1 ][/events_list] ``` This is the equivalent using PHP: ```php echo EM_Events::output(array(‘scope’=>’tomorrow’, ‘limit’=>10, ‘pagination’=>1)); ``` This is a list of locations that have events located in the US tomorrow: ``` [locations_list scope=’tomorrow’ limit=10 pagination=1 eventful=1 country=’US’][/locations_list] ``` This is the equivalent using PHP: ```php echo EM_Locations::output(array(‘scope’=>’tomorrow’, ‘limit’=>10, ‘pagination’=>1, ‘country’=>’US’, ‘eventful’=>1)); ``` ## Search Form Parameters URL: https://wp-events-plugin.com/documentation/search-form/parameters/ The search form provides a powerful set of options to completely customize the look and layout. These options are largely available as settings, but can be overridden completely when displaying directly via shortcode or PHP functions. Below is a comprehensive list of all the accepted attributes you can pass onto a search form display method or component. Components that can display a search form include calendars, events, locations and single search forms. This includes (but not limited to): * [`[events_search_form]`](https://wp-events-plugin.com/shortcodes#events_search_form) * [`[events_list]`](https://wp-events-plugin.com/shortcodes#events_list) * [`[events_list_grouped]`](https://wp-events-plugin.com/shortcodes#events_list_grouped) * [`em_events`](https://wp-events-plugin.com/template-tags/#em_events-args-) * `em_event_search_form()` * [`[events_calendar]`](https://wp-events-plugin.com/shortcodes#events_calendar) * `EM_Calendar::output()` * `em_get_location_search_form` * [`[locations_list]`](https://wp-events-plugin.com/shortcodes#locations_list) * [`[locations_search]`](https://wp-events-plugin.com/shortcodes#locations_search) > **Info:** For parameters with `mixed[]`, `int[]`, and `string[]` type values, can be supplied as comma-delimited lists in shortcode, such as `views="map,calendar"`. Can also be supplied an array if invoked via PHP, both lines below would mean the same. ```php echo EM_Calendar::output( array('views' => array('map','calendar') )); echo EM_Calendar::output( array('views' => "map,calendar" )); // same as an array ``` Single values are also accepted, such as `categories_include="123"` or ```php events_search_form( array('categories_include' => 123 ) ); ``` > **Info:** For parameters with `bool` type values, shortcode would only accept the values `1` or `0` whereas PHP would also accept `true` or `false`. > **Info:** For parameters with *settings* default values, these can be defined in the Events Manager settings page, mostly under the `Formatting > Search Form` section. ### General Options These are options related to the search form in general, and the way results are displayed. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------|--------------------|--------------------|-------------------------------------------------------| | **ajax** | `bool` | `1` | Whether AJAX loading is used, default is defined by the `EM_AJAX_SEARCH` PHP constant, which by default is set to `1` | | **id** | `string` | | Random number to uniquely identify each instance, and is postfixed to class and id names in the search form HTML elements.Define a unique number or word to create a search form with stable IDs for use in CSS/JS customization.For example, `custom` be prefixed to various id and class names, such as `id="search-form-custom"` | | **css_classes** | `string[]` | | Accepts a comma-delimited or PHP array of strings which will be appended to the wrapping HTML element `class` property. | | **saved_searches** | `bool` | `0` | Whether saved searches are enabled, if enabled search settings are saved to browser using cookies. | ### Main Search Form The main search form can be displayed above event/location lists, calendars or on their own. This is an example main search bar: [Image: A main search bar for events] The options below affect the display of the components of the above search bar. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------|--------------------|--------------------|-------------------------------------------------------| | **show_main** | `bool` | *settings* | Whether to show the main search form. It is possible to hide the main search form and only show the advanced search form instead. | | **sorting** | `bool` | *settings* | If the sort button is displayed on the form. | | **search_action** | `string` | `search_events` | *Advanced Usage Only* Action to be performed, submitted during searches to EM backend. Modify in event of advanced customization. | | **search_button** | `string` | *settings* | Text or label for the search button | | **views** | `string[]` | *settings* | Views enabled for the search form, which user can select in search form options. Accepts a comma-delimited string or PHP array. Accepted values are `list`, `list-grouped`, `map`, `grid`, `calendar`**Example:** `list,map,grid` | | **view** | `string` | *settings* | Default view for displaying search results, accepts any value in **views** | #### Search Term This is a text search field, used for searching within event names, descriptions, location info etc. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|------------------------------------------------| | **search_term** | `bool` | *settings* | Show or hide the search term text box. | | **search** | `string` | | Default search term, useful if you would like to populate the form with a default search term. | | **search_term_label** | `string` | *settings* | Placeholder text for the search term input field. | #### Dates (Scope) Displays a date picker when searching events. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|--------------------------------------------------| | **scope** | `string` | | Accepts a [valid scope](https://wp-events-plugin.com/event-search-attributes/#scope) value. Defaults to events search scope in settings. | | **search_scope** | `bool` | *settings* | Show or hide the dates search option in the main form | | **scope_label** | `string` | *settings* | Placeholder label for the dates search input field. | | **scope_seperator** | `string` | *settings* | Separator for dates, for example 12 Dec ` to ` 20 Dec | | **scope_format** | `string` | *settings* | Format for displaying dates within the scope, accepts [JS placeholder formats](https://flatpickr.js.org/formatting/#date-formatting-tokens), `d/m/Y` would be `31/12/2030` | #### Location (GeoLocation) Geolocation involves translating a textual location name into a set of map coordinates (longitude/latitude). > **Warning:** GeoLocation searches requires you to set up [Google Maps API](https://wp-events-plugin.com/google-maps/api-key/) services. It is possible to search for location based on a name which is autocompleted using Google Geolocation Autocomplete services, and obtains a set of coordinates to search for nearby events. The distance searched can also be adjusted via settings below. [Image: An example geolocation search.] Additional search parameters are found in the advanced section, such as the distance radius according to the selected geolocation search. > **Note:** The default distance used to search is based on settings or the **near_unit** and **near_distance** values. If advanced search is enabled along with location search options, these can be overridden in the advanced search options by the user.
**Attribute** **Type** **Default** **Description**
**search_geo** `bool` *settings* Whether geographic search is enabled
**geo** `string` Default geographic search term. > **Info:** This value will not be used unless a user clicks on the input field, and selects a value from the autoselection options. In the screenshot above, if you used `san fr` clicking the search field would show those results immediately without further typing.
**geo_label** `string` *settings* Placeholder label for the geographic search field
**near_unit** `string` *settings* Default unit of distance for proximity search, combined with **near_distance** **Accepted Values :** `mi` or `km`
**near_distance** `integer` *settings* Default distance for proximity search, accepts a numerical value, for example `10` may equate to 10 kilometers if **near_unit** is set to `km`
### Advanced Search The advanced search contains additional search options, such as categories, tags and additional location parameters. This can be displayed in modal form, or inline below the main search form. This can also be displayed instead of the main search form, by supplying **show_main** as `0`. > **Tip:** The advanced search form can contain all the search options from the main bar, and are synced between the two sections. This is particularly useful in situations where just a modal or inline search form options are shown, whilst the main search is hidden. Calendars, for example, can have an advanced search trigger next to the month selection and bring up a modal set of search options, rather than having a search bar above it.
**Attribute** **Type** **Default** **Description**
**show_advanced** `bool` *settings* Whether to show advanced search options, default is based on settings and other conditions.
**advanced_mode** `bool` *settings* Mode or style of the advanced search area which can be `inline` or `modal`. > **Note:** If **show_main** or **advanced_trigger** are set to `0` this value will always be set to `inline`, since there is no way to trigger opening a modal.
**advanced_hidden** `bool` *settings* Whether advanced search options is hidden by default. > **Note:** If **show_main** or **advanced_trigger** are set to `0` this value will always be set to `1`, since there is no way to trigger showing hidden options.
**advanced_trigger** `bool` *settings* Whether a trigger icon is displayed in main search form. Defaults to `1` if advanced search is enabled but hidden.
**search_advanced_style** `string` `accordion` Style of the advanced search dropdowns, which will either show as a collapsible `accordion` or a dropdown-style `multiselect` without any collapsible accordion.
**search_multiselect_style** `string` *settings* Style for multiselect dropdowns, can be used in combination with **search_advanced_style** so that `multiselect` dropdowns are displayed but still collapsed within an accordion.
#### Dates (Scope) Same as the dates search option in the [main search form](#main-search-form). > **Tip:** The date search options are synced between the main and advanced forms, so if a user selects a date range in the advanced form, it will also show up in the main search form if both are set to be shown. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|--------------------------------------------------| | **search_scope_advanced** | `bool` | *settings* | Whether scope options are displayed in advanced settings | | **scope_label_advanced** | `string` | *settings* | Label for the advanced dates search field | | **scope_seperator_advanced** | `string` | *settings* | Separator for dates, for example 12 Dec ` to ` 20 Dec | | **scope_format_advanced** | `string` | *settings* | Format for displaying dates within the scope, accepts [JS placeholder formats](https://flatpickr.js.org/formatting/#date-formatting-tokens), `d/m/Y` would be `31/12/2030` | #### Categories > **Note:** The way tags selections are displayed is controlled by the **search_advanced_style** and the **search_multiselect_style** | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|--------------------------------------------| | **category** | `integer` | `0` | Default category term | | **search_categories** | `bool` | *settings* | Whether category search is enabled | | **category_label** | `string` | *settings* | Label for the category search field | | **categories_label** | `string` | *settings* | Default label for categories select | | **categories_placeholder** | `string` | *settings* | Placeholder text for advanced category search | | **categories_clear_text** | `string` | `"Clear Selected"` | Text for clearing selected categories | | **categories_count_text** | `string` | `"%d Selected"` | Text displaying count of selected categories | | **categories_include** | `mixed[]` | *settings* | Category IDs or slugs to *include* in the list of searchable tags. For example, `jazz,123,rock`. | | **categories_exclude** | `mixed[]` | *settings* | Category IDs or slugs to *exclude* in the list of available tags. For example, `jazz,123,rock`. | #### Tags > **Note:** The way tags selections are displayed is controlled by the **search_advanced_style** and the **search_multiselect_style** | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|--------------------------------------------| | **search_tags** | `bool` | *settings* | Whether to display the tag search option. | | **tag** | `mixed[]` | `0` | Default tag term(s) to be used in searches. Accepts term IDs or slugs | | **tag_label** | `string` | *settings* | Text Label for the tag search field. | | **tags_label** | `string` | *settings* | Default text label for tags select box, default setting is "All Tags" | | **tags_placeholder** | `string` | *settings* | Placeholder text for the tag filter search box, used to find the tag(s) to filter searches with. | | **tags_clear_text** | `string` | `Clear Selected` | Text for clearing selected tags | | **tags_count_text** | `string` | `%d Selected` | Text displaying count of selected tags | | **tags_include** | `mixed[]` | *settings* | Tag IDs or slugs to *include* in the list of searchable tags. For example, `jazz,123,rock`. | | **tags_exclude** | `mixed[]` | *settings* | Tag IDs or slugs to *exclude* in the list of available tags. For example, `jazz,123,rock`. | #### Location User can search and select geographical or geolocation filtering options. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|--------------------------------------------| | **search_geo_advanced** | `bool` | *settings* | Whether geolocation search is shown in advanced settings, | | **geo_label_advanced** | `string` | *settings* | Label for the advanced geographic/geolocation search option fields. | ##### Geolocation Options Geolocation searches are based on autocompletion of a searched place via the Google search service, which correlates to a set of geographical coordinates, as defined in the [main search geolocation](#location-geolocation) options. > **Info:** The geolocation search options are dependent on the geolocation search input, which can be present at the top of the advanced search form and/or within the main search form. Once a geolocation is selected, proximity options will be displayed instead of geographical search options such as town, country etc. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|--------------------------------------------| | **near_unit** | `string` | *settings* | Default unit of distance for proximity search, combined with **near_distance**, accepts `mi`or `km`| | **near_distance** | `integer` | *settings* | Default distance for proximity search, accepts a numerical value, for example `10` may equate to 10 kilometers if **near_unit** is set to `km`| | **search_geo_units** | `string` | *settings* | Unit for geographic search | | **geo_units_label** | `string` | *settings* | Label for the geographic units field | | **near** | `string` | | Default proximity search parameters | | **geo_distance_values** | `int[]` | *settings* | Possible distance values for proximity search | ##### Geographic Search Options Geographic searches are input fields such as city/town, region, country etc. > **Info:** When a dropdown field is selected, other dropdown fields are filtered to provide the available locations with subsequent options. For example, if you choose a country such as *United Kingdom*, only towns, regions, states within that country will be available for choosing, if none exist then only the 'All' option remains available. | **Attribute** | **Type** | **Default** | **Description** | |----------------------------------------|--------------------|--------------------|--------------------------------------------| | **search_countries** | `bool` | *settings* | Whether country search dropdown is displayed. | | **country** | `string` | *settings* | Default country pre-selected in dropdown, default value taken from settings page. | | **country_label** | `string` | *settings* | Label for the country search field | | **countries_label** | `string` | *settings* | Default label for countries select dropdown options, equivalent to `All Countries`| | **search_regions** | `bool` | *settings* | Whether region search dropdown field is enabled | | **region** | `string` | `""` | Default region pre-selected in dropdown. | | **region_label** | `string` | *settings* | Label for the region search dropdown field. | | **search_states** | `bool` | *settings* | Whether state search is enabled | | **state** | `string` | `""` | Default state pre-selected in dropdown | | **state_label** | `string` | *settings* | Label for the state search field | | **search_towns** | `bool` | *settings* | Whether town search is enabled | | **town** | `string` | `""` | Default town pre-selected in dropdown | | **town_label** | `string` | *settings* | Label for the town search field | ## Conditional Placeholders URL: https://wp-events-plugin.com/documentation/conditional-placeholders/ The use of [formats and placeholders](https://wp-events-plugin.com/placeholders/) in Events Manager makes formatting the look of your events very easy even for users with limited HTML knowledge. When events are output by Events Manager, it will also check for tags of `{this}...{/this}` format within a page that accepts placeholders, which is just like HTML elements but with curly braces. Each conditional placeholder will evaluate to `true` or `false`, if `true` the content within the conditional placeholder, such as `...` in the example above, will be shown, otherwise it is hidden. For example, you can decide to show a default image if the event doesn't have a set featured image like so: ```html {has_image}#_EVENTIMAGE{/has_image} {no_image}[Image: #_EVENTNAME - Default Image]{/no_image} ``` > **Note:** Suggestions If there are any conditional placeholders you feel are missing, feel free to suggest them! We'll be regularly expanding this list, so if it's useful to others we'll probably add it at some point. You are also able to create your own conditional tags very easily with a little PHP knowledge and our [conditional placeholder tutorial](http://wp-events-plugin.com/tutorials/creating-conditional-placeholders-for-events/ "Creating Conditional Placeholders for Events"). ### Events These placeholders can be used anywhere normal event placeholders can be used. Content will only be displayed if the condition is met, otherwise the whole placeholder will be omitted. > **Note:** You can also use specific [Tag](#tags), [Category](#categories) and [Location](#locations) conditional placeholders, in cases of tags and categories, the first category/tag will be used for testing conditions. #### General | Placeholder | Description | | --- | --- | | `has_att_X` [ | Event **has** a specific custom field named `X`. Spaces should be replaced with `_` underscores, for example `{has_att_More_Information}` for `More Information`. | | `no_att_X` | Event **does not have** a specific custom field named `X`. See [has_att_X](#has_att_X) for `X` info. | | `has_image` | Event **has** a featured image. | | `no_image` | Event **does not have** a featured image. | | `is_active` | Event has a status of **is** active. | | `is_cancelled` | Event has a status of **is** cancelled. | | `is_private` | Event **is** marked as private. | | `not_private` | Event **is not** marked as private. | | `is_recurrence` | Event **is** part of a recurring set. | | `not_recurrence` | Event **is not** part of a recurring set, meaning it is a single, normal event. | #### Event Times | Placeholder | Description | | --- | --- | | `all_day` | Event **is** an all-day event (regardless of start/end times). | | `different_timezone` | Event's timezone **is different** from the blog timezone. | | `same_timezone` | Event's timezone **is the same** as the blog timezone. | | `has_time` | Event **is not** an all-day event and **does not** have the same start/end times. | | `no_time` | Event **is not** an all-day event and **does have** the same start/end times. | | `is_current` | Event **is** currently happening (according to the timezone of your WordPress site). | | `is_future` | Event **is** in the future. | | `is_long` | Event **lasts longer** than one day (i.e., ends on different dates). | | `not_long` | Event **does not last longer** than one day (i.e., same day events). | | `is_past` | Event **is** in the past. | | `not_all_day` | Event **is not** an all-day event. | #### Bookings | Placeholder | Description | | --- | --- | | `bookings_closed` | Event **has** bookings enabled and spaces **are not** available for the current user viewing the page. | | `bookings_open` | Event **has** bookings enabled and spaces **are** available for the current user viewing the page. | | `fully_booked` | Event **has** bookings enabled and spaces **are not** available. This does not take into account whether the user currently viewing the event can book any of those spaces (for example, there are member only tickets and a guest is viewing). | | `has_bookings` | Event **has** bookings enabled (regardless of space availability). | | `no_bookings` | Event **does not** have bookings enabled (will not show for events with bookings enabled but not available for booking, e.g. if fully booked or bookings are closed). | | `has_spaces` | Event **has** bookings enabled and spaces **are** available. This does not take into account whether the user currently viewing the event can book any of those spaces (for example, there are member only tickets and a guest is viewing). | | `is_free` | Event **is** free, meaning there is no ticket with a price greater than 0. | | `is_free_now` | Event **is** free **at the time of viewing**, meaning there is no available ticket with a price greater than 0 at that specific time. | | `is_user_attendee` | Logged in user **has** a booking for the event. The booking can be of any status, if you'd like to restrict content to users with a booking of a specific status, you can add the status to the conditional placeholder with the status number (for example, pending is 0, confirmed is 1) like so: `{is_user_attendee_1}content{is_user_attendee_1}`. | | `not_free` | Event **is not** free, meaning there is a ticket with a price greater than 0. | | `not_free_now` | Event **is not** free **at the time of viewing**, meaning there is an available ticket with a price greater than 0 at that specific time. | | `not_user_attendee` | Logged in user **does not have** a booking for the event. The booking can be of any status, if you'd like to restrict content to users with a booking of a specific status, you can add the status to the conditional placeholder with the status number (for example, pending is 0, confirmed is 1) like so: `{is_user_attendee_1}content{is_user_attendee_1}`. | #### RSVP Policies Pro #### RSVP Policies [Pro Feature](http://wp-events-plugin.com/features/) | Placeholder | Description | | --- | --- | | `has_rsvp_reply` | Booking **has** an RSVP reply. | | `no_rsvp_reply` | Booking **does not have** an RSVP reply. | | `is_rsvp_reply_X` | Booking RSVP reply **is** a specific value (e.g., `is_rsvp_reply_0` for "No", `is_rsvp_reply_1` for "Yes"). | | `is_rsvp_reply_maybe` | Booking RSVP reply **is** "Maybe". | | `is_rsvp_reply_no` | Booking RSVP reply **is** "No". | | `is_rsvp_reply_yes` | Booking RSVP reply **is** "Yes". | #### Waitlist Pro #### Waitlist [Pro Feature](http://wp-events-plugin.com/features/) | Placeholder | Description | | --- | --- | | `has_waitlist` | Event **has** a waitlist enabled. | | `no_waitlist` | Event **does not have** a waitlist enabled. | | `has_waitlist_booking_limit` | Event **allows** booking a limited number of spaces on the waitlist. | | `no_waitlist_booking_limit` | Event **does not limit** the number of spaces to book per booking on the waitlist. | | `has_waitlist_expiry` | Event waitlist bookings **have** an expiry time. | | `no_waitlist_expiry` | Event waitlist bookings **do not have** an expiry time. | | `has_waitlist_limit` | Event **has** a limited number of spaces for the waitlist. | | `no_waitlist_limit` | Event **does not have** a limited number of spaces for the waitlist. | | `waitlist_closed` | Event waitlist **is closed** to reservations. | | `waitlist_full` | Event waitlist **is enabled and full**. | | `waitlist_open` | Event waitlist **is open** for reservations. | #### Categories and Tags | Placeholder | Description | | --- | --- | | `has_category` | Event **has** one or more categories. | | `no_category` | Event **does not have** one or more categories. | | `has_category_X` | Event **has** a category with a term name, id or slug of value 'X'. Replace X with whatever category you are searching for. You can also add multiple categories, separated by commas like so, `has_category_X,Y,Z...{/has_category_X,Y,Z}`. | | `no_category_X` | Event **does not have** a category with a term name, id or slug of value 'X'. Replace X with whatever category you are searching for. You can also add multiple categories, separated by commas like so: `no_category_X,Y,Z...{no_category_X,Y,Z}`. | | `has_tag_X` | Event **has** a tag with a term name, id or slug of value 'X'. Replace X with whatever tag you are searching for. You can also add multiple tags, separated by commas like so: `has_tag_X,Y,Z...{has_tag_X,Y,Z}`. | | `no_tag_X` | Event **does not have** a tag with a term name, id or slug of value 'X'. Replace X with whatever tag you are searching for. You can also add multiple tags, separated by commas like so: `no_tag_X,Y,Z...{no_tag_X,Y,Z}`. | | `has_taxonomy` | Event **has** at least one tag or category associated. | | `no_taxonomy` | Event **does not have** at least one tag or category associated. | #### Locations | Placeholder | Description | | --- | --- | | `has_event_location` | Event **has** a valid event (**non-physical**) location. | | `no_event_location` | Event **does not have** a valid event (**non-physical**) location. | | `has_location` | Event **has** a location. | | `no_location` | Event **does not have** a location. | | `has_location_venue` | Event **has** a valid **physical** location. | | `no_location_venue` | Event **does not have** a valid **physical** location. | ### Tags | Placeholder | Description | | --- | --- | | `has_tag_image` | tag **has** an image associated with it. | | `no_tag_image` | tag **does not have** an image associated with it. | ### Categories | Placeholder | Description | | --- | --- | | `has_category_image` | category **has** an image associated with it. | | `no_category_image` | category **does not have** an image associated with it. | ### Taxonomies (Tags and Categories) The following conditional placeholders can be used for tags, categories or any (custom extended taxonomy)[/tutorials/using-additional-custom-taxonomies/]. | Placeholder | Description | | --- | --- | | `has_events` | taxonomy **has** upcoming events associated with it. | | `no_events` | taxonomy **does not have** upcoming events associated with it. | | `has_events_X` | taxonomy **has** upcoming events of a specific X archetype associated with it. | | `no_events_X` | taxonomy **does not have** upcoming events of a specific X archetype associated with it. | ### Bookings > **Info:** You can use [Event](#event) and all related conditional placeholders with regards to a booking, this will refer to the event booked. > **Warning:** This may not work as expected if you have enabled [Multiple Bookings Mode](https://wp-events-plugin.com/multiple-booking-mode/) the booking is a multiple booking event. You can use the [`not_multi_booking`](#not_multi_booking) to wrap event conditionals in this situation. #### RSVP | Placeholder | Description | | --- | --- | | `has_rsvp_reply` | Booking **has** an RSVP reply. | | `no_rsvp_reply` | Booking **does not have** an RSVP reply. | | `is_rsvp_reply_X` | Booking RSVP reply **is** a specific value (e.g., `is_rsvp_reply_0` for "No", `is_rsvp_reply_1` for "Yes"). | | `is_rsvp_reply_maybe` | Booking RSVP reply **is** "Maybe". | | `is_rsvp_reply_no` | Booking RSVP reply **is** "No". | | `is_rsvp_reply_yes` | Booking RSVP reply **is** "Yes". | #### Waitlist Pro #### Waitlist [Pro Feature](http://wp-events-plugin.com/features/) | Placeholder | Description | | --- | --- | | `is_waitlist` | Booking **is** on the waitlist or has a booking status of 6, 7, or 8. | | `not_waitlist` | Booking **is not** on the waitlist. | #### Signatures Pro #### Signatures [Pro Feature](http://wp-events-plugin.com/features/) | Placeholder | Description | | --- | --- | | `booking_has_unsigned_signatures` | Booking **has** at least one outstanding [signature field](https://wp-events-plugin.com/forms/fields/signature/signature) — on the booking form or any attendee form — still unsigned. | | `booking_no_unsigned_signatures` | Booking **does not have** any outstanding signature fields; everything required has been signed. | #### Multiple Bookings Pro #### Multiple Bookings [Pro Feature](http://wp-events-plugin.com/features/) | Placeholder | Description | | --- | --- | | `is_in_multi_booking` | Booking **is part of** a multiple booking. | | `not_in_multi_booking` | Booking **is not part of** a multiple booking. | | `is_multi_booking` | Booking **is** a multiple booking. | | `not_multi_booking` | Booking **is not** a multiple booking. | ### Locations | Placeholder | Description | | --- | --- | | `has_events` | Placeholder for locations that have events. | | `no_events` | Placeholder for locations that do not have events. | | `has_loc_image` | Placeholder for locations that have an image. | | `no_loc_image` | Placeholder for locations that do not have an image. | ### Imported Events/Locations Pro #### Waitlist [Pro Feature](http://wp-events-plugin.com/features/) > **Info:** Dynamic Data Some dynamic data such as prices and spaces booked are accurate from time of import or syncing. These conditionals will still equate to `true` a zero-value is provided, since for example an event may be free and marked as $`0` | Placeholder | Description | | --- | --- | | `is_imported` | Item **was imported** by EM I/O. | | `not_imported` | Item **was not imported** by EM I/O. | | `is_imported_X` | Item **was imported** by a specific format source (replace `X` with the source such as `ical`). | | `not_imported_X` | Item **was not imported** by a specific format source (replace `X` with the source such as `ical`). | | `imported_is_public` | Item **was imported** and **is publicly available** at the source. | | `imported_is_private` | Item **was imported** and **visibility is restricted** at the source. | #### Event-Specific Imports | Placeholder | Description | | --- | --- | | `has_bookings_confirmed` | Event **has** booking confirmed spaces defined at import. | | `no_bookings_confirmed` | Event **does not have** booking confirmed spaces defined at import. | | `has_bookings_price` | Event **has** a booking price defined. | | `no_bookings_price` | Event **does not have** a booking price defined at import. | | `has_bookings_spaces` | Event **has** booking spaces defined at import. | | `no_bookings_spaces` | Event **does not have** booking spaces defined at import. | | `has_bookings_url` | Event **has** an external URL for bookings. | | `no_bookings_url` | Event **does not have** an external URL for bookings. | | `has_event_url` | Event **has** an external event URL. | | `no_event_url` | Event **does not have** an external event URL. | ### Other | Placeholder | Description | | --- | --- | | `logged_in` | user **is** logged in. | | `not_logged_in` | user **is not** logged in. | ### Nesting Conditional Placeholders It is possible to use conditional placeholders within each other. However, by default Events Manager will only go one level deep, meaning it won't check conditional placeholders within conditional placeholders. This is due to the extra processing required to achieve such behaviour. In order to enable further levels of nesting, you need to add a line of PHP to your wp-config.php file: ```php define('EM_CONDITIONAL_RECURSIONS',2); ``` The example above will go `2` levels down, meaning you could nest conditional placeholders within another conditional placeholder. If you wanted to nest one inside the nested placeholder, then you need to increase that number to `3`. #### Nesting Example Here is an example of nested conditional placeholders, `2`levels deep. It will show certain content for members or guests for events that have a tag called `private`: ```html {has_tag_private} {logged_in} Here's some more information ... {/logged_in} {not_logged_in} For more info ... log in](#has_att_X)! {/not_logged_in} {/has_tag_private} ``` ## Automated Emails URL: https://wp-events-plugin.com/documentation/automated-emails/ When interacting with events manager, there's various instances that users and admins will receive email notifications. You can configure these emails and add extra information using [placeholders](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders"). Your booking email templates and sending settings can be accessed from your settings page under the Email Settings tab. [Image: Your Emails tab under Events > Settings in your admin menu.] Under this tab, you'll find various panels (if using MultiSite, Email Settings will be in your network admin settings page) including: - [Booking Email Templates](#booking-emails) - [Event Submission Templates](#event-submission) - [Event Reminders (pro)](#event-reminders) Before continuing, make sure you've configured your [mail settings](https://wp-events-plugin.com/documentation/mail-settings/ "Mail Settings") which is in this same tab, first panel. ### Booking Emails These are the emails sent to users and event admins when bookings are made, modified or cancelled. All of these email formats can use  [Booking Related Placeholders](https://wp-events-plugin.com/documentation/placeholders/#booking-placeholders "Booking Placeholders"), [Event Related Placeholders](https://wp-events-plugin.com/documentation/placeholders/#booking-placeholders#event-placeholders "Event Placeholders") and [Location Related Placeholders](https://wp-events-plugin.com/documentation/placeholders/#booking-placeholders#location-placeholders "Location Placeholders") placeholders. If you would like to prevent any of these emails from being sent out, if you leave the subject blank, it will be ignored. #### Sending Settings The first section of the booking email templates panel is concerned with who to send these emails to. You can choose whether to: - Email the owner (contact person) of the event. - Send all new booking notifications to one or more admins. - Disable the user registration email, which is sent to the user when a new account is created with their username and password. #### Admin Emails Admins and event owners  will receive emails in three occasions: - If a booking is pending manual payment or approval. - If a user cancels their booking. - If a user has been successfully booked without manual approval. #### Attendee Emails When a user makes a booking for an event, they will receive emails in these situations: - The user has placed a booking. What gets sent depends on whether the booking is pending approval or confirmed. - Rejected or Cancelled bookings. - The status of the booking has been changed by an admin or as a result of an automatic payment. ### Event Submission Emails When users without publishing permissions submit an event, it is held for approval. An administrator email must be entered in order to start receiving these notifications. #### Admin Emails Administrators will be notified when an event is submitted or re-submitted for modification. #### Submitter Emails Submitters will receive an email when the event is approved or re-approved. ### Custom Booking Emails for Events and Gateways _(pro)_ You can also modify the emails sent for bookings to specific events and using specific gateways with our [custom booking email templates](https://wp-events-plugin.com/documentation/custom-booking-email-templates/ "Custom Booking Email Templates") feature. ### Event Reminders _(pro)_ When users make a booking, you can choose to send users attending your events a reminder email x days before the event starts. Events Manager will check upcoming events on a daily basis and send attendees emails. As with booking emails, you can also use the same set of placeholders. ## Google Maps URL: https://wp-events-plugin.com/documentation/google-maps/ > _Google Maps has limited free usage quotas/limits, if you go over this usage value, you will be billed for service usage. See [our recent announcement](http://wp-events-plugin.com/blog/2018/07/17/google-maps-api-pricing-increases/) for more information about the new pricing changes for Google Maps API._ When you add or edit locations, a Google map should appear and adjust itself automatically as you fill out the location information. The information you type is sent to the Google Maps API which automatically determines your location coordinates on the map, so try and enter as much accurate information as possible (e.g. address, town, country). Once you fill in your information, you can also drag the position marker on the map to pinpoint the exact location if needed. Then, you need to add a #\_LOCATIONMAP [placeholder](https://wp-events-plugin.com/documentation/placeholders/ "Placeholders") in one of the format options in the settings page wherever you would like to show your map. By default, maps are set to show on Location and Event pages. ### Setup Instructions #### 1\. [Set up your Google Cloud Platform Account](https://wp-events-plugin.com/documentation/google-maps/api-key/) You will need to sign up for a new Google API account (if you don't have one already), enable certain API libraries and obtain an API key to display maps on your site. See our [setup instructions](https://wp-events-plugin.com/documentation/google-maps/api-key/). #### 2\. Enable Google Maps for your site To enable/disable maps in Events Manager, go to _Events > Settings > Google Maps & Location Services_ in the admin panel and set _Enable Google Maps integration?_ as needed. You must also enter the API Browser Key you obtained whilst setting up your Google API Account in Step 1. #### 3\. Optimize and Manage your API Usage The Google Maps API is not free, although there is a monthly free usage allowance in the form of a $200 credit. It's important that you learn how to optimize and manage your API usage to minimize your usage costs. Please read up on [our new map load types](https://wp-events-plugin.com/documentation/google-maps/map-types/), [what APIs we use](https://wp-events-plugin.com/documentation/google-maps/api-usage/) and [how to optimize API usage](https://wp-events-plugin.com/documentation/google-maps/api-usage-management/). ### Further Configuration You can edit the balloon content for dynamic maps in _Events > Settings > Formatting > Maps_.  There are two different balloons you can customize, one being the balloon shown on a single location map, and the other is the balloons shown when viewing the global map which displays multiple locations at once. You can also set the default width and height of maps, which can be in pixels or percentage. ### Map Styling Customize the styles of your maps by visiting _Events > Settings > Formatting > Maps > Google Maps Style_ and entering a JSON style format. You can give your maps a unique look to stand out or match the style of your site, here's an example: Google Maps JSON styles can be created from [Google's Map Style Wizard](https://mapstyle.withgoogle.com/) or a service like [Snazzy Maps](https://snazzymaps.com/explore) which has a library of free templates as well as a custom style builder. On both of these sites, you can copy their generated JSON code to your clipboard, and then paste it into the _Google Maps Style_ text box. Additionally, you can provide custom styles to specific maps generated with the _events\_map_ and _locations\_map_ shortcodes. This can be done by supplying a base64 encoded version of JSON code within the _map\_style_ attribute. This requires an extra step of encoding your JSON code, there's plenty of free online encoders such as this one: https://www.base64encode.org/ Your shortcode would look similar to this: \[_locations\_map width="100%" map\_style="Ww0KICB7DQogIC....ogIH0NCl0="_\] ### Known Issues If you have Google Maps deactivated, but then decide to reactivate in the future, you need to revisit the locations you created whilst maps was deactivated and save them again. When you open locations with Google Maps enabled it should automatically detect your address even if coordinates weren't previously saved. #### Maps will not load and/or I see an exclamation mark as below: [Image: maps-api-key-error]This means that you need to add your API key, or you have not properly configured one. Please follow our instructions for [adding a Google Maps API Key](https://wp-events-plugin.com/documentation/google-maps/api-key/). This may also happen if your theme or another plugin loads a Google Maps library before us without adding an API key to their settings. Since we can't load the library twice, the original loading plugin or theme needs to allow for API keys to be used too. To verify this, once you've gone through all the troubleshooting steps to add your API key to our settings page and it's still not working, try loading your site with a default WP theme and other plugins disabled as well. For example, the Divi theme also [has a setting to add your Google API key](https://www.elegantthemes.com/blog/tips-tricks/google-maps-api-key), and copying the key used for Events Manager into their settings will fix the issue. #### When adding a new location, the map shows a grey Loading Map… that doesn't go away. What's wrong? Most likely you have a javascript issue, and most commonly it's one of three things: - Your theme has some bad javascript that breaks the rest and prevents Google Maps from loading - You have a plugin that's conflicting with ours or breaking javascript like above - Your theme does not use the [wp\_head](http://codex.wordpress.org/Function_Reference/wp_head) function, and so the required javascript isn't being loaded. #### My the position on the map is not correct. When entering an address, if the map doesn't find it, try writing the address differently. Events Manager takes your address + town + state + postcode + country and submits it to Google for a location. If your address works on [maps.google.com](http://maps.google.com) then it should work on Events Manager. Additionally, for finer precision you should be able to drag the map position marker to the exact place you want to focus on. ## Google Map Types URL: https://wp-events-plugin.com/documentation/google-maps/map-types/ > _Google Maps has limited free usage quotas/limits, if you go over this usage value, you will be billed for service usage.See [our recent announcement](http://wp-events-plugin.com/blog/2018/07/17/google-maps-api-pricing-increases/) for more information about the new pricing changes for Google Maps API._ Events Manager's integration with Google Maps provides you with multiple map types, each with their own advantages and disadvantages which mainly revolve around cost and flexibility. You can choose what kind of maps to display by visiting your _Dashboard > Events > Settings > General (tab) > Google Maps and Location Services > Google Map Type_ You'll be provided with the following map types: ### Static Maps (Pro Feature) Static Maps is a great way to dramatically decrease API expenses whilst maintaining a professional look with customisation, balance and flexibility. Static maps are images of a map, but will display very similarly to Dynamic Maps (and can be styled the same way), but can be displayed **%70 more times** within Google's free usage limits. The main differences is that users can't zoom in/out or move around the map, and the speech bubble you get in dynamic maps won't appear. However, with Static Maps you also have added options of caching your images, and enhancing user interaction by allowing users to load dynamic or embedded maps when clicking on the map image. Due to the various options afforded with our Static Maps feature, we've created a specific page for [setting up Google Static Maps](https://wp-events-plugin.com/google-maps/static-maps/). ### Dynamic Maps These are the maps that Events Manger has used from the get go for many years now. Previously, the free usage limits offered by Google made this map type a no-brainer, but unfortunately at this point the prices have made this type of map quite costly, affording you only 28,000 free map loads per month. The advantages of these maps is that they are highly customizable and therefore provide you with a degree of flexibility and provide a custom look. You can style your maps via Google Maps settings section of your settings page, and also show text balloons within the map next to the marker of your location which shows your information about your event. There is also no advertising on your map, meaning any competition surrounding your area cannot get your visitor's attention. ### Embedded Maps Embedded maps are free to use. That is the major advantage... set it and forget it! However, there's are some trade-offs... customization and flexibility. Google will display a map tailored to the needs of the user visiting your site. That means that if they're a Google user, they'll see their avatar on the map, and if you're in a heavily populated area there will be other locations showing up on there which you may not want, including any establishments that can advertise via Google Maps. Additionally, there will always be a pane containing information about that location. The nice thing about that is there's a link for users to click for directions, which takes them to a google.com page, or alternatively to star/favourite the location on their own google.com maps account. However, this is all Google-related services when you have no control over. Below the choice of map types on the settings page, you do have the choice of what location information to base your embedded map off, which will affect what is displayed on the aforementioned pane: #### Location and Address This will be the same as going to maps.google.com and searching for the location name and address, which provides an accurate representation of your location on the map. It will, however, bring up information associated with that location place (if registered on Google Maps) including things such as star ratings and comments/reviews about that location. You cannot customize what is shown in this situation, such as bad reviews or low-star ratings. #### Address Only This will display only the address, which may be a good mix between the location/address option and GPS coordinates. There may be a slight variation between exact marker positions, especially for larger buildings with multiple streets or door numbers. #### Coordinates You'll see a set of coordinates on the pane within your map. The marker will be exactly where you placed it whilst editing the location. The downside is it's not very informative for users, unless you actually want to show this to users (e.g. if it's a remote place that can benefit from GPS coordinates). ## Google Maps API Cost Management and Usage Optimization URL: https://wp-events-plugin.com/documentation/google-maps/api-usage-management/ > _Google Maps has limited free usage quotas/limits, if you go over this usage value, you will be billed for service usage. See [our recent announcement](http://wp-events-plugin.com/blog/2018/07/17/google-maps-api-pricing-increases/) for more information about the new pricing changes for Google Maps API._ The purpose of this page is to provide information on how to reduce or entirely mitigate the costs of using the Google Maps API service by optimizing your usage of the service and staying as close to or within the limits of the free monthly usage allowance. For information about usage, see the [Google Maps APIs we use and where we use them](https://wp-events-plugin.com/documentation/google-maps/api-usage/). ### First step... estimate your usage! This is by far the most important step, as it will help you make subsequent decisions. Do you get a lot of visitors? If you get only a few thousand visits a month on your site, all of this is likely to be irrelevant as you'll be well within the limits of Google's free usage tier. The only thing we'd recommend is still set up quotas, just in case, which we cover further down. If you get thousands of visitors per day, then you're likely going to want to explore further and understand what pages visitors regularly visit on your site and optimize accordingly. It's important to understand what kind of usage your site gets, because depending on what kind of site you have, you may have different usage expectations. For example, if you're a site that accepts guest submissions of events, you'll certainly want to monitor your dynamic map loads usage on your submission pages, whereas if you run a popular events site where a handful of admins load events to specific sets of locations, you'd probably concentrate more on the display of maps for the events you publish. ### Managing Events Manager Google Maps Features #### Map Loading Map loads will probably be the largest Maps API call consumer on your site. This should be your primary focus of attention. The first important step is choosing the Google Map type to display on your site according to your needs. We recommend enabling Static Maps if you have Events Manager Pro, or alternatively enable Embedded Maps in Events Manager. We cover [google map types and their API usage](https://wp-events-plugin.com/documentation/google-maps/map-types/) separately and extensively. Additional considerations to make is **when** and **where** to display your maps. By default, Google Maps are displayed on the event and location page, but you can always choose whether or not to display these maps on either page by modifying your event formats. We would also strongly advise not showing maps on your event lists, or loading multiple maps on the same page. For example, if two maps show up on the same page, that page will double your consumption rate. #### Geolocation Autocomplete Queries Depending how you set up your site, it's possible that your site users search for events far more than they actually view event/location pages, in which case the Autocomplete API may get heavily used. Unfortunately, there's little that can be done to optimize these queries. The main question you need to ask yourself is whether this feature is really necessary for you to achieve an efficient user searching experience. Remember, that you can also enable users to filter events by location parameters such as country, city and region, which will narrow down search results sufficiently for most without using the API at all. You can disable the Geolocation Search field entirely via your _Dashboard > Events > Settings > Formats > Search Form > Show Geolocation Search?_ and setting that to 'no'. #### Event and Location Submission Forms Event and location forms will load dynamic maps each time a page containing location information is loaded, or if a user starts typing an address into a new event/location form. If the amount of events and locations you create and manage regularly are limited, this likely won't be a concern for you If you [accept user submitted events](https://wp-events-plugin.com/documentation/user-event-guest-submissions/), this is a source of API usage. Consider whether you would really like guests to submit events anonymously, or if you can force them to register first. By doing so you will prevent random visitors from coming to your site and playing around with submission forms and generating API usage even if they don't submit an event (or spam you). ### Further General Advice #### Do you even need Maps? Ask yourself whether you even **NEED** Google Maps in the first place!? Do you only have one or a handful of locations, even if you have many events? If so, it's likely your users won't search for events by locations anyway, and map generation is very consistent. Consider not using Google Maps at all... grab a screenshot of your location from a non-copyrighted source, such as [Open Street Maps](https://www.openstreetmap.org/), and leave it at that! You could even link to Google Maps with a regular link within the description of your location, or even [set up a custom field](https://wp-events-plugin.com/documentation/event-attributes/) where you can store a maps.google.com URL and show it as a link via your formats, there's lots of ways to inform users of your event locations, they might just require a little more work to begin with! #### Set Quotas, Not Just Budgets! Google is [not very emphatic about how to prevent a large bill](https://developers.google.com/maps/faq#usage_cap), so we feel we should be. There's two ways Google offers for you to help control your spending, Quotas and Budgets. Budgets are only informative, they will not prevent you from racking up the bill should spending go past your comfort zone. Quotas are the only way to programatically limit your usage, the downside being that if you go over your quota, maps stop working. This is why we recommend, particularly for displaying maps, to use our [Static Maps](https://wp-events-plugin.com/documentation/google-maps/static-maps/) feature in Events Manager Pro, and enable map caching. We suggest that you visit your console account, disable any APIs you don't need, and then set up quotas for every API you keep enabled. Use Google's [pricing calculator](https://mapsplatformtransition.withgoogle.com/calculator) to build a balanced set of quotas that remain within the limits of your budget. #### Restrict your API Keys If you haven't already, ensure the API keys you're using are restricted for use only on your sites and servers. If someone gets a hold of your key, they can use it at will on their sites, and you'll foot the bill! See our [Google Maps API Key Setup instructions](https://wp-events-plugin.com/documentation/google-maps/api-key/) which covers this step. ## Google Maps API Usage URL: https://wp-events-plugin.com/documentation/google-maps/api-usage/ > _Google Maps has limited free usage quotas/limits, if you go over this usage value, you will be billed for service usage. See [our recent announcement](http://wp-events-plugin.com/blog/2018/07/17/google-maps-api-pricing-increases/) for more information about the new pricing changes for Google Maps API._ The purpose of this page is to explain what APIs we use, how and where we use them, so you can decide how to make the best of this service without ending up with large unexpected usage bills. We suggest you check out Google's [pricing page](https://cloud.google.com/maps-platform/pricing/sheet/) and [cost calculator](https://mapsplatformtransition.withgoogle.com/calculator) to check if your site usage will generate any costs according to the APIs Events Manager uses as described below. We also have a [Google Maps API usage and cost management](https://wp-events-plugin.com/documentation/google-maps/api-usage-management/) documentation page providing you with information on how to entirely mitigate, or reduce these costs as much as possible depending on your site requirements. With Events Manager (and Pro) we make use of Google API services in the following areas: _Please note that these are not the libraries you need to enable, rather the APIs according to their price sheet. See our [Google Maps setup instructions](https://wp-events-plugin.com/documentation/google-maps/api-key/) for more information on what libraries you need to activate for each feature._ ### Displaying Maps Every time a map is displayed, you are making an API call to the Google Maps Service. Events Manager [offers multiple map types](https://wp-events-plugin.com/documentation/google-maps/map-types/), you will be paying a different price for different types of map loads. Maps are loaded by default on Event and Location pages. You may also be loading maps if using shortcodes to display event/location information which will use one or more of the following APIs: - _Dynamic Maps_ - _Embedded Maps_ - _Static Maps (Pro Only)_ Also, if you're using the \[_events\_map_\] or \[_locations\_map_\] shortcode, each map load will count as one _Dynamic Maps_ API call. If you have multiple maps on a single page, each map displayed counts as one map load, even if on the same page. ### Creating and Editing Locations When creating and editing locations, you'll notice a map that appears next to location address information, and dynamically changes as you change add or edit the address of your location. This map is using the _Dynamic Maps_ API service and the purpose of this map load is to give you a preview of your location on the map, along with the ability to move the pin, changing the GPS coordinates of your exact location. Every time you load a location or event edit page, a map to the corresponding location will be loaded with it. This will count as one API call per page load. If you type in or change the address of your location which changes the location of the map, or move the pin around a _Geolocation API_ call is also made to determine the coordinates based on the new address information. This still counts as one _Dynamic Maps API_ call until the page is reloaded (such as if you click the 'save' button). ### Searching Events with the Near... Field Our search form has a geolocation autocomplete search field, which provides visitors with location names as they type. We use this functionality to determine coordinates of their desired location and search for events within a radius of those coordinates. This service uses the Google _Places Autocomplete_ API. ## Google Static Maps URL: https://wp-events-plugin.com/documentation/google-maps/static-maps/ > _Google Maps has limited free usage quotas/limits, if you go over this usage value, you will be billed for service usage. See [our recent announcement](http://wp-events-plugin.com/blog/2018/07/17/google-maps-api-pricing-increases/) for more information about the new pricing changes for Google Maps API._ Events Manager Pro 2.6.4 introduced Google Static Maps as an option for displaying location maps on your site. Static Maps provide a great option for displaying customised maps of your location with a much higher free usage free usage limit compared to regular (dynamic) maps, and also provide multiple options to still give your users that great experience of viewing dynamic/interactive maps by clicking on them. EMP also provides a caching mechanism which has several benefits including the ability to display relatively sized images, reduce page load times as well as your API usage quotas. ### Setting Up Static Maps #### 1\. Enable 'Static Maps API' Library You will need to enable an additional API library called 'Maps Static API' in the same area you set up your Google API account, please refer to our [Google Maps API setup instructions](https://wp-events-plugin.com/documentation/google-maps/api-key/) or [Google's official documentation](https://support.google.com/cloud/answer/6158841). #### 2\. Obtain Additional API Keys Static Maps require additional API keys, which include a Signature and (optionally) Server key. Signature keys are required, and will prevent users from using your API key to generate map images on their own site. To obtain a signature, visit the [Static Maps API library](https://console.cloud.google.com/google/maps-apis/apis/static-maps-backend.googleapis.com/staticmap) page you just visited and enabled, and click the 'URL Signing Secret' tab. From there, you can enable and generate a new secret, which you will use in the next step. Server keys are used if you will be making use of our caching feature, or if your maps are using relative sizes (for example if you use a location placeholder like #\_LOCATIONMAP\{100%,300}). To obtain a server key, you will create another API key as per our [Google API setup instructions](https://wp-events-plugin.com/documentation/google-maps/api-key/). Whilst optional, you should also restrict the key to the IP of your web server to prevent unauthorized use. #### 3\. Select Static Maps Map Type Once you've enabled the API and obtained the right keys, you will need to go to your _Dashboard > Events > Settings > General (tab) > Google Maps and Location Services > Google Map Type_ and select 'Static Maps' as your map type. When you do this, you'll see additional options appear, including two text inputs where you'll introduce the keys you obtained in step 2 above. #### 4\. Set up additional options At this point, static maps will work and will simply show a static image. If you have defined any [map styling](https://wp-events-plugin.com/documentation/google-maps/#map-styling) these styles will also be applied to static maps. You can also define click actions and enable caching, which we'll cover in the following sections. ### Click Actions & Hover Text Static maps are simply images, compared to dynamic maps which allow you to zoom and move around the map to see further surroundings. However, loading dynamic maps can be costly and unnecessary when a large portion of users will likely never interact with the map. Click actions for static maps provide that balance to provide a great user experience whilst providing optimal API quota usage. When Static Maps are enabled (as per instructions above) in your settings page, you will see a '_Map click action'_ dropdown in the '_Static Maps Options'_ section, allowing you to choose additional actions when the static map image is clicked on. If you choose a click action, when a user hovers over a map image, the 'Static hover text' will show over the map and one of the following actions will occur when clicked on: #### Link to google.com options A new tab will open and will load a map on google.com. There is no API usage cost with this option, and produce the same results as covered by [embedded maps](https://wp-events-plugin.com/documentation/google-maps/map-types/#embedded-maps) map type, along with the related downsides regarding lack of customization. #### Load dynamic map A [dynamic map](https://wp-events-plugin.com/documentation/google-maps/map-types/#dynamic-maps) will replace the static image, which will look somewhat seamless maintaining the same style and aspect as your static image. This is the most professional-looking option, and by loading static images first you've optimized your API usage of dynamic maps preventing them from being consumed unnecessarily for site visitors who don't intend to use it. #### Load embedded map Similar to the dynamic map option, clicking on the static image will replace it with an [embedded map](https://wp-events-plugin.com/documentation/google-maps/map-types/#embedded-maps) with the same dimensions. Embedded maps have no usage quota but come with the downside of lacking customization. ### Static Caching Static map caching will enable you to serve images directly from your own server, which are cached for the amount of days you choose. Aside from the obvious benefit of reduced API usage, there is also a significant performance advantage: **Optimized loading times.** Google Static Maps will load slower, especially when loading dynamically sized images. This is due to the URL signing requirement, which can only be done server-side. With dynamic image sizing, such as loading a map that is 100% the width of your page, the width can only be calculated in Javascript once the page is loaded. At this point, we must request an image from the server running Events Manager with the specific dimensions so it can be signed with your API key and secret. This process requires a certain amount of processing and slows down loading time, which is why caching is beneficial. #### Cache Expiry and Adhering to Google's Terms of Service In order to adhere to Google's TOS you must not keep images stored for more than 30 days, therefore it's recommended you set the '_Static map cache expiry days'_ to a value of less than 30 days. When enabled, images older than x days according to your settings will be deleted on a daily basis from your google maps images folder. Google has strict rules about caching and defines it in their Terms of Service - [Section 10.5 d](https://developers.google.com/maps/terms): > No caching or storage. You will not pre-fetch, cache, index, or store any Content to be used outside the Service, except that you may store limited amounts of Content solely for the purpose of improving the performance of your Maps API Implementation due to network latency (and not for the purpose of preventing Google from accurately tracking usage), and only if such storage: > > 1. is temporary (and in no event more than 30 calendar days); > 2. is secure; > 3. does not manipulate or aggregate any part of the Content or Service; and > 4. does not modify attribution in any way. Caching for our purposes, however, will adhere to these requirements, as the main reason for this is to improve performance and the map content is not modified in any way. #### Troubleshooting Caching If you have enabled caching, it should work automatically. However, if you find that your images are not loading correctly or are loading slowly, please verify that your site is correctly creating a cache folder to save images and has permission to write to the /wp-content/uploads/events-manager/static-gmaps/ folder (create one if necessary). You can also verify your file permissions are correct by trying to upload a file via the WordPress Media section, which uses the same folder Events Manager caches files to. ## Setting Up Google Maps API Keys and Libraries URL: https://wp-events-plugin.com/documentation/google-maps/api-key/ In order to use any Google Maps service, you must enable the relevant Google API Libraries, and obtain a Google Maps API key which you'll add to your Events Manager settings page. If you're unable to load maps or are seeing _Location Not Found_ errors when trying to use maps in Events Manager, make sure you've completed the steps below. _We have removed screenshots, as Google regularly changes their interface and also has varying interfaces for different account types and countries. If these steps don't work for you, please check Google's documentation for creating API keys and enabling libraries, and follow our recommendations for the required libraries and API Key restrictions._ ### Step 1. Sign into your Google Cloud account (or create one) **If you already have a Google Cloud Platform account:** 1. Visit the [Google Cloud Platform](https://console.cloud.google.com/), sign into your Google Account if asked. 2. Select the desired project from the top right of the screen, if you haven't created one already, you'll be asked to do so at this stage. **If you don't have a Google Account or have not previously used Google Cloud Platform:** 1. Visit the [Google Maps Platform](https://cloud.google.com/maps-platform/) website, and click the 'Get Started' box. 2. Choose the 'Maps' and 'Places' checkboxes and click continue. - _You don't have to choose both, you can just choose Maps and enable/disable libraries in the next steps._ 3. Log in or create a new account in the next screen. 4. Follow the next instructions to set up your project name and billing details. 5. At the last step, Google will create new API key for you and enable some API libraries, we'll cover these in following steps. ### Step 2 - Enable the relevant API Libraries 1. Visit the [Google Maps API Libraries](https://console.cloud.google.com/google/maps-apis/) page. You'll see a list of libraries that are enabled, and a second list of disabled libraries. 2. Ensure you have the right project selected at the top left of the page. 3. Enable the Libraries you need (see below) by clicking on the Library name, and then the 'Enable' button. 4. You may see some libraries already enabled, we recommend you disable the libraries you don't need. The libraries you need depend on which features you'll be using in Events Manager. Here's a list of the ones you'll need below and also the optional libraries you might need: - Maps Javascript API - Places API for Web - Geocoding API (_required if you use the geolocation field in your search forms)_ - Maps Embed API (_required if you chose Embedded Maps as your [map type](https://wp-events-plugin.com/documentation/google-maps/map-types/), or as a click action for [static maps](https://wp-events-plugin.com/documentation/google-maps/static-maps/))_ - Maps Static API (_required if you chose the Static Maps as your [map type](https://wp-events-plugin.com/documentation/google-maps/map-types/))_ ### Step 3 - Get your Google Maps API key Google's [official instructions](https://support.google.com/cloud/answer/6158862?hl=en&ref_topic=6262490) are somewhat confusing, especially if you're not a developer, so we've created some of our own step-by-step instructions: 1. Go to [Google Cloud Platform's Credentials](https://console.cloud.google.com/apis/credentials) page. 2. Make sure you've selected the same project you set up your libraries in step 2 at the top left of the page. 3. If you don't have any API Keys already created: 1. Click the 'Create Credentials' button and select API Key 2. You'll see an API Key has been created and a confirmation window showing your new key. 3. Click the 'Restrict Key' option. 4. If you see an API key already in the list (or you clicked the 'close' button on step 3), click on it. 5. (optional) Edit the key Name field so it's something meaningful and easy to remember (e.g. Events Manager Browser Key) 6. In the _Key Restrictions_ section, select _Application Restrictions_ and then _HTTP referrers (web sites)_ 7. You'll see a text box appear under _Accept requests from these HTTP referrers (web sites)_. To make sure that map requests work from anywhere on your domain, we recommend adding more than one entry using the following patterns: - \*.yoursite.com - yoursite.com 8. Click 'Save' 9. Copy your newly restricted API key from your list of keys, for use in Step 4. _If you have enabled [static maps](https://wp-events-plugin.com/documentation/google-maps/static-maps/) as your [map type](https://wp-events-plugin.com/documentation/google-maps/map-types/), then you will need to repeat these steps to create a new server API key. However, instead of choosing 'HTTP referrers' in step 6, you'll need to choose 'IP addresses' and enter your server IP in step 7. To find your server IP, [use this tool](https://toolbox.googleapps.com/apps/dig/) and type in your site url._ If you notice any other API keys in your list, make sure they are also restricted appropriately, and delete any keys you don't use. Unrestricted API keys will show an orange exclamation mark next to it. ### Step 4 - Add the API key to Events Manager Go to _Events > Settings > Google Maps and Location Services_ and paste your key into _Google Maps API Browser Key_. [Image: Selection_009] Click _Save Changes_ and create an event with a map to check that both admin and front-end functions are working correctly, #### Troubleshooting If you're having problems getting Google Maps to work on your site, try testing with _Accept requests from these HTTP referrers (web sites)_ left blank. If maps are loading with that setting, it indicates there's a problem with either the domain name or the pattern used with it. If maps still don't load, you may have a problem with the way Events Manager is configured. Aside from testing, we recommend using a domain pattern in _Accept requests from these HTTP referrers (web sites)_ to prevent unauthorized use of your API key. Note: This credentials page in the Google API Console also shows the usage and quotas for your account, if you need to check this later. ## Hooks and Filters URL: https://wp-events-plugin.com/documentation/hooks-and-filters/ _This page is meant for people that are comfortable using PHP and know their way around WordPress. If you don't know how to use hooks and filters, you should [start here first](http://codex.wordpress.org/Plugin_API)._ We have a large number of actions and filters in our codebase, generally, we aim to place an action/filter where appropriate for every function we have as well as in other relevant places to allow maximum flexibility. At this time, we don't have any documentation for these hooks. If you're a developer and you'd like to see a specific hook or filter placed in the plugin, let us know. If reasonable we'd be happy to add it in! ## Importing / Exporting URL: https://wp-events-plugin.com/documentation/importing-exporting/ Events Manager I/O is our Importer / Exporter add-on > I/O is currently available to Pro+ Users Events Manager I/O provides an abstract layer between import and export formats (what you're importing to/from) and Events Manager. This allows the addition of new formats for import and/or export by developers to be as easy as possible. ### Initial Setup The Events Manager I/O add-on can be downloaded from our [downloads page](https://eventsmanagerpro.com/downloads/) and can be installed on your site in the same way as [installing the Pro add-on](https://wp-events-plugin.com/documentation/installation/) via the WordPress plugin installer. Once you have done this and activated the plugin, you will see a new 'Events I/O' menu item in the admin dashboard. - [Setting Up Imports](https://wp-events-plugin.com/documentation/importing-exporting/import-setup) - [Setting Up Exports](https://wp-events-plugin.com/documentation/importing-exporting/export-setup) ### Supported Formats Our I/O plugin allows you to import and export events and/or locations (when supported by the source). ##### File/Feed Formats These formats can be uploaded or exported as a file, or alternatively can be accessed for import/export via a URL which also enables you to automatically sync and update event data. - iCal - [CSV](https://wp-events-plugin.com/documentation/importing-exporting/spreadsheets/) - [Excel](https://wp-events-plugin.com/documentation/importing-exporting/spreadsheets/) ##### External Services (Separate Add-Ons) - [Google Sheets](https://wp-events-plugin.com/documentation/importing-exporting/google/google-sheets/) - [Google Calendar](https://wp-events-plugin.com/documentation/importing-exporting/google/google-calendar/) - [Meetup.com](https://wp-events-plugin.com/documentation/meetup/) - [Facebook](https://wp-events-plugin.com/documentation/facebook/) _(limited imports only due to API restrictions)_ For more information on setting up each format, click the links above. ### Advanced Features The advantage of Events Manager I/O is that aside from connecting to multiple formats, we offer some advanced features described below. #### Automated Import Scheduling You can schedule imports to run repeatedly over hourly, twice daily, daily, weekly, twice weekly, bi-weekly and monthly intervals. Coupled with Smart Syncing (see below), you can consistently keep your event sources updated. #### Smart Syncing Each import or export job you create maintains a synchronization history, meaning if you run that job again, previously processed items will be ignored and not duplicated. Additionally, you can choose whether to update previously imported/exported items that have been modified. #### Location Import Autocompletion with Google Services Not all sources provide complete location information. For example, iCal formats have no standard format for providing addresses and therefore can be difficult to manually parse for accurate information. With Google Maps service integration, you can improve the quality of your address imports, including geo-coordinates when not supplied. #### Connect to Multiple 3rd Party Accounts External services like Google, Facebook and Meetup.com use OAuth for connecting Events Manager I/O with your account. This method allows you to connect to multiple accounts should you need to. #### Detailed Import/Export History Every time an import or export job creates or updates data, you'll find it in the history tab. See all your import/export history in one place, or drill down to individual jobs or dates to find out what happened. #### Import/Export Filters You can filter events and locations to be imported/exported if they match search text or are within a specific date. You can also limit how many items are processed each time the import/export job is executed. #### Export as Feed URLs For exports such as iCal, CSV and Excel which do not push data to an external service (such as Google Calendar), you have the option of directly downloading the file or publishing it to a publicly accessible URL in the form of a downloadable file or a feed. This can allow other importers (event another Event Manager website) to access this data, which is updated as you add/edit events and locations. #### Import Actions You can also choose what to do when processing each item to be imported. This includes: - Whether to publish or leave it in draft/pending status. - What to do with items that have been updated. - Update, ignore or update and change publish status. - Download or ignore featured images. - Add tags or categories to events when imported. ## Connecting to OAuth Accounts URL: https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/ Services like [Google](https://wp-events-plugin.com/documentation/importing-exporting/google/), [Facebook](https://wp-events-plugin.com/documentation/facebook/) and [Meetup.com](https://wp-events-plugin.com/documentation/meetup/) use OAuth to connect accounts with I/O in a safe way without requiring passwords. Firstly, you need to set up OAuth clients for each respective service, once set up you can then connect to individual accounts. On this page, we'll use Meetup.com as an example, however, each account is relatively similar in steps. ### Adding an Account To add accounts, visit your _WP Dashboard > Events I/O > Settings > Service Connections_ where you'll see the available services to connect to. As you can see in the example above, we have not connected to any accounts, and we've enabled the Google, Facebook and Meetup add-ons. If you do not see your desired format here, make sure you have installed and activated your add-on and also set up an [OAuth client](https://wp-events-plugin.com/documentation/importing-exporting/google/setting-up-google-oauth-2/). Click on 'Connect' and you'll be redirected to Meetup.com and shown a consent screen. Clicking Allow will redirect you back to your site and you should now see the connected profile icon in the Meetup panel. You can disconnect accounts by clicking the 'Disconnect' button, or add multiple accounts by clicking the 'Connect additional account' button. In the example below, we have two accounts connected. In this case, the disconnect button will disconnect all accounts, whereas the disconnect links next to each account will disconnect that individual account. ## Importing Events and Locations URL: https://wp-events-plugin.com/documentation/importing-exporting/import-setup/ This page will help you with setting up an import using our [Events Manager I/O add-on](https://wp-events-plugin.com/documentation/importing-exporting/). Please visit the [main document page](https://wp-events-plugin.com/documentation/importing-exporting/) for links to working with specific import formats/sources. Once installed, head over to the Events I/O > Imports menu in your admin dashboard. You will be presented with an admin area for previously created imports, which will now be empty. Click the Add Import button. You'll be presented with a list of import formats to choose from. > Events Manager I/O has iCal, CSV and Excel formats by default. Other formats such as Google Sheets/Calendar are available as separate add-ons from our [downloads page](https://eventsmanagerpro.com/downloads/) and must be installed along with Events Manager I/O. In this example, we will choose iCal. Most of the options for import are consistent across different formats. The main differences you will notice would be when choosing the source location and how to process locations. ### Main Settings The first section of settings are the most important and are required. The first field 'Reference Name' is simply a name you can choose for future reference. #### Type - What to import Next, you will choose whether to import Events, Locations or Both. Most sources are event-based, such as iCal, Google Calendar, Meetup.com and Facebook which means they do not have a specific way to query locations. If you choose to import only locations, Events will be processed and only location data will be extracted. #### Advanced Location Options If you choose to import locations (with or without events), you will see a link to show/hide advanced options. This enables you to fine-tune how locations are processed. Depending on the import source, location data quality and consistency can vary wildly. Whilst Facebook and Meetup.com provide fairly consistent information, iCal and Excel files can provide a text value without any address info, such as the name of a place for example. **Default Location** will allow you to select a default location if no location is provlded. ##### **Google API** and Location Parsing Google API offers you the possibility to use Google services to either improve the address information already provided by filling in missing information or to automatically guess the address based on the provided information and use the results provided by Google instead. > Google API is a paid service with a free tier of usage. Please [see our documentation](https://wp-events-plugin.com/documentation/importing-exporting/google-api-key/) for setting up an API key for I/O. The next three options in the screenshot above may appear if you select not to use Google API or only want it to improve on the provided address. Whether or not they appear depends on the format and whether address information is supplied as one string of text rather than separate fields. These three options help you establish the format addresses will be provided by your import source. The selection you choose depends largely on the quality of your address information from the import source. If you're confident that every address for each event imported will have a consistent pattern, then you can choose not to use Google's API. If your address data varies, it may be worth using Google API to help generate reliable addresses. You can try without the API first and see how results show in the next preview tab. #### Import Source This varies from format to format. Some formats such as iCal and Excel will allow you to upload a file or a URL. Other formats may require you to choose from a number of sources and/or supply a URL or ID of a page, group or account to import from. #### Frequency - Automated Imports If you would like to automatically check for updates and import new items, you can choose how often to check the source. This can range from hourly to monthly and you can also specify a date range from when to start importing and/or when to stop. If you supply only one date, the blank date will be assumed as starting immediately for the start date, or to run indefinitely with no end date. After you save your import, you will need to activate automated import by clicking the button that appears at the top of the page, or the 'activate' option when viewing all your import jobs in the admin area. ### Imported Item Actions The next section provides you with options on what to do with an imported item. **_Ignore Duplicate Events?_** if set to yes will check other events on your site and compare name and date to see if there's a match. **_Import Status_** allows you to set imported events to Draft, Pending or Published status. **_Import Updates_** decides what to do with events or locations that are updated at the source. You can choose to ignore updates altogether, update the item and either keep the current publish status or set it to draft/pending status so that you can review changes before they get published. **_Attachment Actions_** let you choose whether to download or ignore featured images, if the source provides one. The last input fields will allow you to pre-set categories and tags to imported events, which would allow for easy management of these items. ### Result Filters The following fields allow you to filter out items that do not match the search text or (if importing events) only events that occur within specific date ranges. ### Previewing Results Once you have saved your import job settings, you can then see a preview of your imports. Previews allow you to choose which specific events you'd like to import, or alternatively see what actions would be taken were you to run a scheduled/automated import. Here's an example when previewing an import of our [demo site](https://demo.wp-events-plugin.com) via its iCal feed: In this case, you'll see a few different scenarios we've set up by previously importing to highlight the possibilities. The first event, War, has found a duplicate event with the same name and date/times, and will be ignored as per your settings in the _Imported Items Actions_ section. Some events and locations may have been imported previously. Here, we've previously imported multiple locations for earlier recurrences of this event, and also the second event in the list, Cassandra Wilson. You'll see a checkmark next to events previously imported or next to locations if only the location exists, along with links to view those items on your site. > Import history is considered within the specific import job. If you create two separate import jobs from the same source, you may end up with duplicates. The fourth event, Gatlin Brothers, was previously imported, however, the event details have changed and will be updated. If you delete an imported event, it will not be imported again. As you can see, the location associated with the Cassandra Wilson event was deleted, and so is the Frontier Ruckus event. One scenario which is not included here is when an event or location cannot be imported due to missing information which would cause an error whilst attempting to create it on Events Manager. In these cases, the checkbox would be replaced with an exclamation icon. Once you are happy with the preview, you can then proceed to either click the import button at the bottom to process all the items, or select the specific ones you'd like and then proceed. ## Dealing with importing Source Unique Identifiers URL: https://wp-events-plugin.com/documentation/importer/unique-identifiers/ **Please note that the importer plugin is a beta feature, this documentation is subject to change whilst the plugin is developed further.** When importing from any source, consistent and unique IDs are needed for each event or location provided to the importer so that when re-importing from the same source previously imported items can be identified and ignored or updated accordingly, preventing duplicates. Some sources such as iCal and CSV may not provide a consistently unique ID (or any at all) and can create nuances when re-importing or syncing from the same source regularly. We'll use iCal to illustrate two common scenarios. ### IDs that change when the event or location is modified In many cases, event IDs on iCal feeds are generated by mixing in the event dates with other unique information, meaning that any change to the date or time will change the ID. This scenario creates a nuance where the importer will not be able to identify a modified item as previously imported and therefore will create a new event or location instead of updating the previously updated event. Unfortunately, there is no solution at the moment to prevent duplicates in these situations. ### IDs that change each time you reload the feed In some less common cases (such as older versions of Events Manager prior to 5.6.6, yes we were guilty of this too!) the event identifier changes each time the feed is loaded. This presents an issue because each time you re-import from this feed, previously imported events can't be identified and therefore will be imported again, creating duplicates each time you run the import. The solution in this case is to set the _Ignore Source IDs?_ option to 'Yes'. In this case, a unique ID will be generated by the importer based on the information provided and will remain consistent provided the event or location does not change. Should the source information change, the same issue described in the section above will occur. ### The Ideal Scenario Ideally, a feed will always provide a consistent unique ID for the event and/or the location. That way, even if the details of the event or location change, the importer can correctly find previously imported events and update the item, and ignore those that haven't been modified at all. ## Exporting Events and Locations URL: https://wp-events-plugin.com/documentation/importing-exporting/export-setup/ This page will help you with setting up an export using our [Events Manager I/O add-on](https://wp-events-plugin.com/documentation/importing-exporting/). Once installed, head over to the Events I/O > Exports menu in your admin dashboard. You will be presented with an admin area for previously created exports, which will now be empty. Click the Add Export button. You'll be presented with a list of export formats to choose from. After this, you'll be taken to the add/edit page. > Events Manager I/O has iCal, CSV and Excel formats by default. Other formats such as Google Sheets/Calendar are available as separate add-ons from our [downloads page](https://eventsmanagerpro.com/downloads/) and must be installed along with Events Manager I/O. In this example, we will choose iCal, although at the time of writing all formats offer the same export options, the only difference being between external services such as Google Calendar and downloadable files such as iCal or Excel. Which will be explained further down. ### Main Settings This is where you select what type of data to export and where to export it. **Reference Name** is simply a text name you assign for future reference when viewing your export jobs. **Export Type** allows you to choose whether to export events, locations or both. Some export destinations will allow only events, whilst others may require both events and locations. #### Export Destination This setting will vary depending on whether you will export to an external service such as Google, or to a file format such as iCal, CSV or Excel. We'll address both here: ##### File/Feed Formats Formats such as Excel are generally available as a file, or possibly a feed. With Exports of these format types, you have the option of exporting directly and privately as a file or to also create a URL where this export can be accessed as a feed or downloadable file. This will appear if you have chosen a public URL to publish your feed. A feed is essentially the same as a downloadable file but viewed on-screen and may be useful for other external services needing to access that information. #### External Services Services such as Google Sheets/Calendar and Meetup.com have no options for export destination because any information is exported to their API. In these cases, you will either be provided with a dropdown of potential export destinations which are accessible by accounts you connected to the service with via the settings page. Additionally, you may also need to supply a URL, for example with Google Sheets you define the spreadsheet URL you'd like to export to. Once you have saved your export, you will be shown an option to run the export, which will upload your exported items to your chosen destination. ### Filtering Exports Once you have chosen what and where to export, you can filter your exported items by search term, date range (if exporting events), and limit. Note that with limits, each time you run an export I/O will attempt to export that many items. With external services, previously exported items will not be duplicated or ignored, they will be updated if possible. ## Importing and Exporting Spreadsheets URL: https://wp-events-plugin.com/documentation/importing-exporting/spreadsheets/ This page will provide specific information about importing and exporting spreadsheet formats using [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/). Various spreadsheet formats are supported by I/O, currently Excel, CSV and [Google Sheets](https://wp-events-plugin.com/documentation/importing-exporting/google/google-sheets/). Given spreadsheets operate very much in the same way, this documentation will serve for most spreadsheet-based formats. For more information about general options available see the general [importing](https://wp-events-plugin.com/documentation/importing-exporting/import-setup/) and [exporting](https://wp-events-plugin.com/documentation/importing-exporting/export-setup/) instructions. The main differences between these formats depend whether sheets are stored on a cloud service (e.g. Google Sheets) or are file-based (Excel, CSV). Cloud-based sheets will usually require a URL to the resource after connecting to the account with access to that sheet, whereas Excel and CSV can be uploaded via a file or a URL where the file can be downloaded from. ### Importable/Exportable Information Spreadsheets allow a pretty detailed amount to be exported and imported. Each item exported represents a row on the spreadsheet, if exporting events and locations both event and location information is stored in one row, with location data in the last columns. All information stored in the wp\_em\_events and wp\_em\_locations can be imported and exported, each field represented by a cell/column in a row. [Event and Location custom fields](https://wp-events-plugin.com/documentation/event-attributes/) will also be exported. Additionally, any taxonomies associated with each will also be exported as a comma-delimited field of taxonomy names. Exporting will add a line to the top of a spreadsheet representing the heading for the column. When importing events, you can identify each field in the Field Mapping tab. ### Field Mapping (Imports) After saving your import settings for the first time, you will be presented with the Field Mapping tab. You must complete this form to proceed to the preview. You can select what fields to use and which to ignore, and if headers match the fields in our database these will be auto-assigned. As shown in the screenshot above, you will also see the header names on the left, along with the first row of sample data on the right. The minimum required information is the same as to create a location or event. ## Google I/O URL: https://wp-events-plugin.com/documentation/importing-exporting/google/ Google I/O is an add-on for [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/) which allows you to import and export events to/from Google [Calendar](https://wp-events-plugin.com/documentation/importing-exporting/google/google-calendar/) and [Sheets](https://wp-events-plugin.com/documentation/importing-exporting/google/google-sheets/). Additionally, I/O supports syncing so each import/export job will not duplicate events. ### Installation Google I/O is available to Pro+ users and can be obtained from the [downloads page](https://eventsmanagerpro.com/downloads/). You would install the Google I/O after installing Events Manager I/O just like you would [install the Events Manager Pro plugin](https://wp-events-plugin.com/documentation/installation/). ### Setting Up and Connecting All Google services will require the same initial setup of setting up [OAuth 2.0 credentials](https://wp-events-plugin.com/documentation/importing-exporting/google/setting-up-google-oauth-2/) and only require setting it up once. After following these instructions, you'd proceed to [connect your OAuth accounts](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). ### Exporting and Importing For general instructions, please see our importing and exporting documentation pages. Additionally, see our separate documentation for each Google service: - [Google Calendar](https://wp-events-plugin.com/documentation/importing-exporting/google/google-calendar/) - [Google Sheets](https://wp-events-plugin.com/documentation/importing-exporting/google/google-sheets/) ## Setting up Google OAuth 2.0 Credentials URL: https://wp-events-plugin.com/documentation/importing-exporting/google/setting-up-google-oauth-2/ This document will help you set up a Google OAuth 2.0 service on your [Google developer console](https://console.developers.google.com/) and connect it to your Events Manager I/O installation. > _Screenshots and specific links/locations of options in the Google interface may vary without warning as they do regularly change their interface. For the most up-to-date instructions on general setup of OAuth 2.0 on Google [please see their documentation](https://support.google.com/cloud/answer/6158849?hl=en)_, _we will also link to relevant setup instructions on their docuemtation as well._ ### Create a Project and Enable APIs If you have not created a project before or require a new one, [create a new project first](https://support.google.com/googleapi/answer/6251787) by clicking on the top right of your console screen where you can select your project. Once you have your project selected and set up, we need to [enable the APIs](https://support.google.com/googleapi/answer/6158841?hl=en&authuser=1) of the services you wish to import and export from. Visit the [APIs library](https://console.developers.google.com/apis/library/) and enable the [Google Calendar](https://console.developers.google.com/apis/library/calendar-json.googleapis.com) and/or [Google Sheets](https://console.developers.google.com/apis/library/sheets.googleapis.com) APIs. ### Set Up your Consent Screen Before you create OAuth credentials, you need to set up the [consent screen](https://console.developers.google.com/apis/credentials/consent). The minimum required fields to get up and running are the Application name, scopes and authorized domain. For scopes, you will need to add _../auth/spreadsheets_ and _../auth/calendar_. If you are only using one of the Google services, you need only enable that one. Additionally, if you only intend to import, then you can use the read-only version, such as _../auth/spreadsheets.readonly_. > **Important Note** : You do not need to get your application verified if only you or trusted users will be using I/O to administer your site events, but you will see warnings about an unverified application when linking accounts to your site. > > Based on the above, you also may or may not need to fully fill out this information. If you have users that may not fully trust you (i.e. non-site admins or large organizations), you should fill out all the information on this page and also get your application verified. ### Add an OAuth Client Once you've set up your consent screen, you can then [add an OAuth Client ID](https://support.google.com/cloud/answer/6158849?hl=en) which I/O will use to connect with your Google accounts and access Sheets/Calendar. 1. Visit the [credentials page](https://console.developers.google.com/apis/credentials), making sure you have the right project selected and click the Create Credentials button. 2. Choose OAuth Client ID 3. Select 'Web Application' 4. For **Authorized JavaScript origins** enter your hompage URL 5. For **Authorized redirect URIs** use the URL found in your Dashboard > Events I/O > Settings > Server-Side Credentials (Tab) > Google 6. Save your settings Once created, you will have the option to download a JSON file by clicking the download icon next to your new OAuth Client ID, or at the top of the page when viewing your Client ID. You will use this file to submit to your Google server settings as described in step 5: Once successfully uploaded you'll see a green checkmark in place of the orange flag in the screenshot above. ### Proceed with Account Connections After completing these steps, you and other admins should be able to access the settings page 'Service Connections' tab and [connect accounts to your site](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). ## Google API Key for Importing Locations URL: https://wp-events-plugin.com/documentation/importing-exporting/google-api-key/ With Events Manager I/O, you can use Google APIs to improve or guess the location provided by events you import from different sources. This is particularly useful with sources which have little or no standardization with addresses and therefore require a large amount of guesswork to correctly parse an address. > Google API usage is subject to charges after surpassing their free usage allowance. Each time you preview or import a location with Google APIs enabled, you incur up to 3 API requests per location parsed. To create a Google API, you need to follow the same steps as you would when [setting up a Google Maps API key](https://wp-events-plugin.com/documentation/google-maps/api-key/). The only difference when creating a key for I/O is that you would want to restrict your key by IP Address rather than HTTP referrers. The libraries that need to be enabled is the Geocoding and Places API (which may already be enabled for Google Maps in EM). Once you have obtained your API key, visit Events I/O > Settings > General (Tab) > General Options and enter your Google Server API key there. ## Importing & Exporting with Google Sheets URL: https://wp-events-plugin.com/documentation/importing-exporting/google/google-sheets/ This page will provide specific information about importing and exporting via the Google Sheets service using the Google I/O add-on for [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/). Only major differences from common options are mentioned here, for more general information see the [importing](https://wp-events-plugin.com/documentation/importing-exporting/import-setup/) and [exporting](https://wp-events-plugin.com/documentation/importing-exporting/export-setup/) documentation. Google Sheets will import and export the same way as CSV and Excel, please refer to the [spreadsheet import/export documentation](https://wp-events-plugin.com/documentation/importing-exporting/spreadsheets/) for more general instructions. The main difference being selecting where to import/export and that data is pushed to a destination sheet when exporting (which is why syncing is possible). ### Selecting Sheets When importing or exporting, you will need to select the desired account associated with the spreadsheet you would like to work with. The text field next to it will be the URL to the desired spreadsheet. This is the same URL used to access the spreadsheet, and if you would like to work with a specific sheet within that spreadsheet you need to click on that sheet first so that you have the correct URL. ### Syncing Sheets Google Sheets I/O supports syncing, meaning you can create an import or export and sync events so they are not added twice in either direction and are also updated accordingly. However, given the nature of Spreadsheets, there are some caveats. When importing we strongly suggest you provide an Event ID when using field mapping, otherwise it may not be possible to differentiate a new event from an updated event. Exporting items will update the last known row the item was previously exported to, any new rows are added to the bottom of the sheet below the last row of data. Therefore, if you will be editing the sheet after exporting by adding new rows, you should always add new data to the bottom of the sheet. Alternatively, you can create a new export to the same sheet and all exported data will be added to the bottom of the sheet (this may result in duplicates). ### Importable/Exportable Information Google Sheets will work just like a regular spreadsheet, therefore you can refer to the documentation about [importing and exporting spreadsheets with I/O](https://wp-events-plugin.com/documentation/importing-exporting/spreadsheets/). ## Importing and Exporting with Google Calendar URL: https://wp-events-plugin.com/documentation/importing-exporting/google/google-calendar/ This page will provide specific information about importing and exporting via the Google Calendar service using the Google I/O add-on for [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/). Only major differences from common options are mentioned here, for more general information see the [importing](https://wp-events-plugin.com/documentation/importing-exporting/import-setup/) and [exporting](https://wp-events-plugin.com/documentation/importing-exporting/export-setup/) documentation. ### Selecting Calendars When importing or exporting, you will be able to choose a calendar from a dropdown which is grouped by your [connected accounts](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). ### Syncing Calendars Google Calendar I/O supports syncing, meaning you can create an import or export and sync events so they are not added twice in either direction and are also updated accordingly. ### Importable/Exportable Information Google Calendar events allow a limited amount of information to be read/written by I/O via their API. The fields that are imported/exported are: - Event Title - Summary/Description - Date/Time - Timezone - Location (text only, no coordinates) - Event Link (exports only, link to your event page) #### Importing Locations Locations are stored in Google as a full single line of text. There is no particular required format, therefore especially when importing you may get varying address information. For example, if importing a personal calendar, it's perfectly acceptable to add 'home' as your location when adding a Google calendar event, which will not translate well into an Events Manager location. In these cases, if you cannot be sure that every event in the calendar has a strict format we recommend you use the Google API to improve or guess your locations when importing via locations. ## Importing and Exporting with Meetup.com URL: https://wp-events-plugin.com/documentation/meetup/ This page will provide specific information about importing and exporting to/from meetup.com using the Meetup I/O add-on for [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/). Only major differences from common import/export options are mentioned here, for more general information see the [importing](https://wp-events-plugin.com/documentation/importing-exporting/import-setup/) and [exporting](https://wp-events-plugin.com/documentation/importing-exporting/export-setup/) documentation. ### Installation Meetup I/O is available to Pro+ users and can be obtained from the [downloads page](https://eventsmanagerpro.com/downloads/). Install the Meetup I/O after installing [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/) just like you would [install the Events Manager Pro plugin](https://wp-events-plugin.com/documentation/installation/). ### Setting Up and Connecting Meetup I/O requires setting up an OAuth consumer. This is currently only available to users with a Meetup Pro subscription who can [apply for an OAuth consumer](https://secure.meetup.com/meetup_api/oauth_consumers/create/). One important piece of information needed is the redirect URL, which can be obtained from your _WP Dashboard > Events I/O > Settings > Server-Side Credentials > Meetup_, although this can be modified afterwards. Once your OAuth consumer is approved, visit your [OAuth consumers page](https://secure.meetup.com/meetup_api/oauth_consumers/) to obtain the member app ID/Key and Secret and enter them into the settings page above. After following these instructions, you'd proceed to [connect your OAuth accounts](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). ### Selecting Import/Export Sources #### Importing When importing, you will be provided with a dropdown, grouped by [connected accounts](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). Each account will allow you to choose from either a Group, Single Event, My Events, RSVP'ed events. **Group and Single Events** requires a URL to the group or event page. If this group is private ensure you have chosen an account with access to it. **My Events and RSVP'ed events** will choose events the account has created or has RSVP'ed to. #### Exporting You are only allowed to export events to groups that you are an organizer of. These groups will be displayed in a dropdown, grouped by [connected accounts](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). If you do not see the group you'd like to export to, chances are you don't have the right privileges to do so. > _If you are testing out the Meetup API, you can join the [Meetup API Testing Group](https://www.meetup.com/Meetup-API-Testing/) and then request to become an organizer. We suggest you limit your exports to 1 event, because you're asked to delete created events after you're done, which can only be done one at a time._ ### Syncing Events Meetup I/O supports syncing, meaning you can create an import or export and sync events so they are not added twice in either direction and are also updated accordingly. ### Importable/Exportable Information Google Calendar events allow a limited amount of information to be read/written by I/O via their API. The fields that are imported/exported are: - Event Title - Summary/Description _(exports allow text only, no images/html)_ - Date/Time - Timezone - Event Featured Photo - Location and Coordinates _(if supplied)_ - Event Link _(imports only, link to meetup.com event)_ - Custom Meta _(if available)_ - Booking price _(lowest ticket price when exporting)_ - Booking currency - Available number of bookings - Confirmed bookings _(import only)_ - Bookings URL _(import only)_ #### Importing Locations Locations data provided by meetup.com is structured, meaning relevant information such as address, city, country and coordinates are provided as individual data, meaning address information is pretty accurate. Therefore, using Google API services to guess addresses, in this case, is probably not necessary. Bear in mind that the availability of this information depends on the information provided by the event organizer. In some cases, Google API location services may help where address information is incomplete. ## Importing with Facebook URL: https://wp-events-plugin.com/documentation/facebook/ This page will provide specific information about importing from Facebook using the Facebook I/O add-on for [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/). Only major differences from common import options are mentioned here, for more general information see the [importing](https://wp-events-plugin.com/documentation/importing-exporting/import-setup/) documentation. > _Due to restrictions imposed by Facebook on their API, events cannot be exported to Facebook, and the events you can import are restricted either to events your account has interacted with (i.e. expressed interest or confirmed attendence), events created by you or events belonging to a group or page your account is an administrator of._ ### Installation Facebook I/O is available to Pro+ users and can be obtained from the [downloads page](https://eventsmanagerpro.com/downloads/). Install the Facebook I/O after installing [Events Manager I/O](https://wp-events-plugin.com/documentation/importing-exporting/) just like you would [install the Events Manager Pro plugin](https://wp-events-plugin.com/documentation/installation/). ### Setting Up and Connecting Facebook I/O requires you to [register a Facebook App](https://developers.facebook.com/docs/apps/#register) in the [developers area](https://developers.facebook.com/apps/). On the basic settings page of the app, you need to ensure your domain is added in the 'Valid App Domain' setting page. Additionally, you will need to add the Facebook Login product to your app, and supply the redirect URL as shown in _WP Dashboard > Events I/O > Settings > Server-Side Credentials > Facebook_ Once your app is set up, copy the App ID and Secret from the Facebook App Basic Settings page into the settings page above. After following these instructions, you'd proceed to [connect your OAuth accounts](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). #### App Verification and Development Mode Facebook has lengthy times for app validation. We recommend you try getting your app validated in the event that they change their policy in the future. However, in the meantime whilst you wait, you can keep your app in development mode and use I/O, however, any users you'd like to use the app need to be assigned a role in the Facebook App. This is particularly useful if you only plan to connect to Facebook with accounts belonging to your team. ### Selecting Import Sources When importing, you will be provided with a dropdown, grouped by [connected accounts](https://wp-events-plugin.com/documentation/importing-exporting/connecting-to-oauth-accounts/). Each account will allow you to choose from either a Page/Group, Event, My Events, Created Events, Attending, Maybe, Declined, and Awaiting Reply Page/**Group and Single Events** requires a URL to the group or event page. The account must be an administrator of this page/group or be the author of the event if it doesn't belong to a group/page they administer. **My Events** will import all events associated with the user, including event they have expressed interest in or have RSVPed to. **Created Events, Attending, Maybe, Declined** and **Awaiting Reply** will import events with the selected status of the associated user. ### Syncing Events Facebook I/O supports import syncing, meaning you can create an import or export and sync events so they are not added twice in either direction and are also updated accordingly. Note that syncing is applied for each import job created so if you create another import job duplicates are possible. ### Importable/Exportable Information Google Calendar events allow a limited amount of information to be read/written by I/O via their API. The fields that are imported/exported are: - Event Title - Summary/Description - Date/Time - Timezone - Event Featured Photo - Location and Coordinates _(if supplied)_ #### Importing Locations Locations data provided by Facebook is structured, meaning relevant information such as address, city, country and coordinates are provided as individual data, meaning address information is pretty accurate. Therefore, using Google API services to guess addresses, in this case, is probably not necessary. Bear in mind that the availability of this information depends on the information provided by the event organizer. In some cases, Google API location services may help where address information is incomplete. ## WooCommerce User Fields URL: https://wp-events-plugin.com/documentation/woocommerce/woocommerce-user-fields/ > **Info:** Our WooCommerce integration add-on is now sold exclusively on WooCommerce, documentation specifically about this add-on [can be accessed here](https://woocommerce.com/document/events-manager-for-woocommerce/). ## Zoom Meetings URL: https://wp-events-plugin.com/documentation/location-types/zoom/meetings/ Zoom Meetings are [Event Locations](https://wp-events-plugin.com/documentation/location-types/) and are available once you have [installed and set up](https://wp-events-plugin.com/documentation/location-types/zoom/) the free Events Manager for Zoom add-on. ### Creating/Editing Zoom Meeting Events When creating an event, choose Zoom Meeting as your location type. A new meeting will be created for you when you save your event, which will inherit the name, date/time and description excerpt (with a link to your event page) of your event. Additionally, you will see an option to show/hide advanced options. These options are exactly the same as the options you'll find when creating meetings on Zoom itself. You can see all the options highlighted on their documentation, [adding a meeting via the web](https://support.zoom.us/hc/en-us/articles/201362413-Scheduling-meetings). Editing the event title, name and description, or any of the advanced zoom meeting options will automatically update your meeting. #### Helpful meeting links Once an event has been created (along with the corresponding zoom meeting), you will be provided with a few helpful links just above the advanced options for your meeting. - **Meeting ID -** Useful when joining a meeting directly via the Zoom App. - **View/Edit link** - View your meeting on the zoom.us admin area. - **Registration URL** - A link to register, if registrations are enabled. See "Registrations and Bookings" further down for more information. - **Join URL -** This is a universal Join URL which anyone can use to join the meeting directly. See "Registrations and Bookings" for more info. - **Start Meeting URL -** A direct link to start for **hosts only**. Do not share this with anyone since they can start your meeting as a host instead of you. ### Displaying Meeting Information We have included some [placeholders](https://wp-events-plugin.com/documentation/placeholders/) and [conditional placeholders](https://wp-events-plugin.com/documentation/conditional-placeholders/) and [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/) to help you search and display your meeting information. We recommend wrapping placeholders in conditional placeholders so that non-Zoom Meeting events will not attempt to display it. #### Conditional Placeholders > _\{has\_event\_location\_zoom\_meeting}...\{/has\_event\_location\_zoom\_meeting}_ Displays the ... contents only if the event has a Zoom Meeting as the event location. > _\{no\_event\_location\_zoom\_meeting}_..._\{/no\_event\_location\_zoom\_meeting}_ Displays the ... contents if the event specifically does NOT have a Zoom Meeting event location. #### Placeholders You can use the following bits of information with the following placeholders: - _**#\_EVENTLOCATION\{id}**_ - Meeting ID - **_#\_EVENTLOCATION\{join\_url}_** - Universal (not unique) Join URL - **_#\_EVENTLOCATION\{password}_** - Password for entering the meeting. - **_#\_EVENTLOCATION\{registration\_url}_** - URL for registering to the meeting. Useful only if you do not want to use Events Manager for bookings and would like users to register directly on the Zoom website. - **_#\_EVENTLOCATION\{start\_url}_** - Link for meeting host to start the meeting. **Warning**! Use wisely, anyone with this link can start the meeting as the host, for safety reasons this link will be set to # if the user viewing it cannot manage the event in question (i.e. the owner or an events admin). #### Filtering Zoom Meeting events The _location\_type_ search attribute will support the value _zoom\_meeting_ for filtering events with Zoom Meetings. For example: > \[_events\_list location\_type="zoom\_meeting"_\] ### Meeting Registration Types Events Manager provides a flexible layer of access control on top of Zoom so that users can potentially book directly via Events Manager and automatically have a registration created for the meeting. Zoom Meetings allow 3 types of access levels. - **Open meeting** - Users can simply join the meeting without a required invitation. - **Registered users without approval** \- A registration form must be filled on Zoom.us, then they can join the meeting automatically via a link sent by email. - **Registered users with approval -** After filling the registration form, meeting admins must approve the registrant before they receive a meeting join link by email. All meeting types can add a couple of additional access security layers, such as passwords, requiring a zoom.us account and restriction to specific email domains (for companies), all of which can be configured within the advanced meeting settings whilst editing an event. You can choose the access level to your meeting by clicking the _show advanced options_ link in your Zoom Meeting settings and scrolling down to the _Registration_ section. #### Open Meetings (No registration required) Open meetings do not require registration. If you want an open meeting, you can disable bookings for your event. Open meetings will not sync bookings made on Events Manager and vice-versa. By selecting _No registration required_ your visitors would not need to sign up for the event, they can simply join with a link. There is a single join link in this case that anyone with the link can use to join the event. This join link is available on your event edit page (see further up) or can be displayed via the _#\_EVENTLOCATION\{join\_url}_ placeholder. It is still possible to enable registrations on your site, however you should include the join URL and password (if set) via the booking confirmation emails. #### Registered Meetings (with or without approval) Events Manager essentially treats registration with or without approval the same way, and will only create a pre-approved registration on Zoom once a booking is approved on Events Manager. Bookings made on Zoom directly will not sync with Events Manager bookings. We recommend you keep registrations with approval required, this means that if your registration link directly on zoom.us is somehow obtained, any bookings made there will remain pending. Since bookings will only result in a Zoom registration when a regular booking is approved, you can add all the functionality of Events Manager into your bookings process, which we'll cover in the Bookings section further down. #### "Open" Registration Meetings A third option with Events Manager is enabling registration for Zoom Meetings (with or without approval), and simply directly linking to the registration form on zoom.us. In this case, you can disable bookings for the event itself and link users directly to the Zoom registration form, bypassing booking via Events Manager. ### Bookings via Events Manager Letting Events Manager handle bookings to your meetings is where the possibilities open up, since you are able to do many more things within the booking process. The main highlights are: - Enable payments for meetings and webinars - Automatic syncing of bookings (EM to Zoom) - Add custom questions via your booking form - Multiple attendees in one event booking with our Attendee Forms - Book many events (with/out multiple attendees) at once with Multiple Bookings Mode #### How it works When you set a Zoom Meeting or Webinar as your event location, bookings made via Events Manager will automatically create a registration in Zoom **once the booking has been approved**. If a booking requires approval a registration is not immediately created until it is approved. By default, a booking will create a single Zoom registration belonging to the email and name of the user that made the booking, see further down for custom questions which can also be supplied to the Zoom registrant details. If you want each space booked to have their own meeting invitation, see the Attendees section further down. **Important Note:** Zoom does not have a way of preventing registrations from being made on its own site, so therefore anyone with a link to the Zoom Registration form can potentially book your event, bypassing Events Manager. Therefore, we strongly recommend you NOT display registration links if you want people to book via Events Manager, and additionally keep approval enabled on Zoom, just in case, since any non-EM registrations would still require manual approval. #### Enabling payments Since payments are handled by Events Manager before a booking is approved, there is no difference between having a regular paid event or a Zoom paid event if booking via Events Manager. All you need to do here is ensure you've [correctly set up a payment gateway](https://wp-events-plugin.com/documentation/payment-gateways-overview/), which you may have already done. Once payment is made and the booking is approved, only then will the Zoom registration occur. #### Registering multiple attendees If you would like to register an invitation for each space booked within a single booking, you will need to create a [custom attendee form](https://wp-events-plugin.com/documentation/how-to-add-an-attendee-form/) with the correctly named field IDs. If when making a booking, the attendee forms do not have these correct field names, it will revert to creating one registration to the Zoom Meeting/Webinar in the name/email of the person who made the booking. We have made this easy to do with a single click, which will create a new attendee form containing all the standard Zoom questions. Once you have connected [Events Manager with your Zoom account](https://wp-events-plugin.com/documentation/location-types/zoom/), you will see a link to create an attendee form template in your EM Zoom settings page: Clicking this will create a new attendee form called Zoom Attendee. The minimum required fields here are Email, First Name and Last Name. See the 'Custom booking form questions' below for information about customizing your booking forms. Once you have your attendee form, remember to assign it as your attendee form when creating a Zoom meeting/webinar event. You can also modify any of the fields as needed (including name and email field), provided you maintain the same Field ID. Note that any additional field which does not have the standard Field ID as provided in the template will be treated as a custom question). #### Custom booking form questions For regular booking forms, you can add the same fields as the attendee fields, apart from name/email which is automatically obtained by the user WordPress account (or no-user details). Additionally, if you have mapped user fields in the "_Common User Fields for Gateways_", these will be also used to populate standard Zoom question fields, and do not need to use the same ID as attendee form fields. We suggest creating a custom attendee form and copying over any fields you'd like to use. Any other "non-standard" fields with a different ID to these fields will be treated as a custom question. #### Displaying invitation information Since Zoom registrations are created when a booking is approved, we suggest including Zoom Meeting/Webinar information in the confirmation email. Aside from the regular placeholders further up, you can also use the **#\_BOOKINGZOOMJOINLINK** or **#\_BOOKINGZOOMJOINURL** Placeholder to generate a unique URL for each attendee. Currently, via Events Manager, an email is only sent to the person who made the booking. However, you can also enable email confirmations to be sent directly from Zoom via your meeting/webinar settings when editing an event, which would also email each attendee separately. #### Multiple Bookings Mode If you would like a user to make multiple bookings to different events, and then pay or confirm via a checkout flow, you can use our Multiple Bookings Mode feature, which will automatically create Zoom registrations for each event. This will work much the same way as if the event was booked separately on its own, and each event has its own settings, such as custom attendee/booking forms and meeting/webinar settings. ## Zoom Rooms URL: https://wp-events-plugin.com/documentation/location-types/zoom/rooms/ Zoom Rooms are [Event Locations](https://wp-events-plugin.com/event-locations/) and are available once you have [installed and set up](https://wp-events-plugin.com/documentation/location-types/zoom/) the free Events Manager for Zoom add-on. ### Creating/Editing Zoom Room Events When creating a Zoom Room event, simply select it as your event location type. When doing so, you'll see an additional dropdown menu containing all your available Zoom Rooms. Select the one you'd like to use. Please note that due to lack of API functionality, it is not possible to create or reserve meetings in the Room itself at this time. Displayed events are mainly for informational purposes. ### Displaying Room Information We have included some [placeholders](https://wp-events-plugin.com/documentation/placeholders/) and [conditional placeholders](https://wp-events-plugin.com/documentation/conditional-placeholders/) and [search attributes](https://wp-events-plugin.com/documentation/event-search-attributes/) to help you search and display your room information. We recommend wrapping placeholders in conditional placeholders so that non-Zoom Room events will not attempt to display it. #### Conditional Placeholders > _\{has\_event\_location\_zoom\_room}...\{/has\_event\_location\_zoom\_room}_ Displays the ... contents only if the event has a Zoom Room as the event location. > _\{no\_event\_location\_zoom\_room}_..._\{/no\_event\_location\_zoom\_room}_ Displays the ... contents if the event specifically does NOT have a Zoom Room event location. #### Placeholders You can use the following bits of information with the following placeholders: - _**#\_EVENTLOCATION\{id}**_ - Unique Identifier for the Zoom Room - **_#\_EVENTLOCATION\{room\_id}_** - Globally Unique Identifier for the Zoom Room, used in APIs - **_#\_EVENTLOCATION\{name}_** - The name of the room #### Filtering Zoom Room events The _location\_type_ search attribute will support the value _zoom\_room_ for filtering events with Zoom Rooms. For example: > \[_events\_list location\_type="zoom\_room"_\] ## Zoom Webinars URL: https://wp-events-plugin.com/documentation/location-types/zoom/webinars/ Zoom Webinars are [Event Locations](https://wp-events-plugin.com/event-locations/) and are available once you have [installed and set up](https://wp-events-plugin.com/documentation/location-types/zoom/) the free Events Manager for Zoom add-on. Webinars are nearly identical to how Meetings work. Therefore, we would point you to the [Zoom Meetings documentation](https://wp-events-plugin.com/documentation/location-types/zoom/meetings/), and we'll highlight the differences here. ### Creating/Editing Zoom Webinar Events Instead of "Zoom Meeting", choose "Zoom Webinar" from the dropdown list. Additionally, you will have a few more options available within the advanced settings, which are additional features available to webinars, such as enabling video for panelists. ### Displaying Webinar Information #### Conditional Placeholders > _\{has\_event\_location\_zoom\_webinar}...\{/has\_event\_location\_zoom\_webinar}_ Displays the ... contents only if the event has a Zoom Webinar as the event location. > _\{no\_event\_location\_zoom\_webinar}_..._\{/no\_event\_location\_zoom\_webinar}_ Displays the ... contents if the event specifically does NOT have a Zoom Webinar event location. #### Filtering Zoom Webinar Events The _location\_type_ search attribute will support the value _zoom\_webinar_ for filtering events with Zoom Webinars. For example: > \[_events\_list location\_type="zoom\_webinar"_\] ## Mobile App Notifications URL: https://wp-events-plugin.com/documentation/mobile-app/ The Events Manager mobile app can send a push notification to your phone or tablet the moment something happens on your site: a new booking comes in, a booking is cancelled, or a new event is published. You decide, as a site administrator, which types of notification are available, and each person then chooses the ones they want from inside the app. This page covers how to switch the feature on for your site and how each user turns on the notifications they care about. The app is available for iOS and Android; see [mobile apps](https://wp-events-plugin.com/features/mobile-apps/) for how to install it and connect your site. ### What you can be notified about Events Manager has three built-in notification types: | Notification | When it is sent | What the message says | | --- | --- | --- | | New bookings | Someone makes a booking on one of your events | "New booking received" | | Booking cancellations | A booking on one of your events is cancelled | "A booking was cancelled" | | New events | A new event is published on your site | "A new event was created" | In every case the title of the notification is the event's name, so you can see which event it relates to without opening the app. Tapping a notification opens the app. Add-ons can register further types. Anything Events Manager Pro or another extension adds appears in these same settings automatically, with no app update needed. ### Before you start To receive push notifications you need: - The Events Manager mobile app installed on your device, with your site added to it. - Notifications switched on for the site by an administrator (Step 1 below). - A WordPress account on the site with permission to manage the relevant bookings or events. - Notifications allowed for the app in your device's own settings. The app asks for this the first time you turn notifications on. In-app notifications are available on sites running an Events Manager Pro licence, or with an app subscription. ### Step 1: Turn on notifications for your site An administrator does this once, in WordPress. 1. Go to **Events → Settings → General** and find the **Mobile App Notifications** section. 2. Set **Enable push notifications?** to **Yes**. 3. Under **Notification types**, choose which notifications are available on this site. Each type has its own Yes/No, so you can offer some and not others. 4. Save your changes. [Image: The Mobile App Notifications section of Events Manager settings] The types you switch on here decide what is available on the site. Each user still picks which of those they personally receive, in the app. Turning the main switch off again stops every notification for the site and hides the notification options in the app. Turning a single type off stops that one type for everyone, whatever their personal preference. ### Step 2: Turn on notifications in the app Everyone who wants notifications does this on their own device. 1. Open the Events Manager app and choose the site you want from the **Sites** screen. Notification settings apply to whichever site is active, so switch sites here to set up another. 2. Open the **Notifications** tab. 3. Turn on **Allow notifications**. The first time you do this, your device asks for permission to send notifications: choose Allow. 4. Turn on each notification type you want. Where you manage other people's bookings or events, a second switch appears so you can include those too (see below). Your choices are saved to the site straight away and remembered on your device. ### Who receives what Notifications follow the same permissions as the rest of Events Manager, so people only ever receive notifications for things they are allowed to manage. - **Event owners** are notified about their own events and the bookings made on them. - **Managers and administrators** who can manage other people's bookings, or edit other people's events, see an extra switch on each notification type. Switch it on to also be notified about bookings and events that belong to other users, not only your own. This suits a central organiser or moderator who oversees everyone's events. If your account has no permission for a given type, that type does not appear in your app and you will not receive it. ### Notifications across more than one site The app can be connected to several Events Manager sites at once. The master **Allow notifications** switch and your per-type choices are set separately for each site, so you can have them on for one site and off for another. Each site's administrator controls which types are available on their own site. Booking information never leaves the site it belongs to. Each site sends its own notifications directly to your device, so nothing is routed through a third party. ### Troubleshooting **I turned notifications on but nothing arrives.** Work through these in order: - Check that an administrator has set **Enable push notifications?** to **Yes** under **Events → Settings → General**, and that the type you expect is switched on there. - Check that **Allow notifications** is on for that site in the app, and that the individual type is turned on. - Check that notifications are allowed for the app in your device's own settings. If you declined the first time, the app cannot show them until you enable them there. - Confirm your account has permission to manage the bookings or events in question. You only receive notifications for events you can manage. **The Notifications tab asks me to upgrade.** In-app notifications need an Events Manager Pro licence on the site, or an app subscription. The app shows the available plans. **The app says the site doesn't support notifications yet.** Make sure the site is running a version of Events Manager that includes app notifications and that it can be reached, then reopen the Notifications tab. ## AI / MCP Setup URL: https://wp-events-plugin.com/documentation/ai/ Events Manager 7.3 onwards can be controlled by an AI assistant. You can ask Claude, ChatGPT, Cursor, VS Code, Codex, or any other AI client that supports the **Model Context Protocol (MCP)** to list your events, check booking availability, create or update an event, manage bookings, and more — all in plain language, while WordPress keeps its normal permissions in place. This page walks you through it. The first half is written for site owners who just want to point an AI app at their site. The second half goes into the technical details for developers who want to script, embed, or customise the connection. ### See it in action