Inserting JavaScript with a Shortcode

Have you ever needed to insert a piece of JavaScript into a single post or page? Maybe there is an external contact form from a vendor that you’ve been given a snippet of JavaScript to include? There are a number of ways to do this. You could put a conditional in your template file and only add the JavaScript if your post meets a particular criteria. Another option might be to create a new template that has the JavaScript. That way, the script would only be included on posts using the template.

Another solution that I personally like is to include JavaScript via shortcode. A few reasons that I like this method are:

1. The JavaScript is not dependent on the post’s template. If you wanted to include the JavaScript on two different posts with differing layouts, you would need specific template files for each. Or you would need to add a list of conditionals. This can get messy fairly quickly if the code is needed on multiple posts.
2. Adding the JavaScript to the template file, or to an action hook, makes the JavaScript less visible. It might be unclear to you, a month down the line, why a couple of posts utilize the JavaScript and others do not. A shortcode will be right in your post’s content, plainly visible.
3. A shortcode can be added anywhere on your page. In the example of an embeddable form, this could be best placed in different parts of different pages. A shortcode gives you that flexibility.

Adding a shortcode to WordPress is pretty easy. I am going to run through a very basic example. In our functions file, we can use the add_shortcode function. I am also going to use PHP output buffering so that I don’t need to worry about escaping my JavaScript. In my very simple JavaScript, this isn’t a big deal, but if you have a large chunk of JavaScript, this can make it much more readable. Here is my example code which will simply show a JavaScript alert:

<?php function scc_js_example() {
    ob_start();
    ?>
    <script>
        alert('I am in a shortcode!');
    </script>
    <?php
    $output = ob_get_contents();
    ob_end_clean();
    return $output;
}
add_shortcode( 'js_example', 'scc_js_example' );

The add_shortcode function makes a shortcode available to use with the name of the first parameter. So, I could call my shortcode above with [js_example]. The second parameter is the callback, or the function that should be run when the shortcode is used. Since I am using the callback scc_js_example, the function scc_js_example will be called when using the shortcode.

In my scc_js_example function, I am starting a PHP output buffer. This will pause any output that would normally be displayed to the screen and ob_get_contents() will grab that information. I am storing the buffered information, which is my JavaScript, into the variable $output. This can then be returned to be used by the shortcode. If you did not want to use buffering, you could simply store the information to your output variable:

<?php
$output  = '<script>' . PHP_EOL;
$output .= "alert('I am in a shortcode!');" . PHP_EOL;
$output .= '</script>' . PHP_EOL;

Again, this is manageable for a short bit of JavaScript code but might get confusing if there is a lot of code with a lot of escaping.

That’s it! Now when I want my alert on a page, I can just use the shortcode in the classic editor or in Gutenberg.