Archives

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.

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 have a nice API to fetch all sorts of cool data. For access to this data outside of your WordPress.com site/theme, you can use the CSV API: http://stats.wordpress.com/csv.php

Sitemaps – News and XML

All WordPress.com sites come with XML and News sitemaps built-in. The sitemaps are automatically generated, cached for a 24-hour period, and updated whenever a post is published, updated, or deleted. Learn more about the sitemaps here: http://en.support.wordpress.com/sitemaps/

You can customize some of the output by hooking into various filters. A non-exhaustive list of examples is below. If you’re interested in modifying something beyond what’s shown below, just let us know.

For local testing, you can use the following code, which is a stripped-down version of the sitemap generator we have on WordPress.com: https://gist.github.com/7374b43a477d0eab26b4

XML Sitemap: Exclude certain posts

add_filter( 'sitemap_skip_post', 'x_sitemap_skip_post', 10, 2 );

function x_sitemap_skip_post( $skip, $post ) { // $post is an object with properties: ID, post_type, post_modified_gmt, comment_count
	if ( get_post_meta( $post->ID, 'x_skip_post', true ) )
		$skip = true;
	return $skip;
}

XML Sitemap: Include additional post types

By default, sitemaps only include posts. Use the following to include additional post types.

add_filter( 'wpcom_sitemap_post_types', 'x_sitemap_add_gallery_post_type' );

function x_sitemap_add_gallery_post_type( $post_types ) {
	$post_types[] = 'gallery';
	return $post_types;
}

News Sitemap: Change the publication name

add_filter( 'wpcom_sitemap_news_sitemap_item', 'x_filter_news_sitemap_name', 10, 2 );

function x_filter_news_sitemap_name( $item, $post ) {
	$item['n:news']['n:publication']['n:name'] = 'My Publication'; // modify as needed for your site
	return $item;
}

home_url() vs site_url()

When working with domain-mapped sites on WordPress.com, home_url() and site_url() will return different values.

  • home_url() returns the primary mapped domain (e.g. vippuppies.com)
  • site_url() returns the *.wordpress.com URL (e.g. vippuppies.wordpress.com)

A few notes:

  • home_url() will only return the mapped domain on or after the init has fired. Calling it before then will return the .wordpress.com domain.
  • If you accidentally use site_url() in your templates, theme-side links will still redirect correctly to the home_url() equivalent.
  • home_url() is the preferred method, as it avoids the above redirect.

Adding Open Graph Tags

Open Graph Tags are automatically enabled for all public, non-VIP blogs on WordPress.com. Open Graph tags make it easier for you to control what information Facebook, Google+, and other services display when users share posts from your site. VIP sites are excluded as many existing themes already have custom code that handles these tags. This functionality also enables additional Twitter Card-related metadata.

To enable Open Graph tags, add the following helper function to your functions.php and the tags will be auto-generated for you.

wpcom_vip_enable_opengraph();

The code that generates the tags can be found in Jetpack: http://plugins.svn.wordpress.org/jetpack/trunk/functions.opengraph.php

If you’d like to fine-tune the output of the tags, you can filter jetpack_open_graph_tags and modify the array that’s passed in.

Changing Core WordPress Strings

One of the lesser used filters in WordPress is ‘gettext.’

All strings that use the WordPress translation functions are run through this filter after the translation occurs, enabling developers to manipulate any string in WordPress. VIP’s use this most commonly in the admin area.

Here’s some sample code to filter a few WordPress core strings:

function vipuppies_filter_gettext( $translated, $original, $domain ) {

	// This is an array of original strings
	// and what they should be replaced with
	$strings = array(
		'View all posts filed under %s' => 'See all articles filed under %s',
		'Howdy, %1$s' => 'Greetings, %1$s!',
		// Add some more strings here
	);

	// See if the current string is in the $strings array
	// If so, replace it's translation
	if ( ! empty( $strings[$original] ) ) {
		// This accomplishes the same thing as __()
		// but without running it through the filter again
		$translations = &get_translations_for_domain( $domain );
		$translated = $translations->translate( $strings[$original] );
	}

	return $translated;
}
add_filter( 'gettext', 'vipuppies_filter_gettext', 10, 3 );

Note that this only applies to WordPress core strings. Anything in your own VIP themes or plugins can be changed directly in the files themselves.

Faux Single Sign-On (SSO)

Single Sign-On allows your visitors to have a consistent and personalized experience.

The current approach is to encrypt and store non-sensitive information in a browser cookie that is accessed directly from the theme. This cookie data is used to do things like pre-populate comment forms based on previous user input, or otherwise personalize the viewer’s experience.

We also update our batcache configuration to bypass various caches when these cookies exist, mimicking the experience of traditional logged-in WP.com users.

The most common use-cases for this are leveraging external registration systems (such as our partners at Janrain, or your own custom system) to seamlessly interact with WordPress.com (without the need to create WP.com accounts for those users) and commenting systems like Livefyre or IntenseDebate.

For an example implementation, take a look at the FrontEnd Cookie SSO plugin.

Please contact us to explore this further, or to work out the specific technical details.

Using Theme Constants

On WordPress.com, there are a few circumstances where services and plugins will load your theme’s functions.php even if your theme isn’t directly accessed (such as our Post-by-email service, or mobile themes.)

This means constants such as TEMPLATEPATH and STYLESHEETPATH will not be defined or available, and using them in your theme will likely result in fatal errors.

So:

  • Instead of TEMPLATEPATH, use get_template_directory()
  • Instead of STYLESHEETPATH, use get_stylesheet_directory()

Using the above convenient wrapper-functions will ensure your theme works in all possible scenarios where your functions.php file (or any file included by it) attempts to access the parent or child theme directories.

Retiring Sites from WordPress.com VIP

There may come a time when you might need to retire a site from WordPress.com VIP.

We ask that you notify the VIP team 30 days in advance. At the end of this period, we will normally remove the VIP status and revert the theme to the default theme at the time (Twenty Eleven, Twenty Twelve, etc…) As a non-VIP site, the custom theme, advertising, and other custom functions (including custom post types, taxonomy or shortcodes) will no longer be available.

It’s not a requirement to delete the site; you have a few more options regarding the site’s design and visibility:

  1. Make the site private (Settings > Privacy) The content is accessible to you and your team, but the URL and site’s content will not be available to the public.
  2. Delete the site You can ask us to delete the site to have it no longer be usable or accessible. We strongly suggest getting an export of the site’s content at Tools > Export before deletion.
  3. Use a free WordPress.com theme (Appearance > Theme) The design can be set to any of the free WordPress.com themes available in Appearance > Theme.
  4. Add Custom Design to the site (Upgrades > Custom Design) For a small yearly fee, you can modify any of the free WordPress.com themes CSS stylesheets to give the site a unique look.
  5. Add Domain Mapping (Upgrades > Domains) If you’d like to keep a custom domain mapped to your non-VIP site, you’ll need to purchase the Domain Mapping upgrade for a year. Contact the VIP team so we can help you with this and make sure you have no interruption of service.

Lastly, make sure you have a local copy of your theme checked out on SVN before VIP status is removed; the repository will not be available after the termination date passes.

Twitter and WordPress.com

Twitter can be integrated in multiple ways with your WordPress.com VIP site.

  • Pushing out content updates.
  • Integrating Twitter updates in your site’s theme.
  • Providing your users a quick way to Tweet/share your site’s content.

WordPress.com Publicize

In addition to sending your content updates to Facebook and Yahoo!, the WordPress.com Publicize feature also supports Twitter updates. A full description of the feature can be found at the Publicize WordPress.com Support page.

WordPress.com VIPs can further customize how Publicize works by following our customization guide.

The Twitter Widget

The Twitter widget allows you to display updates from a Twitter account in the sidebar of your blog. It creates an unordered list whose look and feel can be easily altered using CSS.

A full description of this widget can be found at the Twitter Widget WordPress.com Support page.

/via

If you’re using the built-in WordPress.com Sharing buttons, we have a helper function to customize the “/via” tag appended to Tweets. Just add the following to your functions.php and change the argument to the username you want attributed.

wpcom_vip_sharing_twitter_via( 'automattic' );

If you want to disable the “/via”, just pass in false

wpcom_vip_sharing_twitter_via( false );

Twitter Cards

To automatically add Twitter Card support for your site, just use our Open Graph Tags. We’ll add some additional metadata including some user-specific info if you’re using Publicize.

You can customize the output of the tags using the jetpack_open_graph_tags filter:

function my_add_twitter_card_extras( $tags ) {
	$tags[ 'twitter:site' ] = 'automattic'; // set @username of website
	return $tags;
}
add_filter( 'jetpack_open_graph_tags', 'my_add_twitter_card_extras' );

The Twitter API

Using a Twitter client that supports custom APIs, you can connect to WordPress.com to follow your favorite blogs and receive notifications when new posts are published. You can even publish status updates to the WordPress.com blog of your choice.

More information about using the Twitter API can be found at the Twitter API WordPress.com Support page.