1. The javascript function

Lets create our javascript methods first. Create a file effects.js with this content:

kukit.actionsGlobalRegistry.register("fadeOut", function(oper) {
    oper.evaluateParameters(["speed"], {}, "fadeOut action");
    $(oper.node).fadeOut(oper.params.speed);
});

kukit.commandsGlobalRegistry.registerFromAction("fadeOut",
                                                kukit.cr.makeSelectorCommand);


kukit.actionsGlobalRegistry.register("fadeIn", function(oper) {
    oper.evaluateParameters(["speed"], {}, "fadeIn action");
    $(oper.node).fadeIn(oper.params.speed);
});

kukit.commandsGlobalRegistry.registerFromAction("fadeIn",
                                                kukit.cr.makeSelectorCommand);

This creates two actions and registers them with the KSS action registry, as well as registering commands for the two actions. This is needed because KSS actions can only be called client-side, while commands can only be called from the server. In a future version of KSS actions and commands may be merged into a single entity.

Please note that this example relies on jQuery being present to do the actual fading.

Next we need to register this file with Zope to it will be available for use. Add these lines to your configure.zcml file:

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

  <kss:action
      name="fadeIn"
      command_factory="selector"
      params_mandatory="speed"
      jsfile="/docs/how_to/creating_kss_command_sets/effects.js"
      />

  <kss:action
      name="fadeOut"
      command_factory="selector"
      params_mandatory="speed"
      jsfile="/docs/how_to/creating_kss_command_sets/effects.js"
      />

</configure>

your client-side actions are now available for use by KSS. To test them you can try to use an action directly in a kss file. For example:

div:click {
    action-client: fadeOut;
    fadeOut-speed: slow;
}

2. The interface

The next step is to create the command set that we can use to call these actions. First we need to create an interface that defines the contract for the new KSS methods. This is a standard Zope3 interface derived from the kss.core.interfaces.ICommandSet class:

from kss.core.interfaces import ICommandSet

class IEffectCommandSet(ICommandSet):

   def fadeIn(speed):
        """Fade in an element. The speed can be either 'slow', 'normal'
        or 'fast' or the number of miliseconds to run the animation.
        """

   def fadeOut(speed):
        """Fade out an element. The speed should be one of 'slow', 'normal'
        or 'fast'.
        """

3. The commandset class

After defining the interface we can start creating the command set itself. Lets create a new effects.py file:

from zope.interface import implements
from kss.core.kssview import CommandSet
from interfaces import IMyCommandView

class EffectCommandSet(CommandSet):
    implements(IEffectCommandSet)

    def fadeIn(self, selector, speed):
         self.commands.addCommand("fadeIn", selector, speed=speed)

     def fadeOut(self, selector, speed):
         self.commands.addCommand("fadeOut", selector, speed=speed)

The methods are very simple: the only thing they do is tell KSS that a client side action with a given name should be called with a speed parameter. If needed you can do more complex things or issue multiple commands as well.

4. Register the command set

Now that we have written both the interface and the implementation we can register our new command set so we can start using it. Add the following lines to your configure.zcml file:

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

  <kss:commandset
      name="effects"
      for="kss.core.interfaces.IKSSView"
      provides=".interfaces.IEffectsCommandSet"
      class=".effects.EffectCommandSet"
      />

</configure>

5. Using the command set

Now that everything has been setup we can use our new command set from python KSS views. Here is a simple example that will fade out the portal header:

core = self.getCommandSet("core")
effects = self.getCommandSet("effects")
selector = core.getHtmlIdSelector("portal-header")
effects.fadeOut(selector, "slow")