I’ve released this PHP Routing class on Github here, so you can follow and contribute to it’s development progress.

What does this PHP Routing class do?

In short, this class helps you route URL’s to their corresponding Controller and action methods. You can use different HTTP methods to fully benefit from using REST / resourceful routes. Also, setting up dynamic URL’s that pass parameters to their corresponding action are no problem.

• REST Routing
• Use different HTTP methods for same URL’s
• Dynamic URL segments
• Reversed routing, create URL from route

The class is fairly simple and lightweight, it won’t do any unnecessary processing. Have a look at the following snippet taken from the example file to get a better understanding on how to use this class in your projects.

<?php
require 'Router.php';

$r = new Router();

// maps / to controller 'users' and method 'index'.
$r->match('/','users#index');

// maps /user/5 to controller 'users', method 'show' with parameter 'id' => 5
$r->match('/user/:id','users#show');

// maps POST request to /users/ to controller 'users' and method 'create'
$r->match('/users','users#create',array('via' => 'post'));

// maps GET /users/5/edit to controller 'users', method 'edit' with parameters 'id' => 5 and saves route as a named route.
$r->match('/users/:id/edit','users#edit',array('via' => 'get', 'as' => 'user_edit_page'));

// echoes /users/5/edit
echo $r->reverse('user_edit_page',array('id' => '5'));

// maps multiple routes
// GET /users will map to users#index
// GET /users/5 will map to users#show
$r->resources('users',array('only' => 'index,show'));

if($r->hasRoute()) {
    // extract controller, action and parameters.
    extract($r->getRoute());

    ?>
    <h1>Route found!</h1>
    <p><b>Controller: </b><?php echo $controller; ?></p>
    <p><b>Action: </b><?php echo $action; ?></p>
    <p><b>Params: </b><?php var_dump($params); ?></p>
    <?php

} else {
    ?><h1>No route found.</h1><?php
}

?>

If you’re using this class and experience any issues, please post them using GitHub’s issue tracker. Also, feel free to geek around and fork the project to improve this class.

Watch PHP Routing Class on Github!

PHP Routing Class which supports REST routing

Although my detailed post on how to configure it certainly helped I decided it would be cool if I built some kind of tool that helped new users extract the right configuration settings for them. So here it is, the “configuration extractor” that comes with version 1.5.0 of Newsletter Sign-Up.

How does this “configuration extractor” work?

Basically all you have to do is provide a form snippet that you would normally embed in your website’s HTML code, paste it in the configuration extractor text area and hit the extract button. The tool will then try to extract the different values which are needed to get Newsletter Sign-up to work. The tool is still pretty minimal but I will work on it to improve it during the next weeks.

When the configuration settings the tool provided did not work, you can now more easily extract the right values yourself by using the cleaned up form that comes with the results of the configuration extractor. This is basically a stripped down version of your Sign-up form, which makes it way easier to extract the correct settings.

Have a look at the following screenshots to get a better idea of how the tool works or download Newsletter Sign-Up v1.5 straight away!

Let me know what you think of this update. The next thing i’ll work on is error handling and providing an easier alternative to style the form, besides using plain CSS. Of course all suggestions on how to improve Newsletter Sign-Up are welcome !

Newsletter Sign-Up, added configuration helper: Config Extractor

MOVEMBER (THE MONTH FORMERLY KNOWN AS NOVEMBER) IS A MOUSTACHE GROWING CHARITY EVENT HELD DURING NOVEMBER EACH YEAR THAT RAISES FUNDS AND AWARENESS FOR MEN’S HEALTH.

So, if you like my plugins and consider making me a donation, please consider this alternative. Donate some money to my Movember account to support me growing a moustache during November. Or even better: start growing a Movember Moustache yourself. In return, i’ll take weekly pictures of me and my upper lip!

1 November (after shaving)

4 November, going for the ‘Trucker Mo’!

Expected result

Actual end result 

Danny raising money for prostate cancer by growing a moustache!

Remembering that I'll be dead soon is the most important tool I've ever encountered to help me make the big choices in life. Because almost everything — all external expectations, all pride, all fear of embarrassment or failure - these things just fall away in the face of death, leaving only what is truly important. Remembering that you are going to die is the best way I know to avoid the trap of thinking you have something to lose. You are already naked. There is no reason not to follow your heart.

Your time is limited, so don't waste it living someone else's life. Don't be trapped by dogma — which is living with the results of other people's thinking. Don't let the noise of others' opinions drown out your own inner voice. And most important, have the courage to follow your heart and intuition. They somehow already know what you truly want to become. Everything else is secondary.

Stay Hungry. Stay Foolish.

You can find the complete text report or watch the video of his speak here. If you have some spare time, definetly check it out if you haven’t already. Totally worth it!

Some Steve Jobs quotes about death

An easier approach would be to just enable the shortcode so that your user can type some text in one of WordPress’ default text widgets (or a WYSIWYG Widget, to make things a bit easier) and use the shortcode wherever he wants to output the form, or whatever it is your shortcode provides.

By default, shortcodes in text widgets are not enabled in WordPress. However, since the text from a text widget runs trough a filter called ‘widget_text’, enabling them would be pretty easy. In short,everything that’s needed is one simple line of code:

add_filter('widget_text', 'do_shortcode');

Just using this line of code could lead to some problems though. Best thing would be to add a priority so that do_shortcode runs after wpautop (the function that converts linebreaks into paragraph’s). Looking at wp-includes/shortcodes.php you’ll find that the default shortcode filter priorty is 11 so that is what we’re gonna pass as a 3rd parameter.

add_filter( 'widget_text', 'do_shortcode', 11);

Now, to ensure that the output of the shortcode function does not get wrapped in <p> tags because of wpautop it is best to add one more filter, ‘shortcode_unautop‘.

add_filter( 'widget_text', 'shortcode_unautop');
add_filter( 'widget_text', 'do_shortcode', 11);

Note for less tech savvy readers: the above snippet goes into your theme’s functions.php file.

Of course you can use the above snippet for pretty much every filter that’s out there, comment_text, term_description, manual filters, anything really.

If you’re a plugin author and you have a custom widget, another way to enable shortcodes inside your widget is to run the content trough the do_shortcode function. So, let’s say your Widget’s content is stored inside a variable called $text, you’ll pass this variable as a parameter to the do_shortcode function.

...
$output_text = do_shortcode($text);
echo $output_text;
...

Another, more flexible way would be to create a filter for your widget and hook the do_shortcode function to that filter. But, if enabling shortcodes is all that you’re looking for, the above snippet will do just fine!

Got a nice addition to this post? Let me know trough a comment!

Enabling shortcodes in widgets, quick WordPress tip.

I’ve started looking into some dynamic / conditional widget plugins. Some worked pretty good, some were flawed and most were just crap. These are the ones that I found to be quite helpful and with decent code quality, they might be of use to you too.

Widget Logic

This is my absolute favourite, although it might not be the best choice if you’re installing it so your cliënt (with no PHP knowledge) can use it later on. This plugin adds one small (but o so powerful) input field beneath every widget where you can specify any of WordPress’ conditional tags. This makes it possible to restrict a certain widget to a certain post, multiple posts, pages, categories, basically anything you like.

Of course, the downside is that the plugin user needs to know a thing or two about WordPress conditionals or PHP in general. If this isn’t the case you might be better of with one of the other plugins in this article. If the intended user has knowledge or is willing to look into WP Conditionals I highly suggest using this plugin though, as there are practically no limits.

» Widget Logic on the WordPress repository

Widget Context

This plugin adds some display options to all active widgets where you can specify some basic conditionals, as you can see in above screenshot. The nice touch is the textarea where you can specify certain URL’s to show the widget on. You are not limited to one URL and that makes this widget a perfect choice for users with no knowledge of WordPress conditionals. You can use some wildcards to match multiple URL’s with just one rule.

» Widget Context in the WordPress repository

Conditional Widgets

Like widget context, this plugin adds display options to all your active widgets where you can apply some conditionals where to show or hide the widget. Although you can’t restrict widgets to certain posts, you can add conditionals to show or hide the widget at certain category archives (+ posts inside that category) and certain pages only.

The code quality is above average (there is some crap out there..), it’s ease of use is perfect for cliënts with no understanding of PHP / HTML / any other webdevelopment language. All that’s needed is some basic logic.

» Conditional Widgets in WordPress repository

With either one of these 3 plugins you should be able to create a one-to-many relationship between widgets and posts. Do you know a plugin that takes care of creating ‘dynamic widgets’ in a neat and easy-to-use way that isn’t covered in this post? Let me know in the comments!

If you’re looking for a way to display content from your post in a widget area (a one-to-one relationship), i’m actually thinking about developing a plugin for this. There are some out there already, but the ones i’ve looked at are crappy coded and do not support visual editors. Like the idea? Let me know, I won’t make it if you won’t use it!

Conditional Widgets in WordPress

Table of contents

1. Downloading & Installing
2. Configuring Newsletter Sign-up
   1. MailChimp API
   2. YMLP API
   3. Other newsletter services
3. Testing

After releasing ‘Qoate Newsletter Sign-Up’ a year ago, recoding it into ‘Newsletter Sign-up‘ and 25.000+ total downloads i’ve been getting quite a lot of questions on how to properly configure the plugin for the various newsletter services out there. I’m not surprised, configuring NSU isn’t quite easy for the non-tech savvy WP users. Time to make things easier by writing a comprehensive guide on how to configure Newsletter Sign-Up, with screenshots!

Downloading and installing Newsletter Sign-up

You can download and install Newsletter Sign-up just like you would with any other plugin. Head over to the WordPress plugin repository, search for ‘newsletter sign-up’ (which should lead you here) and hit the red download button.

Extract the files of ‘newsletter-sign-up.zip‘ into your wp-content/plugins folder and activate the plugin trough your WordPress admin panel. Not familiar with installing WordPress plugins? The WP Codex has a nice article on installing and managing plugins which should help you out.

Configuring Newsletter Sign-up

If you’ve sucessfully installed NSU your plugins page in the WP Admin will look somewhat like this.

Hit the settings button, which should take you to the Newsletter Sign-Up Configuration page. This page is divided into a few parts, the one that is the most important is also the hardest: General Settings / Newsletter Configuration. These settings are essential if you want to get NSU to work with your newsletter service.

What you fill in here depends on your newsletter service, if you select a mailinglist provider from the select box you’ll see the page change and some more setting fields will apear, or some fields will be autofilled for you to make things a bit easier. You could however just leave the select box at ‘– other / advanced’ and fill in the correct values yourself. If you’re using MailChimp or YMLP you have the option to use their API’s, which I recommend by the way. Let’s start with those two.

Using the MailChimp API

Select MailChimp from the newsletter provider selectbox and tick the checkbox that says ‘Use MailChimp API’. The plugin will now ask you for two values, your MailChimp API key and your MailChimp list ID. If you’re not sure on where to get those just hit the ?-links and you’ll be taken to a page with more information on where to get those.

Using the YMLP API

Select YMLP from the newsletter provider selectbox and tick the checkbox that says “Use YMLP API”. You will now need to provide three values, your YMLP API key, your YMLP username and your YMLP group ID. To get your API Key, just hit the ?-link.

Getting your YMLP group ID is a bit harder. Go to your YMLP dashboard and take a look at the “Your contacts” section. Hover the icons for each of your lists and you’ll notice that each URL ends with &groupid=X. The X is the number you’ll need here. If you only have one default list this number will most likely be 1.

A correctly configured YMLP API should make your NSU configuration screen look somewhat like this.

Other Newsletter providers / custom settings

If you’re using iContact, Aweber, PHPList, ConstantContact or some other newsletter provider, correctly configuring Newsletter Sign Up will be somewhat harder but definitely not impossible!

To understand what we’re trying to do it is important that you understand how NSU works. All newsletter services provide you with a sign-up form in HTML which you can embed on your website. NSU mimics this sign-up request by sending a request to the specified action URL and sending some values along with the request, like the email address of the person who is trying to sign-up.

So, let’s get into it. First, select ‘– other/ advanced’ or your newsletter provider from the select box. You’ll see a few input fields which (for a minimum) ask for a form action and an email identifier.

Head over to your mailinglist service and look for a sign-up form which you can embed. You can extract the form action and email identifier from this HTML snippet. Take a look at the following picture to get a better understanding of what values you need. I really hope this picture makes any sense…

Although the snippet in the above picture is overly simplified it should give you an idea of what to look for and which values you’ll need. Basically, all the input fields need to be covered so NSU can send those values along with the request to the form action whenever someone uses NSU to sign-up to your email list.

Testing if Newsletter Sign-Up is properly configured

Testing to see if you’ve properly configured Newsletter Sign-up is pretty straightforward. Using the checkbox at you’re comment form that asks people if they’re willing to sign-up to your newsletter? Just leave a test comment, tick the checkbox and see if it the email adress you used gets added to your email list.

One small note though. Make sure that you’re using an email address that is not already on your list since most newsletter services tend to ignore those requests. Also, be patient for at least a few minutes and check your spam folder!

Still not getting it? Try this.

• http://unwireme.com/boost-your-e-mail-newsletter-sign-up-conversion-rate-with-this-free-tip/
• Drop me a line trough the support forums for NSU, include your sign-up form and i’ll extract the values as soon as I find a spare minute!

Configuring Newsletter Sign-Up – the definitive guide

This could all be done relatively easy by using the jQuery UI library, some basic HTML + CSS and draggable(). This will however lead to some problems.

For example, when just invoking draggable on a map inside a viewport you will be able to drag the image out of the viewport. This isn’t what we want because a map has edges, and there is nothing but emptiness beyond those edges. This can be solved by using the ‘containment‘ option of draggable but we’ll have to create a constraint div. Wouldn’t it be easy if there was a plugin that took care of all this? Well, since last week there is. I’ve created a simple lightweight jQuery plugin called Mapz that takes care of this.

You can specify different zoom levels, whether to use the mousewheel for zooming and it makes sure that your map cannot be dragged out of view.

Getting started: the HTML mark-up

Ok, let’s get going. Let’s create the HTML mark-up that is necessary to properly create our image map. In this example we’re going to create an image map with just 2 levels of zoom and a few linked area’s.

HTML

<div class="map-viewport">
	<div id="map">
		<img src="img/map-1.jpg" width="1200" height="900" usemap="#html-map" class="current-level level" />
		<img src="img/map-2.jpg" width="1600" height="1200" class="level" />
	</div>
	<map name="html-map">
		<area shape="rect" coords="75,180,100,200" href="#" />
		<area shape="rect" coords="145,140,180,160" href="#" />
	</map>
</div>

CSS

.map-viewport{ position:relative; width:300px; height:300px; overflow:hidden; }
.level{ position:absolute; left:0; top:0; z-index:10;}
.current-level{ z-index:20; }
#map{ width:1200px; height:900px; position:absolute; left:0; top:0; cursor:move;}

As you can see, we’re only specifying an html <map> element for the first zoom level. Mapz will automatically create additional image maps for all zoom levels. Adding a zoom level is easy: just add an image with the ‘level‘ class to the #maps div.

Now, when loading this page you’ll see your viewport with only the top-left corner of your image map visible. Let’s add some JavaScript to add the drag & zoom functionality.

Loading Mapz.js

First, make sure you’ve loaded both the jQuery as the jQuery UI library. I like to use Google Libraries for this, which would make your head section look somewhat like this:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.1/jquery.min.js" type="text/javascript"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.13/jquery-ui.min.js" type="text/javascript"></script>
<script src="js/jquery.mousewheel.min.js" type="text/javascript" ></script>

(note: Mousewheel is a jQuery plugin by Brandon Aaron which lets you bind events to usage of the mousewheel. We’ll need this if we want to be able to zoom in or out by using the mousewheel)

After we’ve loaded jQuery, jQuery UI and Mousewheel (optionally) let’s load Mapz.js and invoke the mapz function on our image map.

<script src="js/jquery.mapz.js" type="text/javascript"></script>
<script type="text/javascript">
$(document).ready(function() {
	$("#map").mapz({
		zoom : true,
		createmaps : true,
		mousewheel : true
	});
});
</script>

Actually, that’s all there is to it. We’ve specified some options, you can read more about these options on the Mapz plugin page. If you followed all the above steps and did things right you should now have a working image map with zooming functionality.

Take a look at the demo which uses the exact code snippets as in this post. I’ve used some kind of fantasy world map for this example and added only two html area’s to it but you should get the idea. If not, drop me a line trough the comments!

• Demo: Draggable image map with zoom in jQuery
• Mapz plugin page

Draggable image map with zoom in jQuery

wp_nav_menu() – This is the function that calls and echo’s the custom menu. You can specify many parameters but the ones we care about at the moment are ‘theme_location’ and ‘menu’. ‘theme_location’ calls the menu that is hooked to the given location, ‘menu’ calls the menu by ID, slug or name.

is_nav_menu() – This function checks if a given menu exists, again accepts (matching in order) ID, slug or name.

With these two functions we can check if a given menu exists and if it does call it, if not we can either do nothing, call a default menu or whatever you want to do when there’s no custom menu hooked to the current page.

Hooking a custom menu to a page or post

Like always, there are multiple ways to do this. We can look for $_SERVER['REQUEST_URI'] and use that as our menu name, however this comes with a big downside: we are limited to 1 page per menu. We won’t be creating a dynamic custom menu for EVERY page or post so this is probably not what you want. What we want is to create a one-to-many relationship between a menu and certain pages or posts. What about adding a post_meta value that holds the menu id or slug, whichever is easiest?

(Note: As of WordPress version 3.1, some screen options on the Post & Page edit Administration Panels are hidden by default. Custom Fields are hidden by default if they have not been used before.)

By specifying the menu slug as a custom field meta value we can call this from our template files from inside the loop by using get_post_meta(). Then we check if a custom menu with that slug exists, just to be sure. If it exists, output the menu using wp_nav_menu(). I’m not specifying a lot of parameters here, but of course you can just specify what’s needed inside the parameter array.

$menu_slug = get_post_meta($post->ID,'menu',true); 

if(is_nav_menu($menu_slug)) {
	wp_nav_menu(array(
		'menu' => $menu_slug
	));
} // optionally, add an else to output something when no menu exists with the given meta value.

So there we have it, we hooked a menu to a post. Using the above method you can of course re-use the same menu for different posts or pages. Now, if we wanted to make things easier we would get all created nav menu’s with wp_get_nav_menus() and add a select box beneath the post editor where a custom menu can be chosen but i’m not going to dive into that.

In fact, I might create a WordPress plugin that does just that if it turns out people are actually interesting in such a thing. Are you? Well, let me know then!

Dynamic custom menu’s in WordPress

By adding a small hack to your theme’s functions.php file we can only call wptexturize() en wpautop() on certain parts of the content. Since there is no way to disable the TinyMCE encoding that happens when switching between ‘Visual’ and ‘HTML’ mode we need to decode the encoded HTML. Let’s say we want to add some inline JavaScript to our post. Since we need to recognize what part of the content needs to be preserved let’s wrap our inline JavaScript with a shortcode.

... post content ...

[preserve]

<script type="text/javascript">

var welcome_string = "Hello. We don't want this snippet to get messed up by wpautop() and wptexturize()";

alert(welcome_string);

</script>

[/preserve]

... some more content...

Now, inside our theme’s functions.php we’re going to remove wpautop() and wptexturize() from the_content filter and add a function of our own to the filter. This function will only call wptexturize() and wpautop() on the parts of the content that are not wrapped in our [preserve] shortcode. Most parts of this snippet come from “disable automatic formatting using a shortcode“, the only thing that has been added is the HTML decoding to revert the encoding that has been done by TinyMCE when switching modes.

function my_preserve_function($content) {
	$new_content = '';
	$pattern_full = '{(\[preserve\].*?\[/preserve\])}is';
	$pattern_contents = '{\[preserve\](.*?)\[/preserve\]}is';
	$pieces = preg_split($pattern_full, $content, -1, PREG_SPLIT_DELIM_CAPTURE);

	foreach ($pieces as $piece) {
		if (preg_match($pattern_contents, $piece, $matches)) {
			$new_content .= html_entity_decode($matches[1]);
		} else {
			$new_content .= wptexturize(wpautop($piece));
		}
	}

	return $new_content;
}

remove_filter('the_content', 'wpautop');
remove_filter('the_content', 'wptexturize');

add_filter('the_content', 'my_preserve_function', 99);

With this snippet inside your functions.php you’ll see that you can effectively insert inline JavaScript or HTML as long as you wrap it in [preserve] and [/preserve]. When switching between Visual and HTML mode TinyMCE will still encode HTML entities but you can just ignore that cause upon generating the content everything will be decoded so that tags etc. will work just fine.

Got a better idea on how to enable inline JavaScript in your posts? Leave it in the comments!

Preserve inline JavaScript or HTML in the WP post editor