KirbyTags

Default KirbyTags

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

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>';
            }
        ]
    ]
]);

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

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.