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 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.
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.
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 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
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:
'name'=>'Get File Listing',
'description'=>'Retrieves a list of files and directories within a given directory',
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:
// 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.
If anyone writes up any plugins that they want included in the SVN download, please email them to me (firstname.lastname@example.org).
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)