Incorporate Co-Authors Plus template tags into your theme

Co-Authors Plus is a plugin maintained by WordPress.com VIP which makes it easy to assign one or more bylines to a post. Upon activation, you’ll be able to start assigning multiple bylines right away. In order for those bylines to appear on the frontend, you may need to make some small modifications to your theme.

Available Template Tags

WordPress offers template tags like the_author() and the_author_posts_link() to display byline information associated with each post post. You might see these inside files like single.php and author.php

Co-Authors Plus has similar template tags for displaying multiple bylines. These are located in the template-tags.php file. The most relevant are:

/**
 * Outputs the co-authors display names, without links to their posts.
 * Co-Authors Plus equivalent of the_author() template tag.
 *
 * @param string $between Delimiter that should appear between the co-authors
 * @param string $betweenLast Delimiter that should appear between the last two co-authors
 * @param string $before What should appear before the presentation of co-authors
 * @param string $after What should appear after the presentation of co-authors
 * @param bool $echo Whether the co-authors should be echoed or returned. Defaults to true.
 */
function coauthors( $between = null, $betweenLast = null, $before = null, $after = null, $echo = true ){
	return coauthors__echo('display_name', 'field', array(
		'between' => $between,
		'betweenLast' => $betweenLast,
		'before' => $before,
		'after' => $after
	), null, $echo );
}

/**
 * Outputs the co-authors display names, with links to their posts.
 * Co-Authors Plus equivalent of the_author_posts_link() template tag.
 *
 * @param string $between Delimiter that should appear between the co-authors
 * @param string $betweenLast Delimiter that should appear between the last two co-authors
 * @param string $before What should appear before the presentation of co-authors
 * @param string $after What should appear after the presentation of co-authors
 * @param bool $echo Whether the co-authors should be echoed or returned. Defaults to true.
 */
function coauthors_posts_links( $between = null, $betweenLast = null, $before = null, $after = null, $echo = true ){
	return coauthors__echo('coauthors_posts_links_single', 'callback', array(
		'between' => $between,
		'betweenLast' => $betweenLast,
		'before' => $before,
		'after' => $after
	), null, $echo );
}

/**
 * Outputs the co-authors display names, with links to their websites if they've provided them.
 *
 * @param string $between Delimiter that should appear between the co-authors
 * @param string $betweenLast Delimiter that should appear between the last two co-authors
 * @param string $before What should appear before the presentation of co-authors
 * @param string $after What should appear after the presentation of co-authors
 * @param bool $echo Whether the co-authors should be echoed or returned. Defaults to true.
 */
function coauthors_links($between = null, $betweenLast = null, $before = null, $after = null, $echo = true ) {
	return coauthors__echo('coauthors_links_single', 'callback', array(
		'between' => $between,
		'betweenLast' => $betweenLast,
		'before' => $before,
		'after' => $after
	), null, $echo );
}

Each of these template tags will present different aspects of the multiple bylines. For instance, the first will display the first and last name of each co-author without any links. The second will display the first and last name of co-author linking back to their author profile page. And so on.

Integrating Template Tags Into Your Theme

To integrate Co-Authors Plus, you’ll want to replace existing author template tags in your theme with a simple conditional that uses the Co-Authors Plus template tags if Co-Authors Plus is available. The conditional prevents your site from breaking (e.g. white screen of death) if Co-Authors Plus isn’t activated.

For example, here’s how you would update the_author_posts_link() to instead use coauthors_posts_links():

if ( function_exists( 'coauthors_posts_links' ) ) {
    coauthors_posts_links();
} else {
    the_author_posts_link();
}

However, the example above is a relatively simplistic way of presenting bylines. There’s a good chance your theme will need an adaptation of it.

For instance, here’s how the change looks for the Hybrid theme:

function hybrid_entry_author_shortcode( $attr ) {
	$attr = shortcode_atts( array( 'before' => '', 'after' => '' ), $attr );
	if ( function_exists( 'coauthors_posts_links' ) ) {
		$author = coauthors_posts_links( null, null, null, null, false );
	} else {
		$author = '<span class="author vcard"><a class="url fn n" href="' . esc_url( get_author_posts_url( get_the_author_meta( 'ID' ) ) ) . '" title="' . esc_attr( get_the_author_meta( 'display_name' ) ) . '">' . get_the_author_meta( 'display_name' ) . '</a></span>';
	}
	return $attr['before'] . $author . $attr['after'];
}

Here’s the new function for TwentyTen:

if ( ! function_exists( 'twentyten_posted_on' ) ) :
/**
 * Integrate Co-Authors Plus with TwentyTen by replacing twentyten_posted_on() with this function
 */
function twentyten_posted_on() {
	if ( function_exists( 'coauthors_posts_links' ) ) :
		printf( __( '<span class="%1$s">Posted on</span> %2$s <span class="meta-sep">by</span> %3$s', 'twentyten' ),
			'meta-prep meta-prep-author',
			sprintf( '<a href="%1$s" title="%2$s" rel="bookmark"><span class="entry-date">%3$s</span></a>',
				get_permalink(),
				esc_attr( get_the_time() ),
				get_the_date()
			),
			coauthors_posts_links( null, null, null, null, false )
		);
	else:
		printf( __( '<span class="%1$s"<Posted on</span> %2$s <span class="meta-sep">by</span> %3$s', 'twentyten' ),
			'meta-prep meta-prep-author',
			sprintf( '<a href="%1$s" title="%2$s" rel="bookmark"><span class="entry-date">%3$s</span></a>',
				get_permalink(),
				esc_attr( get_the_time() ),
				get_the_date()
			),
			sprintf( '<span class="author vcard"><a class="url fn n" href="%1$s" title="%2$s">%3$s</a></span>',
				get_author_posts_url( get_the_author_meta( 'ID' ) ),
				esc_attr( sprintf( __( 'View all posts by %s', 'twentyten' ), get_the_author() ) ),
				get_the_author()
			)
		);
	endif;
}
endif;

Here are a couple more threads you can look at for insights:

Co-Authors Plus: Add guest bylines to your content

Co-Authors Plus is a plugin maintained by WordPress.com VIP which makes it easy to assign one or more bylines to a post. With the guest authors feature, you can assign a byline to content without having to create a corresponding WordPress account. And, if your theme is using the appropriate template tags, you can create guest bylines without any additional configuration.

Creating or Editing Guest Authors

On WordPress.com VIP, guest authors can be created and managed under “Users” -> “Guest Authors”.

Each guest author can have many of same fields a normal WordPress user would typically have, including display name, email address, and website. You can assign a featured image in order to override the avatar typically associated with the email address.

Once you’ve created your guest author, his or her byline can be assigned to a post using the normal Co-Authors Plus interface.

Details for Developers

Incorporating new profile fields

The guest authors feature of Co-Authors Plus was written with extensibility in mind. The default set of profile fields can easily be manipulated using accessible filters. If you want to place your field in one of the existing post meta boxes, it can be as simple as the following example:

https://gist.github.com/ece7e8bb1a97ac4a1977

Then, for use on the frontend, the new field is automatically loaded onto the $coauthor object.

Migrating users to guest authors with wp-cli

If you’re performing a migration of users to co-author guest authors, there are a couple of helpful wp-cli commands packaged with the plugin:

  • wp co-authors-plus create-guest-authors will create guest authors for all of your existing users
  • wp co-authors-plus assign-user-to-coauthor will then assign all of the posts associated with old user to your new guest author

So, the steps to migrate all of your users/authors to your WordPress.com VIP site would include:

  1. Install the Co-Authors Plus plugin on your staging site
  2. Run the create-guest-authors CLI command to create the Guest Authors automatically
  3. Perform an export from your staging site and save the resulting WXR file. The WP-CLI guest authors will be included in this export.
  4. Create a mapping CSV file for editorial users who require real logins from their login on the staging site to their login on the production site (these may or may not be be the same).
    The CSV file format is as simple as:

    johnsmith, johnsmithwp
    janesmith, janesmith
    johndoe, johndoe123
    
  5. Send us the WXR and mapping CSV, and we’ll run the import for you. While Co-Authors Plus will bring over all the bylines, we’ll use the mapping CSV to preserve the bylines for users with real logins.
  6. Have your team QA the imported authors.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.