Shortcodes

As of version 1.5.1 Typemill supports shortcodes. Shortcodes are small snippets that an author can add to a markdown-page. Shortcodes are a super easy and smart way to add any kind of content or feature to a page. The syntax of a shortcode looks like this:

[:shortcodename param1="myvalue" param2="anothervalue" :]

When the markdown is transformed into html, then Typemill will look for such shortcodes and fire the event onShortcodeFound. You can listen to that event, analyse the params of the shortcode and then return any kind of content or feature as HTML.

#Example 1: Replacement Shortcode

Let us quickly create the shortcode [:replace:] that gets replaced with some html. The plugin looks like this:

<?php

namespace Plugins\replace;

use \Typemill\Plugin;

class replace extends Plugin
{

  protected $settings;

  # subscribe to the shortcode event
  public static function getSubscribedEvents()
  {
    return array(
      'onShortcodeFound' => 'onShortcodeFound'
    );
  }

  # listen, when typemill found a shortcode and fires the event
  public function onShortcodeFound($shortcode)
  {
    # read the data of the shortcode
    $shortcodeArray = $shortcode->getData();

    # check if it is the shortcode name that we where looking for
    if($shortcodeArray['name'] == 'replace')
    {
      # and return a html-snippet that replaces the shortcode on the page.
      $shortcode->setData('<span class="tm-green">A replacement from the plugin</span>');
    }
  }
}

Just read the code with the comments and you will easily understand:

  • We subscribe to the event onShortcodeFound.
  • Typemill finds a shortcode and fires the event.
  • We listen to that event and check the name of the shortcode.
  • If the shortcode has the name we where looking for, then we simply return some html.

Now the author can insert the shortcode [:replace:] to the markdown of a page and he will see the replacement from your plugin.

#Example 2: Replace with params

So far so good, but we can make it much more useful. Let us now replace the shortcode and use a text with a color. We need the two params text and color for that so a shortcode might look like this:

[:replace text="I am a red text" color="red":]

In our plugin we can now return the text with the color like this:

<?php

namespace Plugins\replace;

use \Typemill\Plugin;

class replace extends Plugin
{

  protected $settings;

  # listen to the shortcode event
  public static function getSubscribedEvents()
  {
    return array(
      'onShortcodeFound' => 'onShortcodeFound'
    );
  }

  # if typemill found a shortcode and fires the event
  public function onShortcodeFound($shortcode)
  {
    # read the data of the shortcode
    $shortcodeArray = $shortcode->getData();

    # check if it is the shortcode name that we where looking for
    if($shortcodeArray['name'] == 'replace')
    {
      # Of course you should validate the user input here, but let us skip it to keep it easy ...
      $text = isset($shortcodeArray['params']['text']) ? $shortcodeArray['params']['text'] : 'Fallback text';
      $color = isset($shortcodeArray['params']['color']) ? $shortcodeArray['params']['color'] : 'green';
      $html = '<span style="color:' . $color . ';">' . $text . '</span>';

      # and return a html-snippet that replaces the shortcode on the page.
      $shortcode->setData($html);
    }
  }
}

That is all you need to know to create a new shortcode and extend the content area with anything you can imagine. In this simple case we only change the color of a text. If you want to see a more complex shortcode, then you can check the plugin ebookproducts. With that plugin, the user can create multiple product-boxes for eBooks and insert a product box with a shortcode into any page .

Typemill is an open source software and a registered trademark. Read more