How to Use WordPress do_shortcode: Tutorial & Best Practices

Have you ever wanted to add WordPress shortcodes outside your regular post or page content?

If you’ve been using WordPress for a while, you’re likely familiar with the power of shortcodes for inserting features like galleries, buttons, and forms directly into posts and pages.

But what if you want to take this versatility a step further and use shortcodes outside of your typical content editor—say, in your theme files or a custom PHP template?

That’s where do_shortcode comes in. In this guide, we’ll explore how WordPress’s do_shortcode function enables you to integrate shortcodes seamlessly into PHP files, giving you dynamic control over your site’s layout and functionality.

What Are Shortcodes in WordPress?

Introduced in WordPress 2.5, shortcodes allow users to add dynamic content to their posts, pages, or other parts of a website without writing complex code. WordPress Shortcodes can also be referred to as placeholders that represent specific functionality or content.

Shortcodes are useful for developers and designers who prefer working with reusable blocks or content code. Developers can create custom shortcodes in WordPress themes or plugins and use them throughout the website to maintain consistency and perform advanced tasks effortlessly.

The best example to explain shortcode is that a custom shortcode might display a user’s latest tweets, a pricing table, or even pull data from an external API, all without the user needing to touch the underlying code.

List of Some Useful Shortcodes With Functions (Table)

Below is a list of some useful shortcodes in WordPress, along with their functions:

 

Function	Practical Usage
audio	audio src=”#”
embed	embed width=”450″ height=”320″
gallery	gallery id=”32″
video	video src=”#”
playlist	playlist type =”video”
[wpforms]	wpforms id=”10″
[soliloquy]	soliloquy id=”578″

To learn more about shortcodes, read our detailed blog

What Is WordPress do_shortcode?

do_shortcode gives additional flexibility for customizing how and where shortcodes display on a WordPress site.

By including do_shortcode in custom theme or plugin development, you can dynamically embed shortcodes within more structured areas of a site, ensuring that certain features, like forms or widgets, appear exactly where you want them.

Shortcodes are used within posts, pages, or widgets. However, sometimes, you might want to place a shortcode directly within a theme’s code, such as in the header or footer. With do_shortcode, you can do exactly that.

Before we show you how to integrate do_shortcode in WordPress, let’s first check out the benefits of using do_shortcode in WordPress.

Benefits of Using do_shortcode in WordPress

Normally, shortcodes are used in WordPress pages or posts within the editor.

• With do_shortcode, you can use the same shortcodes in any PHP file, such as a theme’s header.php, footer.php, or custom templates. This is especially useful when you want to display dynamic content like forms or galleries outside regular post content.
• Another advantage is improved customization. With do_shortcode, developers can combine multiple shortcodes within PHP scripts to create unique layouts or functionalities that aren’t achievable through the WordPress block editor or shortcode blocks alone.
• By embedding the shortcodes directly in templates, the workflow becomes smoother, and there’s less reliance on third-party plugins.
• Using do_shortcode also helps maintain consistency across a website. If a shortcode is updated—perhaps the parameters or its underlying functionality—those changes will automatically reflect wherever the do_shortcode function has been used. This reduces the need for repetitive edits across templates or pages, improving efficiency and reducing the likelihood of errors. It’s a crucial benefit for developers managing large websites with frequent updates.

How Does the do_shortcode Function Work?

The do_shortcode function works by processing any shortcode enclosed within its parameters and converting it to the intended HTML output.

When you write do_shortcode(‘[shortcode]’), WordPress reads the enclosed shortcode, executes it, and outputs the corresponding HTML or functionality.

This allows developers to bypass the editor limitations and insert specific features wherever they’re needed on the site.

To use do_shortcode, write:

<?php echo do_shortcode('[your_shortcode]'); ?>

This code tells WordPress to locate and execute the function associated with [your_shortcode]. Developers often use do_shortcode to avoid hardcoding certain repetitive functionalities or content elements.

How to Implement do_shortcode in WordPress

To help you understand how the do_shortcode function works, let’s look at a real example.

I’ll be adding a hero image to my website’s homepage by using a shortcode to display it. With the do_shortcode function, you can embed any image directly into your theme’s template files exactly where you want it.

Here’s how can do it.

• Open the WordPress dashboard.
• Click on Plugins>Add New Plugin.
• Search for MetaSlider from the search bar at the top.
• Click on Install and then activate the plugin.

• Open the WordPress dashboard again and go to MetaSlider settings.
• Now add an image to the slider and save the changes.

• Click on New Slide and upload an image you want to add.

• On the bottom right, you will see a block for Shortcode.

• Simply copy the shortcode and note it down. We will use this shortcode in the header of our site to check the functionality of do_shortcode.
• Locate the appropriate theme file for your hero section (e.g., banner-hero.php) in your theme’s folder. If your theme doesn’t have this file, you can choose another appropriate template, such as header.php or home.php.
• I’m adding my image as my hero image, so I’ll be adding the do_short code to my banner-hero.php file.

• Add the following code where you want the slider to appear.

<?php echo do_shortcode("[your shortcode goes here]"); ?>

• Click on the Update File button to save your changes.

Thats it! Check your website, and your uploaded image will appear at the top of your website.

Note: Directly editing theme files via the WordPress Theme File Editor is not recommended due to potential errors and security risks. A better practice would be to create a child theme and make changes there or use FTP/SFTP to edit files.

Best Practices for Using do_shortcode

Now that you have a basic idea of how to implement do_shortcode to your theme let’s go through a few additional practices that can help you make the most of this function.

By following these, you can ensure not only clean and maintainable code but also a smooth and secure user experience.

Using do_shortcode in Page Templates and Widgets

When using do_shortcode within page templates and widgets, it’s essential to consider placement, code structure, and reusability. Here are some guidelines:

Page Templates: To add a shortcode to a page template, call do_shortcode with the shortcode string.

<?php echo do_shortcode('[your_shortcode]'); ?>

This approach enables custom functionality, like a contact form or product grid, to be safely embedded directly into a page layout.

Widgets: Adding shortcodes within widgets enhances their flexibility by enabling dynamic content. While some themes or plugins allow shortcodes in widgets by default, adding this support can be done manually with do_shortcode:

add_filter('widget_text', 'do_shortcode');

After adding this code to functions.php, shortcodes placed within text widgets will be rendered correctly.

Security Considerations with do_shortcode

Ensuring the security of do_shortcode is crucial, especially when dealing with user-generated content or sensitive data. If not managed carefully, shortcodes executed within do_shortcode can potentially introduce vulnerabilities.

Validate Input: Make sure that any data coming into the shortcode is what you expect. For example, if the shortcode expects a numeric ID, check if the value is a valid integer before using it.

The intval() function can be useful here:

$id = isset($atts['id']) ? intval($atts['id']) : 0;

Only allow access to sensitive shortcodes for trusted user roles. This can prevent unauthorized users from executing potentially risky functions.

Limit Access to Sensitive Shortcodes: Only allow access to sensitive shortcodes for trusted user roles. This can prevent unauthorized users from executing potentially risky functions.

Keep Shortcodes Lightweight: Avoid heavy queries or complex computations in shortcodes, as they can impact both security and performance.

Managing and Optimizing Shortcodes for Better Performance

Poorly managed shortcodes can lead to slower page loading times and even server overload. Here are some strategies to keep shortcodes optimized:

Avoid Nested Shortcodes: Although nesting is possible, complex nested shortcodes can slow down the loading process and complicate debugging. Use alternative approaches if possible.

Cache Results: If a shortcode performs a database query or API call, consider caching the result using the WordPress Transients API. This reduces load times by temporarily storing the output.

Minimize Database Queries: Ensure that each shortcode minimizes database queries. Avoid running queries on every page load by caching or loading data only when needed.

Troubleshooting Common do_shortcode Issues

Here’s a step-by-step guide to dealing with common issues, such as shortcodes not displaying, quotation errors, and nested shortcode problems.

I’ve covered each issue is explained with practical fixes:

Shortcode Not Displaying Correctly?

Sometimes, a shortcode fails to render properly and instead displays the raw shortcode text, like [my-shortcode], on the website. This can happen for multiple reasons:

If the shortcode isn’t registered with WordPress, it will not function. Ensure the shortcode is properly added using add_shortcode.

Solution: 

You need to add the shortcode to your functions file or plugin:

function my_custom_shortcode() {
    return "This is the output of my shortcode!";
}
add_shortcode('my-shortcode', 'my_custom_shortcode');

Make sure you are wrapping the shortcode correctly with do_shortcode

Now use:

<?php echo do_shortcode('[my-shortcode]'); ?>

Double Quotes and Quotation Mark Errors

A common issue is the incorrect use of single (‘) or double (“) quotes, which can cause the shortcode to break.

Mixing quotes or copying and pasting shortcodes from external sources can lead to error type “curly” or “mismatched quotation” marks.

Solution:

Always use straight double quotes (“) for attributes:

<?php echo do_shortcode('[button color="red" text="Click Me"]'); ?>

Nested Shortcodes with do_shortcode

Using shortcodes inside other shortcodes or within complex PHP templates can cause unexpected issues, as WordPress might not parse them correctly.

WordPress may not automatically parse nested shortcodes, leaving them unrendered.

Solution:

Use do_shortcode for the nested shortcode explicitly.

Create a nested shortcode within the plugin,

// defining shortcode
function parent_shortcode() {
    $nested_content = do_shortcode('[child-shortcode]');
    return "Parent Content: " . $nested_content;
}
function child_shortcode() {
    return "Child Content";
}
// Rendering the child shortcodes
add_shortcode('parent-shortcode', 'parent_shortcode');
add_shortcode('child-shortcode', 'child_shortcode');

Only use the parent shortcode in a PHP file:

<?php echo do_shortcode("[parent-shortcode]"); ?>

Conclusion

WordPress’s do_shortcode function opens up a world of possibilities, letting you integrate shortcode-driven functionality beyond just the content editor.

You can customize your theme and plugin features with ease, making it simpler to create a tailored user experience and bring dynamic elements into every corner of your site.

We covered the key features and benefits of using do_shortcode, followed by a step-by-step look at how the function actually works and where it can be used effectively.

With these best practices in mind, do_shortcode becomes an invaluable tool in your WordPress toolkit, empowering you to craft a website that is both functional and engaging.