Get Good With ShortCodes

Another awesome tool available to WordPress is shortcodes. Again, most users would just install a plugin or use a widget to add functionality, but many of them you can do yourself with a few lines of code in PHP and a single line of code directly in your posts. It’s really easy!

WordPress allows you to add code to your page or blog templates so the functionality appears on every single page. Sometimes you want a specific functionality only on a single page or post, not on every single page. The feature boxes in the main page of this site, the code page index previews, the links to the other pages in this article series, all instances of code sample markup, and the contact form on this site* are all implemented by shortcodes. Let’s look at one of the shortcodes used on this very page.

A shortcode is a line or sometimes a couple lines of code in your page or post, or even in a text widget, enclosed with brackets. The first token is the function call, separated from attributes by white space.

  
   
     [child_pages_links target = 'parent' class = 'highlight-nav-list smaller']

If there is more than one attribute I generally like to separate them on multiple lines for legibility.

  
   
     [
        child_pages_links
        target = 'parent'
        class = 'highlight-nav-list smaller'
     ]

In this shortcode I’m going to call the function child_pages_links() and the attributes we pass in is an array with keys target and class. What this function does is creates links for all child pages of a given parent page (in this case, the children of the WordPress page.) It is similar to wp_link_pages() which almost does what I need, but not quite, which makes the task a perfect candidate for a bit of shortcode. wp_link_pages() is only available for posts and I don’t need it on every page of the site, just as a navigation among specific child pages.

Like other functionality described in this series, I put all my shortcode together in a single PHP include (see this article for how TEMPLATEPATH is defined.)

  
   
     require_once(TEMPLATEPATH . '/functions/shortcodes.php');

Then I declare the function and register it with WordPress with the call to add_shortcode(). IMPORTANT: the below uses PHP 7+ code. If your server does not run PHP 7 or greater, you will need to change the array declarations and the null coalesce operator to your version’s implementation.

<?php
/**
 * I was surprised this doesn't already exist the way I need it. Allows any
 * child page (not post) to output a set of links to the parent and other
 * child pages for "article navigation." Usage in page content:
 *
 * [
 *   child_pages_links
 *   target = string 'parent' or empty/"anything" - determines "child pages of what?"
 *   class  = string 'CSS class list'
 * ]
 *
 * @param array $atts
 * @return string
 */
function child_pages_links($atts = []) {

    global $post;

    $atts = shortcode_atts(
        [
            'target' => 'this-page',
            'class'  => null
        ],
    $atts);

    $html = '';
    $childpages = '';
    $class = ($atts['class'])?? null;
    $target = ($atts['target'] == 'parent')? $post->post_parent : $post->ID;
    $param = 'echo=0&sort_column=menu_order&title_li=&child_of=' . $target;

    if ($atts['target'] == 'parent') {

        $parent_title = get_the_title($post->post_parent);
        $link = get_permalink($post->post_parent);
        $childpages .= "<li><a href=\"$link\">Return to $parent_title</a></li>" . PHP_EOL;
    }
     $childpages .= wp_list_pages($param);

    if ($childpages) {
        $html = "<ul class=\"$class\">$childpages</ul>";
    }

    return $html;
}

add_shortcode('child_pages_links', 'child_pages_links');

To summarize what is happening:

  • Observe the series navigation below to see the result of this shortcode function.
  • If I am a "parent" page (the "Wordpress" page in this series) just give me a set of links to all the child pages of me.
  • If I am a "child" page, give me the same links but begin the link set with a link back to the "parent" page (the "Wordpress" page in this series.)
  • The attributes in this function only care if we’re sending "parent" as a target. This tells it to get the parent of this page and generate links, otherwise just generate links of my "child" pages.

A similar shortcode is used on the Code page. It acts very similar to the blog index page, with short excerpts, thumbnails, and links to pages. This functionality is inherent in blog index page behavior but is not inherent in pages behavior. Using the above example, it wouldn’t take much to figure out what the function behind the shortcode looks like.

  
   
     [child_pages_preview]

Code Markup. When first building this site I marked up the code samples manually and quickly learned that was totally and completely insane. Code Markup in WordPress covers the shortcode I’ve created that uses a standalone class object to output code from static sample files. It supports markup in PHP, CSS, Javascript, HTML, and Perl and can display code inline or in an overlay window. This page uses the inline flag, an example of the window overlay feature is in the blog post on PSR’s and Legibility.

  
   
     [
        code_sample
        file = 'some-file-in-a-safe-location.php'
        inline = 1
        pre_class = 'code-block full'
     ]

If you’re not really a coder and you learn one thing about coding for WordPress, make it shortcodes. Start small and expand both your PHP knowledge and comfort with creating shortcodes, they can save you time, money, and web site resources if properly used.

*The contact form is a plugin I wrote, but it is instantiated on the front end by a shortcode.