Make WordPress Shortcodes From Core WP Functions, Plugin Functions and Theme Functions

This is part two of JournalXtra’s WordPress Shortcodes tutorial. This part of the tutorial shows how to make shortcodes using the functions written in active plugins, active themes and in the WordPress core scripts. Part one of this tutorial series is here.

WordPress is a collection of scripts used together to make web content management system, CMS. These scripts contain code in functions and classes. As show in part one of this series, shortcodes are tags used in post, page and widget content to display the output of code written in functions and classes.

Functions and classes that make up the WordPress core scripts can be used as shortcodes. That includes action hooks and filters.

Functions and classes found in the active theme of a WordPress site or in the site’s active plugins can be used in shortcodes as well. This is true even when the theme or plugin developer didn’t intend the code to be used in shortcodes.

Make WordPress shortcodes out of existing functions

WordPress functions and classes perform useful tasks. For instance, one function displays the website’s masthead to visitors, another loads the page title, and another shows the comment form. Everything served when the frontend or dashboard of a site is viewed is made possible by functions and classes.

A shortcode is a shorthand tag used to represent a function.

The action hook that turns any function into a shortcode is the add_shortcode() hook.

add_shortcode() is used like this:

Many functions within the scripts of an active theme or active plugin or even many functions within WordPress core can be used in shortcodes.

Sometimes we need to write a separate function to wrap around the the function we want to use as a shortcode. The reason for this is explained in the next few sections of this tutorial.

Find functions, hooks and filters to work with

There are tools we can use to find functions, hooks and filters within WordPress scripts.

The scripts where functions are found usually explain what the functions do and how they are used.

The Hooks Search Tool finds hooks and filters in themes, plugins and WordPress core files. Download the tool here, upload the zip package to a server where WordPress is installed, unzip the package then point a web browser to search tool script. Remember to delete the script after use. Documentation for the Hooks Search Tool is here.

The Function Reference in the WordPress Codex gives examples of how to use core WP functions. This is complimentary to the documentation found in scripts.

The WordPress Hook/API Index at Hookr has information about functions used in plugins and themes found in Github and in the WordPress repository.

PHP Cross Reference is a web application for reading WordPress core files and for seeing where functions are used within core files.

Google is a fantastic resource. Never forget Google.

Making shortcodes

The paginate_links() function displays page numbers on archive pages like the blog archive page or a category archive page. paginate_links() can be used to display previous and next navigation buttons as well. This function is shortcode friendly and easy to understand.

This part of the tutorial will use paginate_links() as a shortocde.

Simple conversion

One line of code is all it takes to make a shortcode of paginate_links().

Add this code to a functions.php file (the active theme’s functions.php file will work fine):

That single line of PHP creates the shortcode [vr-pages]. This shortcode can be used in a sidebar text widget to display pagination buttons in a widget area when archive pages are in view.

The vr- prefix in the shortcode tag prevents conflicts with other shortcodes that might use the pagination tag.

The raw code for paginate_links() can be read here.

Style the output

The shortcode’s output can be altered by wrapping paginate_links() in another (wrapper) function then using this wrapper function in with add_shortcode().

A simple wrapper looks like this:

The above wrapper does not alter the output in any way. The shortcode name is now [vr-pages].

The output of paginate_links() can now be wrapped within HTML tags or be given text.

Here is the same wrapper function but this time the output is wrapped within <div> tags:

The pagination buttons displayed by the shortcode can now be styled with CSS because the <div> wrapped around the buttons has a CSS class to target.

Passing shortcode attributes to function arguments

paginate_links() can take arguments. These arguments change the appearance of the buttons.

Look at the documentation for paginate_links():

A shortcode can accept attributes. Those attributes can be passed back to the function called by the shortcode.

Arguments can be passed from a shortcode to paginate_links():

  1. The wrapper function for paginate_links() can use the WordPress Shortcode API to make a shortcode that accepts attributes. This means the wrapper function can be written to receive data (i.e. the shortcode attributes) which can then be used within the wrapper function.
  2. The attributes used by the shortcode are then passed to paginate_links() where it is used to effect the final output displayed by the shortcode.

For example, the [vr-pages] shortcode can be written to accept attributes to affect

  • the quantity of page numbers shown at the start and end list page ($end_size),
  • the quantity of page numbers shown before and after the current page ($mid_size),
  • The ‘previous’ text ($prev_text), and
  • The ‘next’ text ($next_text).

The above code creates a pagination shortcode that accepts 4 attributes:

[vr-pages end_size=’3′ mid_size=’3′ prev_text='<–‘ next_text=’–>’]

Fix misbehaving shortcode output

Some functions return output that jumps outside the content area or widget area they are used in. Misbehaved shortcode output can be fixed by using output buffering.

An output buffer holds content in memory (the buffer) until it is released for use (flushed).

When activated, an output buffer prevents output going to the screen until the buffer is flushed. This can be used to maintain control of code output until we are ready to release it for other processes to work on it.

The output of paginate_links() behaves well no matter where it displays but let’s buffer the output of paginate_links() for the fun of it.

Compare the above buffered function to the non-buffered version:

The PHP functions ob_start() and ob_get_clean() start and flush the PHP output buffer.

  • ob_start() tells PHP to begin capturing output into a buffer.
  • ob_get_clean() tells PHP to clean the buffer and provide the output for further processing.

The buffered content can be returned directly to the shortcode or it can be stored in a variable which can be edited. The buffer output can be used elsewhere within the function or it can be returned directly as the shortcode output.

Here is an example of how to pass the output buffer content to a variable ($content) and return $content directly as the shortcode output without further processing:

Use output buffering when the content displayed by a shortcode behaves unexpectedly. Unexpected behavior includes shortcode output jumping outside of a sidebar or widget area or the output not respecting theme CSS styles because, for example, WordPress has filtered the output to remove disallowed HTML markup.

Example misbehaving shortcode output

The comment_form() function displays the comment form below posts.

Used as a shortcode, the comment form displayed by comment_form() jumps out of any widget area the shortcode is used within. Output buffering prevents shortcode output misbehavior.

The comment form shortcode, including attributes, is

[vr-comment label_submit=”Send” title_reply=”Respond” comment_notes_after=”Be sensible”]

Check for the existence of a class or function

When a function from a plugin or theme is used as a custom shortcode or in a custom function we need to check the function exists when we use it. Failure to check will crash the site when the plugin or theme is disabled.

We check a function exists with function_exists( ‘function_name’ ).

We check a class exists with class_exists( ‘class_name’ ).

We don’t usually need to confirm the existence of core WordPress functions and classes. The WordPress dev team give advance warning before they remove functions. The above example is given for simplicity.

In the above example, if paginate_links() didn’t exist the output of [vr-pages] would be nothingness: there would be nothing displayed in its place.

Final words

WordPress is a framework of functions, classes, action hooks and filters that can be used to fine-tune WordPress to suit specific needs. These core WordPress functions and classes can be used in the themes, they can be used in shortcodes, and they can be used to make plugins.

Along with core WordPress functions, the functions written in themes and plugins can be used in shortcodes provided the plugins or theme are active within the website where their functions are used as shortcodes. The presence of a function or class can be checked with function_exists() and class_exists(). Failure to confirm the presence of a function or class will crash a website that tries to call an absent function or class.

When add_shortcode() is used in functions.php we are actually making a WordPress plugin. We might not activate and deactivate the code in Dashboard > Plugins but that doesn’t make it any less of a plugin: it is still custom code being plugged into WordPress.

Over to you!

Got a question, suggestion or argument? Add it to the comments.

Win the battle. Social Warfare Dynamik Website Builder Author Pro

Leave a Reply

Be the First to Comment!

Notify of
wpDiscuz

Free to your inbox

Join our mailing list to receive the latest news and updates from JournalXtra.

You have Successfully Subscribed!