KirbyTags

Default KirbyTags

Kirby comes with a set of default KirbyTags for things like including images, links, dates or videos into text fields. See the full list of included KirbyTags.

You can create and use a tag like (wikipedia:) in text fields. For this to work, you have to include a function ->kirbytext() for every field in the template that you wish should support this tag. You can also use KirbyTags directly in your templates. See parsing KirbyTags in your text.

How to create your own KirbyTag

/site/plugins/your-plugin/index.php

<?php

Kirby::plugin('your/plugin', [
    'tags' => [
        'wikipedia' => [
            'html' => function($tag) {
                return '<a href="http://wikipedia.org">Wikipedia</a>';
            }
        ]
    ]
]);

Because of a limitation in Parsedown, the Markdown parser currently used by Kirby, the HTML code you return from your tag should not contain extraneous whitespace, e.g. a line break directly after the tag name of an HTML tag. Otherwise your tag output may be escaped by Parsedown.

If your tag output is messed up, please check if your returned HTML code contains code like this:

<figure
  class="something"
>

Outsourcing code to separate file

/site/plugins/your-plugin/index.php

<?php

Kirby::plugin('your/plugin', [
    'tags' => [
        'wikipedia' => require_once __DIR__ . '/tags/wikipedia.php'
    ]
]);

And then in /tags/wikipedia.php

/site/plugins/your-plugin/tags/wikipedia.php

<?php

return [
    'html' => function($tag) {
        return '<a href="http://wikipedia.org">Wikipedia</a>';
    }
];

Overriding default KirbyTags

You can override Kirby's default KirbyTags by creating a plugin with the same KirbyTag name as the original.

/site/plugins/your-plugin/index.php

<?php

Kirby::plugin('your/plugin', [
    'tags' => [
        'image' => [
            'attr' => [
                // list of attributes
            ],
            'html' => function($tag) {
                // your code here
            }
        ]
    ]
]);

Adding attributes

If you want to add attributes (e.g. (wikipedia: class: my-class)), you can add them as an attr array like this:

<?php

Kirby::plugin('your/plugin', [
  'tags' => [
    'wikipedia' => [
      'attr' => [
        'class'
      ],
      'html' => function($tag) {
        return '<a class="' . $tag->class . '" href="http://wikipedia.org">Wikipedia</a>';
      }
    ]
  ]
]);

Accessing attributes and Kirby objects

The properties of the $tag object can be accessed like this:

The tag's value

$tag->value
// return the value of the tag

Attributes

// the class attribute
$tag->class

// the width attribute
$tag->width

Array of all used attributes

$tag->attrs

The parent page object

$tag->parent()

Files

// all files of the page
$tag->parent()->files()

// a single file by name
$tag->parent()->file('content.jpg')

Options

$tag->option('some.option')

The KirbyTag type

$tag->type()
// returns the name of the KirbyTag

KirbyTag hooks

In addition to your own KirbyTag plugins, you can also hook into the KirbyTags parser. This is very useful if you want to parse the text before or after the KirbyTags parser kicks in with additional regular expressions for example.

`kirbytags:before`

/site/plugins/your-plugin/index.php

<?php

Kirby::plugin('your/plugin', [
    'hooks' => [
        'kirbytags:before' => function ($text, array $data = [], array $options = []) {

            // KirbyTags have not been parsed

            $text = preg_replace_callback('/some-regex/', function () {
                // whatever you want to replace
            }, $text);

            return $text;
        }
    ]
]);

`kirbytags:after`

/site/plugins/your-plugin/index.php

<?php

Kirby::plugin('your/plugin', [
    'hooks' => [
        'kirbytags:after' => function ($text, array $data = [], array $options = []) {

            // KirbyTags have already been parsed

            $text = preg_replace_callback('/some-regex/', function () {
                // whatever you want to replace
            }, $text);

            return $text;
        }
    ]
]);

Reusing parts of existing KirbyTags

You can also reuse parts of the original KirbyTag in your custom tags.