One of my favorite parts of the Post Kinds plugin isn’t just that it provides me the flexibility to add a huge variety of post types to my website or the semantic HTML and microformats it provides to help my site dovetail into the IndieWeb. It’s that it allows me to quickly and easily provide very rich reply contexts to my posts so that I more easily know what I’ve bookmarked, liked, favorited, read, or replied to online. In some sense it helps guard against some of the problem of context collapse found in many social media sites on the internet. As my friend and foodie extraordinaireJeremy Cherfashas said, “a reply without context is like an egg without salt.”
For a long time I had been wanting a bit more control of how the Post Kinds plugin presented some of the data it allows.1,2 After one inputs a URL, the plugin uses several methods to scrape the related web page and returns a lot of metadata about it including the title, a summary, the site name, tags, a featured image, publication date and time, the author and author’s website among others. The data returned depends on how the page is marked up and is generally based on available microformats or open graph protocol data when they’re provided.
The plugin has a setting to “Embed Sites into your Response” on its settings page, and this is generally okay, but it relies on sites to have some sort of oEmbed set up predefined. For bigger sites like YouTube and WordPress, this is generally alright, but it’s not always the case that any data is provided by the external site. Even in YouTube’s case you’ll only display the video with no other meta-data about it. As a result I leave it turned off.
Let’s take a quick look at what some of these default outputs for the reply context with a short comment underneath them look like.
With the embed option turned off the plugin will return a “Summary” of the parsed website page. This too is generally well supported in 90% of websites in my experience. But the data it returns is (smartly) filtered using wp_kses for security so that a malicious page couldn’t inject random html or code into your page. This means that useful functionality is often being stripped out of the “Summary/Quote” field in the reply context. I’d prefer to have the ability to have text with links, video, and audio to appear in-line in these contexts so that there’s a better representation of the actual post I’m reacting to.
The question then, is how can I make this happen?
In older versions of the plugin there was a setting for this feature, but it wasn’t well documented and most people didn’t know what the setting was or what it meant. For simpler UI and support it was ultimately stripped out although the raw code for it was left in. In fact, it’s literally the first short block of code within the plugin’s main code! It looks like this:
To enable the ability to manually add arbitrary html, links, audio, video, etc. you can go to your main administrative user interface in WordPress and go to Plugins >> Edit and then choose the Post Kinds option in the drop down selector in the top right hand corner and click select. Search for the code listed above (it should be right at the top, underneath the title and details for the plugin) and change the single word false to true. Next scroll down the page and click the Update File button.
Now you should be able to manually change any of the fields within the Response Properties metabox and they’d display in full HTML as you’d expect them to. (Caveat: because you’ve disabled a small layer of security, you should keep a close eye on what data appears in your “Summary/Quote” field and make sure you’re not allowing your site or your readers to be led astray or hacked. In my case, I’m almost always modifying it by hand, so it’s not a big issue. Your mileage may vary depending on what you’re posting.)
But wait… What happens when I update the plugin? Won’t the update overwrite the change? Yes, you’re absolutely correct. You’ll have to remember to go back and make this change any time the plugin updates. To prevent this, you could instead modify your wp-config.php file in the root folder of your WordPress install. To do this add the following lines of code to the bottom of this file:
/** Sets up initial variable for the Post Kinds plugin to not filter the Summary/Quote field */
if ( ! defined( 'POST_KINDS_KSES' ) )
define(' POST_KIND_KSES', true );
Next save the file and upload it to your WordPress install. Now you should be all set.
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?!?
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 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.
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.
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.
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.
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.)
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.
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?
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?
In this episode, David Shanske and Chris Aldrich discuss how the Post Kinds plugin mapped IndieWeb types of posts to WordPress and why, the defined as opposed to implied types set up, and avatars.
While the conversation is WordPress-centric, there are a lot of discussions here relevant to a broader IndieWeb audience about adding new types of posts to your site, trying to design things flexibly (although a developer’s guide is probably needed), etc.
I’ve been meaning to write regular updates to highlight some of the useful changes in the functionality of the IndieWeb suite of WordPress plugins, but never gotten around to it. There’s been a few really interesting ones lately, so I thought I’d start. Observant watchers who read through either the code or even the scant change logs before they update their code may catch some of these features, but sometimes interesting tidbits can slip by the most vigilant. Here are some interesting recent ones:
Display of Reads, Listens, and Watches in comments sections
David Shanske’s excellent Post Kinds Plugin allows one to post what they’re reading, listening to, or watching in simple IndieWeb fashion. (Examples of these on my site: read posts, listen posts, watch posts.) These posts types automatically include the appropriate microformats classes so the user doesn’t need to bother doing them manually. For a long time when replying to another’s site, bookmarking it, or even mentioning it when also using the Webmentions plugin would send the site a Webmention that would generally cause it to show up as a native comment, bookmark or mention. With an update late last year, from within the Discussion settings in WordPress, one could set toggles so that many of these webmentions could be displayed as facepiles. Other broadly unsupported post types would typically default to a simple mention.
Recently David Shanske and I started a podcast, and he thought it would be useful if his site could accept listen posts and show them visually within his comments section just like these replies, bookmarks, and mentions. Thus over the past month he’s added code to the Semantic Linkbacks Plugin to add the functionality for these types of posts to properly render showing facepiles for listens, reads, and watches.
This is what webmentions of listen posts look like on his site in his comments section:
Listen (or scrobble) posts can send webmentions (or notifications) to the original content potentially with the experimental listen-ofmicroformat. In the case of scrobbles of podcasts, these webmentions could be displayed as “Listens” which would provide the canonical copy of the podcast some indicator of its popularity and actual audience. It is tremendously difficult to obtain data on the actual number of listens within most of the podcast community and typically a fraction of the number of downloads must be used as an indicator of the actual reach. Being able to display listens could potentially be a boon to the podcasting market, particularly with respect to advertising as this type of open social web functionality spreads.
I haven’t yet seen one for watches in the wild yet, but maybe you’ll be either the first to send or receive one?
The microformats on these posts is generally considered to be experimental, but with the ~500+ users of this suite of tools as well as others who are already using them on other sites, they’ve now taken a dramatic step into the open internet and more widespread use and potential official adoption.
Editable Webmention Types and Avatars
Just yesterday, I spent a few minutes in the IndieWeb chat helping someone to laboriously delve into their mySQL databaset and find a particular snippet of data so they could manually change a received webmention from being a simple mention to being a reply so that it would display as a native comment on their website. I’ve often done this to take what sometimes seem like simple mentions and change them to replies to reveal the richer content they often contain for the broader conversation. Sadly the process is boring, laborious, and fraught with potential ways to mess things up.
As of this weekend, this process is no longer necessary. One can now go to the admin interface for their comments and webmentions (found at the path /wp-admin/edit-comments.php), click on edit for the particular comment they’re changing and then scroll down to reveal a droplist interface to be able to manually change the webmention type.
As another example of a use for this functionality, perhaps you’ve received a listen mention on one of your podcast episodes that has a lot of useful notes or commentary germane to your episode? Instead of hiding it as a simple listen, why not change the type to reply to allow a richer conversation around your content? After all, with a reasonable reply it will be implicit that the commenter actually listened to the episode, right?
Because there is currently no functionality in WordPress for saving or caching the avatars of commenters via webmention, when users change their profile images on siloed services like Facebook, Twitter, et al. the link to their old avatars quits working and they were displaying blank spaces. This is an unfortunate form of linkrot, but one that can become more visually apparent over time.
As one can see in the image for the commenting edit box above, the field for the Avatar is now editable. This means one can update out-of-date or blank avatars. One now also has the ability to moderate/edit or easily remove/switch avatars if users are sending inappropriate photos for one’s site’s audience.
Summary: With the GDPR regulations coming into effect in Europe on May 25th, privacy seems to be on everyone’s mind. This week, we tackle what webmentions are, using them for backfeed, and the privacy implications.