CorePlugin Development

WordPress Plugin Function – add_shortcode()

By December 21, 2018 No Comments

WordPress Plugin Function – add_shortcode()

Shortcodes are a valuable way of keeping content clean and semantic while allowing end users some ability to programmatically alter the presentation of their content.

When the end user adds a photo gallery to their post using a shortcode, they’re using the least data possible to indicate how the gallery should be presented.

Advantages:

  • No markup is added to the post content, which means that markup and styling can easily be manipulated on the fly or at a later state.
  • Shortcodes can also accept parameters, allowing users to modify how the shortcode behaves on an instance by instance basis.

As a security precaution, running PHP inside WordPress content is forbidden; to allow dynamic interactions with the content, Shortcodes were presented in WordPress version 2.5.

Shortcodes are macros that can be used to perform dynamic interactions with the content. i.e creating a gallery from images attached to the post or rendering a video.

Shortcode Best Practices

Best practices for developing shortcodes include the plugin development best practices and the list below:

Always return!
Shortcodes are essentially filters, so creating “side effects” will lead to unexpected bugs.
Prefix your shortcode names to avoid collisions with other plugins.
Sanitize the input and escape the output.
Provide users with clear documentation on all shortcode attributes.

add_shortcode( string $tag, callable $callback )

Care should be taken through prefixing or other means to ensure that the shortcode tag being added is unique and will not conflict with other, already-added shortcode tags. In the event of a duplicated tag, the tag loaded last will take precedence.

Parameters

$tag

(string) (Required) Shortcode tag to be searched in post content.

$callback

(callable) (Required) The callback function to run when the shortcode is found. Every shortcode callback is passed three parameters by default, including an array of attributes ($atts), the shortcode content or null if not set ($content) , and finally the shortcode tag itself ($shortcode_tag), in that order.

Below is an example of how the function can be used.

function add_shortcode( $tag, $callback ) {
    global $shortcode_tags;
 
    if ( '' == trim( $tag ) ) {
        $message = __( 'Invalid shortcode name: Empty name given.' );
        _doing_it_wrong( __FUNCTION__, $message, '4.4.0' );
        return;
    }
 
    if ( 0 !== preg_match( '@[<>&/\[\]\x00-\x20=]@', $tag ) ) {
        /* translators: 1: shortcode name, 2: space separated list of reserved characters */
        $message = sprintf( __( 'Invalid shortcode name: %1$s. Do not use spaces or reserved characters: %2$s' ), $tag, '& / < > [ ] =' );
        _doing_it_wrong( __FUNCTION__, $message, '4.4.0' );
        return;
    }
 
    $shortcode_tags[ $tag ] = $callback;
}

Shortcodes and the use of being able to create a function that is executed by the use of a shortcode anywhere on a website is a powerful thing. Make sure to see how you can use this function with your custom wordpress plugin.

Leave a Reply