Reusing Content on Wikis and Blogs

Since I launched this site last year, I have been looking for an effective way to reuse content on server-installed WordPress blogs. I wanted a solution that’s similar to creating snippets in MadCap Flare.

Flare snippets are the big brother of variables. They’re reusable blocks of content that can store formatting along with the text. They can also include variables and condition tags. You maintain them as individual files and can point to them from multiple topics and projects. A snippet is similar to a text inset in FrameMaker and a linked file in Microsoft Word.

So what’s the equivalent of snippets on wikis and blogs?

The MediaWiki equivalent: transclusion

Last year while working on the National Cancer Institute’s BiomedGT Wiki, I used the MediaWiki equivalent of snippets. For example, I wrote a statement that reminded experts that they needed to register with the site and get a login to be able to perform certain tasks. That statement needed to appear in multiple places, so if reviewers wanted to change the language, I needed to be able to update it in one place and have it update everywhere that it appeared.

I used a process called transclusion. To give you the simplest example, I created a wiki template that included the heading Before You Begin and the paragraph that described the registration requirement. I then pointed to that template from other pages using a simple tag with the template name: {{RegistrationRequirement}}. For more information about how this works on a MediaWiki, see the Wikipedia Help for using templates. The Wikipedia templates work exactly the same way.

The WordPress equivalent: shortcodes

I first realized that I wanted to deploy a similar reuse feature on my WordPress blog when I created my Free Stuff page. The CSS Book list that appears there originated in a blog post on defining Flare styles. If I want to add to the list, I want to be able to update it in one place and have the current list show in both places.

I had read about various WordPress features for possible reuse, but none of them seemed to be exactly what I wanted. So I posted a question on the Thesis forum, where I can get help on customizing my blog’s Thesis theme. One of the moderators recommended shortcodes.

Shortcodes enable you to reuse content using PHP functions and function calls. If that scares you, relax. My PHP skills are still developing. Granted, I have had a lot of scripting experience, so I do understand functions and function calls. If you don’t understand what functions do, read the Wikipedia article about functions.

In a WordPress blog, you normally include shortcode functions in your functions.php file. Make sure that you create a backup copy of the file before you change it. Fortunately, the vendor who designed my WordPress template (DIY Themes), included a custom_functions.php file. Using this file ensures that when I upgrade the template, I won’t lose my custom functions. Nevertheless, I still keep a backup copy of that file, too.

Here’s the example that I used to generate my CSS Book list. The explanatory comments are preceded by two forward slashes (//).

So, when I want to modify the CSS Books list, I modify the HTML markup in the show_css_book_list function. In every location where I have inserted the [cssbooklist] shortcode on my site, the updated book list appears.

If you want to learn more about WordPress short codes and how you can extend them, see Mastering WordPress Shortcodes. I thank WordPress guru Tom Johnson for sending me the link.

Back to top

Tagged as: Wikis