Building a Krang Add-On

Introduction

This document describes how to build Krang add-ons. The Krang add-on facility allows you to develop separate packages of code which can be installed into Krang. An add-on can supply a new element set, a new theme or even a new UI feature. Krang add-ons are separately versioned and can depend on a version of Krang or on other Krang add-ons.

Getting Started

Your first job creating a new addon is to come up with a clever name. For example, I'll create an addon which magically speeds up Krang and call it ``Turbo''. Once you've picked a name you can create a skeleton with krang_addon_framework:

   bin/krang_addon_framework --name Turbo

This command creates a directory called Turbo/ inside the addons/ directory. A single file is created there called krang_addon.conf.

How It Works

An addon's files act as an overlay on top of Krang. For example, if you create a file called templates/Story/new.tmpl in your addon then it will be used instead of the template in that location in KRANG_ROOT. The same is true for Perl modules in lib/ and the files in htdocs/.

This works well for most purposes but occaisonally you'll need something more powerful when overriding a core Krang library. For example, imagine that I created Turbo::Story which had a better find() implementation. Naturally Turbo::Story would inherit from Krang::Story since aside from the new find() Krang::Story's implementation should be used.

Krang addons support a file called conf/class.conf which supports selecting replacement of core libraries. In this case conf/class.conf inside the Turbo addon would contain:

  SetClass Story Turbo::Story

This tells Krang that wherever it would have used Krang::Story previously it should now use Turbo::Story.

An example of using class.conf is included in Krang's test set: t/addons/LazyLoader-1.00.tar.gz. This addon implements lazy-loading for Krang::Story.

krang_addon.conf

The krang_addon.conf file in an add-on directory controls many important aspects of the add-on's operation. The file follows the same Apache-inspired format as Krang's krang.conf file. I'll explain each available directive.

Building an Addon Distribution

In order for other people to install your addon you need to build an addon distribution. This is done with the krang_addon_dist script:

  bin/krang_addon_dist Turbo

This command creates a tar-ball called Turbo-1.00.tar.gz from the source in addons/Turbo/.

Installing an Addon

Installing a Krang addon is done using the krang_addon_installer on an addon file:

  bin/krang_addon_installer Turbo-1.00.tar.gz

For more details see the krang_addon_installer help:

  bin/krang_addon_installer --help

Upgrades

Krang add-ons support the same upgrade facility as Krang. This means you can include an 'upgrade/' directory with standard Krang::Upgrade modules. For example, if Turbo-1.01 is released and must make changes to the database or filesystem then a file called 'upgrade/V1_01.pm' must be created. This file may contain code to run on a per-installation or per-instance basis, just like other Krang upgrade scripts.

Krang's upgrade system is described in the Upgrade System document.