Posts Tagged ‘wordpress’

Customising WordPress Without Modifying Core, Theme Or Plugin Files

A standard WordPress install is incredibly powerful and flexible. For a lot of people, WordPress out of the box plus one of the stock WordPress themes is enough. But the possibilities for customization are endless; you can add plugins and other themes. Sometimes these do just what you want. Sometimes you need to … tweak WordPress.

A very high proportion of the customization advice you’ll find on the web starts with these lines … add the following to the end of your theme’s functions.php or even worse, advises that you modify the source code of your theme or your plugins. This is bad for many reasons:

  • Editing your theme’s functions.php makes theme specific customizations; change your theme and your customizations will no longer get loaded.
  • When your theme and plugins get updated you’ll find all your careful hand crafted customizations get overwritten and lost.
  • A lot of theme and plugin authors won’t offer support for changes you might have made to the source code.
  • Your customizations might work; but you might also inadvertently make some other changes which will stop things working.

WordPress doesn’t yet support a way for site specific customizations to be made and loaded without touching theme, plugin or core files; that’s why I wrote WP Customizer and that’s what this plugin is for. When WordPress does support such a way, this plugin will thankfully be obsolete.

screenshot-1

There’s another, not entirely altruistic, reason behind this plugin. One of the most common support requests I get for WP Biographia is to help with clashes between someone’s theme’s CSS and the plugin’s CSS. Once that’s been resolved, the next question is almost always how do I load this custom CSS? The answer is now straightforward. Put your CSS file in a directory in the root of your WordPress installation, install WP Customizer, tell it to load custom CSS files and where to find them and you’re done. No editing of functions.php. No learning now to hook into the wp_enqueue_scripts action, no learning how to call wp_register_style and wp_enqueue_style. It should all just work.

But WP Customizer works with more than just custom CSS files. You can also load custom PHP functions and custom Javascript and jQuery files as well. What’s more, you can configure these to load just for your site’s publicly visible front end, just for your site’s admin pages or even both.

WP Customizer uses the file system as a data-store metaphor and allows you to main a library of common customisations that are independent of the theme and plugins you’re currently using. Out of the box, the plugin looks for custom files to load in the root of your WordPress installation in a set of named directories which should be relatively self explanatory, functions, admin_functions, common_functions and so on for CSS and for scripts.

But you can just as easily create your own directory structure, put together in a way that makes sense to you, perhaps something along the lines of … site/front-end/css, site/front-end/functions, site/admin/scripts and so on

… you’re limited only by the limitations of your file system and the way of organising things that make sense to you.

screenshot-5

One final word of caution though. In order to use this plugin, you have to know how to write the code that lives in the customisation files themselves. That means knowing how to write PHP functions to exercise the WordPress API. How to write JavaScript and jQuery that works with WordPress. How to write CSS. This plugin can’t help you with that. But there’s ample tutorials and information out there on the interwebs to help you.

Just remember, when you read something that says just add the following code to your theme’s functions.php, ignore this little piece of advice and add it a local customisation file and load that through WP Customizer instead. Your WordPress site will thank you for it someday.

To download or install WP Customizer, either search for WP Customizer from the WordPress Dashboard or go to plugin’s page on the official WordPress plugin repository. If you want to fork the source code of the plugin, you can find it on the plugin’s GitHub page at https://github.com/vicchi/wp-customizer.

Written and posted from home (51.427051, -0.333344)

Foursquare Checkins, Maps And WordPress; Now With MOAR Maps

If you’re an avid Foursquare user you can already display your last checkin, visualised on a map, in the sidebar of your WordPress powered site with the WP Quadratum plugin. Foursquare, checkins and maps … what more could you ask for? Maybe the answer is more maps.

Version 1.1 of the WP Quadratum plugin, which went live this morning, now has added maps. The previous versions of the plugin used Nokia’s maps, because I work for Nokia’s Location & Commerce group and I wanted to use the maps that I work on. But if Nokia’s maps aren’t the maps for you then how about Google’s, or maybe CloudMade’s OpenStreetMap maps or perhaps OpenLayers’ OpenStreetMap maps.

Thanks to the Mapstraction JavaScript mapping API, WP Quadratum now allows you to choose which mapping provider you’d like to see your checkins appear on. And if you don’t want a map on the sidebar of your site, you can embed the checkin map in any post or page with the plugin’s shortcode too.

As usual, the plugin is free to download and use, either from the official WordPress plugin repository or from GitHub.

As a fully paid up and self confessed map geek I may be somewhat biased but surely most things can be improved with the simple addition of more maps.

Written and posted from home (51.427051, -0.333344)

Tracking Down Use Of Deprecated WordPress Functions Or Arguments

If you’ve been running your blog or site on WordPress for any period of time, you may well have come across a message about a deprecated function or argument in your PHP log file or across the top of a page on your site. The message might look something like this …

Notice:  get_bloginfo was called with an argument that is deprecated since version 2.2! The siteurl option is deprecated for the family of bloginfo() functions. Use the url option instead. in /var/web/htdocs/site/wp-includes/functions.php on line 2712

… this often appears after you’ve installed or upgraded a new theme or plugin. This message is helpful but really only 50% useful. The PHP file and line number that’s being reported isn’t where the deprecated function or argument is being used; it’s where it’s being reported from. Often, even after you’ve searched through the source code of the new plugin or theme you’re still none the wiser about where the troublesome piece of PHP that WordPress is telling you about actually lives. WordPress is a complicated mix of PHP, JavaScript and CSS; there’s a lot more going on under the hood than most of us are remotely aware of.

Thankfully WordPress also helps provide an answer, through an undocumented action hook called deprecated_argument_run; that’s undocumented in the WordPress Codex, it is documented in the core WordPress source code, if you know where to look. The clue to unlocking this problem is a comment in wp-includes/functions.php which says There is a hook deprecated_argument_run that will be called that can be used to get the backtrace up to what file and function used the deprecated argument. So here’s how to get that backtrace.

Put the following code somewhere on your site, maybe in your theme’s functions.php, where it will get called by WordPress. Now I know this seeminly contradicts what I said in an earlier post but this is a temporary piece of debugging code and not a permanent feature of your site; I might just make it a plugin some day though.

add_action ('deprecated_argument_run', 'deprecated_argument_run', 10, 3);

Now add the hook function that gets called when a deprecated argument is detected.

function deprecated_argument_run ($function, $message, $version) {
	error_log ('Deprecated Argument Detected');
	$trace = debug_backtrace ();
	foreach ($trace as $frame) {
		error_log (var_export ($frame, true));
	}
}

Reload a page on your site and you’ll see a back trace in your PHP error log of precisely where the deprecated argument is being used.

This technique isn’t limited to deprecated arguments, there’s also action hooks for deprecated functions (deprecated_function_run), deprecated files (deprecated_file_included) and something being incorrectly called (doing_it_wrong_run), all of which can use the same form of back trace technique.

You’ll probably need to ensure that WP_DEBUG is enabled in your wp-config.php and don’t forget to remove your debug code and disable WP_DEBUG after you’ve finished.

Written and posted from home (51.427051, -0.333344)

Of CSS, Pointers, Archive Pages and Meta Boxes; WP Biographia Reaches v3.2

WP Biographia v3.2 got pushed to the WordPress plugin repository this afternoon. In the grand scheme of things it’s not a massive release but it goes a long way to solving some of the most frequently asked questions that arrive in my Inbox and via the plugin’s support forums.

As I’ve mentioned a few times in the past, it’s nigh on impossible to test a WordPress plugin against the myriad combinations of themes and plugins that exist in the WordPress ecosystem. Especially where CSS is concerned, plugins and themes frequently don’t play well together and bleed over from another theme or plugin’s CSS often makes WP Biographia’s formatting look … interesting. This tends to happen in two places. Firstly in the formatting of the contact links in the Biography Box and secondly in the positioning of the user’s avatar image.

Wp Biographia v3.2 provides two workarounds for this. The plugin’s CSS now uses the !important CSS specifier to ensure the CSS is applied as it should be in as many cases as is possible.

But sometimes this isn’t enough to fix formatting issues, especially if the plugin’s the_content filter priority has been dropped below the default value of 10, to get the Biography Box to appear in the right order with the output of other plugins. In this case, the WordPress wpautop filter, which automagically adds paragraph tags, runs after the Biography Box is produced. In this situation you can now tell the plugin to synchronise the wpautop filter to run after the Biography Box is produced.

WordPress v3.3 added support for Pointers; helpful little pop-ups in the WordPress admin screens that display useful information. WP Biographia now supports these and when you install or upgrade you’ll see a what’s new popup, plus a guided tour of the plugin’s settings tabs.

Another frequently requested feature was the ability to break down the display of the Biography Box on archive pages from an all or nothing basis to one where you can select which one of the author, category, date or tag archives you want the Biography Box to appear on. WP Biographia v3.2 now supports this ability.

The full list of new features and bug fixes for v3.2 looks something like this.

  • Added: Support for synchronising the use of wpautop via the the_content and the_excerpt filters to ensure these filters fire before the Biography Box is produced when the plugin’s filter priority is less than the default filter priority to avoid formatting issues for contact links.
  • Added: Support for WordPress Pointers to display “what’s new” information post install or upgrade and to provide a “guided tour” of the plugin’s settings and options.
  • Added: Support for displaying the Biography Box as a widget.
  • Added: Support for a shorter biography to the user’s profile to be used in conjunction with the Biography Box widget.
  • Added: Support to display the Biography Box for all types of archive page; author, category, date and tag.
  • Added: Custom meta boxes to the post/page/custom-post creation/editing screens to hide the Biography Box, making it easier to define the Admin screen’s Exclusion settings.
  • Added: Support for the shortcode’s user attribute; deprecating support for the author attribute.
  • Added: Increased the width of text and select boxes for the Admin and Exclusion admin tabs to allow for longer category names and longer lists of post IDs to be displayed.
  • Added: Wrap the plugin’s avatars (if present) in plugin specific CSS code to prevent theme specific CSS bleeding into the Biography Box.
  • Fixed: The layout of the Biography Box for feeds now ignore displaying contact links as icons and formats them as plain text.
  • Fixed: Example use of the wp_biographia_feed filter in readme.txt.
  • Fixed: Bug where the wp_biographia_feed filter was never called in the context of a feed.
  • Fixed: Formatting of HTML for the Biography Box post/page hiding options in the user’s profile.
  • Fixed: Use the term “hide” consistently across the plugin and documentation; previous versions used “hide” and “suppress” interchangeably.
  • Fixed: Use the term “user” consistently across the plugin and documentation; previous versions used “author” and “user” interchangeably.
  • Fixed: Bug where the last page of a multiply paged post was not correctly detected, resulting in the Biography Box being displayed for all pages.

So where does WP Biographia go from here? That’s a very good question. Unless there’s a major feature which the plugin doesn’t support and which no-one has (yet) asked for I think the plugin will stay pretty much as is for the foreseeable future. For now, the plugin is relatively flexible and fast and I want it to stay that way. Unless you know better. In which case, let me know in the comments.

Don’t Go There, Go Here; A WordPress Redirection Plugin

Despite having written 5 plugins for WordPress I’ve only just scratched the surface of what it’s possible to make WordPress do. So when I want to make WordPress do something that I’m not sure a) how to do and b) whether it’s even possible or not, I turn to a search engine. More often than not I get an answer. Often that answer seems to start along the lines of

put the following code in your theme’s functions.php file

It’s not that this is wrong but I have a slight issue with hacking a theme’s functions.php file, for a number of reasons. Firstly this is theme specific; change your theme and your modifications still exist, they’re just in your old theme and you’ll need to remember to copy and paste them over to the new theme. Secondly, any file which is part of a theme can, and probably will, be overwritten on a theme update and unless you’ve saved a copy of your changes to functions.php, you can wave them goodbye.

So whenever I see the magic phrase put the following code in your theme’s functions.php file, nine times out of ten I mentally read this as this should really live in a plugin.

Which is exactly what happened when I wanted to set up a redirection so that anyone hitting the URL of a certain post on my blog would be automagically redirected to another URL. The most common solution to this was to set up a custom field, called something like redirect and then hook into template_redirect, check for the custom field in the post metadata and then fire off an HTTP 301 redirect via wp_redirect. Where should I do this? In my theme’s functions.php of course. I naturally read this as this should be in a plugin. A quick search through the WordPress plugin repository revealed that there were plugins that sort of did this, but none of them did precisely what I wanted.

Thus was WP Avertere born. It was originally going to be called WP Redirect but that plugin name was already taken and so, in line with some of my other WordPress plugins, WP Biographia and WP Quadratum, WP Avertere, named from the latin for “divert” came into being.

The plugin does all of the above custom field mangling, template_redirect hooking and wp_redirect redirecting that I could have done in functions.php. But it does this … cleaner.

The plugin adds a custom meta box to the Admin Edit screen for posts, for pages and for any custom post type. It allows you to check your redirection URL for well formed-ness. It allows you to set up temporary and permanent redirections. It hooks into the page_link and post_link hooks so that whenever you see a permalink to the old URL it’ll read as a permalink to the new, redirected URL. And most importantly of all, it allows you to cancel an existing redirection for those times when you decide you don’t want a URL to be redirected after all.

As with all the WordPress plugins I’ve written, and this is plugin number 6, the code is up for forking and hacking around on GitHub. It’ll also be on the WordPress Plugin Repository once I’ve published this post and submitted the plugin to the benevolent WordPress plugin overlords. Until then, you can download the plugin’s source in one convenient archive right here, as GitHub’s downloads don’t, for some reason, include Git submodules.

But one final caveat. What happens if the original post or page that you want to redirect has comments? With this first version of the plugin the comments will still be there but you won’t be able to see them as the redirect will automagically push you to the new, redirected, URL. I’m well aware that this is a shortcoming and the next version of the plugin will support the ability to copy the comments from the source post to the new, redirected, post.

Converting Markdown To HTML; In Any Mac Text Editor (With A Little Help From Automator)

There must be a truism somewhere out on the interwebs that goes something like this …

if a computer geek finds himself or herself doing a task repeatedly, he or she will invariably find a way to automate this task

… and if there isn’t a truism to this effect, then I’ve just written it for the first time.

In this particular case, the repetitive task was converting text written using John Gruber’s Markdown syntax into HTML. Those of you who know Markdown will be asking the question “but Markdown is already a text-to-HTML conversion tool, why would you want to do this?“. They’d be right too, so an explanation is due.

Each time I update one of my WordPress plugins, I use the updated readme file as the basis for updating the respective plugin’s home page on my, WordPress powered, blog. Now I could use one of the existing WordPress plugins that allows me to write Markdown inside WordPress. I could, but I haven’t. This is because, for now at least, Markdown support in WordPress is an all or nothing approach. Either you use Markdown everywhere or you don’t use it at all. That’s not good enough for my use case. I want to use Markdown selectively, on a few select pages only.

So I looked for a way of being able to convert the Markdown text of one of my plugin’s readme files in a more selective fashion. I wanted to be able to take a readme.txt file in my text editor of choice and convert it from Markdown into the page I was currently editing in WordPress in the browser. A not inconsiderable amount of web surfing later and I had a solution which almost but not quite got me 75% of where I wanted to be. Adding in support for the current version of Mac OS X and adding a small amount of extra functionality got me to 90%. Now granted, 90% isn’t 100%, but to my mind 90% is far better than 0% and 0% was the repetitive task of selecting, copying and pasting the sections of the readme into WordPress and manually converting the Markdown syntax into HTML tags. This is not only repetitive, it’s error prone and downright tedious.

Firstly install Markdown on your Mac. There’s a variety of ways of doing this but as I already use Homebrew to install all manner of command line stuff, I checked to see if Markdown was supported by the brew command and went ahead and installed it.

$ brew search markdown
markdown    multimarkdown   peg-markdown
$ brew install markdown
==> Downloading http://daringfireball.net/projects/downloads/Markdown_1.0.1.zip
######################################################################## 100.0%
/usr/local/Cellar/markdown/1.0.1: 2 files, 40K, built in 2 seconds
$ which markdown
/usr/local/bin/markdown

Then fire up Automator, located at /Applications/Automator.app. Choose Service as the type of Workflow you want to create.

Add the Run Shell Script Action, which is located under the Utilities section of the Actions Library.

Homebrew installed Markdown as /usr/local/bin/markdown so change the default Action from cat to the path to Markdown. I also chose to make the output replace the text I had selected, you may or may not want to do this.

Then add the Copy To Clipboard Action, again located under the Utilities section of the Actions Library.

Then save your workflow and give it a meaningful name; Automator will save this as Markdown.workflow in your ~/Library/Services folder.

Now I can use this workflow to convert Markdown formatted text to HTML. The workflow I’d just created is now available through the Services menu of any text editor on the Mac. I’m using TextMate but this applies to all apps on the Mac that are capable of working with plain text. If you load up a Markdown formatted file in your text editor of choice and go to the Services menu item, you won’t see your workflow initially.

You need to select the text you want to convert. Then go back to the Services menu item and you’ll see Markdown as a Text Service. Click on this and your highlighted text will be converted to HTML in situ and the resultant HTML will also be on the clipboard as well, ready for pasting into WordPress or whatever you want to use to hold this HTML.

You can also get access to the Services menu by Control-clicking on the highlighted text as well.

As Aaron Cope once said, The label on the tin reads: “It ain’t pretty or classy but it works” and for now, that 90% I mentioned earlier is good enough.

Bending WP Biographia To Your Will; A Configuration Guide

WP Biographia has grown and matured quite a bit since it was first released. A quick glance through the multiple releases of the code that make up the plugin tells me that in v1.0, the plugin was 761 lines of PHP code and 46 lines of CSS. Now in v3.1, that’s increased to 2944 lines of PHP, 92 lines of JavaScript and 174 lines of CSS.

But more importantly, as the plugin has grown and changed and more and more features have been added, so have the number of configuration settings, from 22 in v1.0 to 43 in v3.1. While most people seem to use the plugin out of the box, with little or no customisation, if you do want to take full advantage of all that the plugin has to offer, this means you need to roll up your sleeves and trawl through all of the plugin’s settings, which can be a daunting task at times.

So with this in mind, assuming you’ve installed and activated the plugin, here’s a step by step and screen by screen guide to bending WP Biographia to your will.

Setting Up Your Biography

Firstly, set your biography details up. From the Dashboard, navigate to Users -> Your Profile. Under Name, fill in your First Name, Last Name and Nickname and choose how you want your name to be displayed publicly (you can’t change your username by the way).

Now add your Contact Info. WP Biographia adds fields for Twitter, Facebook, LinkedIn, Google+, Delicious, Flickr, Picasa, Vimeo, YouTube and Reddit to the contact info that WordPress provides out of the box. For each piece of contact information you want displayed in the Biography Box, add the corresponding URL.

Contact Info Gotcha: It’s important to note that you need to enter the full URL to your profile for each social media site. For example, for Twitter you’ll need to add http://twitter.com/user, not just @user.

Now add your biography text to the Biographical Info field under About Yourself.

Biography Gotcha: By default, WordPress restricts the HTML tags you can enter in this box to filter out potentially harmful and/or invalid tags (see $allowedtags in /wp-includes/kses.php for the current list). The most common additional HTML tag that people ask for is the line break tag. You can allow WordPress to accept this tag with a small amount of PHP added to your theme’s functions.php file ().

Finally, click on Update Profile to save all your changes.

Setting Up Your Author’s Picture

Next, set up your author picture, or avatar. By default, WordPress uses Gravatars, short for Globally Recognised Avatars, to display author pictures. Head over to the Gravatar site, sign up for an account and upload your author picture.

Avatar Gotcha: One important gotcha you need to know is that the link between your user profile on your WordPress blog and your author’s picture on the Gravatar site is your email address, so when you sign up you need to ensure you use the same email address as is listed in your user profile on your blog.

Avatar Gotcha: If for some reason you don’t want to use or sign up for a Gravatar, there are other WordPress plugins that can help you upload author pictures to your blog. The key thing is that the plugin you use has to be able to work with author pictures in the same way as WordPress does, otherwise WP Biographia won’t be able to display them in the Biography Box. See this FAQ for more information on this.

Once you’ve done this, head back to your blog’s Dashboard and navigate to Settings -> Discussion and under Avatars make sure that Show Avatars is checked under Avatar Display. Make sure you click on Save Changes.

WP Biographia Settings And Options

Now it’s time to make WP Biographia do what you want it to do. From the Dashboard navigate to Settings -> WP Biographia. You’ll see that there are 7 tabs of settings and options. The Display tab should be the first one that’s shown so let’s start there.

Basic Settings; The Display Tab

This tab has broad settings to control how the WP Biographia Biography Box is displayed and where. You can choose one or all of displaying on your blog’s front page, on individual posts, on post archives, on individual pages and in your blog’s RSS feed. You can also choose whether to display the Biography Box before or after the content of a post, a page, an archive or the RSS feed. If your blog has custom post types, perhaps provided by your theme, you’ll also see the option to control display of the Biography Box here.

Display Gotcha: If you choose to display the Biography Box on post archives, this will do so for all archive types, be that tag archives, author archives, category archives, date archives or so on. If you want to restrict the display to a particular type of archive, you’ll need to add some conditional tags to your theme’s template files.

Click on Save Display Settings before moving onto the Style tab.

Basic Settings; The Style Tab

This tab controls how the Biography Box is styled, its background colour and what sort of border, if any, is drawn around the Biography Box. You can enter the background colour as an HTML colour code or use the built-in colour picker tool.

Style Gotcha: The Style tab provides only a basic set of styling options. If you want more fine grained control, or if your theme’s style is interfering with the way in which the Biography Box looks, you’ll need to know how to control this via CSS and how to add extra CSS to your blog. This article should tell you how to do this.

Click on Save Style Settings before moving onto the Content tab.

Basic Settings; The Content Tab

This tab controls what information is and what isn’t displayed in the Biography Box. You can choose to override the prefix, the text that’s display before the author’s name, how the author’s name is displayed, whether the author’s picture is displayed, whether the author’s biography is displayed and whether to show the author’s profile’s contact links as text or as icons.

Content Gotcha: To ensure that a contact link is displayed in the Biography Box, you’ll need to ensure that it’s not only enabled in the Content tab but also that there’s a valid URL in the corresponding contact information field in your profile. If you do the former but not the latter, the Biography Box won’t know to display the link. If you do the latter but not the former, the plugin isn’t clever enough to know what the link needs to be without you telling it.

Content Gotcha: WP Biographia supports 12 different contact/social media links, but to keep the settings and options under control, that number won’t be growing anytime soon. But what if you want to display a link to one of the ever growing number of social media sites that isn’t supported natively by the plugin? With a little bit of PHP coding in your theme’s functions.php you can add as many contact links as you like. This FAQ tells you how to do this, with some further reading, plus working code examples, on the plugin filters you’ll need to use here.

Click on Save Content Settings. That’s pretty much it for WP Biographia’s basic settings and options. The Exclusions and Admin tabs contain more advanced and fine grained settings.

Advanced Settings; The Exclusions Tab

This tab allows you to control where the Biography Box is displayed, or not, with much finer control that the broad controls on the Display tab.

Firstly, the Post, Page and Custom Post Type Exclusion Settings allow you to stop the Biography Box being displayed on one or more single posts, for all ways in which one or more posts might be displayed, such as singly, one the front page or on an archive page and for one or more pages. To do this you’ll need the Post ID or the Page ID for the posts or pages you want to restrict the Biography Box from being displayed on.

Exclusions Gotcha: If you’re using the default permalink structure (found from the Dashboard under Settings -> Permalinks), the Post ID or Page ID is part of the URL to the post or page you’re viewing, something like http://www.vicchi.org/?p=123. But if you’re using a custom permalink structure such as http://www.vicchi.org/2012/05/18/sample-post/ the Post or Page ID is hidden. To find the ID you need, from the Dashboard, navigate to Posts -> All Posts or Pages -> All Pages. Hover your mouse over the post or page name and then under Edit and you’ll see the URL to edit the post or page in your browser’s status bar, along the lines of http://www.vicchi.org/wp-admin/post.php?post=2628&action=edit; the Post ID (in this case) is 2628.

The Category Exclusion Settings allow you to stop the Biography Box being displayed on a single post or custom post by the post’s category. Simply click on the category or categories you want to exclude and click on the Add button.

The User Suppression Settings allows you to stop the Biography Box being displayed on all posts and/or pages by one or more authors. Select and add the users in the same way as you do for category exclusions.

Don’t forget to click on Save Exclusion Settings to preserve your changes.

Advanced Settings; The Admin Tab

By default, if you add a new user/author to your blog, that author automatically has the Biography Box added to their posts and pages, subject to the other configuration settings you’ve enabled. The New User Settings allows you to automatically add newly created users to the list of excluded users which is managed on the Exclusions tab, under User Suppression settings. You can then choose to selectively re-enable your new users as you wish.

Also by default, WP Biographia adds two settings to each user’s profile to allow the user to control whether the Biography Box is displayed for their posts and for their pages. The User Profile settings allows you to hide these settings from your users on a per-user basis.

Finally, the plugin uses the standard WordPress the_content and the_excerpt filters to add the Biography Box to your posts and pages, either at the start or at the end of the content. As this is a standard WordPress feature, you may find other plugins and/or themes do exactly the same thing, which means that if you have multiple additions to a post or a page via this mechanism you may not end up with the additional content in the order you want. The Content And Excerpt Priority Settings allows you to adjust the filter priority to get the order you really want; a lower priority means the plugin’s filters will fire earlier, thus bumping them up the order in which the additional content is added, a higher priority will fire later, with the opposite effect.

So that’s about it; hopefully a gentle and thorough guide to bending WP Biographia to your will. If you’re still not sure about what to do, or something’s not working the way you expect it, firstly consult the plugin’s FAQs. If this doesn’t help then please read this first and get in touch.

Written and posted from home (51.427051, -0.333344)

WordPress Shortcodes; Documenting The Undocumentable

WordPress shortcodes. A great idea. Small snippets of text with a special meaning, enclosed in left and right angle brackets. Put one of these in a WordPress post or page and WordPress automagically expands the shortcode and replaces it with the thing that the shortcode does.

WordPress has a built-in set of shortcodes and many plugins add to this repertoire, adding one or more of their own shortcodes. But here’s the problem. Shortcodes are meant to be expanded and in 99.999% of cases, that’s just what you want to do. But what happens if you’re one of those 0.001%; you’ve written a plugin that adds a shortcode and you want to document it. You can’t just write the shortcode in a post as WordPress will go ahead and expand it for you.

You could take the time and effort to replace the [ and ] characters which surround a shortcode, writing something like [shortcode], which is exactly what I’ve been doing since I released the first version of WP Biographia. But this is a long and laborious process. Frankly, it’s boring and a pain in the backside.

But then I noticed a crucial phrase in the documentation for the WordPress Shortcode API

The shortcode parser uses a single pass on the post content. This means that if the $content parameter of a shortcode handler contains another shortcode, it won’t be parsed

… in other words, if you put one shortcode inside another shortcode, the shortcode inside won’t be automagically expanded by WordPress for you. Which is exactly what I wanted to stop me from constantly having to write posts using the HTML entities for [ and ].

So, despite the irony inherent in writing a plugin to stop the shortcode from another plugin working, I hacked together WP Shortcode Shield. As far as plugins go, it doesn’t really do much, it just defines two shortcodes, one called [wp_scs] and a slightly more long-winded one called [wp_shortcode_shield] which allows me to wrap references to other shortcodes in a post without WordPress doing what it’s supposed to do, but which I don’t want it to do.

Which means I can write this post … without having to worry about WordPress shortcodes. Of course, this feature of the WordPress shortcode API may well be fixed at some point, in which case WP Shortcode Shield will promptly stop working, but for now, it does the job. As with all of the other plugins for WordPress I’ve written, it’s sitting in the WordPress Plugin Repository right now, as well as living on GitHub.

Photo Credits: Erik Hersman on Flickr.
Written and posted from the Hilton Berlin Hotel, Berlin (52.51191, 13.3926)

Two WordPress Plugins And The (Missing) Nokia Map

It’s a glaringly obvious oversight but a few month’s back I realised that given what I do for a living, there’s something missing from my blog and that something is a map.

There’s a whole slew of “where am I” style WordPress plugins out there, but after some careful research I decided that none of them did precisely what I wanted, which was to show the last check-in I made on Foursquare, on a map, in the sidebar of my blog.

Those that did come close still didn’t do the key thing I wanted and that was to use the map I work on as part of my day job. Now don’t get me wrong, I’ve got nothing against the maps that I could have used; Google, Bing, Mapquest and OpenStreetMap produce very fine maps and they all have the JavaScript API I’d need to display my last checkin. But none of them used my map and that means a Nokia Map.

So taking what I’d learnt about WordPress plugins during the course of producing 12 versions of the WP Biographia plugin, I rolled up my sleeves (mentally and literally) and started work on what would become WP Quadratum. I seem to have a thing about naming my plugins using a Latin derivation of their name; I have no idea why, but it seems to be better than something along the lines of WP Yet Another Foursquare Checkin Plugin. But I digress.

Several months later, after wrestling with getting a plugin to authenticate with Foursquare via OAuth 2 and learning how to write not only a WordPress plugin but also a WordPress widget, WP Quadratum appeared on the sidebar on my blog. It’s over there right now, towards the top right of your browser screen, unless your reading this on a mobile device, in which case you’ll just have to take my word for it for now.

Now Nokia allows free and unauthenticated use of the JavaScript Maps API, but only up to a certain number of transactions over a lifetime. So I also built in support for supplying Nokia’s Location API credentials as well. But then I stopped. Why build custom support for authentication and credentials into a plugin, only to probably have to copy-and-paste the code into another plugin I write that will use the same Maps API? So I digressed again and wrote another plugin, WP Nokia Auth, that handles the Nokia credentials for me, and then made WP Quadratum play nicely with WP Nokia Auth, if it’s installed, active and configured.

It took a while, but v1.0 of both plugins are now up on the WordPress plugin repository and on GitHub as well, for the usual forking, downloading, hacking and poking around. Whether they get the same number of downloads as WP Biographia has (over 7,000 to date) I somewhat doubt, but unless I release these, I’ll never know, so that’s just what I’ve done.

Written and posted from home (51.427051, -0.333344)

Finally WP Biographia v3.0 Makes It Off Of The Starting Blocks

It’s taken a while but I just did this …

$ rsync --recursive --verbose --exclude '.git' * ~/Projects/svn/wp-biographia/trunk/
$ svn up
$ svn stat
$ svn ci -m 'Updating with v3.0 changes from master on github'
$ svn cp trunk tags/3.0
$ svn ci -m 'Tagging v3.0'

… and after much coding, rewriting, testing and documenting, v3.0 of WP Biographia has finally made it off of the starting blocks.

As per usual, you can read the change log here, grab the source here, or download it here.

But what I really want to say, right here, is what you’ll find in the Acknowledgements side bar after you’ve installed the latest version.

The fact that you’re reading this wouldn’t have been possible without the help, bug fixing, beta testing, gentle prodding and overall general warmth and continued support of Travis Smith and Bruce Munson. Travis and Bruce … you’re awesome. Thank you.

Photo Credits: tableatny on Flickr.
Written and posted from home (51.427051, -0.333344)