lars/wordpress-shortcode-loader

v1.0.1 2017-07-17 13:57 UTC

README

This package extends a theme with an automatic shortcode loader.

Installation

Execute the following command in the theme folder to initialise the loader:

composer require lars/wordpress-shortcode-loader

Then add the following line at the first row of your functions.php (after <?php):

require(__DIR__ . '/vendor/autoload.php');

The Wordpress Shortcode Loader has been configured and loaded. The first time you start the website, it will generate the folder App/Shortcodes/ in your theme folder. You may also create this folder yourself.

Configure a shortcode

Create a PHP file in the App/Shortcodes/ called ExampleShortcode.php if your are creating the Example shortcode.

We will generate a minimal hello world shortcode in this readme. Include the following into ExampleShortcode.php:

<?php

namespace App\Shortcodes;

use Lars\Shortcodes\Shortcode;

class ExampleShortcode extends Shortcode
{
    /**
     * Mandatory string defining the shortcode.
     *
     * @var string
     */
    protected static $shortcode = 'example_shortcode';

    /**
     * Mandatory handle function which is called after validating and sanitizing the attributes.
     * In this function, it is allowed to echo data to the screen, but it is recommended to use Blade.
     *
     * @param $attributes
     * @param $content
     * @param $tag
     */
    public static function handle($attributes, $content, $tag)
    {
        echo 'Hello World!';
    }
}

When the file has been saved, the shortcode will work. So in this case, you can use [example_shortcode] and it will be replaced with Hello World!.

Using attributes

When you want to use attributes, you need to define those in the class, like this:

...
class ExampleShortcode extends Shortcode
{
    /**
     * Mandatory array defining the parameters that are allowed and (optionally) required.
     * This array is also used for validation. Validation is done by GUMP.
     *
     * @var array
     */
    protected static $parameters = [
        'id' => 'required',
        'email' => 'required|valid_email'
    ];
    
    /**
     * Mandatory array defining the sanitation of the parameters, minimum is ''.
     * Uses GUMP.
     * Default: []
     *
     * @var array
     */
    protected static $inputSanitizer = [
        'id' => 'trim',
        'email' => 'trim|sanitize_email'
    ];
...

In this example, an id and email attribute are created. Both fields are required and email should be a valid email address. All validation rules can be found at the GUMP documentation.

Parameters must be sanitized, recommended is to always include 'trim', but '' is the minimum. All sanitizers can be fount at the GUMP documentation.

Using the handle function

When a shortcode is executed, the attributes are validated and sanitized. After that, the handle function is called.

...
class ExampleShortcode extends Shortcode
{
...
    /**
     * Mandatory handle function which is called after validating and sanitizing the attributes.
     * In this function, it is allowed to echo data to the screen, but it is recommended to use Blade.
     *
     * @param $attributes
     * @param $content
     * @param $tag
     */
    public static function handle($attributes, $content, $tag)
    {

    }
...

The handle functions gives you the attributes as an array ($attributes['id']), the content between the tags as string and the tag as string. You can use the content when rendering if you'd like to add other HTML around the content.

Enabling the shortcode

The enabled property enables you to (temporary) disable a shortcode.

...
class ExampleShortcode extends Shortcode
{
...
    /**
     * Optional boolean defining if the shortcode should be loaded.
     * Default: true
     *
     * @var bool
     */
    protected static $enabled = false;

...

Contributing

Do you want to contribute? Please, create a pull request. I'm always open to feedback and improvements.