Document Actions

Creating a KSS plugin

by Jeroen Vloothuis — last modified 2007-08-15 11:28

This tutorial will explain how to write a simple KSS plugin. A KSS plugin allows you to extend the available command set. This means you can write plugins to integrate existing Javascript code or enable new functionality.

Intended audience

The tutorial contains much information on how to integrate this plugin with Python and Zope. If you are only interested in the Javascript related bits, you might go directly go to the Javascript section.

Setup the basic structure

You will need to create a new Javascript file.

Because we are using Zope in this tutorial, we will also create a python package with the appropriate code that registers the javascript file. Lets start with an empty package first. Create a folder structure like shown below:

kssplugintutorial
- kssplugintutorial
  - tutorial.pt
  - tutorial.kss
  - tutorialplugin.js
  - __init__.py
  - configure.zcml
- setup.py

Most of this stuff is common Python packaging practice and some is Zope-specific. Let us first setup the package. Open the setup.py and paste in the following code:

from setuptools import setup, find_packages
import sys, os
version = 'demo'

setup(
	name='kssplugintutorial',
	version=version,
	packages=find_packages(exclude=['ez_setup']),
	include_package_data=True,
	zip_safe=False,
	install_requires=['setuptools',],
)

This is basic setuptools configuration. See the setuptools page for more information on how to setup a package. This allows us to register our package with Python without actually installing it. We will show how to do this.

Now we will continue with setting up our Javascript file so Zope can use it. Open the configure.zcml in you favorite editor. Now paste in the following code:

<configure 
    xmlns="http://namespaces.zope.org/zope" 
    xmlns:browser="http://namespaces.zope.org/browser" 
    xmlns:kss="http://namespaces.zope.org/kss">

  <kss:action 
        name="ksstutorial-demoplugin"
        command_factory="selector"
        params_mandatory="text"
        jsfile="/documentation/tutorials/creating_a_kss_plugin/tutorialplugin.js" />

  <browser:page
        for="*" 
        template="tutorial.pt"
        name="kssplugintutorial"
        permission="zope2.View" />

   <browser:resource 
        file="tutorial.kss"
        name="tutorial.kss" />

</configure>

The first part of code (kss:action) registers our Javascript file with the KSS framework. The Zope KSS framework collects all plugins registered this way and concatenates all Javascript into one big file. This has the advantage of not having to add HTML to the header for each new js file and to provide faster page loading times for visitors. The registration process also makes sure there are no duplicate definitions and so on.

Required parameters are also specified. This is a space seperated list of names. So when you need more than one than just add a space and name the next one. You can also specify optional parameters like this by using params_optional. It follows the same syntax as params_mandatory.

You can also see that we need to specify a command_factory. This factory can be of several types. The most common one is selector. This is used for any action that requires a node to operate on. You can also have actions like alert which do not need a node. These are global actions and use the global factory.

The two other directives are the registration for our page template file and our kss file.

We will now create our HTML file so that we can experiment with a clean slate. Paste the following code into tutorial.pt:

<html>
	<head>
		<script type="text/javascript" src="/documentation/tutorials/creating_a_kss_plugin//resourcesarissa.js"></script>
		<script type="text/javascript" src="/documentation/tutorials/creating_a_kss_plugin//resourcecssQuery.js"></script>
		<script type="text/javascript" src="/documentation/tutorials/creating_a_kss_plugin//resourcekukit_src.js"></script>
		<link href="./++resource++tutorial.kss" 
                      type="text/css" rel="kinetic-stylesheet"/>
	</head>

	<body>
		<div>Hello Plugin</div>
	</body>
</html>

As you can see, we need to load a few Javascript files. Sarissa is a general purpose Javascript library for Ajax and other things. The cssQuery library is used for looking up nodes in you browsers DOM using CSS selectors. And the final piece of Javascript contains all of KSS. It includes all plugins we registered using the ZCML we saw earlier. The <link rel="kinetic-stylesheet"> tells where to load a KSS file, in a very similar way to CSS.

Paste the following code into ksstutorial-configure.zcml:

<include package="ksstutorial"/>

You will need to copy this file to your Zope installations etc/package-includes folder. All this does is tell Zope to look in this package for a configure.zcml so it will initialize our package.

Now that we have our package we can install it. Go to your ksstutorial folder (the top level one) and run python setup.py develop (you need to have setuptools installed for this). This will make sure Python can find the tutorial package. You might need to run it with sudo if you are on Linux or Mac. Be sure to run it with the same Python you use for running Zope.

The Javascript

Now that we have everything setup we will can start with the plugin itself. A KSS plugin consists of some Javascript to hook a function into the KSS registry. Paste the following example into tutorialplugin.js:

kukit.actionsGlobalRegistry.register("ksstutorial-demoplugin", function(oper) {
	// code goes here
});

The first line registers our plugin with the action registry. This registry is used by KSS to look up commands. Therefore it is important to keep the name the same as in the configure.zcml. We also give the register method an anonymous function. This is where the actual code for our plugin is going to be. You can also see the only parameter an action plugin will receive when it is called. Not to worry though as this object has quite a few properties and methods. Let us look at the code below to see one of the most used methods in action.

kukit.actionsGlobalRegistry.register("ksstutorial-demoplugin", function(oper) {
	oper.completeParms([], {}, 'ksstutorial-demoplugin action');
});

The oper.comleteParms method makes sure all required parameters are available. You the first argument to it is a list of string which indicate which named arguments must be present. The second dictionary specifies a optional parameters with a default value. And the last parameter is used for debugging purposes (this is what is used in the error display).

Now lets make something a bit more interesting. We will create a simple plugin which will show alert messages to a user.

kukit.actionsGlobalRegistry.register("ksstutorial-demoplugin", function(oper) {
	oper.completeParms(['text'], {}, 'ksstutorial-demoplugin action');
	alert(oper.parms.text);
});
kukit.commandsGlobalRegistry.registerFromAction('ksstutorial-demoplugin', 
                                                kukit.cr.makeSelectorCommand);

You can see it is easy to read in an incoming variable. Now lets make some KSS to hook this up. Paste the following code into tutorial.kss:

div:click {
	action-client: ksstutorial-demoplugin;
	ksstutorial-demoplugin-text: 'Greatings from KSS'
}

Now we are completely done with our setup. Start (or restart) Zope and make a Plone site (THIS SHOULD NOT BE NEEDED). Now add kssplugintutorial to the URL, mine looks like this: http://localhost:8080/plone/kssplugintutorial. Click the text in the div to trigger the plugin code. You should see an alert box.

If the example does not work you can use the Firebug console to see what is happening. Make sure there is a line in there like "EventRule #0 mergeid @@0@@click selected 1 nodes". This signals that our event rule is bound to the div. If you do not see output like this make sure the KSS file can be loaded.

That is it for this tutorial. Have fun with KSS.

KSS (Kinetic Style Sheets)

Sections

Personal tools

Document Actions

Creating a KSS plugin

Intended audience

Setup the basic structure

The Javascript