This website uses cookies to ensure you get the best possible experience. See our Cookies Policy.

PMG Digital Made for Humans

An Introduction to WordPress Shortcodes

4 MINUTE READ | January 21, 2012

An Introduction to WordPress Shortcodes

Shortcodes are WordPress‘ way of inserting content within a given post, page or custom post type. This content is often of a more dynamic nature. Take for instance, the gallery shortcode built into WP. Just pop

into any WordPress post and out pops a nice gallery of all images attached to that post. Awesome!

In this tutorial, we’ll cover the basics of creating your own shortcodes.

The first step is actually add the shortcode – that is, let WordPress know about it. We do this with a function called, conveniently, 

add_shortcode
. It takes two arguments: the shortcode name, or the stuff your surround with brackets in the post to make it work and (2) the call back function.

I like to wrap the call to add_shortcode inside a function hooked into init. Why? Because WordPress loads in phases. Registering a shortcode on init ensures the entire WordPress enviroment is loaded (including the add_shortcode) function before doing anything.

<?php

add_action( ‘init’, ‘pmg_sctut_add_shortcodes’ );

function pmg_sctut_add_shortcodes()

{

add_shortcode( ‘post-link’, ‘pmg_sctut_shortcode_cb’ );

}

What happens when WordPress encounters a shortcode in post content is it looks for it in its array of registered shortcodes. If it finds it, it calls the callback function (registered with add_shortcode), which returns a value. WP then replaces the shortcode with that returned value.

The callback function is where the work happens. Our shortcode will insert a link to another post based on an id attribute.

Shortcode callbacks receive two arguments: attributes of the shortcode and the content. [shortcode-name these="are" attributes="yes"] this is content[/shortcode-name]. Content doens’t have to be used, so it’s best to give that function argument a default value. With that in mind, here’s the skeleton of our callback.

<?php
function pmg_sctut_shortcode_cb( $atts, $content = null )
{
// do stuff here
}

The attributes passed into a shortcode can be dangerous. And you also probably don’t want to have to call isset all the time to make sure certain attributes were included. Enter, shortcode_atts. It takes two arguments, the first is an array of allowed attribute array keys, and their default values. The second should be the array of atts passed into the shortcode callback function. shortcode_atts will check to see if the passed in attributes has a given key. If it does, that key’s value will be sent in the returned array. If the attributes array doesn’t a have a key, the default value will get returned.

Our call to shortcode_atts is wrapped in extract, a built in PHP function.

<?php
function pmg_sctut_shortcode_cb( $atts, $content = null )
{
extract( shortcode_atts(
array(
‘id’ => False
),
$atts
) );
}

Next up, we’ll check to see if we have our id attribute and get the post associated with it. Make sure the post is published, and then build our link.

<?php
function pmg_sctut_shortcode_cb( $atts, $content = null )
{
extract( shortcode_atts(
array(
‘id’ => False
),
$atts
) );
// no id?  bail
if( ! $id ) return ”;
// get the post we’re linking to
$tolink = get_post( absint( $id ) );
// not a published or we didn’t get a post, bail
if( ! $tolink || ‘publish’ != $tolink->post_status ) return ”;
$link = get_permalink( $tolink );
$title = $content ? $content : $tolink->post_title;
return sprintf(‘<a href=”%s”>%s</a>’, esc_url( $link ), esc_html( $title ) );
return sprintf(‘<a href=”%s”>%s</a>’, esc_url( $link ), esc_html( $title ) );
}

The only thing of note in the remainder of that function is the check to see if the $content variable actually contained a value. This is common: content is not required of a shortcode, so if you’re planning on using it, have a default or something else you can use.

Shortcodes are awesome. But they are not the solution for everything. For instance, you could use shortcodes to replace something like <div class="alert">Some message<div> with [error]some message[/error]. That shortcode looks suspiciously like HTML. If that’s the case, why not just learn HTML?

Insights meet inbox

Sign up for weekly articles & resources.

Shortcodes can also cause a lock in effect. Deactivate the plugin that adds them or change away from the theme that adds theme, and you now have ugly shortcodes in your content. Awesome. There’s not much that can be done about that, but it’s something to be aware of.


Posted by Christopher Davis

Related Content

thumbnail image

Get Informed

PMG Innovation Challenge Inspires New Alli Technology Solutions

4 MINUTES READ | November 2, 2021

Get Informed

Applying Function Options to Domain Entities in Go

11 MINUTES READ | October 21, 2019

thumbnail image

Get Informed

My Experience Teaching Through Jupyter Notebooks

4 MINUTES READ | September 21, 2019

Get Informed

Trading Symfony’s Form Component for Data Transfer Objects

8 MINUTES READ | September 3, 2019

Get Inspired

Working with an Automation Mindset

5 MINUTES READ | August 22, 2019

Get Informed

Parsing Redshift Logs to Understand Data Usage

7 MINUTES READ | May 6, 2019

Get Inspired

3 Tips for Showing Value in the Tech You Build

5 MINUTES READ | April 24, 2019

thumbnail image

Get Informed

Testing React

13 MINUTES READ | March 12, 2019

Get Inspired

Tips for Designing & Testing Software Without a UX Specialist

4 MINUTES READ | March 6, 2019

Get Informed

A Beginner’s Experience with Terraform

4 MINUTES READ | December 20, 2018

All POST