Column Writing Tutorial

From KnowledgeTree Document Management Made Simple

Writing a column for the browse and search views is a good introduction to how much of KnowledgeTree is put together. Unlike many other Web-based applications, a lot of the development work for KT is done via plugins and extensions, all through some well-defined API. Columns are no different.

Boilerplate

We're going to create a whole new plugin for this (if this is unfamiliar, read up about Plugin Registration. Since that's not the focus of this tutorial, I'm going to suggest you create a new directory and put the following in a file called "TutorialColumnPlugin.php" in that directory.

<?php

// Tutorial code from wiki.ktdms.com

require_once(KT_LIB_DIR . "/plugins/plugin.inc.php");
require_once(KT_LIB_DIR . "/plugins/pluginregistry.inc.php");

class TutorialColumnPlugin extends KTPlugin {
     var $sNamespace = 'wikitutorial.columntutorial.plugin';
     function TutorialColumnPlugin($sFilename = null) {
          $res = parent::KTPlugin($sFilename);
          $this->sFriendlyName = _kt("Column Tutorial Plugin");
     }

     function setup() {
          $this->registerColumn(_kt("Tutorial Column"), 'wikitutorial.columntutorial.column', 'TutorialColumn','TutorialColumn.php');
     } 
}

$oRegistry =& KTPluginRegistry::getSingleton();
$oRegistry->registerPlugin('TutorialColumnPlugin','wikitutorial.columntutorial.plugin', __FILE__);

?>

That does all the boilerplate installation stuff you'll need. Next up, the meat of the application - TutorialColumn.php.

A Basic Column

A column is a class, which is asked for the HTML to render a particular part of the browse view. The basic idea is:

1. the column is created, and configured by the system
2. the column is asked to render (return the html for) a header (this is done by the basic column ... usually you should be doing this yourself)
3. the column is then asked to render (return the html for) a series of entries in the collection (folders and documents).

That's it. There are a few other things you can do (such as tell the collection how to sort itself, etc.) but those are more advanced than we're going to look at right now. Feel free to experiment and read plugins/ktcore/KTColumns.inc.php for more details and maybe even add a section at the end of this document extending the tutorial to cover sorting!

Anyway, the basics of writing your column are as follows. In the file TutorialColumn.php, put

<?php

require_once(KT_LIB_DIR . "/browse/advancedcolumns.inc.php");

class TutorialColumn extends AdvancedColumn {

    var $name = 'tutorial';
    var $namespace = 'wikitutorial.columntutorial.column';   // this is a unique name for this column, so kt doesn't get confused
    var $sortable = false; // we don't cover sorting
    
    // a constructor - its important that this takes no arguments.
    function TutorialColumn() {
        $this->label = _kt("Tutorial Column");    // a friendly name for the column
    }

So far so good. This is all very similar to any of the other KT plugins, so you should have had any difficulty with it. Next up we're going to handle configuration. Configuration of columns happens like the configuration of most other things in KT - via Option Arrays

    function setOptions($aOptions) {
         $this->document_text = KTUtil::arrayGet($aOptions, 'document_text', 'a document');
         $this->folder_text = KTUtil::arrayGet($aOptions, 'folder_text', 'a folder');
         return parent::setOptions($aOptions);
    }

 

Again, pretty simple. we're setting up two variables on the column object - document_text and folder_text. Next, we're going use those when the column is rendered.

    function renderData($aDataRow) {
         if ($aDataRow['type'] == 'folder') {
              return $this->folder_text;
         } else if ($aDataRow['type'] == 'document') {
              return $this->document_text;
         } 

         return 'unknown type';
    }     

}

?>

And that's it - a basic, working column. If you move the plugin folder into the plugins directory, and go to DMS Admin > Misc > Plugins, you should be able to refresh the list and install your column. Going to "Manage Views" you should now be able to add your column to a view!

Doing Something Useful

Of course, a column which says whether something is a document or a folder is not terribly useful. We want to make this do a little more work. What we're going to do is display whether the document is checked-out or not. This is very straight forward: first, we change its label.

    function TutorialColumn() {
        $this->label = _kt("Status");
    }

Then we change how the "renderData" function works. We don't want to say anything if its a folder, and we want to print out "Checked Out" if its checked out. Again, this is very simple:

    function renderData($aDataRow) {
         if ($aDataRow['type'] == 'folder') {
              return $nbsp;   // say nothing
         } else if ($aDataRow['type'] == 'document') {
              $doc = $aDataRow['document'];
              if ($doc->getIsCheckedOut()) {
                   return "<strong>Checked Out</strong";
              }
         } 

         return ' '; // show nothing if not checked out or not a document.
    } 

And that's it.