Registering Shortcodes - 3ev/wordpress-core GitHub Wiki

Registering Shortcodes with Wordpress Core provides a better separation of concerns than Wordpress's built in add_shortcode() method. You are given the option of using a full PHP class for your shortcode, as well as a separate view file.

###The config file

Your plugin's shortcodes should all be registered in the config/shortcodes.php PHP file inside your plugin's root folder. This file should return a simple PHP hash, with each key being a shortcode identifier and each value being either a fully-qualified class name of a shortcode provider, or an inline callback function.

An example file might look like:

<?php

return array(

    'myshortcode' => 'MyPluginVendor\Shortcode\MyShortcodeProvider',

    'myothershortcode' => function ($attrs, $content, $renderer) {
        // Render shortcode here
    }
);

###Using a shortcode provider

The recommended way of registering a shortcode is to use a shortcode provider class. A shortcode provider is a PHP class that extends Tev\Plugin\Shortcode\AbstractProvider. The provider at a minimum needs to provide a shortcode() method, which accepts two parameters:

• $attrs: Hash of passed shortcode attributes
• $content: Shortcode content

$attrs and $content should be familiar if you've used add_shortcode(), as they mirror the parameters passed to its callback function exactly.

An example of a provider is:

config/shortcodes.php:

<?php

return array(

    'myshortcode' => 'MyPluginVendor\Shortcode\MyShortcodeProvider'
);

src/MyPluginVendor/Shortcode/MyShortcodeProvider.php:

<?php
namespace MyPluginVendor\Shortcode;

use Tev\Plugin\Shortcode\AbstractProvider;

class MyShortcodeProvider extends AbstractProvider
{
    public function shortcode($attrs, $content)
    {
        // The DI container is accessible at $this->app

        return $this->renderer->render('my-shortcode.phtml', array(
            'colour'  => isset($attrs['colour']) ? $attrs['colour'] : 'red',
            'content' => $content
        ));
    }
}

As you can see from the example, the DI container is available at $this->app. Also, notice the $this->renderer object.

###The view renderer

The $renderer variable is a simple PHP renderer that will render content from a PHP file in a configured directory, and return it as a string. The view renderer available on the provider class is configured to load views from the src/views/ in your plugin's root dir.

To a render a view, you simply call the render() method. This method accepts two parameters; the first is the path to the .phtml view, and the second is an optional hash of variables to pass to the view.

###Using a callback function

Although it's recommended to use a provider class, you can also register a shortcode inline with a callback function. The callback function will be passed $attrs, $content and $renderer parameters which mimic the functionality available to the provider classes.

For example:

config/shortcodes.php:

<?php

return array(

    'myshortcode' => function ($attrs, $content, $renderer) {
        return $renderer->render('my-shortcode.phtml', array(
            'colour'  => isset($attrs['colour']) ? $attrs['colour'] : 'red',
            'content' => $content
        ));
    }
);

Note: You can use the DI container with via the tev_app() helper.