How We Got Into This Mess

When I was hired at Pop Art in early 2006, there was no official Pop Art blog. The design team had their own site, which was sporadically updated and not branded as a Pop Art site. Several members of the dev team also had work blogs, but again, they were not branded. As somewhat of a blogging zealot, I pushed hard to standardize these onto one site, and in August, I got the go-ahead to set something up.

When I started looking into solutions, I was working with a few assumptions. First, that the existing blogs would stay up, and the central blog would syndicate their posts by pulling in their RSS feeds. Secondly, despite my strong preference for Wordpress, that it was not a viable option for us. That’s because we’re a Microsoft shop, so we don’t have a lot of PHP experience in-house, and we don’t have any Apache boxes to host the site on. Also, since I was assuming we wanted multiple blogs syndicated at one domain (rather than a single blog with multiple authors), there wasn’t a good way to do that with Wordpress at the time (Wordpress MU hadn’t really taken off at the time).

Given those assumptions, we ended up installing Community Server. I felt good about this because it was the product used to host all the blogs at Microsoft, and appeared to be well-supported and active.

Increasing Difficulties with Community Server

However, installation and customization were a nightmare. After a lengthy struggle to get everything set up correctly, it became increasingly clear that some of our assumptions were inaccurate.

Although we started with independent blogs being syndicated, our CEO eventually wrote a company blogging policy disallowing this, so we ended up with a Community Server site that had 20+ single-author blogs being aggregated onto a single homepage to give the appearance of a standard multiple-author blog. We weren’t taking advantage of anything the multiple-blog scenario was originally set up to do.

Over time, we found out that Community Server was not only difficult to customize, it was also poorly supported. After we purchased and installed CS2007, they released two further versions, and stopped supporting ours. (When we contacted them about purchasing an updated for our license to add more blogs, we were told our version was no longer supported, and they offered to let us upgrade at a discounted price of $900. We didn’t purchase that upgrade, and three months later, they announced that they were changing their license structure again, and we would now have to pay full price for a brand new license if we wanted to upgrade.) I know that companies make money by releasing new versions, but it seems crazy that less than two years after we bought their product, they wouldn’t support us at all without a full upgrade.

To cut a long story short, the straw that finally broke the camel’s back was when we decided to integrate Twitter into our blogs. We were able to add the javascript twitter script to the sidebar to display the Pop Art feed easily, but in order to add individual twitter feeds to the profile page, we were going to need to bring in the .NET programmers, who are always really busy — and I realized that if we were using Wordpress, I could do everything myself.

There were other factors, including our frustration with the licensing situation, and the fact that we didn’t need the overly complicated multiple blog situation anymore, but the customization difficulties were the kicker. Once I was able to assure our CEO that switching to Wordpress wouldn’t lead to a repeat of this situation in a few years, we had the green light to make the switch.

Exporting Posts from Community Server

Getting our posts from Community Server to Wordpress was our first hurdle. Out of the box, there’s no way to make it work, other than having Wordpress scrape the RSS feed — and that would lose all the comments. Thankfully, other people had already done the legwork for me. Bear with me here.

Aaron Lerch wrote a great post in August 2007 about switching from Blogger to Wordpress using BlogML. I already knew from when we originally set it up that Community Server supports BlogML, and Aaron wrote a module for Wordpress to import from BlogML format.

Then, in October 2007, Rob Walling wrote a post about switching from Community Server 2007 to Wordpress. He updated Aaron’s Wordpress importer because Wordpress 2.3 switched from categories to tags.

Finally, in October 2008, Kavinda Munasinghe wrote a post about switching from DasBlog to Wordpress, and once again, updated Aaron’s Wordpress importer.

So, I grabbed the BlogML Export module for Community Server 2007, and Kavinda’s updated BlogML Importer for Wordpress, and set about my business.

Importing Posts to Wordpress

The first problem I ran into is that I couldn’t get one big export file of every blog in our Community Server installation, I had to create an export file for each one.

The second problem I ran into is that my exports didn’t import correctly. Now, I have no idea if the problem was from one of the versions of the importer, or if the exporter wasn’t working correctly, or even if the latest version of Wordpress just has a slightly different database. What it boiled down to is that I had to manually reformat each of my 32 export files.

The biggest issue was with categories/tags. First of all, all my tags were being imported as categories. I was willing to ignore this, since Wordpress has a “convert categories to tags” feature, but it was still annoying. In addition to that, however, all the categories were importing as numbers. Turns out that Wordpress was grabbing the category ID instead of the category name.

I looked at both the importer and the exporter, but I didn’t have the programming know-how to fix it, so ultimately, I just wrote a simple regular expression to reformat all the categories so that their names were in the ID attribute so they would import correctly.

In addition to that, author names weren’t importing correctly, draft status posts were being published, and a couple of older blogs where the authors had copy-and-pasted from Word were bringing in a bunch of crazy custom microsoft markup. All in all, I probably spent about 3-4 hours manually cleaning up all my export files. This all sounds like a huge pain (and it was!), but I’m happy to say that once I was done, everything imported perfectly.

Redirecting Old Posts

The final thing I needed to do was set up a 301 redirect for all the old posts. Aaron’s importer script gives you a file that you can use to build a list of redirects in your .htaccess file, but I was sure there was a better way. After a bit of digging, I found a forum post about using mod_rewrite to change dynamic to static URLs that helped me write the following regular expression to redirect from our old permalinks to our new ones.

RewriteRule
     ^([^/]+)/archive/([^/]+)/([^/]+)/([^/]+)/([^/]+).aspx$
     http://blogs.popart.com/$2/$3/$5 [R=301,L]

Note that normally, that would all appear on one line. I’ve broken it up for readability. That looks for urls like /scott-vandehey/archive/2006/11/09/post-title.aspx and redirects them to /2006/11/post-title/. With that one rule in our .htaccess file, all our old blogs posts would automatically get a 301 redirect to the new URLs.

Now that we’ve made the switch, I’m really happy we spent the time on it. We took the opportunity to redo the design to better match our main site, and the template engine in Wordpress is a real joy to work with — and well-documented, more importantly! I’m confident that we’ll be able to handle the evolving needs of our company in the future, and informally, I can say that everyone seems happier using the new system. The transition was a pain, but the results were worth it.

Use RSS Excerpts to Strip All HTML

/*
	just like the_excerpt, but really strips all the HTML, including BR tags
*/
<p><?php the_excerpt_rss(); ?></p>

We wanted to display a post excerpt on most pages. Normally, I would just use wordpress’ the_excerpt function. It automatically displays the post excerpt if it exists, and if not, then it grabs the first 50 words of the post, and even strips the HTML! Sounds great, right? Except for one thing — it doesn’t strip line breaks, so instead of a page full of single-paragraph excerpts, I had several posts with two small paragraphs displaying. Not a big deal, but it was messing up our design.

After doing a little digging in the wordpress documentation, I found that the_excerpt_rss does exactly what I was looking for. It’s intended to be used in RSS templates, but you can use it in your regular pages and it works just as well. The only hiccup is that you’ll need to wrap it in a <p> yourself.

Use the Nickname Field for Job Titles

<?php the_author_meta('nickname'); ?>

Our design shows the job title under everyone’s name. There’s no “job title” field in the user accounts, but I was able to repurpose the nickname field. To display it in the site, just use the code shown above in your post templates. Remember, the people looking at your site won’t know that you’re using the “wrong” database field! (You know, unless you tell them, like I’m doing.)

Bit.ly Shortener for Twitter Links

/*
	Bit.ly URL Shortener
	Automatically shorten a URL using the Bit.ly API
	based on code from http://davidwalsh.name/bitly-php
*/
function make_bitly_url($url) {
	$login = 'YOUR BIT.LY LOGIN';
	$appkey = 'YOUR BIT.LY API KEY';
	$format = 'xml';
	$version = '2.0.1';
	$bitly = 'http://api.bit.ly/shorten?version='.$version.'&longUrl='.urlencode($url).'&login='.$login.'&apiKey='.$appkey.'&format='.$format;
	$response = file_get_contents($bitly);
	//parse depending on desired format
	if(strtolower($format) == 'json') {
		$json = @json_decode($response,true);
		return $json['results'][$url]['shortUrl'];
	} else { //xml
		$xml = simplexml_load_string($response);
		return 'http://bit.ly/'.$xml->results->nodeKeyVal->hash;
	}
}

Adding a “retweet this” link at the bottom of every post is pretty easy. You just link to twitter.com and pass a “status” query string in the URL with whatever you want their tweet to include — namely, the URL to the post they’re retweeting. But our URLs can get pretty lengthy, since they include the post title. Obviously, with Twitter’s 140-character limit, every character counts. To get around this, I found some code by David Walsh to make a bit.ly short URL. It works great, but you’ll need to register for an API key on their site to use it. This code goes in your functions.php file, and then you can call it from any post loop like this:

<?php echo make_bitly_url(get_permalink()); ?>

Use a Custom Default Gravatar

/*
	Add new default avatars
	based on code from http://wpengineer.com/add-avatar-to-wordpress-default/
*/
if ( !function_exists('fb_addgravatar') ) {
	function fb_addgravatar( $avatar_defaults ) {
		$stormtrooper = get_bloginfo('template_directory').'/images/avatar.png';
		$avatar_defaults[$stormtrooper] = 'Storm Trooper';
		return $avatar_defaults;
	}
	add_filter( 'avatar_defaults', 'fb_addgravatar' );
}

Wordpress’ built-in support for gravatars in comments is fantastic, but if your commenters don’t have a gravatar account, the default avatar will be displayed. Wordpress lets you choose between a simple gray silhouette or several dynamically generated icons, none of which really fit our design. Luckily, I found this code that lets you add your own default avatar to the list — in our case, a lovely photo of a storm trooper. This code goes in your functions.php file, and it adds a new option to the default gravatar list in your admin area.

Use HTML in User Profiles

/*
	Turn off HTML filter for user profiles
*/
remove_filter('pre_user_description', 'wp_filter_kses');

Our fancy profile pages use the “Biographical Info” field in the user profiles. The only problem is that by default, wordpress strips any HTML from it. You can disable that feature by adding this bit of code to your functions.php file.

Add More RSS Feeds

<link rel="alternate" type="application/atom+xml" title="<?php bloginfo('name'); ?> Full Posts" href="<?php bloginfo('atom_url'); ?>" />
<?php
	// add comments feed on single-post pages
	if (is_single()) {
		while (have_posts()) : the_post();
			if ('open' == $post->comment_status) : /* If comments are open */
?>
<link rel="alternate" type="application/atom+xml" title="Comments on <?php the_title(); ?>" href="<?php bloginfo('url'); ?>/index.php?feed=atom&amp;p=<?php the_ID(); ?>" />
<?php
			endif;
		endwhile;
		rewind_posts();
	// add category feed on category archives
	} else if (is_category()) {
		$category = get_the_category();
?>
<link rel="alternate" type="application/atom+xml" title="Posts in the <?php echo $category[0]->cat_name; ?> category" href="<?php echo get_category_feed_link( $category[0]->cat_ID, 'atom' ); ?>" />
<?php
	// add tag feed on tag archives
	} else if (is_tag()) {
?>
<link rel="alternate" type="application/atom+xml" title="Posts tagged with <?php single_tag_title(); ?>" href="<?php echo get_tag_feed_link( get_query_var('tag_id'), 'atom' ); ?>" />
<?php
	// add author feed on author pages
	} else if (is_author()) {
		if(isset($_GET['author_name'])) :
		$curauth = get_userdatabylogin($author_name);
		else :
		$curauth = get_userdata(intval($author));
		endif;
		$authorfeedlink = get_author_feed_link( $curauth->ID, 'atom' );
	?>
<link rel="alternate" type="application/atom+xml" title="Posts by <?php echo $curauth->display_name; ?>" href="<?php echo $authorfeedlink; ?>" />
<?php
	}
?>

Finally, one of the best (and relatively unknown) features of wordpress is that you can get an RSS feed for just about every page on the site, just by adding /feed/ to the end of the URL. I wanted to take advantage of this feature to add link elements for those special feeds on different pages — for example, a feed for an author’s posts on their profile page, or for comments on a post on that post’s page. The above code is a little convoluted, but it includes all the logic to add the following feeds on the appropriate pages:

• Complete blog feed on every page
• Comments feed on individual post pages
• Category feeds on category pages
• Tag feeds on tag pages
• Author feeds on author profile pages

Note that I’ve set this up to provide Atom feeds, but you can change it by replacing every instance of atom with rss2. This code goes in your header.php file, near the rest of your meta and link elements.

If you’re reading this in your feed reader, then our RSS feed has automatically redirected, and you shouldn’t have any problems. But in case you’re a stickler for official URLs, or you haven’t subscribed, our new feed can be found at blogs.popart.com/feed/atom/.

In the next few days, there are some more posts coming, including one from Mark about the new design, one about how we integrated Twitter, one about some nifty Wordpress tricks we learned, and a long one about our experience converting from Community Server 2007 to Wordpress (long story short: it makes scaling Everest look like walking up the stairs).

So please: snoop, dig, stop and smell the roses. And welcome to the redesigned and improved Pop Art Blog, it’s where the magic happens (or something like that).

Before I get into how it went wrong, let me point out what went right. First of all, we did eventually succeed in getting nearly everything we wanted done, and I’m incredibly proud of the final results. Secondly, although I experienced many frustrations along the way, the official support forum was very helpful, and I always got a response to my questions within 24 hours. If you’re going to try skinning a CS2007 site, I highly recommend getting an account on the forums, and working with a programmer, if you can (more on that later).

Finally, although I did have difficulties, CS2007 is built to support a corporate blogging environment from the ground up. Wordpress and Movable Type are better programs in terms of the overall blogging experience, but their support for multiple-user scenarios are limited at best. Wordpress MU comes close, but I don’t like being removed from the primary development branch. At the end of the day, CS2007 is clearly the best solution for corporate blogging the way we want to do it.

With that out of the way, let’s talk about why skinning it was such a frustrating experience. It all boils down to one simple problem: A complete and total lack of documentation for non-programmers. Allow me to explain.

There are basically three classes of users for a product like CS2007 or Wordpress. You have your basic users who don’t know anything about the code, and only interact with the program through the browser interface. These users have minimal documentation needs. Give them some instructions on how to make a new blog post or add their logo to the default template, and they’re good to go. Both Wordpress and CS2007 have this basic documentation.

Next, you have your programmers. These are power users who are happy to muck around in the source code if they don’t like the way something works. These users have advanced documentation needs, because they need insight into things like the database schema, program controls and common functions. Both Wordpress and CS2007 have this advanced documentation. In fact, Community Server’s comes in an MSDN-style CHM file listing all the controls that are available. My programmer cohorts assure me that this documentation is quite thorough and gave them everything they needed to know.

Lastly, you have your casual developers. These are the guys like me who are very familiar with front-end code like HTML, CSS and javascript, but don’t know any .NET or PHP. These users have moderate documentation needs. They don’t need to understand how the source code works or the structure of the database necessarily. What they need is an easy way to pull out specific bits of information.

To give you a way to compare, let me give you a simple example common to both WordPress and Community Server.

In Wordpress, to display the date a post was made, you use this code: <?php the_date(); ?> I found this out by going to the Wordpress documentation, clicking on Template Tags, and then clicking on the_date in the “Date and Time tags” section. I was given a description of the tag, a list of parameters, and some examples of how to use it.

In Community Server, to do the same thing, you use this code: <CSBlog:WeblogPostData runat="server" Property="PostDate" /> I found this out by visiting the Community Server documentation section, and searching (in vain) for information on modifying templates. Eventually, I stumbled onto the Single Value Controls page, which helpfully explains the structure that is used to get a bit of information out of the database. This page does not give a complete list of values, however. To get that, I had to backtrack using the breadcrumb trail at the top of the page to the Chameleon Control Documentation page, which links to the MSDN file I mentioned before, as well as “API Property Documentation”, which includes a link to Blog Control Property Data, which lists all the properties for the CSBlog:X control. By combining the structure I found on the Single Value Controls page and the property names I found on the Blog Control Property Data page, I was able to make a control that echoes out the post date.

Now, that’s really not a great example, because I was never trying to look up something as simple as the post date. For something like that, I would look for an example in an existing theme. I’m just using this to illustrate what a pain it is to find any information on the Community Server side if you’re not a programmer. I tried looking in that MSDN document, but it was all greek to me. Even when my programmer cohorts were assisting me and walking me through the document, I didn’t understand what I was looking at.

A more common example of the kind of thing I needed documentation for was how to display a list of weblog posts but limit it by a certain tag. I never did find any documentation explaining how to do something like that. If you need anything like that, your only recourse is the forums. For example, here is a search I did for filter blog posts by tag. You’ll notice that of the results I got, most of them have nothing to do with my search, except that they are about how to use tags. Of the posts that do seem relevant, you’ll notice that most of them date from 2005 or 2006 – meaning they refer to the previous version of Community Server, and are no longer relevant.

Everything is like this. Searching for the most simple information becomes an incredibly frustrating ordeal. The only saving grace of the forum is that it is populated by people like Ben Tiedt, who managed to answer all the questions I posted within 24 hours, and was really helpful.

So, to recap: If you want to find anything out about Community Server, be prepared to spend hours trolling the forums and documentation, sifting through the irrelevant and out-of-date results to possibly find an answer, but more likely, you’ll have to post a question yourself, and wait for a community member to help you out.

I can’t be the only one who thinks that forums should not be the primary method of sharing information. Community Server desperately needs Wordpress-style documentation aimed at casual developers (like myself) who have higher needs than the average end user, but aren’t programmers.