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.
How to use your own KirbyTag
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
<?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
<?php
Kirby::plugin('your/plugin', [
'tags' => [
'wikipedia' => require_once __DIR__ . '/tags/wikipedia.php'
]
]);
And then in /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.
<?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
<?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
<?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.