This issue came up while my co-worker Tim at Wufoo was documenting parts of the latest Wufoo API. Some of the API pages have areas on them that are exactly the same as other pages, for example, a chunk of navigation that links to other pages of documentation.

One possible way to deal with this is to make a special template just for these pages and include that chunk inside that template. This solution edges on the issue of template-bloat which I’ve been thinking a lot about lately. Creating a new template every time you need one little change is solving the problem with a sledgehammer rather than a scalpel.

The ideal solution is just to make a shortcode. You pass the ID of the post (in our case, page) that you want to include and the shortcode is replaced with that content. This is the usage, where XXXX would be the ID of the post:

[digwp_include postidparam=XXXX]

To make it work, we’ll add a fairly simple function to the functions.php file in our theme. The function will take the parameter, run a query for it, and return back the content if it finds any:

function digwp_includeContentShortcode($atts) {
  
  $thepostid = intval($atts[postidparam]);
  $output = '';

  query_posts("p=$thepostid&post_type=page");
  if (have_posts()) : while (have_posts()) : the_post();
    $output .= get_the_content($post->ID);
  endwhile; else:
    // failed, output nothing
  endif;
  wp_reset_query();

  return $output;

}

// USAGE
// In the post content, you can use [digwp_include postidparam="1234"]
// "1234" would be the WordPress ID of the Page you are trying to include

add_shortcode("digwp_include", "digwp_includeContentShortcode");

Now you can publish small modules of content, and include them on any Post/Page that needs them! I’d probably create a Page on your site called like “Includes” or “Modules” and post them as Pages with that as the Parent Page. That way you don’t clutter up the root and they all stay organized together.

Check out this graphic (click for full size), which hopefully will drive home the idea:

Random notes:

• This is similar to the custom loop shortcode I previously published.
• This may be good territory for a plugin rather than functions.php code as I have done.
• Notice the function is properly prefixed.

© 2010 Digging into WordPress | Permalink | 28 comments | Add to del.icio.us | Post tags: content, include, shortcode

Combine the power and elegance of shortcodes with the convenience of private post content

For those unfamiliar with shortcodes, they are basically short strings of bracketed text used in post content to run functions and output content. Since WordPress 2.5, WordPress’ Shortcode API provides a set of functions for creating macro codes. Here are some hypothetical examples:

• [homepage] – displays your blog’s home URL
• [navigation] – displays a list of links to your categories
• [copyright] – displays your copyright information

For shortcodes to work, you just add a custom function to your theme’s functions.php file. Once that’s in place, you simply type the shortcode text-snippet anywhere in your post content. When such posts are viewed on your blog, the shortcode will run its function and output content, filter posts, or whatever else you’ve rigged it to do. Shortcodes can really simplify and speed up content creation.

You can create shortcodes for just about anything, including custom permalinks, calling widgets, Google Maps, and even custom queries. In this post, we’re combining the power and elegance of shortcodes with the convenience of private post content. And the best part is that it’s so easy..

Step 1: Add some code to your functions.php file

Slap the following code into your active theme’s functions.php file:

// add private content via shortcode
function private_content($atts, $content = null) {
	if (current_user_can('create_users'))
		return '<div class="private-content">' . $content . '</div>';
	return '';
}
add_shortcode('private', 'private_content');

What we’re doing here is creating a function that will recognize a shortcode named “[private]” and only display its contents if the user is logged in as an Administrator. For everyone else, the private content remains just that – completely private.

Step 2: Be a private-content shortcode ninja

Once you have the custom function in place, you are ready to add some private content to any of your posts. Here is an example of how to use the shortcode:

[private]
Note to self: this post contains some private content!
[/private]

Then, when the user is logged in as Admin, this private content will be displayed wrapped with the following markup:

<div class="private-content">
Note to self: this post contains some private content!
</div>

By using the “private-content” class, you can style your private content with a little CSS to make it all sweet ;)

Now in plugin flavor!

Since posting the article, we have seen two different plugins for this “private-content shortcode” functionality. After reading this post, Aldo Latino whipped up UBN Private Content, which takes it to the next level by using shortcode attributes to enable private content for any user-permission level (i.e., not just Admin). Download here!

There is also the The Esconder Shortcode Plugin is in Portuguese, and enables private content that is viewable by any logged-in users (i.e., not just Admin). See the linked post for download.

As Barry points out in the comments, using a plugin for private post content is a better idea if you ever plan on switching themes. Plugins work across themes, so your private content will always stay private. Conversely, when implemented via your local theme’s functions.php file, the shortcode function will keep your content private only for the current theme.

© 2010 Digging into WordPress | Permalink | 28 comments | Add to del.icio.us | Post tags: Security, shortcode, tips, tricks

But alas…

This ain’t gonna work “out-of-the-box”

After tinkering with some far-too-complicated solutions, someone on Twitter helped me with a deliciously simple solution: Just add this to your functions.php file:

add_filter('widget_text', 'do_shortcode');

This will ensure that the text content of widgets is parsed for shortcodes and those shortcodes are ran. Awesome.

Stephanie Leary wrote a great article on Using Shortcodes Everywhere, which covers this as well as using shortcodes in a bunch of other places: Comments, templates, excerpts, etc.

© 2010 Digging into WordPress | Permalink | 4 comments | Add to del.icio.us | Post tags: shortcode, widgets

Hence, the Custom Query Shortcode!

This is basically how I wanted it to work. You have a shortcode with one single parameter called “query”. (Remember, shortcodes are those things in brackets you can use in the body of Pages/Posts that do special stuff). In the “query” parameter, you literally enter exactly what you would enter for a query when using the query_posts() function. In other words:

[loop query=""]

You can pass whatever query you want to it. For example, let’s say you wanted to query for 20 Pages that were the child of a specific page and list them in Ascending order:

[loop the_query="showposts=20&post_type=page&post_parent=453&ord=ASC"]

What it returns

This is totally customizable in the function itself, but I made the judgement call for myself that it would return list items with linked post titles inside. So you’d go like this:

<ul>
[loop query="posts_per_page=3"]
</ul>

and you’d get:

<ul>
<li><a href="http://digwp.com/post-1/">Post 1</a></li>
<li><a href="http://digwp.com/post-2/">Post 2</a></li>
<li><a href="http://digwp.com/post-3/">Post 3</a></li>
</ul>

And of course those would be real URL’s and real Post titles…

The Code

This would go in your themes functions.php file. Now that I’m thinking more clearly about it, this probably makes more sense to be a plugin since it probably shouldn’t be theme-dependant, but oh well, we can do that another day.

function custom_query_shortcode($atts) {

   // EXAMPLE USAGE:
   // [loop the_query="showposts=100&post_type=page&post_parent=453"]
   
   // Defaults
   extract(shortcode_atts(array(
      "the_query" => ''
   ), $atts));

   // de-funkify query
   $the_query = preg_replace('~&#x0*([0-9a-f]+);~ei', 'chr(hexdec("\\1"))', $the_query);
   $the_query = preg_replace('~&#0*([0-9]+);~e', 'chr(\\1)', $the_query);

   // query is made               
   query_posts($the_query);
   
   // Reset and setup variables
   $output = '';
   $temp_title = '';
   $temp_link = '';
   
   // the loop
   if (have_posts()) : while (have_posts()) : the_post();
   
      $temp_title = get_the_title($post->ID);
      $temp_link = get_permalink($post->ID);
      
      // output all findings - CUSTOMIZE TO YOUR LIKING
      $output .= "<li><a href='$temp_link'>$temp_title</a></li>";
          
   endwhile; else:
   
      $output .= "nothing found.";
      
   endif;
   
   wp_reset_query();
   return $output;
   
}
add_shortcode("loop", "custom_query_shortcode");

Credit

When I first wrote this up to use, it totally didn’t work. I couldn’t figure it out… the query was getting passed over just fine, and if I hard coded the query, the whole thing would work just fine. It turns out that because the shortcode lived inside the content of a Post/Page, the ampersand characters in the query were getting encoded, and thus screwing up the query.

Dan Smith had the genius idea to use html_entity_decode() on the query before using it in query_posts(), but for some reason I couldn’t get it to take.

Roger Stringer coded up the solution with regular expressions you see above. Thanks guys!

© 2010 Digging into WordPress | Permalink | 10 comments | Add to del.icio.us | Post tags: functions, loop, shortcode

Put in functions.php file

//Google Maps Shortcode
function fn_googleMaps($atts, $content = null) {
   extract(shortcode_atts(array(
      "width" => '640',
      "height" => '480',
      "src" => ''
   ), $atts));
   return '<iframe width="'.$width.'" height="'.$height.'" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" src="'.$src.'&amp;output=embed"></iframe>';
}
add_shortcode("googlemap", "fn_googleMaps");

Usage inside Post/Page:

[googlemap width="200" height="200" src="[url]"]

Notice the three parameters above. Width and height are self explanitory, don’t use them at all for the default values set in the function itself. The src URL you can snag from Google Maps like this:

Easy!

This post is a good reminder of how easy it is to build your own shortcodes for specific bits of functionality that are specifically useful to you, whatever that might be. In the past, we’ve covered making shortcode permalinks.

© 2010 Digging into WordPress | Permalink | 12 comments | Add to del.icio.us | Post tags: functions, PHP, shortcode

Not great:

<a href="/contact/">Contact</a>

Much better:

<a href="<?php echo get_permalink(12); ?>">Contact</a>

That “12″ would be the ID of the Post or Page. Why is this better?

• If the slug ever changes, you are still cool.
• If the site moves from a subdomain (like if you were developing and then moving) to a top level domain or vice versa, you are still cool.

Doing it this way is a permanent reference to that Post or Page that will never change. This works great when we are working within our theme files, but what about when we are working within WordPress and actually writing Posts and Pages?

By default, we can’t run PHP within the content of our Posts and Pages, so we can’t use the get_permalink function. What we can do, is create a shortcode with just about the same functionality. And here it is:

function permalink_thingy($atts) {
	extract(shortcode_atts(array(
		'id' => 1,
		'text' => ""  // default value if none supplied
    ), $atts));
    
    if ($text) {
        $url = get_permalink($id);
        return "<a href='$url'>$text</a>";
    } else {
	   return get_permalink($id);
	}
}
add_shortcode('permalink', 'permalink_thingy');

This shortcode can be used in two ways:

Basic:

<a href="[permalink id=49]">Using without providing text</a>

This way you only provide the id parameter and it only returns a URL. This was you can use that URL however you want. For example, if you needed to add a special class name to the link or something (but only occasionally).

Providing text:

[permalink id=49 text='providing text']

This way returns a fully formatted anchor link back, using the text you pass.

© 2009 Digging into WordPress | Permalink | 13 comments | Add to del.icio.us | Post tags: functions, Links, shortcode, tricks

Custom fields allow us to attach data to Posts or Pages that we can yank out and use at will in our templates. They are awesomely flexible and single-handedly allow WordPress to be used for about any CMS need. The fact that they can only be used on single Posts can be limiting in some circumstances. Sometimes you wish you could grab a custom value that you can control and is consistent globally, regardless of the current post. In this post we’ll look at a technique to do so.

Fair Warning

This might not be the perfect technique. If you read this and have a smarter way, I’m all ears, this worked for me in my quick testing. What would really be slick is to make a plugin out of this, where you can create global key/value pairs through a special settings panel that could be use anywhere.

WordPress already has a somewhat-similar system in place through how the bloginfo function works.

<?php bloginfo('name'); ?>

Perhaps that could be tapped into and expanded upon, I dunno.

Example Use

One idea is for something like an Amazon affiliate ID code. You might use a value like this all over the place on a site, embedding within amazon links and widgets. If you hard-code this value, and then need to change it someday, that would suck. It would be better to save this value in one place, and use a variable (global custom field) to output it.

1. Create a Page

Call it “Global Custom Fields”. It doesn’t need any content, but you can use this page to add the custom fields you wish to use globally.

Notice down below, we just add custom fields in key/value pairs like any other custom fields on any other Page or Post.

Make sure to note the ID of this Page. We’ll need that ID for the custom functions we are about to write, but you can also use it to exclude this page from any dynamic navigation and such, as it’s not really meant for public viewage.

2. Create Generic Function

The built-in WordPress get_post_meta function accepts any Post ID and any key value. So we’ll add a new function to our theme’s functions.php file that generically returns values for keys we pass it. The Page ID will be hard-coded, equal to the value we just noted down.

function global_custom_field($key) {
   $output = get_post_meta(677, $key, true);
   echo $output;
}

3. Create a Shortcode Function

With our generic function, we can already use it just as-is in our templates. Without a special plugin though, you can’t execute PHP functions in the body of articles though. We can be even smarter though, and create a shortcode function for use in our content.

More stuff for your functions.php file:

function gcf_func($atts) {
    extract(shortcode_atts(array(
		'key' => 'amazon_id'  // default value if none supplied
    ), $atts));
    return global_custom_field($key);
}
add_shortcode('global_custom_field', 'gcf_func');

4. Use it!

Now anywhere in our template we wish to call in the value of a global custom field, we just pass the function the key value and we get back our value:

echo global_custom_field("amazon_id");

Or right inside our posts content:

[global_custom_field key="amazon_id"]

© 2009 Digging into WordPress | Permalink | 12 comments | Add to del.icio.us | Post tags: custom-fields, echo, functions, shortcode, tricks