shortcode-plugin/README.md

# Shortcodes for October CMS

Adds the ability to use shortcodes within October CMS

### Add new shortcodes

Add the shortcode in the `boot` function of a plugin.

Then, use the provided facade to add new shortcodes in your own plugins:

    \Shortcode::add('code', function(ShortcodeInterface $s) {
        $text = "<h2>Shortcode Name: {$s->getName()}</h2>";
        $text .= "<p>Shortcode Parameter: {$s->getParameter('param', 'Not Found')}</p>";
        $text .= "<p>Shortcode Content: {$s->getContent()}</p>";
        return $text;
    });

The above registration would enable the following shortcode to be used:

    [code param="Parameter Value"] Inside Content [/code]

### Use the shortcode within a page or blog post:

The usual shortcode syntax is supported:

    [code]
    [code argument="value"]
    [code novalue argument=simple other="complex value"]
    [code]content[/code]
    [code argument="value"]content[/code]

For nested shortcodes, you must call the `parse` method within the function.

### Enable shortcodes on all pages

To enable shortcodes on all page rendering, go to **Shortcode Settings** in the admin settings panel and check "Enable Shortcodes on all page rendering".

### Using filters and functions

If you don't want to enable shortcodes on all page rendering, you can use the built-in filter or function.

To use the `shortcode` filter within a blog post or page, add the `shortcode` filter before any `raw` filtering.

    <div class="cp-post-content">{{ post.content_html|shortcode|raw }}</div>

To use the `shortcode` function within a layout and against the October CMS `page` tag, change the `page` tag from a token to a function:

    {% page %}

Becomes:

    {{ shortcode(page()) }}

    -- or --

    {{ page()|shortcode }}

### Strip Shortcodes

You can strip shortcodes from text using the `Shortcode::strip` function.


    \Shortcode::strip($content);


### Dependency Issues with Service Provider and Facade

When using this plugin within another plugin, you may find that the Service Provider and/or Facade are not loaded if the dependant plugin loads prior to the Shortcode plugin.

In that case, you can either explicitly register the Shortcode plugin within the `boot` method of the plugin. For example:

    // Add Shortcode Service provider
    App::register('\Sensory5\Shortcode\Classes\ServiceProvider');

    // Add Shortcode facade
    $alias = AliasLoader::getInstance();
    $alias->alias('Shortcode', '\Sensory5\Shortcode\Classes\Facade');

Or, you can add the Service Provider and Facade into the `config/app.php` file at the root of the OctoberCMS site. For example:

    'providers' => array_merge(include(base_path().'/modules/system/providers.php'), [

        'System\ServiceProvider',
        'Sensory5\Shortcode\Classes\ServiceProvider'

    ]),

    'aliases' => array_merge(include(base_path().'/modules/system/aliases.php'), [

        'Shortcode' => 'Sensory5\Shortcode\Classes\Facade'

    ]),