title: Shortcodes
summary: Flexible content embedding
# Shortcodes
The [ShortcodeParser](api:SilverStripe\View\Parsers\ShortcodeParser) API is simple parser that allows you to map specifically formatted content to a callback to
transform them into something else. You might know this concept from forum software which don't allow you to insert
direct HTML, instead resorting to a custom syntax.
In the CMS, authors often want to insert content elements which go beyond standard formatting, at an arbitrary position
in their WYSIWYG editor. Shortcodes are a semi-technical solution for this. A good example would be embedding a 3D file
viewer or a Google Map at a certain location.
```php
$text = "
My Map
[map]"
// Will output
//
My Map
```
Here's some syntax variations:
```php
[my_shortcode]
#
[my_shortcode /]
#
[my_shortcode,myparameter="value"]
#
[my_shortcode,myparameter="value"]Enclosed Content[/my_shortcode]
```
Shortcodes are automatically parsed on any database field which is declared as [HTMLValue](api:SilverStripe\View\Parsers\HTMLValue) or [DBHTMLText](api:SilverStripe\ORM\FieldType\DBHTMLText),
when rendered into a template. This means you can use shortcodes on common fields like `SiteTree.Content`, and any
other [DataObject::$db](api:SilverStripe\ORM\DataObject::$db) definitions of these types.
Other fields can be manually parsed with shortcodes through the `parse` method.
```php
$text = "My awesome [my_shortcode] is here.";
ShortcodeParser::get_active()->parse($text);
```
## Defining Custom Shortcodes
First we need to define a callback for the shortcode.
**mysite/code/Page.php**
```php
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 "" . $tagName . " " . $content . "; " . count($arguments) . " arguments.";
}
}
```
These parameters are passed to the `MyShortCodeMethod` callback:
- Any parameters attached to the shortcode as an associative array (keys are lower-case).
- Any content enclosed within the shortcode (if it is an enclosing shortcode). Note that any content within this
will not have been parsed, and can optionally be fed back into the parser.
- The ShortcodeParser instance used to parse the content.
- The shortcode tag name that was matched within the parsed 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.
**mysite/_config.php**
```php
// 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
Internal page links keep references to their database IDs rather than the URL, in order to make these links resilient
against moving the target page to a different location in the page tree. This is done through the `[sitetree_link]`
shortcode, which takes an `id` parameter.
```php
```
Links to internal `File` database records work exactly the same, but with the `[file_link]` shortcode.
```php
```
### Images
Images inserted through the "Insert Media" form (WYSIWYG editor) need to retain a relationship with
the underlying `[Image](api:SilverStripe\Assets\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)
Many media formats can be embedded into websites through the `