Event Roles and Capabilities

From version 3.3 on wards, amr-events now has three optional additional roles:

  • Event Contributor
  • Event Editor
  • Event Manager

If you wish to keep your event creation separate from your post creation, these may be useful.  If you are updating the plugin, you may find that you need to force an update of the various roles (even existing admin may need capabilties manually added).  So while one hopes not, just in case:  use a role manager like https://wordpress.org/plugins/members/

Event Capabilities as seen in the members role plugin
Event Capabilities as seen in the members role plugin

Custom post types, taxonomies , capabilities, roles

Are you you getting the browser messages when saving a new custom post type draft?

  • Firefox: “This page is asking you to confirm that you want to leave – data you have entered may not be saved.”
  • Internet Explorer: “Are you sure you want to leave this page”
  • Chrome: “The changes you have made will be lost if you navigate away from this page”
  • “Leave page or Stay on page” when you click save draft on a new custom post type?
What happens when you do not have the right capability
What happens when you do not have the right capability
Leave or Stay message in chrome
Leave or Stay message in chrome

What happens?

You opt to leave and the post was still saved but the custom fields etc do not save.  BUT then you CAN edit the post and then add in the custom fields / meta box without any further problem (what the?)

And of course admin’s have no problem!

Why?

This appears to be because we have said that the custom post type supports the default taxonomies and possibly wordpress is trying to do something with javascript (maybe assign a default category to the custom post type) but the user is not allowed to.  However it also happens when the custom post type has tags but not categories?  But it does not happen if it just has the custom taxonomy (with the assign_terms or assign_terms=>edit_events capability).    The behaviour only occurs with default taxonomies.

Key finding:

If you are allowing your custom post type to be assigned categories and tag taxonomies like normal posts, then ANY role that is required to be able to create the custom post type while default taxonomies are supported, must also have ‘edit_posts’ capability. (Unless you have code to change the default taxonomies, but then you will be messing with the standard posts capabilities)

Arguably the wordpress default capability ‘assign_terms’ should not be mapped by default to ‘edit_posts’ as this is what is making life complicated.  Possibly a contributor should have ‘assign_terms’ capability directly?   Or one might say that it’s the sharing of taxonomies that is causing the complication.

Background

I wanted a role that could create events but NOT also create posts.  Similarly with editors.
Custom roles can be setup to manage custom post types (in this case events) and one can isolate these capabilities.  However when one adds taxonomies (default and custom) into the mix, things get more interesting.

Default taxonomy capabilities for categories and tags

$default_caps = array(
 'manage_terms' => 'manage_categories',
 'edit_terms'   => 'manage_categories',
 'delete_terms' => 'manage_categories',
 'assign_terms' => 'edit_posts',
 );

While one could overwrite these capabilities with say ‘assign_terms’=>’assign_terms’, then one would not be able to assign categories and tags to standard post types without also ensuring that the default roles were assigned the capability ‘assign_terms’.  All achievable, it just seems wrong to have to mess with standard wp and risk breaking other plugins.

Registering custom taxonomy means that in this case ‘edit_events’ capability is enough to be able to assign this custom taxonomy to this single custom post type

'capabilities' => array (
 'manage_terms'=> 'manage_categories',
 'edit_terms'=> 'manage_categories',
 'delete_terms'=> 'manage_categories',
 'assign_terms' => 'edit_events'  // strictly speaking need one for each new posttype ?
 )

 

TIP: while you are testing this all out, a role manager plugin like Justin Tadlock’s members plugin is very helpful.  Roles and their capabilities are saved in the database and unless you ‘remove’ the role and add it again, the capabilties will not update as you might want them to.

I was actually trying to create a custom role that can assign categories, tags and custom taxonomies to your custom post type. If you give these roles ‘manage_categories’, they’ll be able to add new categories BUT still not assign a post to existing categories.  They have to have ‘edit_posts’ or obe has to override the default wp setup.

 

How to change icon images (subscribe to calendar, add to google)

The plugin comes with two sets of default icons (16px and 32 px).  It also includes extra icons that match those for your use.

screenshot of icon listing
some of the available icons

Don’t like those icons?

You could do one or more of the following:

  1. Switch images off
  2. Use Css to replace the text with your own images
  3. Write own formatting routines

Switch images off

You could choose just to have the link text for the actions behind the icons.  See the “Listing events’ settings.

settings screenshot to show you how to switch images off
Switch images off

Use Css to replace the text with your own images

First switch the default  images off and then use css to show your chosen icons instead.

text replaced with image
text replaced with image

There are various techniques that one can use to replace text with an image. The following was used to demonstrate the above replacement using the plugins html classes.

a.icalsubscribe { 
    display: block;
    height: 50px;
    width: 50px;
    background-image: url(http://i.stack.imgur.com/XtpTm.png);
    background-size: 50px 50px;
    text-indent: -9999px;
    overflow: hidden;
}

Some of the link classes that you may wish to define image icons for are:

  • subscribe
  • icalsubscribe
  • addtogoogle
  • hrefaddtogoogle
  • hrefmap
  • timezone
  • refresh

Add the extra css :

  1. Either to your custom themes stylesheet (not to one that gets updated automatically, because you will lose your modifications), or
  2. use something like jetpacks wordpress custom css, or
  3. use a custom ical events list css

Write own formatting routines

See the pluggable files in each plugin folder.  Use the function there as a base for your new function.  Add your function to your custom themes function.php or to your own site specific snippets plugin.

some pluggable functions in amr-icalevents-list

  • add_cal_to_google
  • add_event_to_google
  • amr_ical_showmap
  • amr_show_refresh_option
  • amr_format_tz

some pluggable functions in amr-events

  • amr_subscribe_to_event_series
  • amr_subscribe_to_event

 

Groupings of events, expanding and collapsing the groupings

Events can be grouped in many ways. To set up groupings see this post on event grouping and styling.

Expand and Contract Groupings

To expand and contract groupings, tick the ‘load js’ in the listing events settings

Use js
Use js

and optionally add a shortcode to add text to showall or hideall detail of groupings

[expandall]
[events]
Events collapsed behind groupings
Events collapsed behind groupings
One event grouping expanded
One event grouping expanded

Grouping events

Events can be grouped by date formats or by categories, tags or custom taxonomies.

  • Events can be grouped by days, weeks, months and some funkier options that no one will probably ever use, but I liked the challenge! Actually I imagined one could do some seasonal styling perhaps? each grouping has it’s own css classes, and date/time format
  • Grouping also allows one to do timetables (grouped by day), weekly schedules, or monthly, quarterly or seasonal event views.
  • See how to format the date related groupings here.
  • Each grouping comes with css classes so you could for example do seasonal styling of event groups.
  • By adding in the javascript in the settings, one could also expand and collapse the groupings.

Settings

 

Grouping settings
Grouping settings

Styling Groupings – use the css classes

Example of html produced with css classes
Example of html produced with css classes

Correct Handling of UID, RECURRENCE-ID, SEQUENCE

Modifications to events, especially to an instance of a recurring event, or an update to a modified instance can all seem quite complex.  It’s not that bad once you understand the various bits that you need to provide for the receiving application to make sense of it. See the RFC5545 spec for details.  This tools.ietf.org version or icalendar.org or the kanzaki version.

  • UID – must have and must be unique
  • SEQUENCE – numerically update to indicate which is the latest version
  • RECURRENCE-ID – if modifying a single instance with in a recurring stream.  Note that for a UID and SEQUENCE pair, the “RECURRENCE-ID” value for a recurrence instance is fixed. The event date may change but the “RECURRENCE-ID” does not. It must always be the original date as generated by the RRULE.
  • LAST-MODIFIED – Probably a good idea top update this too

Note also:

  • if a user subscribes to an ICS URL, then the receiving application will check for updates on a regular basis at a frequency determined by it.  It will be seen as a separate calendar.  It will use the SEQUENCE numbers to determine the latest event details. There may be a delay in an update being made on the originating system and it being reflected in the receiving system.   The only reliable way to be sure that users will have updates seen in their calendars is if you can get them to subscribe to the url (or ‘import’ the url, not the file)
  • if an ics file is imported (eg: when event details are sent as an ics file attachment, not as a url, or if the user downloads the ics file from a url and then imports it), then it will be added as events into the calendar chosen by the user.  Updates may overwrite IF the user re-imports the events AND the application is clever enough to match up the UID’s (and RECURRENCE-IDs if it’s part of a recurring set).  It should then also use the SEQUENCE to determine if the details are actually the latest.  There is no way on devices to force a user to load an updated ics file sent to them.

Example

Modifications to recurring rules or rdates and modifications to instances of those recurring rules (themselves already a modification.)

Assume we have a recurring event.  It starts with a SEQUENCE: 0

DTSTART;VALUE=DATE:20140421
 RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=3MO
 UID:1f4irrb5uh6q3cdfsnq15vd00g_R20140421@google.com
 SEQUENCE:0

This generates an infinite set of mondays, including the following

  • 19th May
  • 16th June
  • 21 July
  • 18 August
  • etc

Now, one of the instances gets modified.  (This could be just the description or the actual date.)  A RECURRENCE-ID VEVENT is created for each instance modification and the SEQUENCE NO is updated.   The recurrence-id matches the date in the recurring rule that it applies to. The combination of UID, RECURRENCE-ID and SEQUENCE helps us identify the instance that is being updated.

For a given pair of "UID" and "SEQUENCE" property values,
   the "RECURRENCE-ID" value for a recurrence instance is fixed.
DTSTART;VALUE=DATE:20140721  (ie no date change in this example)
 DTSTAMP:20140720T064853Z
 UID:1f4irrb5uh6q3cdfsnq15vd00g_R20140421@google.com
 RECURRENCE-ID;VALUE=DATE:20140721

Now assume the original RRULE is modified too, perhaps just the description or shock horror, the recurring date definition?  It’s sequence-no is updated too BUT now what should happen to the RECURRENCE-ID instance?  Should it be updated to indicate it is still valid?  IE we now have:

  • generated date 21 July 2014 with UID and SEQUENCE = 3 and
  • RECURRENCE-ID;VALUE=DATE:20140721 with matching UID and SEQUENCE = 3

It appears that perhaps SEQUENCE numbers can increment separately, so one could conceivably receive a file with a RRULE with an equal to or  greater sequence number than a RECURRENCE-ID.       From   this discussion, it is really not clear what the supplying calendar application will do:

Once UID 1/SEQUENCE 0 hits UID 1/SEQUENCE 1 (which would
mean something significant about the set of instances
has changed) all bets are off in regards to RECURRENCE-ID
values that previously existed.

If the UID/RECURRENCE-ID/SEQUENCE matches a generated date from the rrule with same SEQUENCE (ie both have been modified), then what?  One cannot just use eg: LAST-MODIFIED:20140620T200327Z.  Who is to say that a mod of the RRULE was intended to overwrite the RECURRENCE instance?   Quite possibly not.

Some lengthy related discussions here and in other parts of the thread:

Complications that urge one to keep events as simple as possible:

Searching the web seems to indicate some folks believe RECURRENCE-IDS should not change.  So should we assume that if the RECURRENCE-ID vevent is still in the file then it is still valid and should be included.  (What does this mean for syncing and deletions?  IE How does one ‘delete’ an existing event.  Or should one always delete events from an ics file and reload ONLY what’s in the ics file?)