Learn how to create your own Kirbytags and add filters to further extend content.
Kirbytext — Kirby's extension of Markdown — comes with a set of helpful tags, which editors can use to add links, include images, embed videos and much more.
To make it even easier for your editors to create content and format text Kirbytext can be further extended with your own custom tags and rules.
Custom Kirbytags are installed in /site/tags
. Each tag gets its own PHP file.
The most simple form of a Kirbytag looks like this
<?php
kirbytext::$tags['wikipedia'] = array(
'html' => function($tag) {
return '<a href="http://wikipedia.org">Wikipedia</a>';
}
);
You can invoke this by using the following tag in Kirbytext
(\wikipedia: somevalue)
The tag is pretty stupid though. It will only generate a link to Wikipedia with a link text called Wikipedia. It completely ignores the value of the tag so far.
To make use of the entered value the $tag object has an $tag->attr($attr)
method, which can be used to fetch the value of any attribute of the tag.
<?php
kirbytext::$tags['wikipedia'] = array(
'html' => function($tag) {
return '<a href="http://wikipedia.org/wiki/' . $tag->attr('wikipedia') . '">Wikipedia</a>';
}
);
Now the tag will fetch the wikipedia
attribute and pass the value to the link. The tag is now able to link to any article on Wikipedia:
(\wikipedia: Content_Management_System)
It's very easy to add more attributes to make the tag even smarter. An additional attr
array defines which attributes are allowed within the tag. You don't have to define the main attribute though.
<?php
kirbytext::$tags['wikipedia'] = array(
'attr' => array(
'text'
),
'html' => function($tag) {
$url = 'http://wikipedia.org/wiki';
$article = $tag->attr('wikipedia');
$text = $tag->attr('text', 'Wikipedia');
return '<a href="' . $url . '/' . $article . '">' . $text . '</a>';
}
);
You can now pass a text attribute to the tag and it will be used to build the link text.
(\wikipedia: cat text: Read all about cats…)
Another great feature of the $tag->attr()
method is the fallback value, which makes it possible to react on missing or empty attributes and still provide some useful alternative.
$text = $tag->attr('text', 'Wikipedia');
// if no text is given, the link text will be 'Wikipedia'
Just like in this example, tags can be very simple and generate something like a link. But of course you can extend this to generate entire galleries, tables, download lists or whatever you need.
For some tags it might be necessary to access the current page or files of the current page. The $tag
object has three methods to help you with this:
$tag->page()
$tag->files()
$tag->file('myfile.jpg')
We can make use of this to create a simple download list tag.
<?php
kirbytext::$tags['downloads'] = array(
'html' => function($tag) {
$html = '<h2>' . $tag->attr('downloads') . '</h2>';
$html .= '<ul>';
foreach($tag->page()->documents() as $doc) {
$html .= '<li>';
$html .= '<a href="' . $doc->url() . '">' . $doc->filename() . '</a>';
$html .= '</li>';
}
$html .= '</ul>';
return $html;
}
);
…which can be embedded in the text like this:
(downloads: Download documents)
This could be easily extended with more attributes/options to limit the number of files or download a different type of files, etc.
Besides additional Kirbytags, Kirbytext has another option to be extended with filters. You can apply a pre and post filter, which will be called before or after tags and markdown are being parsed.
The best place to add those filters is in plugins.
In this section we are going to create a very simple text snippet replacement plugin. The plugin will make it possible to define text snippets in the config file, which can be triggered with simple placeholders in Kirbytext.
Placeholder | Snippet |
---|---|
{{email}} | bastian@getkirby.com |
{{lorem}} | Lorem ipsum dolor sit amet… |
The definition of text snippets in /site/config/config.php
will look like this:
c::set('kirbytext.snippets', array(
'email' => 'bastian@getkirby.com',
'lorem' => 'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.',
));
The placeholders should be replaced before Markdown or Kirbytags are being parsed. That makes it possible to use the placeholders in Markdown and Kirbytext. So we are going to define a pre
filter for Kirbytext.
// filters which are called BEFORE markdown and tags are parsed
kirbytext::$pre[] = function($kirbytext, $value) {
// your filter code
return $value;
};
// filters which are called AFTER markdown and tags are parsed
kirbytext::$post[] = function($kirbytext, $value) {
// your filter code
return $value;
};
The code for our pre filter is pretty straight forward. We are fetching the array with placeholders and text from the config file with c::get('kirbytext.snippets')
. Afterwards we do a simple str_replace
on the Kirbytext value to replace all placeholders with the defined text snippets.
<?php
kirbytext::$pre[] = function($kirbytext, $value) {
$snippets = c::get('kirbytext.snippets', array());
$values = array_values($snippets);
$keys = array_map(function($key) {
return '{{' . $key . '}}';
}, array_keys($snippets));
return str_replace($keys, $values, $value);
};
This plugin shows quite well how simple it is to write helpful extensions for Kirbytext, which will massively benefit your editors. There's hardly any limitation how to go forward and extend it even more.