kfm2: plugin management

I know, I promised this last week – I’m afraid I’ve been up to my eyes in work and just exhausted at home, so all I can do is apologise.

Anyway, I’ve put together the basics enough that there is one single plugin, which gets a directory listing, and echoes it to the screen in JSON.

You can get a copy of the basics using the following SVN command:

svn checkout http://kfm.googlecode.com/svn/kfm2/ kfm2

In that, there are two directories – trunk and plugins. The trunk is what will become the new KFM core, and the items in plugins will be server-side plugins that can be used by copying them into trunk/plugins/ (or do as I do and ln -s ../../plugins/* from the trunk/plugins/ to create symlinks).

When you load up KFM2 initially, it will do an extremely basic install, with no plugins enabled. Follow the instructions on-screen to get set up.

The config.php contains just two items at the moment. I want to keep this as absolutely clean as possible, so the items in there are the only essentials – all other configuration will be done using KFM’s admin section.

  • KFM_USERDIR – this is the directory that is to be managed by KFM. Just like KFM1, a directory called .files will be created in there that holds config stuff, such as the list of enabled plugins, etc.
  • KFM_ADMIN_PASSWORD – this password allows access to KFM’s admin section, where you can currently just enable/disable plugins. By default, it is blank, and you will need to change it before you can access the admin section.

There is no JavaScript yet in this, so it’s tricky to see exactly what it’s supposed to do.

I’ve set up a basic demo here, but loading that directly will just get you a login screen.

KFM2 is designed to be interacted with purely through RPC (except for configuration which requires browser access). The demo has the first plugin, “get_file_listing” enabled, which we can use to see what happens.

/?p=get_file_listing – this example calls KFM2 and tells it to run the get_file_listing plugin. by default, it will return the root directory of your KFM_USERDIR in JSON format:

{
  "d":"",
  "files":{
    "file2":{
      "size":0,
      "mtime":1255875795
    },
    "file1":{
      "size":0,
      "mtime":1255875794
    },
    "file3":{
      "size":0,
      "mtime":1255875796
    }
  },
  "directories":{
    "dir1":{
      "mtime":1255875809
    }
  }
}

The d parameter there is the directory that was requested (by default, it’s blank), which is internally added to the KFM_USERDIR to get the actual local directory.

The results returned are separated into two arrays, of files and directories. My guess is that most required uses on the client-side will be specific to either directories or files, so this saves you having to separate them yourself.

Changing the requested directory is simple – just add a d parameter to the request URL:

/?p=get_file_listing – this example requests the contents of /dir1.

How to write your own plugin

The system as it is will let you write plugins that handle most of the things that you might want to do – upload files, create/move/delete files or directories, download files, etc.

I’ll get around to writing these anyway, but if you feel like writing them, then feel free! Just copy how the get_file_listing plugin works.

So, here’s how a basic plugin works.

In KFM2’s plugin’s directory, create a directory named after the plugin. Please use just lowercase letters and underscores. Examples: “upload”, “get_file”, “rename_file”, “zip_directory”, etc.

In that directory, create a plugin.php file, which describes the plugin:

<?php
$plugin=array(
  'name'=>'Get File Listing',
  'description'=>'Retrieves a list of files and directories within a given directory',
  'version'=>0
);

Use an integer for the version number. It will probably never need to be used, but if it is, it is easier to compare two integers than two of the usual x.y.z version numbers.

When you log into your admin area, you’ll see the details above shown in your plugin management module.

For most plugin cases, you will also need a file named after the plugin itself. Until the events code is written, this is all cases.

In our example, we create a file named plugins/get_file_listing/get_file_listing.php. It should contain a function also named after the plugin:

function get_file_listing(){
  // place plugin code here
}

In the URL above, I had /?p=get_file_listing – what KFM then did was to load up the get_file_listing/get_file_listing.php file and run get_file_listing(). That function then used whatever other things were mentioned in the $_REQUEST array to carry out its work.

That’s pretty much it for now. That should be enough to create most basic plugins.

For the next KFM article, I’ll write up another server-side plugin, and will add in some client-side code so you can see how it would actually be used in a real project. It will demonstrate how JavaScript and KFM will talk to each other.

If anyone writes up any plugins that they want included in the SVN download, please email them to me (kae@verens.com).

Requested plugins

Here’s the list of plugins that have already been identified as needing to be written.

Server-side plugins that can be written right now:

  • file upload
  • delete file / directory
  • rename file / directory (also counts as “move”)
  • download file
  • create zip of directory
  • unzip a zip file
  • manipulate an online image

Plugins that require more work in the core:

  • connect to remote file-systems (FTP, NFS, other KFMs, etc)
  • user-based security
  • different KFM_USERDIR based on the logged-in user, or even the site’s hostname
  • plugin to resize images that were uploaded so they’re kept to a certain max size
  • quotas (can /probably/ be done at the moment… but not sure)
  • databases

One Reply to “kfm2: plugin management”

  1. Oh – just to make sure – all plugins should return their results in JSON, so that it can be interpreted on the client-side.

    There’s no reason why the client-side must be JavaScript, btw, so if anyone wants to create a Java app which handles uploads (for example), or a Fuse script for connecting the the local file-system to a KFM instance, they should be able to do that.

Leave a Reply