Adding to a WordPress page’s URL without changing the URL of its Child Pages.

I was recently asked to add an extra path component to the URL of a WordPress page for SEO reasons. It took some diving into the internals of WordPress. Here’s the setup:

  • WordPress is installed in the site root, at example.com
  • We are using a static homepage
  • The company blog is at example.com/blog/
  • I was asked to make the blog URL be example.com/blog/some-extra-keywords/ without changing the URL of the current and future blog posts, which are currently example.com/blog/post-name/

There are 3 things required to make this work:

  1. A filter to tell WordPress to process requests for /blog/some-extra-keywords/ as if they are for /blog/
  2. A filter to change permalinks from /blog/ to /blog/some-extra-keywords/ (Optional, but recommended).
  3. A redirect from /blog/ to /blog/some-extra-keywords/ (Also optional, but also recommended).

Treat /blog/some-extra-keywords/ requests like /blog/

We don’t want to change the URL of the blog page in WordPress’s Edit Page screen because that will change the URL of past and future all blog posts. We need to tell WordPress that a request for /blog/some-extra-keywords/ is a request for /blog/. This is done by adding a filter to WordPress’s request filter hook:

/**
 * Make the URL /blog/some-extra-keywords/ respond as /blog/ 
 * would.
 * @param  array $request The request array that WP generates.
 * @return array          The modified request array.
 */
function jb_filter_blog_url_request( $request ) {

    if ( isset( $request['name'] ) && 'some-extra-keywords' == $request['name'] ) {
                // it's a page we're requesting. If you're doing this to something other
                // than a page, try setting $request['name'], and don't unset it 2 lines
                // later
        $request['pagename'] = 'blog';
        unset( $request['name'] );
    }

    return $request;
}
add_filter( 'request', 'jb_filter_blog_url_request' );

Since WordPress identifies pieces of content by the last part of the URL, (the “name”), that’s all we have to change. In this case, because the blog is on a page, we had to set $request['pagename'].

Note: This is optional, but recommended. If you don’t do this you must do the next item, (redirect /blog/ to /blog/some-extra-keywords/), but you get the most SEO benefit if you do both.

With #1 it’s time to change links to the blog page to point to the new URL. The old URL still works, and you’ll be redirecting it in Step 3, but modifying the links cuts out a round-trip to the server, making your site faster, and it means that anytime a spider crawls the site it will find the correct URL.

Again, we create a filter function and hook it up. Because I’m doing this all to a page, I’m hooking on to the page_link filter, but the function also works with the post_link filter. In fact, I originally used the post_link filter, which doesn’t work for pages, and spent a while banging my head against a wall trying to figure out why it didn’t work.

By hooking into page_link or post_link you’ll modify the URL everywhere it is generated with get_permalink(), which is almost everywhere. Menus, lists of pages, and even the XML Sitemap that Yoast’s WordPress SEO plugin makes will be have the new URL. If you have typed the URL somewhere this filter will not change it, but that’s why you’ll set up a redirect in Step 3.

The code:

/**
 * Modifies the blog URL when it's requested using get_permalink(). 
 * 
 * Note that this filter is set up to work on both posts & pages, and the 
 * post_link and page_link filters don't pass quite the same parameters:
 * - $post is an post object for post_link and a post ID for page_link, so we
 *   get the post object if $post is numeric
 * - $dontuse is completely different between the two filters, but not needed,
 *   so we ignore it.
 * 
 * @param  string $url       The URL to be filtered.
 * @param  mixed  $post      The post ID or post object that corresponds to $url
 * @param  mixed  $leavename Differs depending on filter. Ignore.
 * @return string            The possibly-modified URL.
 */
function jb_modify_blog_url( $url, $post, $leavename ) {
    $true = false;
 
        // don't do it in the admin, I'm afraid the modified URL will get
        // added to the URL slug field on the Edit Page screen, and get
        // permanently added, with another copy of it being added every time
        // the page is saved.
    if( ! is_admin() ) {

        if ( is_numeric( $post ) ) {
            $post = get_post( $post );
        }


        if( 'blog' == $post->post_name ) {
            $url .= 'some-extra-keywords/';
        }
    }
    return $url;
}
add_filter( 'page_link', 'jb_modify_blog_url', 10, 3 );

The magic is in the third if condition: If the page name is ‘blog’ add the extra keywords to the URL.

Redirect from /blog/ to /blog/some-extra-keywords/

Note: This is optional, as well, but if you don’t do it the blog homepage will be available at both /blog and /blog/some-extra-keywords/ which could lead to a duplicate content penalty from Google.

We’re going to do a 301 Redirect to tell search engines that the blog is now at /blog/some-extra-keywords/. I’m going to do this in a .htaccess file because that way the web server doesn’t have to start PHP or WordPress.

If you’ve already got a rewrite section in your .htaccess file, add the following line to it:

RewriteRule ^blog/?$ /blog/some-extra-keywords/ [R=301,L]

This will redirect both /blog/ and /blog, (the first ? makes the slash right before it optional), to /blog/some-extra-keywords/. If you don’t have a rewrite section, add one:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /

RewriteRule ^blog/?$ /blog/whole-house-fan-energy-saving-tips/ [R=301,L]

</IfModule>

And that’s it.

Conditionally Loading Javascript & CSS with Fancybox for WordPress

The Problem

I’ve been working on improving the performance of a client’s WordPress-based website recently and it’s become very clear to me just how much CSS & Javascript plugins load, even when it’s not needed.

On this particular website 47% of the Javascript and 57% of the CSS loaded on the site’s homepage is not required on the homepage, but is required elsewhere, so it should be loaded conditionally. Sometimes this is easy, but sometimes it’s not.

Fancybox for WordPress is not an easy plugin to make load client-side resources, after all, it’s made to show a lightbox on any image, and especially on any gallery. When the wp_enqueue_scripts action happens, where it is recommended that we set the scripts and styles that will be used on a page, we don’t yet know what will be on the page. Fortunately, we can call the wp_enqueue_script() function after that, during the body of the page, and those scripts will be printed in the wp_footer() function. The same is true for wp_enqueue_style(). So, here’s what we do:

  1. Stop Fancybox for WordPress from including its scripts & styles by default.
  2. If a gallery or image that we want to use Fancybox on is displayed, we tell WordPress to display the Fancybox scripts & styles in the footer.
  3. Enjoy faster pageloads.

Sounds simple, but there are a few interesting bits. Now for the code.

The Code

I use three functions to check if the Fancybox scripts & styles are needed. They can be in a theme’s functions.php, (where I have them at the moment), or they could even be rolled into their own plugin.

First tell Fancybox not to include its code by default. Instead of manually dequeuing every style & script, remove the Fancybox functions that do the enqueuing from the wp_enqueue_scripts and wp_head action hooks:

// don't enqueue Fancybox scripts by default.
function jb_dequeue_fancybox_css_js() {
    remove_action( 'wp_enqueue_scripts', 'mfbfw_styles' );
    remove_action( 'wp_enqueue_scripts', 'mfbfw_scripts' );
    remove_action( 'wp_head', 'mfbfw_init' );
}
add_action( 'wp', 'jb_dequeue_fancybox_css_js' );

Next create a function that re-enables Fancybox, and remembers that it did so. Here there are two static variables, which will hold their value between function calls, (kind of like hidden globals), which store state. The $fancybox_is_used variable is returned so this function can be called with no arguments to find out if Fancybox has been used on page. Note the priority of 25 when hooking mfbfw_init() to the wp_footer action. This is needed because mfbfw_init() prints some Javascript to the page that relies on jQuery, and WordPress prints the enqueued scripts in the wp_footer action with a priority of 20, so mfbfw_init() needs to execute with a priority higher than 20.

function jb_fancybox_is_used( $used = false ) {

    // this is returned so we can call this function with no arguments to learn
    // if Fancybox has been used on a particular page.
    static $fancybox_is_used = false;

    // remember if Fancybox has been re-enabled already, so we don't enqueue the 
    // scripts multiple times
    static $fancybox_is_setup = false;

    if( $used === true ) {
        $fancybox_is_used = true;
    }

    if( $fancybox_is_used && ! $fancybox_is_setup ) {
        if( function_exists( 'mfbfw_styles' ) ) {
            mfbfw_styles();  // enqueue fancybox styles
            mfbfw_scripts(); // enqueue fancybox scripts
            // the 25 is important. WordPress prints footer scripts in the
            // wp_footer action with a priority of 20, and mfbfw_init() has to
            // be called after the footer scripts are already on the page.
            add_action( 'wp_footer', 'mfbfw_init', 25 ); 
        }
        $fancybox_is_setup = true;
    }

    return $fancybox_is_used;
}

Finally, make a function that looks for places where Fancybox is used on the page. On the site I’m working on the CSS class fancybox is used on images and in galleries that I want to be Fancyboxed, so I look for the string “fancybox” in the_content filter, and when it’s found I call jb_fancybox_is_used( true ) to re-enable Fancybox on the page. I added this to the_content with priority 11 because shortcodes, including gallery shortcodes, are executed at priority 10, and I want to be able to look through the output of short codes for the fancybox CSS class:

function jb_hunt_for_fancybox( $content ) {

    if( false !== stripos( $content, 'fancybox') || false !== stripos( $content, 'thickbox' ) ) {
        jb_fancybox_is_used( true );
    }
    return $content;
}
add_filter( 'the_content', 'jb_hunt_for_fancybox', 11 );

If you include a something you want to fancybox in a template you can call jb_fancybox_is_used( true ) manually from the template file to include the CSS & Javascript.

Other Ways

This isn’t the only way to conditionally include Fancybox’s Javascript & CSS. Instead of using jb_hunt_for_fancybox() to filter the_content there’s probably an action or filter in the gallery shortcode that jb_fancybox_is_used() could be hooked onto. It may even be possible to use the $wp_query object in an action hook just before wp_enqueue_scripts to determine if there is content on the page that needs to be Fancyboxed, let that decide whether or not to run jb_dequeue_fancybox_css_js(), and forget about the other two functions.

Let’s Do Better

Plugin authors should be working hard to only add what is needed to each page load. Who is doing a great job? How can we hack our themes to bend other plugins to our will? Comment or tweet @johnbeales to let me know.

Announcing DeadTrees

Today I’m releasing DeadTrees, a WordPress plugin to share the books you read. Get it from wordpress.org or search for DeadTrees in the Plugins > Add section of your WordPress admin.

Features

DeadTrees lets you post the books you read, with or without writing about them, (really, does the internet need to know what you thought of the last mystery you read?). It generates Amazon affiliate links to those books so you, (or I), can make a little money if your readers buy the books, and it auto-fetches the books’ cover art from Amazon so things look cool.

Why?

I have been posting about books that I read for a while now, but ground to a halt when I got lazy & didn’t want to write a whole post about each book, and realized often it doesn’t matter what I think about a book. However, I did want to keep posting at least the te title & author of each book I read, (and so my sister can check to see what I’ve read before giving me a book).

Why write a plugin when there are other plugins to share the books I read? Because the other plugins didn’t do it how I wanted them to. I couldn’t find another plugin that uses WordPress’s Custom Post Types to store books I’ve read, and books are such a perfect use of CPTs that they’re even used as the example in the WordPress documentation!

Support & All That

I’ve put DeadTrees up at GitHub, if you have issues try to submit them there. My contact page is also always available to reach me.

See It Live

DeadTrees is up & running here. Take a look at the books I’ve read.

Improving Trac’s Tickets By Milestone Report

I entered a ton of tickets & milestones into a Trac installation today and when I was done the Active Tickets report was a mess. Tickets by Milestone was better, but still far from perfect.  Time for report customization. Google helped, and so did the #trac IRC channel. If you’re lazy & want to just jump to the solution, do it.

Here’s what I was looking for in my report:

  • Group tickets by Milestone
  • Order milestones by due date, (soonest first)
  • If a milestone had no due date, put it at the end of the report, (if it’s important it’ll have a due date set, otherwise it’s a “backlog” item that hasn’t been prioritized yet.
  • Display the due dates with the milestone names.

To get started, go to the Tickets by Milestone report that’s in Trac by default and click the “Copy Report” button, you’ll get a copy of Tickets by Milestone to play with. Click the Edit Report button and we’ll update the SQL to get the report we want. Grouping by Milestone is already done in this query, so we’ll start with ordering by milestone due date and putting milestones without a due date at the end of the report.

Order by Milestone Due Date

To order by date we need to join the milestone table. Add to the line after FROM ticket t:

LEFT JOIN milestone ms ON ms.name = t.milestone

Then to the beginning of the ORDER BY statement add (ms.due > 0) Desc,ms.due, so the ORDER BY is now:

ORDER BY (ms.due > 0) Desc,ms.due, (milestone IS NULL),milestone, CAST(p.value AS integer), t.type, time

The (ms.due > 0) Desc part makes milestones that have a due date come first, then ms.due orders those by due date with the soonest first.

Display Due Dates with Milestone Names

For Trac 0.12 and above replace the line

'Milestone '||milestone AS __group__,

with:

'Milestone '||(milestone || CASE WHEN ms.due > 0 THEN ', (due ' || datetime(ms.due/1000000, 'unixepoch')  || ' UTC)' ELSE '' END) AS __group__,

And for Trac versions below 0.12 replace the line with:

'Milestone '||(milestone || CASE WHEN ms.due > 0 THEN ', (due ' || datetime(ms.due, 'unixepoch')  || ' UTC)' ELSE '' END) AS __group__,

The difference is that in Trac 0.12 dates, (at least milestone due dates), started to be stored as mircoseconds since the unix epoch, and before that they were stored as a simple unix timestamp, so now, to use SQLite’s datetime function we have to divide the stored value by 1,000,000.

This statement makes milestone names look like this:

Milestone Page Style Updated, (due 2011-11-21 23:00:00 UTC)

Note that there’s a UTC time listed. This is because I can’t figure out how to get a user’s timezone offset preference into the query. It would be relatively simple if the time was attached to a ticket, but in this case it’s attached to a milestone. If anyone knows how to work the proper timezone offset into the SQLite query please let me know.

Bonus: Link the Milestone Titles to Reports Showing Only That Milestone

It’s possible to create a link a list of that milestone’s tickets. Just add this line after the line that you just altered:

(CASE WHEN(milestone IS NOT NULL) THEN '../query?group=status&milestone=' || milestone ELSE NULL END) AS __grouplink__,

The grouplink column is a magic column that Trac understands and uses as a link for the group title, (in this case, the milestones).

The Full Solution

For you lazy folks, here’s the full query:

SELECT p.value AS __color__,
   'Milestone '||(milestone || CASE WHEN ms.due > 0 THEN ', (due ' || datetime(ms.due/1000000, 'unixepoch')  || ' UTC)' ELSE '' END) AS __group__,
  (CASE WHEN(milestone IS NOT NULL) THEN '../query?group=status&milestone=' || milestone ELSE NULL END) AS __grouplink__,
   id AS ticket, summary, component, version, t.type AS type, 
   owner, status,
   time AS created,
   changetime AS _changetime, t.description AS _description,
   reporter AS _reporter
  FROM ticket t
  LEFT JOIN milestone ms ON ms.name = t.milestone
  LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
  WHERE status <> 'closed' 
  ORDER BY (ms.due > 0) Desc,ms.due, (milestone IS NULL),milestone, CAST(p.value AS integer), t.type, time

Getting Started with HTML5

I’m working on a project now were we’ve decided to go with as pure HTML5 as posible, and it’s a breath of fresh air. Things work more or less how they should, and Internet Explorer is even playing along, with a little help. Getting started was a bit of a trick, though, as it can be hard to find information on how HTML5 works without diving into specification documents, which is never fun, or easy, (if you don’t want to read the story, skip straight to the resources).

I hadn’t been following the development of HTML5 with more than a passing interest. I figured that when it was ready, then I would start using it. I also understood that there were different parts that may reach completion at different times, and was keeping my eye open for some sort of “completion” signal. 2009’s 24 Ways was that signal for me. There were several articles on using HTML5 features along with their CSS3 counterparts, and enough evidence that browser support is there to start my investigation.

Here’s the deal: Basic HTML5 support is pretty good in webkit-based browsers, alright, (read usable), in Gecko, and kind of lacking in Internet Explorer. However, if you can rely on Javascript being present, (which I can in my project), there’s an HTML5 Shiv Javascript by Remy Sharp that makes it so that you can style HTML5 in Internet Explorer. Add it using a conditional comment and you’re good to go.

So, we have useable cross-browser support, but where do we turn to learn about which tags are in, which are out, the correct doctype and mime-type, and all that? We could read the specification, (and we will have to read a bit, at least), but it would be nice if there was an introduction to HTML5 somewhere. It turns out that Robert Nyman has written an Introduction to HTML5. It’s detailed enough to get you started, but not so detailed that you get lost, (like the spec), and if you’re looking to be convinced of the value of HTML5, check out HTML5: Tool of Satan, or Yule of Santa?, Have a Field Day with HTML5 Forms, and Breaking out the Edges of the Browser from 24 Ways 2009.

Once you dive a little deeper you’ll find that there are elements of HTML5 that you need more in-depth information for, so it’s time to turn to the spec. However, there are 2 groups, (W3C and WHATWG), working on HTML5, and therefore 2 spec documents, (fun!). Fortunately, the two groups have the same editor, so they’re more or less working on the same thing. I find the WHATWG HTML5 document easier to read, but if you prefer the W3C version, go nuts.

Finally, the whole content-type debate that’s been going on for what seems like centuries is still a mess. In HTML5 you’re supposed to include a Document Type Definition and there should be no namespaces on the HTML element if you’re serving as text/html, and you’re supposed to serve in application/xhtml+xml if you want to use namespaces, or force XML validation, or anything like that. The problem is that Internet Explorer really doesn’t like application/xhtml+xml, (it shows the raw XML document), so if you need a namespace for some reason, (for example, you want to use Facebook Connect on the site), you can’t serve valid markup.

So, that’s it. HTML5 has arrived, or at least parts of it. If you can rely on Javascript being present, or rely on IE users not using your web app, you can go ahead and start using it. Here’s a quick recap of the resources: