The tutorial has been updated for kss.core v1.2. Updated version

Installation

KSS is included with Plone 3.0. (We also plan provide backports for earlier versions, at a later point.) THIS DOCUMENT IS CURRENTLY IN THE PROCESS OF UPDATING to the newest version.

It is also important for all the further work that you run zope in debug mode and that you disable caching from your browser. In FireFox, if you install the Web Developer assistant in FF, this can be achieved from the leftmost menu by ticking in the Disable cache checkbox. Note that otherwise you need to force the  browser to  reload the page completely  after each change you have made in your kss resource files. In case you have made a change and  yet nothing happens on reload, it is caching to be blamed.

Also you would need to familiarize yourself with reading javascript exceptions that occur on your page. KSS will raise a javascript error in case something is wrong and you would be able to see this from your browser, some browsers (IE?) may require some debug option to set up.  In case you have no browser preference we suggest to use FireFox as it comes with the most friendly debugging facilities. You are also suggested to install the FireBug extension.

Note that apart from reading the error message, you do not need to be able to understand or debug javascript at all. Also you will not touch any javascript code during this tutorial.

Production and Development mode

There is an additional logging facility that provides you with useful debug and informational messages about what happens. Debug information is only shown in Development mode of KSS. Development mode can be activated if you enable Debug mode in portal_javascript tool. After doing so, you must reload your page in the browser. If you want to switch back to Production mode, you will need to reload the page again. Production mode offers a slightly smaller javascript to be loaded into your page, and slightly faster execution, for example, by not giving you  logs and detailed error messages. If you ever see the javascript error message "Unknown message (kss optimized for production mode)", this means you are running in Production Mode and you need to switch to Development Mode in order to see what happens.

If you are in Development Mode, and are using FireFox with the FireBug extension, you need not do anything, logs will appear directly in the FireBug console. If you use Safari, logging also appears in the Safari console. If these possibilities are not available for you, you have two other choices: either use Firebug Lite (on IE). or MochiKit (all browsers).

Activating logging with Firebug Lite (IE)

To activate Firebug Lite, you need to manually add the javascript file ++resource++firebuglite.js into the set of resources. You need to set this script to Non-Merging, and set its compression level to None. You must also make sure that you move this file above the ++resource++kukit.js and ++resource++kukit-devel.js. (Don't miss to press Save after this!) When this is done, you need to reload the page. After this Firebug Lite can be activated by pressing F12.

Activating logging with MochiKit

You need to do this only if you are unable to use both FireBug or FireBug Lite for some reason, although this should not happen.

First you need to enable MochiKit's javascript in the portal_javascript tool. Find the line with the id ++resource++MochiKit.js, and enable it, then press Save. Following this, reload your original page.

Then enter the following url into your browser after your page has been loaded (you can bookmark this as a link to avoid typing it in each time):

javascript:kukit.showLog();

See the result of logging

In your debug console (depending on the debug method you use) some log messages will start on reloading a page. They will begin this way:

INFO: Initializing kukit
...

If this does not happen, check if you have succeeded with the steps described above, most notably, are you in Development Mode? You may also need to log in to the portal, as by default KSS is disabled in Plone for non-authenticated users.

The text following the first line may indicate that KSS installed more eventrules on its own. This would not be a problem, but to allow us starting from a clean situation, we will disable all existing rule files.

Disable KSS's default event rule (KSS) files

We have installed PloneAzax into our portal. PloneAzax has put some KSS rules in effect, which produces a lot of log messages. So first we want to disable this file. Go to the ZMI in the portal root, enter the tool plone_kss and unselect the checkbox left from the names of plone.kss and at.kss. Then save this page.

Reload your original portal page and activate the loggingpane b entering the following url into the browser:

javascript:void(createLoggingPane(true));

At this point this your page is split and a debug window appears on the bottom, displaying some log messages.

INFO: Initializing kukit
INFO: actions for Plone legacy js registered (initialize collapsible)
WARNING: addDOMLoadEvent is not found in PloneAzax, skipping DOMLoad activation (add event-registration.js to ResourceRegistries?)
INFO: actions for Plone legacy js registered (bind menus)
INFO: PloneAzax initializeMenus 3
INFO: Nr of Rule Sheet Links: 0
INFO: Starting setting up events for document
DEBUG: Binding 0 special rules in grand total
DEBUG: Binding to 0 nodes in grand total
INFO: Finished setting up events for document in 0 ms

This means that KSS is active in the page, but there were no rule sheets to set up - so nothing happened. After reloading the page the debug window disappears which means you need to open it manually after every page load or reload.

If the number of rule sheet links is not zero, you need to return to the previous steps and make the remaining kss resources inactive.

Some more explanation about the messages. The lines before the "INFO: Nr of Rule Sheet Links: 0" are messages from plugin components that initialize themselves. There is no need to worry about that now.

Having arrived to this point, we can now proceed to start our first usage example.

Attach an event rule (KSS) file

First you need to attach a KSS resource file to your page. This is similar to a CSS file in purpose - even the syntax is almost valid CSS - but it has different semantics and it controls how KSS events are bound to your page elements.

To do it simplest, create a file named tutorial1.kss in your custom skins directory. To make the file bound to each page in the portal, we will use ResourceRegistries. Go to the ZMI in the portal root, enter plone_kss, press add and customize your new entry in the following way:

Notice that rel must be kinetic-stylesheet, (this differentiates it from normal css files), render type must be link and merging must be disabled.

After pressing Add, navigate back to your portal frontpage, reload it, and after starting the loggingpane you should see the following messages:

INFO: Initializing kukit
...
INFO: Nr of Rule Sheet Links: 1
INFO: Start loading and processing http://localhost:9777/tutorial/portal_css/Plone%20Default/tutorial.kss resource type kss
INFO:
Finished loading and processing
http://localhost:9777/tutorial/portal_css/Plone%20Default/tutorial.kss
resource type kss in 31 + 0 ms
INFO: Starting setting up events for document
DEBUG: Binding 0 special rules in grand total
DEBUG: Binding to 0 nodes in grand total
INFO: Finished setting up events for document in 1 ms

This means that your kss file is active on the page, although it is yet not doing anything. At this point you can proceed to the next chapter.

REMARK: If you place your file on your filesystem skins directory, you should call it as tutorial1.kss.dtml, otherwise it will not  appear  in Plone. We will solve this problem, in case there is a way to register a new file type with CMS.

(optional:) Doing it the zope3 way

In the zope3 style of development instead of putting files into skins, we prefer to use resources. From the point of view of kss this is all the same but this leads to a cleaner development style, better supported in the future versions of Plone. Do not attempt to do this however if you do not know at least a little of Five, because in this tutorial we will not teach you Five itself, we only show the way to use it for kss. Remember: zope3 development style is easy once you have learned it,  but one might feel that it has a steep learning curve.

To do this, you have to create a new product for the tutorlal or use one of your existing products. In the product directory on the filesystem, create a browser subdirectory and save the kss file there with the name tutorial1.kss. Then in the product root create a configure.zcml file with the following content:

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

  <!-- the kss resource -->
  
  <browser:resource
    file="browser/tutorial1.kss"
    name="tutorial1.kss"
   />

</configure>

After this you need to restart zope: if you have made an error in this file you see it immediately as zope will refuse to start at all. If zope has started up, then check that the url <portal_root>/++resource++tutorial1.kss returns the kss file correctly from the browser (replace the beginning with your portal root url).

Also to use this file you must use ++resource++tutorial1.kss as the name of the file in the portal_css tool. After making this change you should reload your page from the browser, open the loggingpane and see the log messages like above. (If this does not work, read here about the required patch of ResourceRegistries).

In addition, since now you have a separate tutorial product, you could also make a plone Install.py script that automatically registers the kss resource with the css tool. To have an example of this, you may want to peek in to some of our example products in the bundle and borrow some working code from there. - However this step is totally optional and you might want to skip it at this point.

Write a simple event rule

Now we will add a KSS event rule to the kss file we created. This is the base unit that controls the dynamic behaviour of your page. A KSS rule looks similarly to a css  There is a selector part that selects one or more html nodes just like in css, then there is an event descriptor that is attached to the css selector with the comma. We will use the click event that will trigger when the selected node or nodes are clicked with the mouse.

First we decide which nodes we bind to . This can be any selectable element in the page. Let us first bind the event to the active element of the navtree - that is, the element where we are at the moment. Inspecting the page we will see the html of the required line:

<a title="" href="http://localhost:9777" class="navTreeCurrentItem visualIconPadding">
    Home
</a>

We can see that the selector of this node can be, for example, a.navTreeCurrentItem so this will be the selector we use. The full event rule that we enter into the kss file will be this:

a.navTreeCurrentItem:click {
    action-client: alert;
}

Notice that after the selector we put :click, this tells kss what event to use and is always obligatory in the kss rule. Between the braces we have various properties that control what actions are bound to the selected nodes, and also the parameters for this actions. This rule says that when the event gets triggered, we do not want to communicate with the server yet, but simply pop up an alert box. This is just a debugging aid that helps us see if we are on the right track. The line action-client: alert; says we have a client action with the name alert. Later we will learn to use server actions.

Now reload the page, start the loggingpane and you should see the following log:

INFO: Initializing kukit
INFO: actions for Plone legacy js registered (initialize collapsible)
WARNING: addDOMLoadEvent is not found in PloneAzax, skipping DOMLoad activation (add event-registration.js to ResourceRegistries?)
INFO: actions for Plone legacy js registered (bind menus)
INFO: PloneAzax initializeMenus 3
INFO: Nr of Rule Sheet Links: 1
INFO: Start loading and processing http://localhost:9777/tutorial/portal_css/Plone%20Default/tutorial.kss resource type kss
DEBUG: EventRule #0: a.navTreeCurrentItem EVENT=click
INFO: Finished loading and processing http://localhost:9777/tutorial/portal_css/Plone%20Default/tutorial.kss resource type kss in 31 + 2 ms
INFO: Starting setting up events for document
DEBUG: EventRule #0 mergeid @@0@@click selected 1 nodes
DEBUG: Binding 0 special rules in grand total
DEBUG: instantiating event id=@@0, classname=0, namespace=null
DEBUG: Binding to 1 nodes in grand total
INFO: Finished setting up events for document in 34 ms

Important is to see that our newly created eventrule is in effect  (EventRule #0),  and that it is bound to 1 node in the page. The rest of the log can be ignored right now.

REMARK: If the new contents of the kss file does not come into effect, there is a problem. The forced browser reload should be sufficient, however some users experience that it does not help but setting "Caching enabled" to False in the ResourceRegistries solves the problem.  However we do not suggest this practice and further investigation is required in this subject.

If we click on the Home line in the navtree portlet (or to the item line which is current and highlighted), the following popup dialog  appears:

This  tells us that the event has triggered in order, and also gives some additional information, like the number of the event rule (#0) and the html node that triggered the event (A).

After pressing the OK button, the page will be reloaded because the link will be followed as if we would have clicked it normally. We will deal with this soon.

We should however note an important principle right away. If the rule does not select to any nodes, simply nothing happens: no error message will be raised. This is the designated behaviour and it is in line with how css behaves too.  This is what allows us to put a lot of rules into the same kss file. No need to set up conditions: if the selected nodes are not present in the current page, simple nothing happens.

This is also the time to see what happens if we have an error in the kss file. Let us change click to klick and reload the page. We will get a javascript error, in FireFox for example:

[Exception... "'Error parsing kss at
http://localhost:9777/tutorial/portal_css/Plone%20Default/tutorial.kss
: ParsingError: Undefined event name="klick", namespace="null" at
position 0' when calling method: [nsIDOMEventListener::handleEvent]"
nsresult: "0x8057001e (NS_ERROR_XPC_JS_THREW_STRING)" location:
"<unknown>" data: no]

We get the same message also appearing in the loggingpane (in case we do not see the javascript error in the browser):

NFO: Nr of Rule Sheet Links: 1
INFO: Start loading and processing http://localhost:9777/tutorial/portal_css/Plone%20Default/tutorial.kss resource type kss
DEBUG: EventRule #0: a.navTreeCurrentItem EVENT=klick
FATAL: Error parsing kss at
http://localhost:9777/tutorial/portal_css/Plone%20Default/tutorial.kss
: ParsingError: Undefined event name="klick", namespace="null" at
position 0

The important part of the message says that the klick global event does not exist, the rest is just FireFox cruft. If we just make a syntax error, we get a ParsingError that also give the position of the error in the file. As a consequence nothing will work and we are forced to fix the error immediately and reload the page afterwards.

Specify an event binding parameter

Sometimes it is necessary to customize the way the event is bound. This can be done with parameters with the event binding. In the previous example after we closed the alert, the page reloaded because the link was followed by default. The click event has a parameter preventdefault which can be used to override this. The modified rule will be:

a.navTreeCurrentItem:click {
    evt-click-preventdefault: True;
    action-client: alert;   
}

The full property name is evt-click-preventdefault where three segments are separated with dashes:

• evt says this is an event binding parameter
• click is just thename of the event, it has no semantic meaning other than to increase readibility
• the last segment is the name of the parameter itself that we are setting.

It is entirely up to each event which parameters they take and which ones are obligatory, or which ones have a default value. At the moment the preventdefault event is only usable for the click event and it has a default value of False. Obviously it may only be necessary to set this parameter if there is otherwise something that the browser wanted to do on the click, before we started to modify its behaviour.

The order of the lines within the rule block otherwise does not matter.

If we reload the page, after clicking on the link the alert will pop up but afterwards the link will not be followed.

Specify an action parameter

We can also specify parameters to the actions themselves. The main difference between the event binder and the action parameters is, that the previous ones are effective when the event is bound (i.e. when we load the page) while the latter ones come to effect when the event is triggered (i.e. when we clicked on the link). As was the case with the event parameters, it is entirely up to the given action to decide what parameters it accepts and handles. Now, the alert action just happens to accept a message parameter, so we extend our rule with one line:

a.navTreeCurrentItem:click {
    evt-click-preventdefault: True;
    action-client: alert;
    alert-message: "Hey, we are here";
}

The property name was alert-message, the semantics is that we must always use the name of the action (alert) followed by a dash and the name of the parameter. Notice also that we stringified the value on the right side: this is only necessary if the value is not a single word. Both single and double quotes can be used and the quotes can also be used backslashed inside the string.

Reload a page, click on the link and see the alert popup appearing with the text we specified, with debug information added to the end of it:

This may also be the right moment to experiment if caching is not keeping you away from seeing your changes immediately. Principally, during development, when you have modified and saved the kss file, after reloading the page you should have the new values in effect - if you assure this, you will save yourself from a lot of headache.

You have learned the basics of setting up kss rules so far, but nothing that would really do anything so far. It is now time to sit back and relax a bit before we get to the definition and usage of server actions. Continue...