Kirby

Blog (RSS)

News about Kirby and stuff

Follow kirby on Twitter
@getkirby for more
updates.

Tags

Extending Kirbytext

Kirby has a built in formatting language called Kirbytext. Kirbytext is an extension of John Gruber's Markdown.

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Kirbytext combines all the features of Markdown with a set of Kirby-specific tags to make it easier to build links or embed videos and images for example.

With the latest release it is now possible to extend Kirbytext and add your own tags, which you can use as shortcuts in your content.

Anatomy of a Kirbytag

Tags in Kirbytext look like this:

(tag: some value attribute1: foo attribute2: bar)

Here's an example:

(youtube: http://www.youtube.com/watch?v=d9NF2edxy-M width: 300 height: 200) 

The Kirbytext Plugin

To extend the core Kirbytext class and to add your own tags you need to add a new file to your site/plugins folder, called kirbytext.extended.php. If the plugins folder does not exist yet, simply create it now. Kirby will take care of loading your custom Kirbytext file and extend the core class.

The skeleton

The basic structure of the Kirbytext plugin must be followed. Otherwise the extension won't work.

<?php 

class kirbytextExtended extends kirbytext {
 
  function __construct($text, $markdown=true) {
   
    parent::__construct($text, $markdown);
   
    /*  

    // define custom tags
    $this->addTags('mynewtag');
   
    // define custom attributes
    $this->addAttributes('mynewattribute');    
   
    */

               
  }  

  /*
 
  // define a function for each new tag you specify  
 
  function mynewtag($params) {
    // do something with the passed params here.
  }
 
  */

 
}

?>

You can also find this template for the Kirbytext plugin on Github.

A new Wikipedia tag

For this tutorial I'm going to add a new Wikipedia tag, which will make it possible to link to Wikipedia articles very quickly. The final Kirbytag will look like this:

(wikipedia: Twitter)

… and it will produce a full link to the Wikipedia article about Twitter. There will be some bells and whistles, but I will get back to that later.

Defining a custom tag

To define the new wikipedia tag, we are going to add it in the __construct() method of our Kirbytext plugin class and we will also add a new method with the same name, which will later handle the given parameters and build the output.

class kirbytextExtended extends kirbytext {

  function __construct($text, $markdown=true) {
   
    parent::__construct($text, $markdown);
   
    // define custom tags
    $this->addTags('wikipedia');
               
  }  

  function wikipedia($params) {

  }

}

The wikipedia() method

Our new wikipedia method will be called whenever a (wikipedia: …) tag is found in your content. The $params argument contains an array with all values, specified in the wikipedia tag.

If the tag is…

(wikipedia: Twitter)

$params will be …

array(
  'wikipedia' => 'Twitter'
)  

If some attributes are available…

(wikipedia: Twitter text: Lookup Twitter on Wikipedia language: de)

$params will be …

array(
  'wikipedia' => 'Twitter',
  'text'      => 'Lookup Twitter on Wikipedia',
  'language'  => 'de'
)

This makes it very easy to generate output based on the given values:

function wikipedia($params) {
 
  $search = $params['wikipedia'];
  $url    = 'http://en.wikipedia.org/w/index.php?search=' . urlencode($search);
 
  return '<a class="wikipedia" href="' . $url . '">' . html($search) . '</a>';    
   
}

The custom tag methods always must return the final HTML. Echoing it will not work.

Working with attributes

The example above will work fine, but it can only handle a simple tag without attributes:

(wikipedia: Twitter)

Specifying a custom link text instead of just the article title would be cool and it would also be nice to select which language version of Wikipedia should be linked. I already mentioned this example above, but here's the final tag again:

(wikipedia: Twitter text: Lookup Twitter on Wikipedia language: de)

The core Kirbytext class already has a text attribute defined, so we don't need to add that. But the language attribute is new. If we don't define it, the entire tag will not be recognized. It is done in the same way as defining tags.

function __construct($text, $markdown=true) {
 
  parent::__construct($text, $markdown);
 
  // define custom tags
  $this->addTags('wikipedia');

  // define custom attributes
  $this->addAttributes('language');
             
}

The code for the wikipedia method is just slightly more sophisticated. When working with attributes it makes sense to define default values, so it will be optional to add them to the tag or not. I'm using a similar way to handle params and default values here as in jQuery plugins. Defining an array of default values first and then merging it with the given parameters produces some nice clean code IMHO. But it's up to you how you handle this.

function wikipedia($params) {
   
  $search = $params['wikipedia'];

  // define default values for attributes
  $defaults = array(
    'language' => 'en',
    'text'     => $search
  );
 
  // merge the given parameters with the default values
  $options = array_merge($defaults, $params);

  // build the final url
  $url = 'http://' . $options['language'] . '.wikipedia.org/w/index.php?search=' . urlencode($search);

  // build the link tag  
  return '<a class="wikipedia" href="' . $url . '">' . html($options['text']) . '</a>';    
   
}

The result

Here's the final result for our little Wikipedia example:

<?php 

class kirbytextExtended extends kirbytext {
 
  function __construct($text, $markdown=true) {
   
    parent::__construct($text, $markdown);
   
    // define custom tags
    $this->addTags('wikipedia');
    $this->addAttributes('language');
                   
  }  

  function wikipedia($params) {
     
    $search = $params['wikipedia'];
 
    // define default values for attributes
    $defaults = array(
      'language' => 'en',
      'text'     => $search
    );
   
    // merge the given parameters with the default values
    $options = array_merge($defaults, $params);
 
    // build the final url
    $url = 'http://' . $options['language'] . '.wikipedia.org/w/index.php?search=' . urlencode($search);
 
    // build the link tag  
    return '<a class="wikipedia" href="' . $url . '">' . html($options['text']) . '</a>';    
     
  }

}

?>

I hope this example shows how easy it is to build your own Kirbytags. I'm excited to see what you are building with it. Feel free to submit your custom implementations. I'd be happy to add them to the Downloads section and share them with other Kirby users.

‹ Back

blog comments powered by Disqus