Create Custom Shortcodes for WordPress in Two Minutes

Tara Hornor
Tweet

I love shortcodes. If there’s a time to drop the childish quip, “Then why don’t you marry it?” — now would be the right time. That’s how much I love shortcodes in WordPress.

WordPress’s biggest strength can also be its biggest weakness. While it does have all kinds of powerful tools and security built in, making custom functions and features can be a huge pain.

But that’s where shortcodes come in. Once you’re comfortable with creating a shortcode, you can create custom functionality in just minutes — your imagination is the only limit.

Summary for Future Reference

Because I hope you’ll bookmark this page and reference later, here’s a summary of what it takes to get a shortcode functioning:

  1. Create the code you want
  2. Save the code (usually in some place like the wp-content folder)
  3. Include the new file you saved within the functions.php file
  4. Reference your shortcode using add_shortcode(‘shortcode’, ‘function’)
  5. Place your shortcode wherever you want it

Why All the Shortcode Love, Exactly?

If you’ve ever had to do any kind of WordPress development, you’ve run into the situation where you need some custom functionality or a specialized design element. For security reasons, WordPress strips a lot of HTML tags and all PHP code out of posts and pages.

This is usually for our own good, but it makes for a nightmare when you just want a simple design modification.

Shortcodes are the stop-gap. They allow you to inject any PHP or other code right where you want it. Once you’re comfortable creating the shortcode markup, you’ll never go back.

So, let’s jump into creating a custom shortcode and build out a process that you can reference in the future when you’re ready to make your own.

Step 1: Create the Code

This is where you need to create your functionality. I don’t know what you want to accomplish, but here’s a very simple example of a shortcode that allows me to inject a custom message into a post. This is just for demonstration purpose, but it should get your imagination fired up:

<?php
function some_random_code(){

echo 'Thanks for reading my posts!';
}// End some_random_code()

?>

So we have a very simple little PHP function. You could literally put anything in this function that you want to execute on your site — a custom form, special HTML markup, or calls to an external database.

Step 2: Save the Code (But NOT in the Functions.php File)

While you can store the above code within the functions.php file, I would be setting you up for failure long-term if I actually advised it. I strongly recommend that you create a separate file for your own custom shortcodes. Call it whatever you like, and store it in the wp-content folder, or create a plugin (see my article on creating WordPress plugins).

For this example, create a file named “my_custom_shortcodes.php” and save it within the wp-content folder. This folder is generally safe from WordPress upgrades and core updates that can overwrite your existing functions.php file. You can lose a lot of work fast if a client decides to update to the latest theme update or install a new theme without telling you. It’s a lot easier to just go in and recreate the next few steps.

Step 3: Include Your Custom PHP File

Now we need to tell WordPress where to find your custom shortcode file. Assuming you saved it in your wp-content folder, here’s what you need to add to your functions.php file:


include(WP_CONTENT_DIR . '/my_custom_shortcodes.php');

Now, WordPress is aware of your content and will integrate it into its functionality. We’re 90% done at this point!

Step 4: Define Your Shortcode

Before you can actually start using the shortcode throughout your site, you need to tell WordPress that it is, in fact, a real shortcode. Right below your code in Step 3 within your functions.php file, add the following:


add_shortcode( 'some_random_code_sc', 'some_random_code' );

Here’s what’s happening — the first part of the add_shortcode call is the name of the shortcode you want to use. This is what will be put in your posts and pages. The next argument is the name of the function. So here’s an example in more plain English:


add_shortcode( 'shortcode_name', 'function_name' );

Quick note: I like to use the name of the function for my shortcode, but I add the “_sc” to the shortcode (for ShortCode) to help me track down my code if I want to edit it later.

Here’s what my functions.php file looks like after I’ve added my two lines of code:

Step 5: Add Your Shortcode

Now, all you need to do is add your shortcode to any post or page! Create a new post/page and add the shortcode to it, publish, and view the page.

And you should see your code output on the published page:

You did it! Now you can quickly create all kinds of custom functionality and integrate it into your WordPress site in minutes.

How are you using shortcodes? Show off your work in the comments!

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • Bob

    I don’t include them directly in functions.php, I put it in a separate file and then include that file from functions.php.

    Then again, normally I’m working with custom templates where I have more certainty that nothing will get erased.

  • http://www.adrenalinaestudio.net Ruben

    Very well explained Tara, congratulations i´m going to try this right now. I´ll be waiting for the post about plugins creation.

    • https://plus.google.com/u/0/117883511520701899763?rel=author Tara Hornor

      Great! I’ll be sure to add in the link to this article once it is published.

  • http://lienhard.net Steven Lienhard

    This is great information. I was using the plugin PHP exec shortcode to do this, but I think this may be a preferable way to do it. Didn’t know about the add_shortcode function. Thanks!

  • http://www.klageswebdesign.com Ken

    Thanks for such a great, clear set of instructions. Once you create a bunch of shortcodes, what do you do to document them for future reference and possible use by the end users?

    Do you have some simple way to display a list of shortcodes and what they do in the admin area? Or some other way to let the clueless end users remember there is a feature there they can use? If we send them a list of shortcodes as a separate document, you know they will lose it and /or forget they ever received it.

    • https://plus.google.com/u/0/117883511520701899763?rel=author Tara Hornor

      Hey Ken!
      This will depend upon whether you create shortcodes in a theme or a plugin.

      If your shortcodes are in a theme, there are methods for displaying the shortcodes in the Appearance panel.

      If you used create a plugin, you could probably just list them in your Readme.txt.

  • https://plus.google.com/u/0/117883511520701899763?rel=author Tara Hornor

    Hey, Everyone! The plugins article is now live on DesignFestival: http://designfestival.com/design-a-wordpress-plugin-in-five-minutes-or-less/

  • Trey Mitchell

    Not sure if it’s just me, but the shortcode as written generates two lines of ‘Thanks for reading my posts!’. One appears where you’d expect it, in the post where you put the shortcode.

    The appears inside the head of the document. I think this is happening when the theme calls wp_head().

    I fixed it by replacing ‘echo’ with ‘return’ in the some_random_code function.

    Maybe a difference between WP and WPMU? or a recent update to WordPress? Anyway, thought it worth passing along in case others encounter the same issue.

    • https://plus.google.com/u/0/117883511520701899763?rel=author Tara Hornor

      Thanks for the info, Trey! I’ll check into this and see what’s happening. What version of WP were you using to test this in?

    • Skweekah

      You are doing it the right way Terry. Using return is preferred to using echo, which causes placement issues on the live site. Also, not sure how not placing the code in the functions.php file and using include to find the file is vastly different. I guess it saves on having a functions.php file that is too bloated. If you are worried about theme updates and over-riding files, create a child theme.

  • Skweekah

    Sorry, Trey not Terry!