Integrating External Content with WordPress - Detailed Instructions

I've wrapped my solution up into a WordPress plugin. To use this you'll have to be willing to edit your theme files, a couple of general-purpose include files and, if you're linking into Jalbum, the slide template for your Jalbum skin.

The plugin is designed and tested to work with WordPress 3.0, but it should work with 2.9 which also supports the required metadata functions.

Your can download the latest version from the WordPress plugin repository. If you like this plugin, then feel free to make a donation towards future developments.

There are five files in the plugin directory:

• linkexternal.php - the main plugin file, which defines the key functions of the plugin. You should not need to edit this file.
• linkexternaleditable.php - a secondary plugin file which defines functions which you may want to personalise or localise. These are held separately to make it easier to upgrade the plugin if you ever need to.
• simple_html_dom.php - S C Chen and Jose Solorzano's excellent simplehtmldom library for HTML parsing in PHP. This is used without modification, and you should not need to make any changes to this file. See http://sourceforge.net/projects/simplehtmldom/ for more details.
• comments.php - this code runs in an iframe on an external page to view comments on that page, and link back into the blog. You may want to move this to a more convenient location for easy access by other pages in your site, and will almost certainly want to personalise it.
• albumcomments.php - this code runs in an iframe on a Jalbum slide page to view comments on that image, and link back into the blog for comments management. You may want to move this to a more convenient location for easy access by your slide pages, and will almost certainly want to personalise it.
• albumcommentsinclude.php - this is an alternative version of albumcomments.php suitable for inclusion via a server side include instead of an iframe if that works better with your Jalbum skin.

The following sections describe how to integrate the plugin into your blog, and into your external content.

Each blog post with external content should be tagged with a custom field which holds the URL for the external content. The plugin supports two different custom fields:

• full This is the URL of a page, probably on the same website as your blog (although that's not required), which you want to fully link into WordPress, supporting comments. The URL of a page on the same site can be relative rather than fully-qualified. For example, the blog post for this article has a full custom field set to "/thoughts/linkexternal.asp"
• link This is the URL of a page, typically external to your website, for which you just want to provide an explicit link from your blog post.  The page won't link back to WordPress for comments.

Once you've installed the plugin, you need to make a few changes to your WordPress theme to support the links. You can make any combination of the following changes to suit your needs, or modify them as required. You may have to make similar changes in a few places, depending on your template: I had to make changes to both loop.php and single.php.

Firstly, I wanted the link from the blog post title to go directly to the full article, with a separate link to the blog permalink and comments. To do this, use the function GetFullURL(). For example, in loop.php you'll find the following line under a comment like "/* How to display all other posts. */":

You may also want to provide an explicit link to the article. To do this, just include the following at an appropriate point (e.g. after the section with the_content()):

To display comments in the external page itself, you need to include some PHP code which connects to and displays relevant content from WordPress. This also includes a link back to the permalink of the WordPress post, which is where readers can add their own comments. As my external pages are written in a variety of languages, the simplest solution is a stand-alone PHP file which can be included via an iframe, as follows:

The only change required per external page is to change the slug query value to match the WordPress blog post which points to the external page, and manages comments for it. As I use "pretty permalinks" this is a meaningful string - the format will be different for other sites, but should work the same way. You might also want to adjust the size of the iframe and its scrolling settings, but the defaults here are quite good.

You will probably need to make a few changes to comments.php:

• Move it to a location which makes it easier to refer to from external pages (like my "thoughts" directory),
• Change the linked stylesheet and background to match your site,
• Change the text displayed around the comments to match your own inimitable style.

As a future enhancement I may look at trying to find a way to include the comments form directly on each external page through the same technique.

The idea behind Jalbum integration is that I want the ability to pull an image into a post directly from my Jalbum album, complete with its metadata, without having to create a separate copy in the WordPress structure. I also want WordPress to manage comments on my images. The solution broadly follows the same model as linking to external pages, but is a bit more complex.

Editing the Slide Template

To enable full integration, you may have to make a couple of small changes to your slide template (the slide.htt file of your chosen skin). Open this file in your HTML editor, and first look for the line which outputs the main image on the slide page. In the Chameleon skin, it looks like this:

(Note that this may be prefixed with a ja:if tag, and may have other additional attributes.) The key is the attribute id="slide". If the image is given a different id tag, you may have to edit the plugin code. If it isn't given any id tag, you need to edit the template and add one.

Next, look for the code segment which outputs the image metadata. (This step is optional if you are not going to output image metadata in your blog posts). In Chameleon this is a <table> tag which looks like the following:

This needs a recognisable id attribute, so edit it to add the attribute id="metadata" as follows:

If your skin supports multiple different slide or metadata positions which are selected at generation time, then you need to make the same changes to each instance.

Finally, to include comments on the images, and a link to a page to capture and manage those comments, add one of the following to the template (or, alternatively, you can include this in the slide header or footer through the Jalbum GUI if your skin supports it).

This is generic for Jalbum integration, so you don't need to tailor it per page in the same way as linking external pages to blog posts. However, you do need the right path to wherever you hold albumcomments.php or albumcommentsinclude.php.

When you've made all your changes, remember to re-generate and re-publish your album.

Including Jalbum Images in Blog Posts

Each blog post which includes a Jalbum image needs a custom field which holds the URL for the slide page: image. The URL of a slide on the same site can be relative rather than fully-qualified, for example, "/album/-%20My%20Tenset/slides/1009_40D_9643.html".

You also need to make a few changes to your WordPress theme, wherever you want to include the images, for example in loop.php and single.php.

Where you want the image to display, you need a simple call to the ShowPhoto() function. I put this in front of the_content(), so that it's above related blog text:

The function takes two Boolean parameters:

1. ShowMeta, which is true if you also want to display the metadata table, otherwise false,
2. ShowCentred (optional), which is true if you want to centre the image and metadata within the column. If false or omitted the positioning is dictated by your theme's style.

If you want to provide a link to the slide page in the album (so that, for example, readers can view other pictures in the same series), just include the LinkExternal() function, as above. This is exactly the same function as for external page support - you only need it once, and it will display an external page link or an album link automatically as required.

Making It All Match

You'll need to make a few changes so that things all match. The details will depend on your Jalbum skin, your WordPress theme, and your own tastes, but typically they will be on the following lines.

1. Add styles to your WordPress theme (e.g. by editing the theme's .css file) to make sure image metadata displays correctly. I had to add font definitions for the .smalltxt class, and border styles for .slideImage.
2. Adjust how the image displays. This may mean adding outer tags around the ShowPhoto() function, and adding or adjusting the styles which control them.
3. Move albumcomments.php to a location which makes sense for inclusion in your album pages, change the linked stylesheet and background to match your album, and adjust the text displayed around the comments.

Supporting Comments on All Images

If I have more than one blog post for a specific image, I want comments against all those posts displayed in the album. If I have the same image in different places in my album(s), I want each to show the comments. Also, I need a way to collect comments against images for which I haven't made a blog post.

This is enabled by tagging comments with the ImageID, effectively the root filename of the image. This is extracted from the slide URL passed to WordPress, so that if the image tag is "/album/-%20My%20Tenset/slides/1009_40D_9643.html", ImageID is set to 1009_40D_9643. This value is stored in the wp_commentmeta table, and manipulated with the *_comment_meta functions.

To collect comments against all your images, you need a WordPress page for this purpose. I created one called "imagecomments" - if you choose a different name you'll need to edit albumcomments.php so that it calls the right page. You then need to make a couple of modifications to your WordPress page template (e.g. page.php):

1. At an appropriate point (e.g. above the_content()), add a call to ShowPhoto(), as above.
2. After the_content(), add the following code:

This page can then display any image, and display and collect comments on that image. You may not need to add any text, but that's entirely up to you.

Adding Blog Images to Your Feeds

You can also make your images show up as thumbnails in your RSS feed, and feed readers which support them such as Internet Explorer 8, and the iGoogle feed support. To achieve this edit the file wp-includes/feed-rss.php or  wp-includes/feed-rss2.php (whichever you use for your feeds), and add the following function calls in the while loop which processes the feed items:

• To GetThumbForFeed() after the call to the_category_rss(),
• To GetImageForFeed() before each call which outputs the item content or excerpt (there may be several of these).

The following code excerpt shows how I have done it:

(Note that it may also be possible to make this work with other feed types, but only if they support the media namespace which RSS uses to support feed attachments.)

Version 1.0, August 2010

First Stable Version

Version 1.1, October 2010

1. Fixed various minor bugs, including support for non-standard HTTP ports
2. Fixed major memory leak with image page parsing
3. Added ability to centre featured image
4. Added support for blog images in feeds

Further Options

To follow