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.
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.
Copy and paste this code.
// 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.
Here’s sample data for you to give this a test run.
<h2>Shortcodes aren't so hard</h2>
Move on to the next step.
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.
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.
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.
This means that WordPress isn’t seeing the shortcode you added to the page as shortcode. Why does this happen?
“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. If your code will break things, draft it in a different file and only paste it in when it’s complete.
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.