Knowledgeroot Project Page

(Last modified by ookami on 18.03.2010 10:17:52)

Knowledgeroot Extension Interface

last change: 4. November 2007

This documentation is directed at those writing extensions to knowledgeroot. The Extension Interface was introduced in version 0.9.8, so you need a version later than 0.9.8-dev.

The extension interface eases the inclusion of new features, or enabling/disabling of existing ones.

1. Create folders and files

All extensions are located in the folder "system/extension". Each extension requires its own subfolder. This folder must be named like your extension! You have to arrange for the following 5 files in this folder: "info.php", "install.php", "language.php", "config.php" and the extension's php class. This last file must be named after your extensionname in the following fashion: "class-extensionname.php". Example: your extension is called "testextension", the filename should read "class-testextension.php".

1.1 info.php

First, we will take a look at info.php.

$CONF = array (
	"title" => "title for my extension",
	"description" => "discription for my extension",
	"version" => "0.1",
	"dependencies" => "",
	"state" => "devel",
	"author" => "your name",
	"author_email" => "your@name.tld",
	"author_company" => "your company",
);
?>

info.php contains an array with a detailed discription of your extension. It is crucial to name the variable $CONF. dependencies to other extensions must be listed in the corresponding field "dependencies". List elements are separated by commas.

1.2 install.php

This file is needed for clean installation and updates of your extension! It declares whether your extension is an adminextension, its current version and the version history. Here is an example:

$CONF = array(
	"admin" => 0,
	"version" => "0.2",
	"version_history" => "0.1;0.2",
);

Setting "admin" to 1 turns your extension into an Adminextension. The current version is noted in "version", and "version_history" takes a list of all prior versions, up to and including the current, seperated by ";".

So what is this for? If your extension maintains own tables and a version modifies their layout, this is nessecary to seamlessly upgrade from any older version to the current!

1.3 config.php

This file supplies a default configuration setting for your extension. It is defined in the variable $CONF. An example, with a single configuration value:

$CONF = array (
	"myconf" => "myvalue",
);
?>

Your extension class retrieves values from this configuration using:

$this->CONF['myconf']

Users can override your default settings by editing the config file ./config/config.inc.php. They should not modify your provided default file.

Here is an example how to override the default myconf value from the example above:

$CONF['ext']['extensionname']['myconf'] = "my new value";

Your extension code need not be modified to see the replaced value.

1.4 language.php

This file contains the translated phrases for all languages your extension supports. The translations are arranged in a multi-dimensional array, as shown in the following example:

$LANG = array(
		'de' => array(
			'translateme' => 'Übersetzung',
		),
		
		'en' => array(
			'translateme' => 'translation',
		),
	);

?>

This array must be called $LANG! Its elements are language tags pointing to arrays of translations. Tags should look like, for example, de for German or en for English. The translation array the tag points to, consists of simple (keyword, value) pairs. The keywords should cover all phrases to translate in your extension code, and their value is, of course, the translated item.

OK. Now, you know how to create a language file but you do not know how you can use them. To use this extension you must use the following construct.

$this->CLASS['language']->get['ext']['extensionname']['translateme']

With that construct you can get you translation for the keyword. The language is set by the user or by the configfile.

1.5 class file

The next step is to create your class in the "class-yourextension.php". Here is an example.

/******************************
 * extensionname
 * your name
 * date
 *
 * version
 * description
 ******************************/

class yourextension extends extension_base {

}

?>

This is a default class for your extension. This class should extends on the class "extension_base". So it is easy to have access to all other extensions and to have no problems if new things will be added to knowledgeroot.

The default class "extension_base" contains only small things that are required to run a your "naked" extension. In the default class it exists the function __construct that create a reference to all other classes. Here the variable $CLASS is used in the default class. So you can use

$this->CLASS

in your extension to have access to all other extensions and classes and to your languages!

The next default function is show_content that has one argument, the content id. This function is used to show different content between the normal content elements. For example if you want to create a diagram as content you should return here your diagram. To display this you can use the id. This is the id from the table content that contains the rights and other things.

You do not need more at this point to create a simple extension for knowledgeroot. The next step will be to create a menu.

2. Create menu items

Now, we will create menu items that you need for your extension. This should be a easy process and we use php arrays for this.

We have 8 different menus in knowledgeroot. Each menu has a name or a keyword. Here are the menus.

top - for top navigation
tree - for the tree navigation
page - navigation for each page
content - navigation for each content
contentline - navigation on the horizontal line.
toolbar - navigation in the toolbar at the bottom
pagecontext - right click menu on tree elements
contentcontext - right click menu on content elements

This are the 8 menus in knowledgeroot you can use. You can create items to all of this menus and you can also order them! The default menus are create in "include/class-default-menu.php". In this file you found all the code that is needed to create the default menus in knowledgeroot. You can take a look at this file to get an impression of how this works. But now its time to create your own menu item.

If you want to create a new item at the top navigation you can this with the following code.

$this->menu['top']['myname']['name'] = "my name";
$this->menu['top']['myname']['admin'] = 1;
$this->menu['top']['myname']['link'] = "index.php?action=myaction";

You see now a simple array of a menu item. The first section in this array contains the one name of the 8 menus. You can not use "config" as name for menu. This is used for settings for this menu. So here we use top. The next section must be a unique name at this menu section! Here we use "myname" for this. The last section in this array contains the options for this menu item. You should set a "name" and a "link" to each item! Here, the option "admin" is set to 1. That means that you need admin rights to display this item. With that short array you have create your first menu item.

Now you will get all options you can use to create a menu item.

tooltip	Set title or alt to img and link
name	Set the name to this item. You should use here the translation for each language
link	Set the link to this item
addid	Will add a page or content id to the end of the link if it is present. That could be used at the page or content menu.
atagparams	Here you can set extra parameter for the a tag in this item. This could be used for extra javascript.
image	Set url/path to a image that will be displayed instead of the name
imagewidth	Set width to the image
imageheigt	Set height to the image
target	Set a target to the link
admin	Set to 1 if admin rights are needed. Empty or 0 is for no admin rights are needed.
pagerights	Set to the rights that are needed for this page. Empty or 0 is for no rights are needed. 1 for read rights are needed and 2 for read and write rights are needed.
contentrights	Set to the rights that are needed for this content. Empty or 0 is for no rights are needed. 1 for read rights are needed and 2 for read and write rights are needed.
login	Set to 1 if login is needed. Default is empty or 0.
logout	Set to 1 if logout is needed. Default is empty or 0.
contenttype	Here you can discribe at what content type this item should be displayed. This can only be used at the menu content or contentline. Default is empty or text. If you want a item for your extension here you must name your extension.
wrap	You can set a wrap around your link. For example "\|" will create "mylink"
priority	Set a priority to your item. This is used to order the items. The default items begin with 10. So you can set a value smaller than 10 to create a item at the first place. If you set no value the default value will be 90. If you want to create a item that should be displayed at last you must set a value greater than 90.

This are all options that you can use for your menu items.

One special feature is left. You can use "{$ID}" in your options. It will be replaced with the contentid or pageid if it exists.

As you read a few lines before you can not use "config" as name for menu. You can use "config" for settings for the hole menu. At the moment we only have one setting here. You can set a wrap for the hole menu. So you can do the following to put div's around your menu:

$this->menu['top']['config']['wrap'] = "<div>|</div>";

The next step will be to show some content.

3. Show content

At this part you will create the output of your extension. This will only be a small example.

OK. Here is a small example of a class.

/******************************
 * extensionname
 * your name
 * date
 *
 * version
 * description
 ******************************/

class yourextension extends extension_base {

	function main() {
		$this->menu['top']['register']['name'] = "register";
		$this->menu['top']['register']['link'] = "index.php?action=register";
		$this->menu['top']['register']['priority'] = "1";
		 
		if($_GET['action'] == "register") {
			$content =$this->show_register();
		}
 
		return $content;
	}

	function show_register() {
		return "hello world!";
	}
}

?>

This easy class will display a menu item to the top navigation. If you click on that link the text "hello world!" will be shown.

This is a easy way to create some new features to knowledgeroot like a register form.

The next example will be create a own content type.

For this we should define a new function to our class. This function must be called "show_content" and has one parameter. The parameter is for the contentid.

So a simple class could look like this

class yourextension extends extension_base {
	function show_content($id) {
		return "content for id " . $id;
	}
}
?>

So this function will be display the text "content for id" and the id itself. So here you can do all you want with that id. For example you could can select other things from other tables. A good pratice example could be content element like a normal wikisyntax. For that we must display and convert the wiki syntax to display the htmlcode. Here you can use the table "content" in the database to save the content. So if you need more tables for your content you can create it with your extension. All is possible to do now.

So one thing is left. The creation of your new content element. You must create a row in the table "content" to display the content on this page. For the coloum "type" you must insert the name of your extension to show the content with your extension after creation. If this coloum will be empty or the coloum is filled with "text" then only a text is shown.

Coming to the end. This is the extension interface in knowledgeroot you can use to create your own extensions! It is possible that some things will be changed in the future. If this is happend we will change this documentation, too. So for questions or ideas to this interface please use the mailinglist to contact us developers.

Thank you for reading and happy extension developing.

With kind regards,
Frank Habermann

[Top]