


$text = "<h1>My Map</h1>[map]"

// Will output
// <h1>My Map</h1><iframe ..></iframe>

Here's some syntax variations:

[my_shortcode /]
[my_shortcode,myparameter="value"]Enclosed Content[/my_shortcode]

Shortcodes are automatically parsed on any database field which is declared as HTMLValue or DBHTMLText, when rendered into a template. This means you can use shortcodes on common fields like SiteTree.Content, and any other DataObject::$db definitions of these types.

Other fields can be manually parsed with shortcodes through the parse method.

use SilverStripe\View\Parsers\ShortcodeParser;

$text = "My awesome [my_shortcode] is here.";

Defining Custom Shortcodes

First we need to define a callback for the shortcode.


use SilverStripe\CMS\Model\SiteTree;

class Page extends SiteTree 
    private static $casting = [
        'MyShortCodeMethod' => 'HTMLText'

    public static function MyShortCodeMethod($arguments, $content = null, $parser = null, $tagName) 
        return "<em>" . $tagName . "</em> " . $content . "; " . count($arguments) . " arguments.";

These parameters are passed to the MyShortCodeMethod callback:

  • The ShortcodeParser instance used to parse the content.
  • An associative array of extra information about the shortcode being parsed. For example, if the shortcode is is inside an attribute, the element key contains a reference to the parent DOMElement, and the node key the attribute's DOMNode.

To register a shortcode you call the following.


// ShortcodeParser::get('default')->register($shortcode, $callback);

ShortcodeParser::get('default')->register('my_shortcode', ['Page', 'MyShortCodeMethod']);

Built-in Shortcodes

SilverStripe comes with several shortcode parsers already.




Links to internal File database records work exactly the same, but with the [file_link] shortcode.

<a href="[file_link,id=99]">


Images inserted through the "Insert Media" form (WYSIWYG editor) need to retain a relationship with the underlying Image database record. The [image] shortcode saves this database reference instead of hard-linking to the filesystem path of a given image.

[image id="99" alt="My text"]

Media (Photo, Video and Rich Content)


Since TinyMCE can't represent all these variations, we're showing a placeholder instead, and storing the URL with a custom [embed] shortcode.

[embed width=480 height=270 class=left thumbnail=]

Attribute and element scope

HTML with unprocessed shortcodes in it is still valid HTML. As a result, shortcodes can be in two places in HTML:

  • In an attribute value, like so: <a title="[title]">link</a>
  • In an element's text, like so: <p>Some text [shortcode] more text</p>

The first is called "element scope" use, the second "attribute scope"

You may not use shortcodes in any other location. Specifically, you can not use shortcodes to generate attributes or change the name of a tag. These usages are forbidden:

<[paragraph]>Some test</[paragraph]>

<a [titleattribute]>link</a>

You may need to escape text inside attributes > becomes &gt;, You can include HTML tags inside a shortcode tag, but you need to be careful of nesting to ensure you don't break the output.

<!-- Good -->

<!-- Bad: -->



Element scoped shortcodes have a special ability to move the location they are inserted at to comply with HTML lexical rules. Take for example this basic paragraph tag:

<p><a href="#">Head [figure,src="assets/a.jpg",caption="caption"] Tail</a></p>

When converted naively would become:

<p><a href="#">Head <figure><img src="assets/a.jpg" /><figcaption>caption</figcaption></figure> Tail</a></p>

However this is not valid HTML - P elements can not contain other block level elements.

To fix this you can specify a "location" attribute on a shortcode. When the location attribute is "left" or "right" the inserted content will be moved to immediately before the block tag. The result is this:

<figure><img src="assets/a.jpg" /><figcaption>caption</figcaption></figure><p><a href="#">Head  Tail</a></p>

When the location attribute is "leftAlone" or "center" then the DOM is split around the element. The result is this:

<p><a href="#">Head </a></p><figure><img src="assets/a.jpg" /><figcaption>caption</figcaption></figure><p><a href="#"> Tail</a></p>

Parameter values

Here is a summary of the callback parameter values based on some example shortcodes.

public function MyCustomShortCode($arguments, $content = null, $parser = null, $tagName) 
    // ..
$attributes     => [];
$content         => null;
$parser         => ShortcodeParser instance,
$tagName         => 'my_shortcode')
$attributes      => ['attribute'  => 'foo', 'other'      => 'bar']
$enclosedContent => null
$parser          => ShortcodeParser instance
$tagName         => 'my_shortcode'
$attributes      => ['attribute' => 'foo']
$enclosedContent => 'content'
$parser          => ShortcodeParser instance
$tagName         => 'my_shortcode'




The parser will raise an error if it can not find a matching opening tag for any particular closing tag

Related Documentation

API Documentation