This tutorial is the second part of Creating a kss plugin. If you have not read the first part, you might want to read it first.

Let us start with some basic file layout. Take the code from the previous tutorial and add empty files so it looks like:

• kssplugintutorial
• setup.py
• kssplugintutoria
• __init__.py
• configure.zcml
• kssplugintutorial-configure.zcml
• tutorial.pt
• tutorial.kss
• tutorialplugin.js
• interfaces.py <new>
• tutorialplugin.py <new>
• demoview.py <new>
  

Before we start with the code, I will first explain what the server side part of our plugin does. Normally, when developing server-side methods with KSS, you use a KSSView in which you do something like self.getCommandSet('core'). Those command sets that have the methods which prepare the response for KSS client-side engine.

A command set is a wrapper mechanism that avoids you to need to know about the inner workings of KSS. It also allows you to create complex commands which are composed of multiple smaller ones. Now that you have some background on command sets, we will start with creating our own command set. Open interfaces.py and paste in the following code:

from zope import interface

class IKSSPlugingTutorialCommands(interface.Interface):
	'''The commands used in our tutorial'''

	def demo(selector, text):
		'''Notify a user with a message'''

As you can see we defined a simple interface. Now let us continue with the implementation. Paste the following code into tutorialplugin.py:

from kssplugintutorial.interfaces import IKSSPlugingTutorialCommands
from kss.core import CommandSet
from zope import interface

class KSSPluginTutorialCommands(CommandSet):
	interface.implements(IKSSPlugingTutorialCommands)

	def demo(self, selector, text):
		command = self.commands.addCommand('ksstutorial-demoplugin', selector)
		command.addParam('text', text)

This code sets up a simple command set. The demo method is responsible for the creation of the proper KSS commands. As you can see, it uses the self.commands.addCommand method. This will return the command object so that we can parameterize it further if needed.

There is no limit to the amount and type of commands you create in a method like this. Keep this in mind because a lot of complex behaviour can be reduced for server side users by using advanced command sets.

An example of this is portlet reloading in Plone. This uses Plone specific command set which does both the component architecture lookups as well as the KSS replacement calls based on few variables. Take a look at the plone.app.kss package for more information.

Now we will continue with the configure.zcml. We need to register our command and command set. Paste in the following code between the configure tags:

<kss:commandset name="tutorial"
                for="kss.core.interfaces.IKSSView"
                provides=".interfaces.IKSSPlugingTutorialCommands"
                class=".tutorialplugin.KSSPluginTutorialCommands" />

The name is used to get a command set from a KSSView. It is therefore very important that you choose a nice descriptive name. All other attributes are pretty self explanatory. They are needed for the component architecture to find our command set.

We are basically done now. To prove it, all we need is a view which will call our command. Paste the following code into demoview.py.

from kss.core import KSSView, kssaction

class DemoPluginView(KSSView):

	@kssaction
	def rundemo(self):
		core = self.getCommandSet('core')
		selector = core.getCssSelector('div')
		tutorial = self.getCommandSet('tutorial')
		tutorial.demo(selector, 'Server says: Hello!')

We need to register the view in the configure.zcml by using the following code:

  <browser:page for="*"
                name="rundemo"
                attribute="rundemo"
                class=".demoview.DemoPluginView"
                permission="zope2.View" />

To actually call the server-side code, we need to modify our kss file. Replace its contents with the following code:

div:click {  action-server: rundemo; }

Ok, time to restart the Zope server and make sure it works. This wraps our tutorial on how to create a simple plugin for KSS.