Skip to content
Carver Plugin for Kirby 3
Branch: master
Clone or download
Latest commit bf940da Mar 24, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.

Kirby Carver

What it does

This plugin allows you to write custom HTML tags, powered by PHP.


Kirby is most awesome, but I do miss the simplicity of Textpattern's templating language, which looks like HTML. Having gone through available alternative templating engines like Twig and Blade, without much love, I decided to put this together.

For example, to get the a formatted date from a field, normally you would do something like this:

<time class="mytime">
  <?php echo $page->date()->toDate('d/m/Y') ?>

What if you could do this instead?

<kb:date format="d/m/Y" field="date" wraptag="time" class="mytime" />

You can find some example tags in site/plugins/carver/library


  • Download the files and place in plugins/carver
  • Create a folder called carver under the site folder. This is where you tags will be stored.


Let's create a simple tag as an example to show what this can do, based on the date tag mentioned above.

Start by creating the following file: 'site/carver/date/tag.php'.

Add this code to the file:

	function kb_date($tag)
		// Get the attributes
		$att = json_decode(json_encode($tag['attributes']), true);

		// Deal with the attributes
		$format 	= isset($att['format']) ? $att['format'] : 'd/m/Y';
		$wraptag 	= isset($att['wraptag']) ? $att['wraptag'] : 'p';
		$class 		= isset($att['class']) ? $att['class'] : '';

		// Get the field date or use todays date if its not set or cant be found
		$dateval = isset($att['field']) ? page()->{$att['field']}()->toDate($format) : date($format);

		return Html::tag($wraptag, $dateval, ["class" => $class]);


Let's explain how that works. Our tag looks like this:

<kb:date format="d/m/Y" field="date" wraptag="time" class="mytime" />

It has three custom attributes, format, field and class.

If you use that in your template right now, you will get this rendered, assuming you have a date field set in your blueprint with a value stored:

<time class="mytime">02/02/2019</time>

Pretty self explanatory, you can set the field to use, the class to give the output, and the date format to use. But thats not all - you can skip some of the attributes because fallbacks have been set.

Doing this in a template will use todays date instead, format it to 'd/m/Y', and without adding a class:

<kb:date />

Will result in this:


More tag examples

<!-- Render a gist -->
<kb:gist url="" />

<!-- Render a youtube video -->
<kb:youtube url="" width="100%" height="450px" autoplay="1" loop="1" />

<!-- Render a vimeo video -->
<kb:vimeo url="" width="100%" height="450px" autoplay="1" loop="1" autopause="0" />

<!-- Render an iframe -->
<kb:iframe url="" width="100%" height="400px" wraptag="div" class="iframecontent" wrapclass="iframecontainer" />

<!-- Render a link -->
<kb:a href="" class="mylink" rel="nofollow" />

<!-- Title -->
<kb:title field="title" wraptag="h1" />

<!-- Kirbytext from a field -->
<kb:kt field="text" />

<!-- Obfusifcated Email Link -->
<kb:email field="email" text="Email us today" class="mail" />

<!-- Images from a field, wrapped in a container tag and items wrapped in a tag each -->
<kb:images class="images" file="gallery" wraptag="ul" breaktag="li" />

<!-- Single image by name -->
<kb:image class="myimage" file="lw31n7hd1i.jpg" />

<!-- Handle a missing image gracefully -->
<kb:image class="myimage" file="lw31n7hsdfsdfd1i.jpg" />

Road Map

  • Bring tag parser up to date
  • Refactor tag parser to allow for options to be set via config
  • Create a big library of built in tags that work with Kirby's built in functions.
  • Composer support


When I am not using Kirby, I am using Textpattern. Sadly, Dean Allen, who created Textpattern died about a year ago. His philosophy of simplicity in a CMS aligns with that of Kirby, and this plugin is in his honour.

You can’t perform that action at this time.