Basic Dashlet Tutorial

From KnowledgeTree Document Management Made Simple

Introduction

This tutorial will show how to create a basic dashlet.

Requirements

It assumes you are familiar with basic PHP and smarty templating.

More information is available on the [PHP documentation site] and the [Smarty Templating site].

Download

Download a the [sample code].

MyDashlet.php

Create MyDashlet.php in the folder plugins/mydashlet.

1 class MyDashlet extends KTBaseDashlet 
2 {
3        function MyDashlet ()
4        {
5                // set the title
6                $this->sTitle = _kt('My Dashlet Title');
7        }
8
9        function is_active($oUser) 
10       {
11               // some boolean expression to decide if the dashlet should be displayed to the current user.
12               // The root user has an id of 1.
13               return ($oUser->getId() == 1) || ($oUser->getUsername() == 'myname');        
14       }
15       
16       function render() 
17       {
18               // we must now render our dashlet.
19               $oTemplating =& KTTemplating::getSingleton();
20               $oTemplate = $oTemplating->loadTemplate('MyDashlet');
21
22               $aTemplateData = array
23               (
24                       'is_root' => ($oUser->getId() == 1),
25                       'user' => $oUser->getUsername()
26               );
27
28               return $oTemplate->render($aTemplateData);                
29       }
30 }

Line 19: We create a reference to the templating engine. Line 20: We pull the smarty template from the templating location. This is normally set by the master plugin that does the following:

$oTemplating->addLocation('My Plugin', '/plugins/mydashlet/templates');

Line 22: The associative array is used to pass information to the smarty template.

MyDashlet.smarty

In the render() function above, we saw the call to loadTemplate('MyDashlet').

This is infact loading the smarty template plugins/mydashlet/templates/MyDashlet.smarty

{if $is_root}
   You are the root user.
{else}
   Hello {$user}. This is your first dashlet.
{/if}

MyPlugin.php

We need to have a core plugin file that registers our dashlet. This plugin is self registering and is otherwise quite simple.

1  class MyPlugin extends KTPlugin
2  {
3         var $sNamespace = 'myplugin.plugin';
4
5         function MyPlugin($sFilename = null) 
6         {
7                $res = parent::KTPlugin($sFilename);
8                $this->sFriendlyName = _kt('MyPlugin');
9                return $res;
10        }
11
12        function setup() 
13        {
14               $this->registerDashlet('MyDashlet', 'mydashlet.dashlet', 'MyDashlet.php');
15
16               require_once(KT_LIB_DIR . "/templating/templating.inc.php");
17               $oTemplating =& KTTemplating::getSingleton();
18               $oTemplating->addLocation('My Plugin', '/plugins/myplugin/templates');
19        }
20 }
21
22 $oPluginRegistry =& KTPluginRegistry::getSingleton();
23 $oPluginRegistry->registerPlugin('MyPlugin', 'myplugin.plugin', __FILE__);

General comments

The sample above demonstrates how to create a simple dashlet. When creating more complicated dashlets, you would place more logic in your render() method and pass all the required information to the smarty template by populating the array such as $aTemplateData above.

Very often your logic may require you to access the context of the current user in the render() method. The most common way of doing this is storing the user in the class attribute. e.g.

class MyDashlet extends KTBaseDashlet 
{
       var $oUser;

       ...

       function is_active($oUser) 
       {
               ...
               $this->oUser = $oUser;
               ...
       }

       ...
}

Dashlet States

Dashlets may be in one of 3 states: ktBlock, ktError or ktInfo.

The default state is ktBlock.

State	Background Colour
ktBlock	White
ktError	Yellow
ktInfo	Grey

To change this, you can update the $sClass attribute.

class MyDashlet extends KTBaseDashlet 
{
       var $sClass='ktInfo';
}

Finally

To enable the plugin, you must 're-read the plugins' in the administration section and enable the plugin for it to be enabled in the system.