Month: June 2018

The Post Kinds plugin, essentially an extended version of WordPress’s core Post Formats functionality, allows one to make a variety of types of posts on one’s website that mirrors the functionality provided in a huge variety of social media platforms. This is useful if you’re owning all of your own data and syndicating it out to social silos, but it’s also great for providing others better user interface for reading and consuming what you’re posting.

I’ve documented and written about it quite a bit in the past and am obviously a big fan. In addition to most of the default post types (notes, favorites, likes, bookmarks, reads, listens, etc.), my personal site also supports follows, eat, drink, wishes, acquisitions, exercise, and chickens! Wait a second… CHICKENS?!?

Yes, that’s chickens, not checkins, which I also support.

One of the nice benefits of the plugin is that it’s fantastically modular and extensible. As an exercise a few months back I thought I would take a shot at adding chicken post support to my website. Several years ago in the IndieWeb, partly as an educational exercise and partly for fun, several people thought it would be nice to add a post type of “chicken” to their sites. What would it look like? What would it entail? How might it evolve? Since then interest in chicken related posts has naturally waned, but it does bring up some interesting ideas about potential new pieces of functionality that one might want to have on their personal websites.

While I currently support many post types, I’ve discovered recently that I have a variety of notes and checkins that relate to items I’ve purchased or acquired. I thought it might be worthwhile to better keep track on my own website of things I acquired  in a more explicit way to make posting them and searching for them a lot easier. But how could I do this myself and potentially contribute it back to a broader base of other users? I started with a bit of research on how others have done this in the past and tried to document a lot of it on the Indieweb wiki. I eventually asked David Shanske to reserve the idea of acquisitions within the Post Kinds plugin, which he did, but I wondered how I might have done some of that work myself.

So below, as an example, I thought I’d write up how I’ve managed to add Chicken posts to my website. To a great extent, I’m using data fields and pieces already built into the main plugin, but in doing this and experimenting around a bit I thought I could continue to refine chicken posts until they did what I wanted, after which, I could do a pull request to the main plugin and add support for others who might want it. Hopefully the code below will give people a better idea about how the internals of the plugin work so that if they want to add their own pieces to their sites or contribute back to the plugin, things might be a tad easier.

Pieces for a new Post Kind in WordPress

Adding a new Post Kind primarily consists of three broad pieces  which I’ll address below. The modularity of the plugin makes adding most of the internals for a new kind far simpler than one might imagine.

Adding Taxonomy Support

New kinds in general will require a small handful of properties which include:

• a name (as well as its singular, plural, and verb forms);
• a microformats 2 property;
• a format, so that the plugin can map the new post kind to a particular Post Format type within WordPress core so that themes which use these can be properly set when needed. Format options include: aside, image, video, quote, link, gallery, status, audio, and chat. Some post kinds may not have an obvious mapping, in which case the value can be left as empty;
• a generic description for display within the admin user interface as well as for the archive pages for the type which are auto-generated;
• a description-url, typically this is a link to the IndieWeb wiki that has examples and details for the particular post kind. If there isn’t one, you could easily create it and self-document your new use case. It could even be empty if necessary;
• A show setting with a value of true or false to tell the plugin to default to showing the kind in the Post Kinds “Kinds” metabox so that the new kind will show up and be choose-able from within the interface when creating new posts.

Code to include these pieces of data will need to be added to the /includes/class-kind-taxonomy.php folder/file path within the plugin so that the plugin knows where it needs to be found.

As an example, here’s what the code looks like for the bookmark kind:

'bookmark'    => array(
	'singular_name'   => __( 'Bookmark', 'indieweb-post-kinds' ), // Name for one instance of the kind
	'name'            => __( 'Bookmarks', 'indieweb-post-kinds' ), // General name for the kind plural
	'verb'            => __( 'Bookmarked', 'indieweb-post-kinds' ), // The string for the verb or action (liked this)
	'property'        => 'bookmark-of', // microformats 2 property
	'format'          => 'link', // Post Format that maps to this
	'description'     => __( 'storing a link/bookmark for personal use or sharing with others', 'indieweb-post-kinds' ),
	'description-url' => 'http://indieweb.org/bookmark',
	'show'            => true, // Show in Settings
	),

For direct comparison, and as an explicit example for my chicken post kind, here’s the block of code I inserted within the class-kind-taxonomy.php file immediately below the section for the acquisition type:

'chicken'    => array(
	'singular_name'   => __( 'Chicken', 'indieweb-post-kinds' ), // Name for one instance of the kind
	'name'            => __( 'Chickens', 'indieweb-post-kinds' ), // General name for the kind plural
	'verb'            => __( 'Chickened', 'indieweb-post-kinds' ), // The string for the verb or action (liked this)
	'property'        => 'chicken-of', // microformats 2 property
	'format'          => 'image', // Post Format that maps to this
	'description'     => __( 'Owning all the chickens. Welcome to my chicken feed.', 'indieweb-post-kinds' ),
	'description-url' => 'https://indieweb.org/chicken',
	'show'            => true, // Show in Settings
	),

You’ll probably notice that beyond the simple cut and paste, I haven’t really changed much. Syntax aside, most of these pieces are relatively obvious and very straightforward, but I’ll add some commentary about a few parts and what they do which may not be as obvious to the beginner. When creating your own you can copy and paste this same block into the code at the bottom of the list of other types, but you’ll want to change only the data that appears within the single quotes on each of the nine lines for the various settings.

For those not familiar with microformats you may be asking yourself what snippet to add for the property setting. The best bet is to take a look at the microformats wiki or look for possible examples of people doing the same type of post you’re doing and copy their recommended microformat. For extremely new and likely experimental edge cases, chances are that you’ll need to choose your own experimental microformat name. In these instances you can use prior microformats as examples and potentially follow the format. In my case I knew about the bookmark-of, like-of, favorite-of, and the experimental read-of, listen-of, and watch-of microformats, so I followed the pattern and chose chicken-of for my experimental chicken posts. One could also potentially ask for recommendations within either the microformats IRC/chat channel or the IndieWeb chat. If you create a new and experimental one, take a few moments to document your use case in the IndieWeb and/or Microformats wikis for others who come after you. Keep in mind that if you change the property name at a later date you will need to go into your database and change the wp_postmeta database meta_key field from mf2_property1 to mft_property2 so that WordPress will know where the appropriate data is stored to be able to display it.

The show setting is fairly straightforward, but may not be as obvious to some. It has either a value of true or false. If the value is false, the new post kind won’t be displayed in the radio button options within the admin UI for creating new posts. If the value is true, then it will be available. The Post Kinds plugin has a number of reserved post kinds which aren’t displayed by default on most sites–primarily because they do not have appropriate views or data fields defined–but they could be enabled by changing the show flag from false to true. Most often we recommend you only show those kinds that you’re actively using.

Additional examples of the dozen or more standard post kinds can be found within the code to provide some additional potential clarity on what types of data each of them are expecting.

I debated a while on making the verb ‘chickened out’ instead of ‘chickened,’ but I chickened out thinking that it would make my posts something wholly different. Obviously you can now make your own choice.

With this chunk of code saved into the plugin, it is now generally aware of the new post kind and can save the appropriate data for this new kind of post.

Template/View Support

Now you’ll want to add some code to the plugin to tell the plugin how it should display the data it’s saving for your posts. The easiest way to do this is to copy and paste the code from one of the many default views already in the plugin and just change a few small pieces of data to match your post kind. This code can be created as a new file with your new matching post kind name (the one at the top of your code snippet above that appears on line 1 before the word ‘array’) in one of two places. If you put it in the views folder in the plugin, you may need to re-add it later on if the plugin updates. Otherwise you can add the code into a file which can be placed into a folder named kind_views in either the folder for your theme (or your child theme, if you have one.) We recommend placing it in your child theme, so if the parent theme updates, your code won’t accidentally be lost.

There are a variety of views for many post kinds available to stand as examples, so you can look at any of these and tweak them as you wish to get the output you desire. For more complicated output displays it might certainly help to have some PHP coding skills. For my chicken post kind I simply copied and pasted the code for the bookmark kind view and pasted it into a file named kind-chicken.php following the naming convention of the other files.

Below is a copy of the code I added for the chicken post kind which is nearly identical to the bookmark view with exception of changing the name of the template, adding u-chicken-of and changing the get_before_kind to chicken instead of bookmark. Note that because the chicken-of microformat is wrapped on a URL, it has the u- prefix, otherwise if it were on plain text it would have been p-chicken-of using the standard microformat h-, u-, p-, and e- syntax.

I also put both the u-chicken-of and the u-bookmark-of microformats in the view so that sites using the post type discovery algorithm that don’t recognize the chicken-of microformat won’t choke on the proverbial chicken bone, but will default back to thinking this post is of the bookmark type. I suspect that I could also have left the u-bookmark-of off and many would have defaulted to thinking this post was a simple note as well. You can make your own choice as to which you prefer as a default.

<?php
/*
 * Chicken Template
 *
 */

$mf2_post = new MF2_Post( get_the_ID() );
$cite     = $mf2_post->fetch();
if ( ! $cite ) {
	return;
}
$author = Kind_View::get_hcard( ifset( $cite['author'] ) );
$url    = ifset( $cite['url'] );
$embed  = self::get_embed( $url );

?>

<section class="response u-chicken-of h-cite">
<header>
<?php
echo Kind_Taxonomy::get_before_kind( 'chicken' );
if ( ! $embed ) {
	if ( ! array_key_exists( 'name', $cite ) ) {
		$cite['name'] = self::get_post_type_string( $url );
	}
	if ( isset( $url ) ) {
		echo sprintf( '<a href="%1s" class="p-name u-url">%2s</a>', $url, $cite['name'] );
	} else {
		echo sprintf( '<span class="p-name">%1s</span>', $cite['name'] );
	}
	if ( $author ) {
		echo ' ' . __( 'by', 'indieweb-post-kinds' ) . ' ' . $author;
	}
	if ( array_key_exists( 'publication', $cite ) ) {
		echo sprintf( ' <em>(<span class="p-publication">%1s</span>)</em>', $cite['publication'] );
	}
}
?>
</header>
<?php
if ( $cite ) {
	if ( $embed ) {
		echo sprintf( '<blockquote class="e-summary">%1s</blockquote>', $embed );
	} elseif ( array_key_exists( 'summary', $cite ) ) {
		echo sprintf( '<blockquote class="e-summary">%1s</blockquote>', $cite['summary'] );
	}
}

// Close Response
?>
</section>

<?php

Icon Support

Finally, you’ll want to include the appropriate svg icon within the plugin so that it will display on the post (if the appropriate settings are chosen within the plugin’s settings interface: either “icon” or “icon and text”), and within the Kinds metabox in the post editor.

You’ll want to have one icon named kindname.svg in the svgs folder and another named kinds.svg in the plugin’s root folder. The kinds.svg is a special ‘master’ svg of all of the kinds icons bundled together. If it helps in matching the icon set, all of the current kind icons are made with Font Awesome icons which have the appropriate licensing for distribution.

In my chicken example, I opted for the feather icon since Font Awesome didn’t have an actual chicken available.

When you’re done

Thanks to the rest of the plugin’s functionality, you should now automatically be able able to make and display individual chicken posts, display a chicken feed (pun intended), and allow people to subscribe to the RSS feed of your chicken posts.

Creating a plugin for new kinds

Naturally some people may want to display particular exotic kinds which might not extend to the broader public. A chicken post type certainly falls under this umbrella as I wouldn’t expect that other than for novelty, obsessive IndieWeb post kinds completeness, or for a very small handful of specialized farming, juggling, or comedy websites that anyone else in their right mind would really want to be doing a lot of posting about chickens on their site.

David Shanske, the plugin’s creator, has made it possible to create a sub-plugin of sorts so that one can add one-off support to these types using  a variety of filters and functions. This could be useful so that updates to the plugin don’t overwrite one’s work and require adding the pieces outlined above back in again. Sadly, this is a tad beyond my present abilities, so I won’t address it further at the moment other than to say that it’s possible and perhaps someone might document it for others to use a similar template in the future.

Try it yourself

Now that you’ve got the basics, it should be relatively easy to add many of your own new post kinds.

Exercise One

If you want a simple exercise, you should be able to go into the code and manually change the show flags for the eat and drink kinds from their default false to true to enable posting food to create a food diary on your website. (These have a reasonable default view and icons already built in.)

Exercise Two

With slightly more work you can change the show flag on the follow kind and copy a view based on the bookmark view to make a follow view to make follow posts. (Here’s a link to my version.) Similarly other hidden kinds like wishes and acquisitions can be enabled easily as well. These also have default icons already built in, but just need a view defined to show their data.

Exercise Three

If you want a slightly larger challenge that uses all of the above, why not attempt adding the appropriate machinery to create a want post?

Exercise Four

Though David has often said before that he wouldn’t build in support for multi-kinds, some people may still want them or think they need them. If you’re exceptionally clever, you might be able to create your own explicit multi-kind by mixing up the details above and creating a kind that mixes a variety of the details and creates a view that would allow the specific multi-kind you desire. Caveat emptor on this approach if you should take it.

Share your ideas

Now that you’ve got the general method, what kinds are you going to deploy in the future? What have you already created? Feel free to reply with your ideas and thoughts below in the comment section or send us a webmention from your own site with what you’ve done. Maybe consider doing a pull request on the plugin itself to add the functionality for others?
​​​​​​​​​