The bulk of my custom development work falls into 2 groups: custom theming and custom shortcodes. Tools like Elementor make custom theming simple and (mostly) code-free. But when those tools fall short, shortcodes can give you the ability to create levels of customized output that can’t be found in an off-the-shelf solution.
WordPress shortcodes are written in .PHP and the output is processed as raw HTML. This gives you the ability to reach into the database and get anything you want (posts, custom fields, taxonomies) and display them however you want.
Creating shortcodes for WordPress with a WordPress shortcode template
Step 1: Find the place to add your code
For this tutorial, I’ll assume that you are using your very own custom plugin to house your shortcode script. There are other places you can put your scripts like a child theme. But I like this method best.
Download the file you’re going to edit and save it somewhere easy to find. You don’t need to download the plugin’s entire folder – just the .PHP file.
Step 1.5: Make a backup
Make a copy of the file. An easy way to do this is to open the file in your text editor and immediately use the SAVE AS command to create a 2nd file.
Why? This is to save your butt when you screw up. You will. Maybe not this time, but errors and goofs happen to everyone.
Step 2: Add this template
Copy and paste this code.
- Paste this below the plugin’s information header.
- Pay attention and do not paste this in the middle of another function, script, or comment.
// start output
$thisOutput = ob_get_clean();
add_shortcode( ‘shortcode-name’ , ‘function_name’ );
A quick explanation and a warning
“function” tells the server that this is a block of code to be executed when its name is called.
“function_name” is the name that you gave the function. It MUST be unique or you can crash the site. An easy way to ensure uniqueness is to put your initials at the beginning of the name. And use underscores (_) not dashes (-).
“//start output” is where you start adding your custom code. The “//” means that it’s a comment so don’t put your code on that line. Start on the live after it.
“//return output” is where you stop adding code. Leave the rest of the function alone. It cleans up a few things to ensure your output is proper and that it doesn’t interfere with any other WordPress functions.
“add_shortcode( ‘shortcode-name’ , ‘function_name’ );” is the command that actually creates the shortcode. “shortcode-name” is the part you put in brackets on a WordPress page. (Use dashes (-), not underscores (_).) And lastly, there’s “function_name”. It must match the name you used at the beginning of the function.
Quick trick: Here’s a simple convention to keep things simple and clear. I might name a shortcode “jwr-page-list”. I’d use the same pattern for the function name: “jwr_page_list_fn” (fn is an abbreviation for function).
Warning: You can do anything you want except put a return statement in your output. That can have unpredictable results.
Now is a great time to update your plugin’s table of contents. Should you add it to the table if this is your 1st script? Hell, yes. It’s a habit that you need to create.
Step 3: Some basic edits to get you started
Here’s sample data for you to give this a test run.
- Do everything in Step 2.
- Change “shortcode-name” to “my-sample-shortcode”.
- Change “function_name” to “my_sample_shortcode_fn”. Don’t forget to change it in both places.
- In between “start output” and “return output”, add this code:
<h2>Shortcodes aren’t so hard</h2>
Move on to the next step.
Step 4: Upload the modified file
You might have to do a little file juggling, but you need to upload your edited file and replace the old plugin’s file. And it has to have the old file’s name.
Step 5: Shortcode usage
Create a new page and add “[shortcode-name]”. If you’re following the additional edits data, use “[my-sample-shortcode]” instead. Publish the page.
You should see “Shortcodes aren’t so hard” on the page.
Troubleshooting shortcode issues
The white screen of death or other WordPress crashes
This problem is easy to fix. All you have to do is upload the old plugin file.
The bug itself isn’t always to identify. But if you crashed the site, the issue is probably bad code. Look for typos. Something as simple as switching a single quote for a double quote can kill your script.
You see the shortcode
This means that WordPress isn’t seeing the shortcode you added to the page as shortcode. Why does this happen?
- There’s a typo in the shortcode you added to the page.
- There’s a problem with your “add_shortcode” line:
- Did you upload the right file?
- Did you save the file before you uploaded it?
- There’s some other typo in the line either related to the name or the code structure.
“No output” is actually a step in the right direction. You didn’t crash the site so your code is at least passable. The shortcode was processed so that part is also working correctly. Your issue is in between “start output” and “return output”. Double-check that area.
Congratulations! You’ve exceeded the scope of this tutorial.
This has the same origin as No Output. There’s something wrong in that output area.
As you move into making your own custom-coded shortcodes, I want you to keep 2 things in mind.
Save often. Nothing is more frustrating than losing your work because you forgot to save.
Test often. Don’t wait until you think you’re done to test your work. I like to add in/then statements to verify that variables are set or certain processes run. If they run, it prints a statement to the screen. It lets me know what steps have processed. Just don’t forget to remove those bits of code before you publish it.