Customizing Publicize Sharing Behavior

Publicize makes it easy to automatically share WordPress.com posts on Facebook, Twitter, Tumblr, LinkedIn, and Yahoo!

WordPress.com VIP clients can customize which shortlink Publicize uses, when Publicize shares to which accounts, and other behavior changes using standard filters.

Conditionally allow services or connections to be utilized

Publicize includes an extremely helpful wpas_submit_post? filter for determining whether a given post should be submitted to a given service or connection. It looks like this:

$submit_post = apply_filters( 'wpas_submit_post?', true, $post_id, $service_name, $connection_data ) )

$service_name will be a value like ‘twitter’ or ‘facebook’, and $connection_data will have metadata about the connection.

Here’s how you might reserve a “@vipwpnews” Twitter account exclusively for posts in the “WordPress” category:

add_filter( 'wpas_submit_post?', 'vipx_wpas_submit_post', 10, 4 );
function vipx_wpas_submit_post( $ret, $post_id, $name, $connection ) {

	$categories = get_the_terms( $post_id, 'category' );
	if ( 'twitter' == $name && '@vipwpnews' == $connection['meta']['display_name'] ) {

		if ( is_array( $categories ) )
			$categories = wp_list_pluck( $categories, 'slug' );

		if ( empty( $categories ) || ! in_array( 'wordpress', $categories ) )
			$ret = false;

	}
	return $ret;
}

Note: This filter is applied both when the post is published and in the post metabox to determine which services should appear as available to the writer or editor. It will also let authors add their own services.

Add a checkbox to send new post updates to Publicize

When liveblogging or making frequent updates to a post, you may want to send multiple updates to Publicize.

Publicize’s default behavior is to only syndicated a post once. You can add a checkbox for writers or editors to publicize a post a second time using this code snippet:

add_action( 'publicize_form', 'vipx_filter_publicize_form' );
function vipx_filter_publicize_form( $form ) {
	global $post;

	// Only add the checkbox if the post was already published
	if ( 'publish' != $post->post_status )
		return $form;

	$checkbox = '<label for="vipx-republicize"><input type="checkbox" id="vipx-republicize" name="vipx-republicize" /> Re-Publicize Post?</label>';

	$form .= $checkbox;

	return $form;
}

add_action( 'save_post', 'vipx_action_save_post_republicize', 5 );
function vipx_action_save_post_republicize( $post_id ) {

	if ( isset( $_POST['vipx-republicize'] ) ) {
		update_post_meta( $post_id, '_publicize_pending', true );
		add_filter( 'wpas_force_publicize', '__return_true' );
	}
}

The message shared to the service will be whatever is in the Publicize textarea.

Implement your own URL-shortening service

By default the Publicize feature uses wp.me as a URL-shortening service. You can also use any other URL-shortening service that can return a shortened URL.

The easiest way is to filter pre_get_shortlink or get_shortlink (called by wp_get_shortlink). For an example, check out the bit.ly plugin.

The following filter is available to alter the URL sent in your update:

$url = apply_filters( 'wpas_post_url', wp_get_shortlink( $post->ID, true ), $post->ID, $this->slug );

Altering the default messages

It is also possible to change the default message that is created with the following filters:

apply_filters( 'wpas_default_message', $this->default_message, $this->slug )
apply_filters( 'wpas_default_prefix', $this->default_prefix, $this->slug )
apply_filters( 'wpas_default_suffix', $this->default_suffix, $this->slug )

These filters are used in the following context:

$title = sprintf( $this->default_prefix, $url ) . sprintf( $this->default_message, $post->post_title, $url ) . sprintf( $this->default_suffix, $url );

and allow the wildcards '%title%', %url% within the default_message/prefix/suffix variables.

You can also alter the message that is sent to Twitter / Facebook with a simple function attached to the following filter to Twitter:

$status_update = apply_filters( 'publicize_twitter_message', $message, $post, $url );

and to Facebook:

$status_update = apply_filters( 'publicize_facebook_message', $custom, $post, $url );

Infinite Scroll

Some of the standard themes on WordPress.com support infinite scroll, meaning additional posts are loaded and displayed as you approach the bottom of the page. Our metrics have shown that this increases reader retention. You can see it in action at http://raanan.com or http://matt.wordpress.com.

If you would like to add this functionality to your theme, please visit the Jetpack support page on Infinite Scroll.

By default on WordPress.com, Infinite Scroll is only enable on the home page. You can use the infinite_scroll_archive_supported filter to enable it in additional contexts within the theme.

For example:

function mytheme_infinite_scroll_archive_supported() {
    return is_home() || is_archive();
}
add_filter( 'infinite_scroll_archive_supported', 'mytheme_infinite_scroll_archive_supported' );

Note: when you enable Infinite Scroll, the posts per page value is changed to seven. Every Ajax load puts seven more posts and counts as one pageview.

Using Data from WordPress.com Stats

We’ve created various helper functions that make it easy to work with WordPress.com Stats data. You can find these functions in the following helper file: vip-helper-stats-wpcom.php. This file is auto-loaded for you.

Note: Please use these functions with care as they can be fairly resource-intensive and can cause issues if abused under high traffic scenarios.

Getting Most Popular Posts

The following helper function returns popular posts for a specified number of days: wpcom_vip_top_posts_array. It returns data in the raw format returned by the Stats API. If you don’t care much about the actual view count, you can easily use the returned post_id to fetch the full post objects.

This function fetches the list of posts (and pages) that have had the most views recently, and doesn’t do any filtering of the resultant data.

If you want to exclude pages from the listing on your sites, or previously popular posts that you have now deleted, then you need to add code to your theme to filter these out from display.

Getting Other Data

Using the wpcom_vip_get_stats_array function, you can retrieve the following data:

  • views (daily views)
  • postviews (top posts)
  • referrers (top referrers)
  • searchterms (top referring search terms)
  • clicks (top outbound clicks)
  • authorviews (top authors)

Stats API

WordPress.com Stats has a nice API to fetch all sorts of cool data too! For access to this data outside of your WordPress.com site/theme, please read our documentation here.

Gravatars and Blavatars

Gravatars

A Gravatar is a Globably Recognized Avatar (and Profile), a service by Automattic that allows any person to assign an image to an email address. WordPress.com makes extensive use of Gravatars whenever possible, and we recommend using them in your theme and assigning a Gravatar to every author.

For user profiles and Gravatar management instructions, please visit the Gravatar and Public Profile pages on the WordPress.com support site.

To learn how to implement Gravatars in your site theme, please visit Using Gravatars in the WordPress.org codex.

Tip: If you are not seeing avatars on your site, check to make sure Avatar Display is enabled in Settings -> Discussion.

Blavatars

Blavatars are site icons which are automatically used on WordPress.com as the site favicon, iPhone home screen icon, etc.
You can set your site Blavatar under My Sites (top left corner) > Settings -> General tab in the Calypso dashboard.

Note: If your theme already contains a reference to an icon in the header.php file, the blavatar will be ignored.

You can also use the blavatar directly in your theme, with the following functions:

blavatar_exists( $domain )
get_blavatar( $url, $size = '96')
blavatar_current_domain()

Example:

if ( blavatar_exists( blavatar_current_domain() ) )
    echo get_blavatar( blavatar_current_domain(), 128);

Disabling

If you are not using Gravatars and Blavatars and need to disable the loading of related Javascript and CSS resources, you can use wpcom_vip_disable_hovercards() in your theme.

You’ll also want to disable the default favicon redirect with remove_action( 'init', 'dynamic_favicon' );

You can disable the built-in site icon functionality by including the following in your functions.php file:

remove_action( 'init', 'dynamic_favicon' );
remove_action( 'wp_head', 'blavatar_add_meta' );
remove_action( 'admin_head', 'blavatar_add_meta' );

Ready to get started?

Tell us about your needs

Let us lead the way. We’ll help you select a top tier development partner. We’ll train your developers, operations, infrastructure, and editorial teams. We’ll coarchitect your deployment processes. We will provide live support for peak events. We’ll help your people avoid dark alleys and blind corners, and reduce wasted cycles.