This page has not been updated recently. It contains some information that has changed in the new release.

What happens behind the scenes?

I attempt to describe how your page starts to work with KSS. If you are just interested in what steps you actually have to make to make your pages work in Zope or Plone, skip reading this and go to the end of this chapter.

KSS adds dynamic behaviour to your pages. To make this work, the following elements must be present

On the client side:

• The page must import the necessary javascript resources. This enables the system to work.
  
• The page must import the event rule resources (KSS): This describes how it should work.

On the server side:

• The above mentioned resources must be supported. This enables the system to work.
  
• The azax methods that give the responses to the azax requests must be present. This is part of describing how it should work.
  

So on both the client and the server there are the pre-written resources that must be present and there are those that must be written for each page We won't learn here how to do the latter one.

Javascript resources

First the client page must import different javascript resources from the HTML header. There are the following third party resources necessary:

• sarissa.js

• cssQuery.js

• Mochikit.js

• ajaxslt_misc.js

• ajaxslt_dom.js

• ajaxslt_xpath.js

These are offered as zope resources from the server, so the can be included from any path that is Five-traversable. Typically, they would be uniformly included from the application or the Plone site root, to help caching. One example of include that appears in a page:

<script type="text/javascript"
    src="http://localhost:9777/azaxdemo/++resource++sarissa.js">
</script>
<script type="text/javascript"
    src="http://localhost:9777/azaxdemo/++resource++cssQuery.js">
</script>
<script type="text/javascript"
    src="http://localhost:9777/azaxdemo/++resource++MochiKit.js">
</script>
<script type="text/javascript"
    src="http://localhost:9777/azaxdemo/++resource++ajaxslt_misc.js">
</script>
<script type="text/javascript"
    src="http://localhost:9777/azaxdemo/++resource++ajaxslt_dom.js">
</script>
<script type="text/javascript"
    src="http://localhost:9777/azaxdemo/++resource++ajaxslt_xpath.js">
</script>

We will further consolidate the list of the third party modules. Some remarks:

• Mochikit wil not be needed, it is optional only for logging and debugging
  
• from Sarissa you need at least the version that we included, earlier versions contain a critical bug
• azaxslt stuff will be optional, it will only be needed for xpath selectors in commands
  

Also you are not forced to use the modules bundled in azax, you can also use your own libraries so if they are already included in your page that is enough.

And in addition the page must include the most important javascript that contains the kukit.js library itself:

<script type="text/javascript"
    src="http://localhost:9777/azaxdemo/++resource++kukit.js">
</script

The kukit.js is an interesting beast since it is already constructed dynamically by azax. One nice thing is that the different library sources are assembled together and compressed on the fly. The other important feature is that kukit has a plugin mechanism, which means that individual Zope products have the possibility to define their own plugins and register them with the system. Then the kukit.js also contains all the necessary javascript  provided by these individual modules. The registration happens automatically when the products are imported, and there is no additional import necessary from any more pages in the system.

To assemble the kukit.js page azax does not use Plone's ResourceRegistries but uses zope constructs directly. The reason for this is that we wanted to make it independent from Plone on the architectural level. However the kukit.js resource appears as one single resource for ResourceRegistries that it can handle as usual.

The event rule descriptor resources

The page must also include the necessary kss resources that govern its working. There can be one or many of these resources. These resources are read by the kss library automatically, when a page loads. The general scheme that must appear in the header, per each resource, is this:

<link rel="kukit" type="text/css"
          href="http://localhost:9777/azaxdemo/++resource++azax_demo.kss" />

The important elements are

• the link tag with rel="kukit", this is used to identify that we deal with a kukit resource
• the type="...", the system can support different resource description types. All these describe the same semantics but different data formats can be used. The formats are identified by their mimetype that is just chosen to be a valid mimetype too.
• The href of the page itself, now it happens to be a zope resource but this is not necessary, it can be any file accessible from the server.

There are the following resource types available:

• KSS: this is a CSS-like description that has the mimetype "text/css". In fact, KSS is 100% valid CSS in its syntax.
• XML: this was the old format and it has the mimetype "text/xml". It is temporary disabled in the current implementation but it will appear again if it makes sense (although KSS seems to be much more powerful and sensible, but XML might have its role too)
  

The advantage of the KSS format is that it can be handled by Plone's ResourceRegistries just as if it were a CSS resource, only the "rel" atttribute must be set appropriately to "kukit.".  Compression, aggregation is possible. (The only patch that is necessary on ResourceRegistries is a plain Five issue: the bundled version cannot handle Five resources and since we have them it is necessary to use the branch patched by me. But this is not for enabling KSS itself, that works out of the box.)

In Plone all the resources are registered for the scope of the entire portal: this is in line with how it is currently done with all sort of resources. It is not a problem to have them globally in each page, because KSS is also selecting nodes with CSS selectors, so the ones that are not in your page simple have no effect.

We plan to provide, although not strictly necessary, a Plone tool for handling just the KSS resources at one point.

Enable it with Zope

You need to install the azax product and otherwise do most of the above described steps manually. I will not give a recipee for this but you can have a look at the azaxdemo product that gives you a simple idea.

Enable it with Plone

You need to install the following products into Zope:

• azax: this contains all the server side support and also all the javascript libraries are bundled with it and offered as zope resources.
• AzaxPlone: this contains all Plone specific support. At the moment this is rather an empty shell but it will be filled up as time goes.

AzaxPlone is also a Plone product that you need to install into your portal via the quickinstaller. This, and:

• Any other product that offers azax support and you want to use in the portal.

Since kukit has a plugin mechanism, each product can bring their own server and client side components with it. To use them, just need to install them into Plone as usual. Any such product should also depend on AzaxPlone (and azax) and install it automatically.

Be a kss designer

As a kss designer our main task will be to write event rule descriprions, that is, KSS resources to describe the dynamic behaviour bound to your page. To do that, you either modify one of the existing resource that is already registered for the portal, or you make a new one for yourself.

• To modify an existing KSS, you look for them in the skins or in the "browser" directory of a Product on the filesystem. The latter one is the zope style resource handling, the preferred new way. However use which one you like.
• To make a new resource the simplest way is to create it in the skins and register it manually from ResourceRegistries.

If you are modifying a resource it is important to know that your browser will cache the files indefinitely so if you cannot force the browser to reload not only the page but everything it depends on, it will take quite some time until you realize why nothing happens. If you use FireFox, the best practice is to install the "Web Developer" extension and then set "Disable Cache" from its leftmost menu.

In addition if you are using  zope browser resources (defined from configure.zcml)  you must be aware that if you change the file and you are running in debug mode, the file will be refreshed but if you are not running in debug mode, your zope instance must be restarted in order for the changes to take effect.

An error in the KSS file will result in a javascript error and nothing will happen. To learn more about your process you need to know more about KSS itself and this will happen in another document.

Be a programmer of kss server actions

This is one step towards becoming a component developer but yet does not require a lot of deep knowledge. Especially since you do not have to touch anything on the client side, so if you are experienced with python and zope, you will find this really easy. In other words you only modify server side methods and make new ones.

What happens is that when from KSS you specify a kss server action, this is a method name that is called up on the server on the current context object. The task of the method is to assemble a response which consists of parametrized commands that the client will execute. At this point you choose from already implemented commands but you can combine and parametrized them easily. This is, since all action happens on the server, the equivalent process of making a thin client.

The best way to create the azax method is write a browser view originating from the AzaxView class. We prefer this style of development since it is in line with the Zope3 way. You could otherwise also use a traditional method if you are not familiar with Five. In our method you have a simple API for building up the response commands in the desired order, with the desired parameters. The marshalling of the commands in the required data format will be automatic. You can also carry out other server side tasks during this, modify content, etc.

This approach gives you higher power then just modify KSS, and you do not  need to wet your hands with any javascript. In most of the cases you do not need to go further (as in a large number of the use cases a thin client is just totally sufficient).

Be a kss component developer

As a component developer, you will design new kss components. This consists of

• writing azax methods on the server side that specifies a kss server action, these are the ones that finally get called according to the KSS file and in return they marshall the client to make some changes on the original page (Like described under the previous part).
  
• writing javascript code on the client side that  defines different types of kss plugins, these offer new behaviour that can be utilized from KSS. The following plugin types are present:
• event plugins describe new complex azax events
• action plugins describe localy executable actions in addition to the normal workflow in which actions are typically defined and executed on the server
• command plugins that as a result of the server response are executed on the client and do different page manipulations

Both the server methods and the javascript plugins are bundled into a zope Product that, once installed, makes the new features transparently available in the site. This way it functions as a blackbox and hides implementation details which is one of the main goals here. Also it makes possible to start from a thin client implementation and gradually fatten your client if necessary, but the thickness of the client is also hidden in this implementation layer.

To do kss component development is not meant to be a simple task: it designfully requires an expert knowledge. You must know python, javascript and kss itself in details. Most of the times however, you don't need to do all this: KSS is expressive enough with the already supported plugins, and in most of the cases you will only need to write a new action on the server side (be an azax commander).

The kss component development API is yet under changes, and once consolidated will be well documented.