add_rel_lightbox version 0.4.1

Upgrade from your WordPress admin panel, or download from

When I moved add-rel-lightbox across to using Simple DOM Parser in place of the regex controlled for version 0.4, I had a little problem with the pre-release code stripping line breaks from every post that, although it didn’t cause a display problem by it’s self, caused another regex based plugin to bork the page at the point of render. While this was sorted for the version 0.4 release, there was still some quieter newline-stripping that was still going on that version 0.4.1 now resolves.

As with the previous problem, this again came from the default settings of the Simple HTML DOM Parser. By default, the parser will try to close any un-closed html tags in the input that it’s given; to try and allow for malformed html with the minimum of fuss, and allow the PHP that’s using the parser to call any tag in the content. However, one of the results of this behaviour is that it will concatenate all the lines of a multi-line tag — such as <code> or <pre> — by removing all the newlines.

To stop this happening, I’ve set $forceTagsClosed = false for the the parser. While this option true by default to allow for less trusted html, this shouldn’t be an issue for parsing WordPress post content as this is inherently trusted content and because only a small subset of tag information is used, it should have little effect on the actual output.

If you’ve seen multi-line <code> or <pre> elements reduced to one line after installing version 0.4, an update to version 0.4.1 should fix that for you.

add-rel-lightbox Version 0.4 Released

Upgrade from your WordPress admin panel, or download from

Version 0.4 switches from identifing the link-wrapped images in a page with hacked-together regexes that just about work, to properly parsed HTML structure using PHP Simple HTML DOM Parser.

When I initially tried to release version 0.4 and installed the updated plugin on this site, suddenly the content for half the posts stopped being displayed. After retracting the update, having a small panic, and reviewing the code that had been working without error in testing, I eventually found the culprit of the missing content: a regex in another plugin!

It turns out that the Simple HTML DOM Parser is set to strip linebreaks from the HTML input as standard. It was this operation, on content that otherwise was not altered by add-rel-lightbox that was breaking a (.*?) heavy regex. See also: Death to Dot-Star!

I’ve now changed add-rel-lightbox to leave the linebreaks in the content, so it will return content completely untouched if there are no link-wrapped images in the post. This means that it will play nicely with with other plugins but, if nothing else, this is a good example of why HTML should be parsed properly instead of using regular expressions for all but the most predictable content.

The couple of questions on the plugin’s support forum suggests that add-rel-lightbox is being used with less lightbox-compatible image handlers, so it’s probably a good time to add some configuration options for the plugin. Nothing too complex; just some variables that can be stored so they don’t get overwritten by a plugin update.

add-rel-lightbox now using Simple HTML DOM

When I first mashed together add-rel-lightbox, I used regular expressions to control and replace the relevent parts. This was my fault. Regexes were the only tool I had. It was a bad thing. Parsing HTML with regex is wrong.

[…]using regex to parse HTML has doomed humanity to an eternity of dread torture and security holes using regex as a tool to process HTML establishes a breach between this world and the dread realm of c͒ͪo͛ͫrrupt entities (like SGML entities, but more corrupt) a mere glimpse of the world of reg​ex parsers for HTML will ins​tantly transport a programmer’s consciousness into a world of ceaseless screaming, he comes, the pestilent slithy regex-infection wil​l devour your HT​ML parser, application and existence for all time like Visual Basic only worse[…]

The whole StackOverflow answer makes a very sane and reasonable argument for not using regexes to try and parse HTML, so I’d recommend taking a look. However, if you’re not totally convinced, perhaps you’d prefer Bring Me Your Regexes! I Will Create HTML To Break Them!. That did convince me.

PHP does have a DOM extension, so it’s possible to use that to operate on XML elements, but it all looked to complex and involved for me to find a way in, but S.C. Chen’s PHP Simple HTML DOM Parser made the whole thing fairly straight forward.

The whole, commented, revised code is up at Github, but while I have a few regular expression match calls, they’re all operating now on the returned HTML attributes from the DOM parser, instead of trying to pull put the details from raw HTML.

After including the Simple HTML DOM library, the script:

  • Finds any link wrapped images.
  • Checks that the link points to an image file and doesn’t have a “lightbox” relation proterty applied. (as a side effect, any link with rel=”nolightbox” will also be overlooked)
  • Adds the popup caption from the database if it’s a single hosted image, or part of a gallery.
  • And finally, adds “lightbox[post-(post_id)]” to the rel attribute of the link

This should be more robust than version 0.3, although I haven’t seen any problems with that version in practice. However it does also make the code much easier to extend or expand in the future.

While I’ve been meaning to do this for a while, I’ve only just got round to coding it up. Everything in the “DOMcontrolled” branch looks good in the initial testing, so the version is currently set at 0.4.RC1, which I’ll roll out after it’s survived more prodding.

See also: Coding Horror > Parsing HTML the Cthulhu Way

add-rel-lightbox version 0.3

New for version 0.3:

  • Adjusted the filter hook priority so it uses the core shortcode function.
  • Also works with the_extract() e.g. on front page and category listings.
  • All images and gallery form one linked gallery per post/page.

Search for “add-rel-lightbox” from your WordPress installation or download the source from:

Where version 0.2 added the capability for add-rel-lightbox to add attributes to image links from the WordPress shortcode, it did replace the WordPress core gallery_shortcode() function. Clearly, replacing a function means having to keep the plugin code updated if there are any changes to the relevant core code, so it’s not an ideal solution. However, at the time, I didn’t know how to ensure the link filter ran after the gallery shortcode.

The answer is in the WordPress codex (, where it states:

do_shortcode() is registered as a default filter on ‘the_content’ with a priority of 11.

So just setting add-rel-lightbox’s filter priority means it will run after all shortcodes by default, and the core gallery_sortcode() can be used.

Also from a suggestion from Jason Spatola, version 0.3 also works with the_excerpt, so images in post excerpts also have lightbox attributes added. But so that all the images on the page aren’t called in one single gallery, the rel="lightbox" now has includes the post number.

<a href="/url/to/" rel="lightbox[post-$id]" title="Media description"><img…></a>

Gallery images are also supplemented by post ID, so all local embedded images form one linked gallery per post. Continue reading add-rel-lightbox version 0.3

add-rel-lightbox version 0.2

New for version 0.2, the plugin will now also add the lightbox attribute and caption to image linked galleries using the [gallery link=”file”] shortcode.

add-rel-lightbox is a WordPress plugin that will automatically add a rel=”lightbox” attribute and the image appropriate description from the media library to link-wrapped images placed in WordPress posts.

Previously, the plugin only worked with images placed into posts of the exact format used by the “add media” dialogues, and only for images that are in your media library. This means it will not interfere with any images that have already added attributes to.

New for version 0.2, the plugin will now also add the lightbox attribute and caption to image linked galleries using the [gallery link=”file”] shortcode.

In addition to the add-rel-lightbox plugin, to work properly, lighbox (or a lightbox clone such as slimbox) must be active on your site. This can be either as part of your theme, or included as a plugin. If at any time, either component is not activated, the site will revert gracefully to the standard function of “open image as new page”.

So with the plugin activated and your lightbox clone active, using

[gallery link="file"]

in your post will give:

Plugin available at the WordPress Plugin Directory or search for “add-rel-lightbox” in the `Plugins -> Add New` page of your site administration.

Code is available for play with, adjust, fork and modify at, improvements are accepted.

add-rel-lightbox now available as WP plugin

add-rel-lightbox, the code discussed in this post is now available in the WordPress Plugin Directory. This means that you can install it in your WordPress site by searching for “add-rel-lightbox” in the `Plugins -> Add New` page of your site administration.

The code is also hosted at github ( for you to pull, fork, alter or adjust (git is my preferred revision controller): improvements are accepted.

To make it work, you will also have to have a lightbox/slimbox/lightbox clone installed on your site — either as a plugin, or as part of your theme, however if one is missing or disabled, add-rel-lightbox will fail gracefully and silently. I’m using “slimbox plugin” (also on the WP Plugin Database), which despite not being listed as compatible, continues to work on my up-to-date WP versions.

That is all.

Add rel=”lightbox” to WordPress Images

Now a WordPress Plugin, see the most recent version releses: Category > add-rel-lightbox

I really like the pop-up display style of lightbox and slimbox, and WordPress has a really nice integration for adding pictures, but the two don’t talk to each other automatically. Getting images insterted from the WordPress media dialogue has a few requirements:

  • Automatically add the rel="lightbox" to a link that wraps an image, but only when the link points to the original image
  • Be able to identify that the inserted image and link is the format inserted from the WordPress media library
  • Add a caption to the lightbox that is correctly formatted to include any html characters. If you have to manually enter lightbox captions for the same picture on every page, then that’s much worse than only entering them once in the media library
  • should fail gracefully if lightbox or slimbox is removed/deactivated
  • Ignore link-wrapped-images that already have lighbox attributes set

What I’ve got in the form of a basic plugin is shown below.
Continue reading Add rel=”lightbox” to WordPress Images