Migrating to version 6.x
This article will provide you with some insight to the changes in Events Manager that may affect those updating to version 5.
This particularly will be useful for those that have made major customizations to the plugin, either via our formatting settings or via overriding our template files.
Given the myriad of ways one can customize Events Manager, and the various setting combinations possible to change the look and flow of our plugin, it's impossible to cover them all here. We will touch on some basic concepts regarding how our new styling may be affecting your styles and how you can get yours back.
Firstly, BACK UP before upgrading!
If you're upgrading any plugin (or software in general for that matter) to a major new version, and it's an integral part of your site, you should definitely be taking a backup before taking the plunge, just in case!
Make sure you back up both your website and your database. In the specific case of Events Manager 6.0, the main parts that receive changes are our core plugin template files and the settings formatting options (which are only overwritten with your consent during the upgrade).
Undoing the upgrade to 6.0
Events Manager 6.0 is completely backward-compatible. If you're unhappy with the changes, you can always obtain previous versions of Events Manager from the wordpress.org plugin page (see bottom of page), or alternatively use a rollback plugin such as WP Rollback
Breaking Changes
Events Manager 6.1 Breaking Changes
With 6.1, we do multiple things to the database:
- add some new tables, wp_em_tickets_bookings_meta and wp_em_bookings_meta
- migrate data from the bookings_meta field within the wp_em_bookings table to the above tables (nothing here gets deleted)
- add a booking_uuid record to the wp_em_bookings table, each with a unique UUIDv4 id for later use in upcoming updates
- change the records in wp_em_tickets_bookings so that every row is 1 space, as well as adding a unique UUIDv4 field, ticket_uuid
The last step is 'breaking', because previous versions of EM would group ticket types up whereas now we consider each space its own ticket for future features.
Whilst you could theoretically roll back the plugin version, we'd advise against editing previous bookings, new bookings should still go through as usual.
Events Manager Pro 3.0
Pro 3.0 changes how attendee information is stored. Previously, attendee information was stored in the booking record within the wp_em_bookings table. This record is moved to the wp_em_bookings_meta table during the 6.1 upgrade and then moved to the wp_em_tickets_bookings_meta by Pro 3.0 afterward. The end result is that each space booked now stores its own attendee information, opening up the possibilities for new features such as QR check-ins (included in 3.0!).
Pro 2.x Backwards Compatibility
Pro 2.x is largely compatible with EM 6.1, despite the shift in storage logic. There is one line of code that you need to change for attendee custom forms to continue working for new bookings. This is located in events-manager-pro/add-ons/bookings-form/attendee-forms.php around line 318:
if( $EM_Form->get_post(false, $EM_Ticket_Booking->ticket_id, $i) ){
Change this to:
[php][/php]
if( $EM_Form->get_post(false, $EM_Ticket_Booking->ticket_id, $EM_Ticket_Booking->ticket_uuid) ){
And you're done!
Rolling Back/Forth - Steps to Take
If you do roll back to version 5 and then initiate an upgrade again, make sure you change the version number in the database, so that when you do eventually upgrade, we'll migrate any extra data you may have accumulated whilst on version 5 again. You can do this by visiting yoursite.com/wp-admin/options.php and looking for the dbem_version and/or the em_pro_version options. Set them to something like 5.9999 and 2.9999 respectively.
UI Changes and how to handle potential breakages
Events Manager 6.0 receives a major UI update, involving changes to CSS, HTML templates, and our formatting options. Whilst the latter two don't get overwritten if you've made overriding changes in your themes and settings, the CSS rules we add may interfere with your customizations. However, in all cases you can revert back to your previous setup and remain in 6.0. What you need to do varies depending on what you've done to your setup and far you've gone with customization.
CSS
If you've made CSS customizations to change our aesthetics in previous templates, then the first step is to lower the intensity of our new CSS styles.
You can easily turn these off in the Settings > General > Styling Options settings section.
If you've made heavy changes, try turning off all the styling - 'Enable All Styling', or make less sweeping changes with the options further down. The further down you go in the options, the more specific you get about what gets overridden with our CSS.
Enable All Styling - Will remove the em class from the wrapping HTML element for all our content, it does most of the styling for specific structure, such as structuring calendars, lists etc. You'll likely want to keep this on.
Theme Styling - This is the more aggressive styling class, called pixelbones which styles more common elements in a theme such as form fields, buttons and regulates spacing and sizing of common elements such as paragraphs, font-sizes etc. This may be what is more likely conflict with theme styling, you can turn this off, or optionally turn parts of it off in the subsequent Individual Options section.
Finally, the Individual Components section will allow you to enable both options mentioned above, but for specific subsets of our plugin, such as an events list, event calendar etc.
As you can see, you have many options here, you can play with these settings turning them on/off as you wish, if the results aren't what you wanted, turn it back on again and there are no side-effects.
Formatting Settings
Most users will most likely have touched our formatting settings in one way or another. The formatting settings you see on our settings page are all stored in your database. We don't overwrite this, but do offer the option to preview them in the new update, migrate (copy them);
Migration Options
Preview mode will temporarily short-circuit all the formatting settings on your settings page and use the ones we store as template files (this is new we'll touch on this further down).
If you're happy with all the formatting changes, you can do a complete reset of your formatting settings by hitting the 'Migrate Formats' button. With this, we take all our default placeholder formatting settings and overwrite your settings in the database. This can be undone! Once you press that button, you'll get one last chance to confirm your changes, or undo and go back to the screenshot above:
Clicking Undo will revert your previous settings; Dismiss will finalize the migration and delete the temporary 'Undo' data i.e. your old settings. This can't be undone! Therefore, we strongly advise you back up beforehand, particularly the wp_options table which is where all settings info is stored.
Advanced Modes for Formatting Options
Another option you can take is dismissing this migration option in the first window, and playing with our new Advanced Mode settings, which you'll find in the formatting tab;
This is now a permanent fixture, and our answer to frequent requests for making the settings page a little simpler, you can revisit it any time.
New Formatting Logic - (Briefly) how it works
Previously, any output for things like event lists, location pages, etc. would take the formatting option you have in your settings page and use that. This remains the same. However, there's now a hardcoded format for each setting in the events-manager/templates/formats/ folder, which is used when you first install the plugin to populate your settings page and subsequently if you have disabled advanced mode. This is useful for two scenarios:
- If you're not an advanced user and don't want to tweak our layouts, then any improvements we make to those formatting options are reflected as and when you update (not something we plan to do often!).
- If you want to override any of these settings via template files, then we'll grab those before our own.
If you disable advanced mode, then we circumvent the settings and use our template files directly, and these settings are hidden.
Default when upgrading - Super Advanced Mode
When upgrading, you will automatically find yourself in Super Advanced Mode, which is basically all the options visible and overridable which is the same as you'd have seen in version 5 (minus a few new additional formatting options).
Advanced Mode - probably your best option
For most users upgrading from 5, Advanced Mode is likely the middle ground you're after. If you disable Super Advanced Mode, you'll see Advanced Mode, which will give you this sort of option within the formatting tab sections:
As you can see, anywhere with formatting options bigger than a simple line will now be hidden with the option to override. That means you can choose to use our defaults or override them with your own as per the settings page.
The nice thing here is that none of your settings are lost vs the full migration option mentioned earlier. They'll remain safely stored in the database. Any overriding options you turn off will simply refer to the template files referred earlier, your previously saved format remains intact and will re-appear if you enable it again.
Tweaking New Formats
Another scenario many will run into is wanting to make a minor tweak to a specific format, such as adding some explanatory text to each event for example. In these cases, you may want to make use of our new formats, but keep your old ones elsewhere.
In this situation, you could load that individual default format into your setting and tweak it accordingly, To do that, click the little icon next to the format you're after, and it'll load the default format from our template file:
Template Files
This remains the same as before, although we now have a new location you could potentially move your files to, the wp-contents/plugin-templates/events-manager or wp-contents/plugin-templates/events-manager-pro
However, we have modified many of these, we suggest you compare the changes, and if possible at least copy´/mimick the class structure we use so that all the JavaScript will find what it needs.
The major change here is the calendar. We've moved all calendar theming to its own calendar folder within the templates root folder. If you overrode either the calendar-full.php or calendar-small.php we'll still refer to those before loading our new templtes.
The Nuclear Option
If you, for whatever reason, want to use our old templates, then you have one drastic option... copy over the entire contents of the templates folder to wp-contents/plugin-templates/events-manager and at that point you'll have the exact same templates you had in Events Manager 5. We don't recommend this, but for some situations where lots of customization has been done, it may be a good first step so you have time to transition over.
Note that some new features depend on our new class structure, so some JavaScript-related functionality may not work as expected, although we've kept previous JS functions intact for now so they refer to old class structures for backward compatibility.
Conclusion
We hope you enjoy the new update! We appreciate there's a lot of changes here, but the end goal is a better plugin with many new features on the way.
This new UI opens the doors to new possibilities, and we hope at this point onwards that the changes to templates/theming/CSS will be progressive, manageable and non-breaking from this point onwards.
There's still some work to be done, particularly around the booking admin areas both on the front and backend. We hope, however, that this will impact far fewer users and ultimately will benefit even the most heavily customized templates with awesome new features!