Tutorial: WordPress: Building a "Topics" Site
A news site often publishes many related articles on the same topic, such as "Healthcare Reform." While these disparate articles may be linked to one another through a tagging or category interface, it's ideal if a site can maintain a stable, easy-to-remember URL that gathers related content under a single umbrella. Having a "topic page" like this helps readers, who now have a single definitive source to bookmark for a given topic, helps with search engine optimization, and helps the publication generate traction on particular areas of coverage.
This tutorial has two goals:
- Provide instructions to fellows in KDMC training programs on using the demonstration Topics Central CMS we provide for demonstration purposes.
- Show developers how to create a Topics Section-oriented site with WordPress. We even provide a downloadable Topics theme!
Using the KDMC Topics CMS
This section is intended for fellows in KDMC training programs that utilize our WordPress-based Topics CMS. If you are a WordPress developer trying to build a Topics CMS, skip to Building a Topics CMS.
KDMC trainers will have provided a login and URL for the CMS in advance. Once logged in, you'll need to change your password and tweak your profile immediately.
Click on your name at the top right of the screen:
This will take you to your profile page. If we created your account, the first thing you should do is change your password. Scroll to the bottom of the page and enter a new password twice. Your password must contain at least seven characters, including at least one digit and one punctuation mark. Click the Update Profile button.
In the "Name" section, make sure your first and last name are correct. Then, from the "Display name publicly as" picklist, select the format you want your byline to appear in (most likely FirstName LastName).
A little farther down the page, find the "Jabber / Google Talk" field. WordPress doesn't have a Twitter field, but we're going to include your recent tweets in the sidebar of stories you write. Those tweets will be obtained by looking up the Twitter account listed in this field, so please enter your Twitter username here.
Finally, scroll down to the "Biographical Info" field. Each author in the system will get a page of their own, displaying their bio and a list of stories they've written. This field does not have a rich text editor, but feel free to format your bio with simple HTML, if you know how (or ask us for a hand).
When a user clicks a byline link, your bio will appear on the site like this:
A list of stories written by the author will appear directly beneath the bio.
Content Widths and Image Preparation
Our Topics system uses the following dimensions, which you'll want to keep in mind when preparing media content:
Content area: 640px
Optional full-width content area: 900px
Banner image: 900 x 140px
You'll need to prepare a banner image for your topic in Photoshop at 900x140px.
Managing Your Topic
Before getting into the specifics of the Topics CMS, you'll want to familiarize yourself with using WordPress in general. If you've never used WordPress before, please see our Using WordPress tutorial.
A Topic page provides more than just a place to aggregate the stories, mashups, data visualizations and videos you'll be producing. It's also a place to provide a running summary of content in your Topic Section. Your topic should be "curated" to provide maximum usefulness to readers. Our system modifies the way the WordPress "categories" system works, adding a rich text editor for convenient editing, and a custom banner image that will be displayed on each story that belongs to the topic. Therefore, you'll be spending a lot of time managing your WordPress "category."
You'll find the Categories link on the left side, under the Posts section.
KDMC staff should have created a Category (Topic) for you. If not, click Add Category, give it a name, and a nice short slug. For example, if your Topic Section is called "Healthcare Reform," then "healthcare" would be a good slug (the slug will become part of the URL, and URLs should be as short as possible, while still remaining meaningful).
After saving, click your category name to edit it and you'll see an editing pane that looks something like this:
You'll probably want to make the editing field much larger than it is by default. To do this, drag the "grippy bars" at the lower right corner of the field and drag.
Enter a summary of your Topic here. While you'll be entering your topical stories elsewhere in the system, you can return here at any time to update your summary, or to add media.
Your Topic Section page, and all stories that live within it, will be topped by a banner image that connects them visually. Create an image in Photoshop at 900x140px, save it as a web-ready JPG, and upload it here.
If you want to add images to the text portion of your Topic page, note that you won't find the usual "Add Media" buttons seen elsewhere in WordPress. This is a bit of an inconvenience, and is due to the fact that WordPress categories were never meant to be used in quite this way. There is, however, still a small "Photo" icon on the toolbar, which can take any existing image URL. So to get images into your Topic page, follow these steps to get the URL to a previously uploaded or new image:
Note: These are not the instructions for adding images to general stories - the extra steps are required only for adding images to Topic pages.
Go to one of the Posts associated with your Topic (via Posts | Edit)
Click the small Add Image icon:
If you want to re-use an image that was previously uploaded into a story, click the Gallery tab in the popup window:
Click the "Show" link and find the "Link URL" field.
Click the "File URL" button to make sure the correct URL is displayed, then triple-click in that field to select it. Press Cmd-C to copy that URL to the clipboard.
If you want to upload a new image, the process is similar, except that you'll need to upload the image normally, then find its Link URL field after uploading. Either way, you now have the image URL on your clipboard. You can close the Media panel and return to your Category editing page.
Once there, click the small "tree" button in the toolbar.
Paste the image URL from the clipboard. Optionally set the image to Align Left (or right), or change its dimensions.
After clicking Insert, your image will appear in the Topic section.
Adding External Links
Internal links, i.e. links between the stories in your Topic section, are created automatically and appear under the Related Stories section of the sidebar.
Your readers may also appreciate useful external links pointing to sites or stories elsewhere on the web on the same topic. WordPress provides a Links manager, which you can use for this purpose. The idea is to put your links in "Categories" that match your Story categories. Locate the Links Manager in the left rail:
Visit the "Link Categories" section and ensure that there is a link category with a slug field that exactly matches the slug of your main Topic category. Now click Add New and create a link in that category.
That's all there is to it. Every story in your Topic will get a Links element in the sidebar that includes only the links in your category.
Adding Stories to a Topic
Now that your Topic has been created, it's time to associate stories with it. When users view any story that belongs to a topic, they'll have easy access to both the parent Topic page and to all of the other stories in that topic.
Click the New Post icon at the top right of the screen:
Before you do anything else, associate your new story with the Topic it belongs to by finding the "Categories" section at the right side of the screen and checking the box for your Topic.
While it's possible to associate a story with multiple Topics/Categories, try to avoid doing so, as it creates ambiguities in the system (for example, when viewing that story's page, which topic banner should it display? Our system will simply use the first one encountered in that circumstance, which may not be what you want).
The rest of the story entry process is straightforward WordPress (again, see our Using WordPress tutorial), with two exceptions:
- The rich text editor can work in either "HTML" or "Visual" mode. Switch between them by using the tabs at the top of the editor (see image below). We recommend staying in Visual mode unless you need to embed code from other web sites (as when embedding YouTube video or Google Maps). In those cases you'll need to switch to HTML mode.
- Use the "More" icon (circled below) to insert a break after the lede. This will cause only the first paragraph (or first sentence, or whatever you choose) to appear on the home page and Topic pages, and the full story to appear only when a user clicks through to read it.
As noted above, the width of the main content area in story bodies is 640px. This should accommodate most multimedia elements. However, if you want to embed HD video or a really wide map or data visualization, our Topics system gives you the option to drop the sidebar and use the entire 900px canvas.
Scroll down to the Custom Fields section and select "full_width" from the picklist. Enter the number "1" in the Value field. Click the "Add Custom Field" button and Update your post.
The rest of the Topics system is "standard WordPress" in all other respects. Again, see our Using WordPress tutorial for more information.
Authors and editors can stop reading here. The rest of this tutorial is written for people who want to implement a Topics site of their own.
Building a Topics System
So you'd like to implement a Topics system for your own publicaton? There are basically two approaches you could take:
- Work with your web engineering team to build similar functionality into your current CMS.
- Create a new Topics site parallel to your main site, designed to do just this.
The rest of this tutorial explains how we modified WordPress to function as a Topics system, so you can apply the same approach to any WordPress theme. We've also made our demo site available as a free download, which you can use as a starting point. You can download the demo theme at the end of this tutorial.
Our Topic Central theme, based originally on the popular Cutline theme, relies on the following plugins. Please install and activate them before working with our sample theme:
Allow HTML in Category Descriptions
The core of the Topics system is the WordPress "category," which means authors and editors will be doing lots of editing to category descriptions. By default, HTML is stripped from category descriptions. This plugin overrides that behavior.
Category Description Editor
Places a rich text editor on the category description field, allowing authors and editors to work in a familiar environment, without having to type HTML manually.
Category Images II
Allows authors and editors to associate a unique banner image with each category (topic). Images must be prepped in Photoshop or similar before upload (our demo theme assumes a banner image of 900x140px).
Weasel's HTML Bios
Our demo theme provides "Author" pages, which show the author's bio as well as links to all stories written by that author. By default, the simple WordPress bio field for authors does not allow HTML. With this plugin installed, authors can craft a fancier bio.
Twitter for WordPress
On individual posts, this theme will display the author's last three tweets at the bottom of the sidebar. There are many Twitter plugins for WordPress, but we like this one. Simple, but very programmable. We utilize the Jabber / Google Talk field in the profile editor for Twitter integration.
This one handles a couple of thorny security issues. To post embed code from YouTube, Google Maps, etc., users need the "administrative" role. However, that role gives each author way too much control (potentially dangerous to the whole site). And keep in mind that Administrators and Editors can edit all posts, while Authors can only edit their own. By giving writers the Author role, you prevent confusion when someone accidentally edits the wrong story. The solution is to use a Role Manager plugin like this one and just give normal authors and editors the ability to post embedded content from other sites (which they don't have by default). We also need to let authors edit category description pages. After installation, use the role manager plugin to give authors and editors these three capabilities: "manage_categories," "unfiltered_html," and "manage_links."
By default, WordPress does not return search results for text found anywhere in the database besides Posts and Pages. Text in category descriptions is not returned, but our Topics system relies heavily on category description fields. Our hope was that this plugin would solve this problem, but unforunately it does not. However, it will return results for associated posts. For example, if the word "zippy" is present in the category description for the topic "Healthcare Reform" and a user searches on "zippy," the results will show posts belonging to the Healthcare category, even though they won't return the topic page itself. We hope this issue is fixed in the future.
This section is written for WordPress developers who know PHP and are comfortable editing template files manually.
To get those nice rich category descriptions to show up at the top of Topic pages, add this code to your archive.php template (see full working example in the downloadable demo at bottom of this page).
This is an optional step. By default, Topic pages will appear at /category/[slugname]. We prefer to display them at /topic/[slugname].
To make this happen, go to Settings | Permalinks and enter the word "topics" into the "Category Base" field.
Links to Related Content and Tag Cloud
For any given story page, we need to determine which categories it belongs to, and display links to all stories that are also in those categories (ideally a story is only in category at a time, though in practice, we need to assume that a story can be in multiple categories).
Somewhere near the top of the sidebar code (in sidebar.php), we need to reset the internal query that creates a "loop" for WordPress to iterate through, so it only iterates through the posts that really are related. Add code like this:
Now to display the actual related stories and tags. Note that we only display this block when viewing a category (topic) page or a single post. We don't show Related Stories or Tags on the Homepage, About page, etc.
The tag cloud is generated with WordPress' own internal function for this purpose. The tag cloud is global to the whole site - it does not attempt to filter for tags related to the current story (doing so wouldn't leave us with much of a tag cloud).
Serving suggestion -- season to taste.
Authors and Editors can create external links associated with a category (topic). To make sure we only display links from the current category or categories, use:
We want to get the author's Twitter handle from the "Jabber" field in their profile, then retrieve their most recent three Tweets via the plugin we installed earlier.
Note the is_single() conditional here - we only display the Twitter feed on single post pages.
One of the challenges of building a topic-centered site with WordPress is in customizing the banner images for various sections of the site, in such a way that site editors can change them themselves without manual template editing. The goal is to have that banner image appear in place of the default whenever either the topic page or any story associated with that topic is viewed. In all other cases we want to fall back to a default image.
Our system uses a modified version of Category Images II (CI II) , which is the only plugin we could find that even came close to fulfilling this need. Even so, it isn't perfect and we had to modify the way it works a bit.
Unfortunately, CI II doesn't have a concept of a "default" image, so you'll need to code your fallback images in manually. Note the calls to the plugin-provided function calls ciii_category_images() and ciii_category_archive_image() below. See header.php in the demo theme for details.
In addition, there's the thorny problem of displaying banner images for posts that belong to more than one category. CI II is designed to show a series of icons -- one for each category the current post belongs to. But because you can only have one banner image per page, we've modified the view code slightly to grab the image for the first category in the array. Not perfect, but it gets the job done. You'll find our modification in [themedir]/view/category-images-ii/category-images.php, which is a template file used when CI II images are displayed.
$categories is the bit we changed. Note that this component is NOT contained in the plugin itself - if modifying your own theme rather than using ours, just copy the "view" folder out of our theme and into your own and you'll get the right functionality.
Our theme provides an author.php file, which displays the HTML-formatted bio field for a particular author, as well as a list of all stories that author has written. To get access to all of the author data, we'll need this awkward little gem at the top of the author template:
With that in place, we can now pull in the author bio farther down the page with:
The story list will work like a standard WordPress loop.
To link to the author page from bylines in any template, use:
Again, a full working example can be found in our downloadable demo.
Download the Demo Theme
Please feel free to implement, augment, or modify this demo theme in any way you see fit. Just leave a comment or send us email - we'd love to know how it's being used out there!
About this Tutorial
Tutorial presented by the Knight Digital Media Center at the University of California, Berkeley
This content may not be republished in print or digital form without express written permission from KDMC. Please see our Content Redistribution Policy at kdmc.berkeley.edu/license.