Working with CiviCRM 4.6 in WordPress

The release of CiviCRM 4.6 marks a watershed moment for integration with WordPress. Read on for a guide to what's new and what you can do with these cool new features.

CiviCRM 4.6 opens a world of new possibilities for developers and administrators of WordPress-based systems. CiviCRM administrators will be happy to hear that they can now reliably use shortcodes in both static pages and chronological posts. CiviCRM content inserted via a shortcode can even appear in blog archives now. For developers, the big news is that for the first time, multiple plugins can receive callbacks from CiviCRM's hook system. What this means is that WordPress developers can now begin building an ecosystem of plugins to rival the ecosystem of Drupal modules.

Anatomy of a plugin

This section is mostly aimed at site administrators but is also recommended for developers who want to know more about WordPress integration. The new version of the plugin clearly and explicitly handles CiviCRM in the four contexts in which it may be called:

• In WordPress admin
• On the wpBasePage
• via AJAX/snippet/iCal etc
• via a shortcode

So let's have a look at these contexts in turn…

WordPress admin

Using CiviCRM in the WordPress admin hasn't changed visibly. The biggest enhancement is that plugin now invokes CiviCRM properly, so that CiviCRM's resources are only added when the CiviCRM admin page is loaded. Previously they were added on every admin page. This should make things more reliable and speed up the non-CiviCRM sections of the WordPress admin section.

The wpBasePage

Previously, CiviCRM would default to using a website's homepage for public-facing CiviCRM content. This often led to display problems when the homepage was not a static page and no "base page" had been set in CiviCRM's little-known "Settings - WordPress Integration" admin page. From now on, fresh installs of CiviCRM will now auto-create a "base page" for CiviCRM. The new page is called (surprise, surprise!) "CiviCRM" and is where CiviCRM will present its public-facing content by default. Public links in CiviCRM admin will reference this page: so, for example, when you create an event, the public link will point to your base page.

If the plugin detects an existing page by that name (and it has the 'civicrm' slug) it will assume that this is a pre-existing base page and use that instead. To provide as much support for different themes as possible, the template for the base page is assigned to the standard 'page.php' template in the active theme. This can be overridden with the 'civicrm_basepage_template' filter for those who want to use a different one:

// override base page template
add_filter( 'civicrm_basepage_template', 'my_basepage_template' );
function my_basepage_template( $template ) {
  return 'my-template-name.php';
}

AJAX/snippet/iCal calls

Most people are unlikely to use these, but for those who do, it may be worth noting that AJAX/snippet/iCal calls exit much earlier now, which should make them more efficient.

And lastly... Shortcodes

The most noticeable change to shortcodes is the addition of a "Hijack" option in the CiviCRM Shortcode Generator dialog box. What does this do? Well, as long as you only insert a single shortcode into the content, the the shortcode will "hijack" the containing page or post - it will overwrite the HTML title, page title and page content with the relevant parts of the CiviCRM entity that the shortcode represents. This is a really nice way to present CiviCRM content on your site.

You do not have to hijack the containing page, however - you can just insert a shortcode anywhere into a page or post and choose not to hijack it. This will render the CiviCRM content in the appropriate place in thepost content. Whatever you decide to do, you can now have comments enabled on the post or not - previously, comments were automatically disabled.

Multiple shortcodes are now handled quite nicely. When the plugin encounters them (whether on an archive or within a single page) it renders the title and, optionally, the summary/description of the entity with a link to either the containing page or the base page, where the content can be viewed with full functionality.

WordPress plugin development

Let's turn now to the topic of plugin development. Be warned that this gets pretty technical - so if you're not a plugin developer you might want to head off now, make yourself a nice cup of tea and reflect on how much nicer your WordPress CiviCRM site is going to be. You may like to take a look at some of the new plugins that you can now use on your WordPress site, which are listed at the end of the article. If you're a developer, however, please read on - you may even enjoy the following...

First, a bit of background context. Prior to 4.6, in CiviCRM's hook system, there was only one callback that could be defined for a particular hook. So, for example, when CiviCRM fired 'hook_civicrm_pre' the only callback that received data from this event was the function 'wordpress_civicrm_pre()'. Clearly, this prevented multiple plugins from co-existing because of the function name collisions if they both wanted to receive callbacks from 'hook_civicrm_pre'.

With the release of 4.6, there is complete compatibility with the WordPress actions and filters system (well almost - more on that later). The rule for targeting the hook is to remove the 'hook_' prefix when you create the filter or action. So, if your plugin wants to receive callbacks from 'hook_civicrm_pre', you can do it in global scope like this:

// hook into civicrm_pre
add_filter( 'civicrm_pre', 'my_plugin_pre_callback', 10, 4 );
function my_plugin_pre_callback( $op, $objectName, $objectId, &$objectRef ) {
  // your code here
}

And of course, if you write your plugins in object-oriented code, you can target your class methods as callbacks the way you normally would:

class Civi_Foo {
  function __construct() {
    add_filter( 'civicrm_pre', array( $this, 'my_pre_callback' ), 10, 4 );
  }
  public function my_pre_callback( $op, $objectName, $objectId, &$objectRef ) {
    // your code here
  }
}
new Civi_Foo;

Just remember that because the parameters are passed by reference, you can modify them in your callback if you need to - and that modification will be passed on to the next callback in its modified state. You can use WordPress hook priorities to easily determine (and modify) what the order of callbacks is.

The caveat I mentioned earlier? Ah, yes. Because of the way some CiviCRM hooks are constructed, the WordPress Plugin API cannot be used for hooks that require a return value, because they are seemingly incompatible with 'apply_filters' and 'apply_filters_ref_array' which expect the first parameter passed to the hook to be the one returned. Luckily, there are very few of them at present. The full list is:

• 'hook_civicrm_upgrade'
• 'hook_civicrm_caseSummary'
• 'hook_civicrm_dashboard'

Any plugins that need to have callbacks for these hooks must register a unique code with CiviCRM. The code must be a valid part of a PHP function name, so stick to letters and underscores. This allows the plugins to use global scope functions as callbacks in the form:

{code}_{hookname}

So, for example, a plugin that registers the prefix 'my_unique_plugin_code' and wants a callback from 'hook_civicrm_dashboard' must create a function called:

function my_unique_plugin_code_civicrm_dashboard( $contactID, &$contentPlacement ) {
  // your code here
}

If a plugin needs to keep its logic inside a class, it will have to route the call to the class method from the global function. If you're used to writing Drupal modules, all of this should be quite familiar, except that Drupal does the 'module_prefix' discovery for you. To register your plugin's code, use the 'civicrm_wp_plugin_codes' filter:

add_filter( 'civicrm_wp_plugin_codes', 'register_my_civicrm_plugin_code' );
function register_my_civicrm_plugin_code( $plugin_codes ) {
  // add our unique code and send back to CiviCRM
  $plugin_codes[] = 'my_unique_civicrm_plugin_code';
  return $plugin_codes;
}

So then, because there are no more function name collisions, there are no more restrictions on the number of plugins that can be written to work simultaneously with CiviCRM. So go forth, WordPress plugin developers, and multiply those plugins!

Further Resources

Here's a list of some of my CiviCRM-related plugins. You can install some of them directly from your WordPress admin. Have a look at them to see the new hook system in operation - and, if you can, please create Pull Requests if you find any bugs. I'd love to have feedback on any of these plugins.

CiviCRM WordPress Profile Sync

This keeps the "First Name", "Last Name", "Email Address" and "Website" fields of a WordPress (and BuddyPress) user profile in continuous sync with a CiviCRM contact: https://wordpress.org/plugins/civicrm-wp-profile-sync https://github.com/christianwach/civicrm-wp-profile-sync Use this in combination with BP XProfile WordPress User Sync to enforce the use of "First Name" and "Last Name" in BuddyPress communities: https://wordpress.org/plugins/bp-xprofile-wp-user-sync/

CiviCRM WordPress Member Sync

Keeps a WordPress user's capabilities (rather than roles - since multiple roles is a Drupal thing - although the plugin supports roles too) in sync with a CiviCRM membership. Works seamlessly with the popular Members plugin: https://wordpress.org/plugins/civicrm-wp-member-sync/ https://github.com/christianwach/civicrm-wp-member-sync

CiviCRM Admin Utilities

Modifies and enhances CiviCRM's behaviour in single site and multisite WordPress installs. You can choose which post types the CiviCRM shortcode button appears on and enhance the appearance of the CiviCRM menu. In multisite, you can restrict the appearance of CiviCRM on sub-sites without disabling it - useful in combination with CiviCRM WordPress Profile Sync, for example, where you want to track profile changes on sub-sites: https://wordpress.org/plugins/civicrm-admin-utilities/ https://github.com/christianwach/civicrm-admin-utilities

BuddyPress Groups CiviCRM Sync

A port of the Drupal civicrm_og_sync module that enables two-way synchronisation between BuddyPress groups and CiviCRM groups. If you're familiar with Organic Groups in Drupal, using this should be straightforward: Coming soon to the WordPress Plugin Directory https://github.com/christianwach/bp-groups-civicrm-sync

/**
 * Disable BuddyPress UI components
 */
function my_bp_disable_ui() {

	// get user
	$user = wp_get_current_user();

	// replace with your capability that allows access
	if ( $user->has_cap( 'civimember_2' ) ) return;

	// cannot favourite
	add_filter( 'bp_activity_can_favorite', '__return_false' );

	// hide friend buttons
	add_filter( 'bp_get_add_friend_button', '__return_false' );
	add_filter( 'bp_get_send_public_message_button', '__return_false' );
	add_filter( 'bp_get_send_message_button', '__return_false' );

	// hide group buttons
	add_filter( 'bp_user_can_create_groups', '__return_false' );
	add_filter( 'bp_get_group_join_button', '__return_false' );

	// hide activity comment buttons
	add_filter( 'bp_activity_can_comment_reply', '__return_false' );
	add_filter( 'bp_activity_can_comment', '__return_false' );
	add_filter( 'bp_acomment_name', '__return_false' );

	// hide bbPress
	add_filter( 'bbp_current_user_can_access_create_reply_form', '__return_false' );
	add_filter( 'bbp_current_user_can_access_create_topic_form', '__return_false' );

	// hide menu
	add_filter( 'bp_use_wp_admin_bar', '__return_false' );
	remove_action( 'admin_bar_menu', 'bp_members_admin_bar_notifications_menu', 90 );
	remove_filter( 'edit_profile_url', 'bp_members_edit_profile_url', 10 );

}
add_action( 'bp_ready', 'my_bp_disable_ui' );

/**
 * Check if current user should be denied access or not
 */
function my_bp_deny_access() {

	// get user
	$user = wp_get_current_user();

	// replace with your capability that allows access
	if ( $user->has_cap( 'civimember_2' ) ) return;

	// hide BuddyPress
	if ( function_exists( 'is_buddypress' ) AND is_buddypress() ) {
		wp_redirect( get_bloginfo( 'url' ) );
		exit;
	}

	// hide bbPress
	if ( function_exists( 'is_bbpress' ) AND is_bbpress() ) {
		wp_redirect( get_bloginfo( 'url' ) );
		exit;
	}

}
add_action( 'wp', 'my_bp_deny_access' );