Javascript sucks, but it's what we're stuck with.

KSS accepts this and tries to make the best of a bad deal by allowing (Plone) developers to add dynamic elements to pages using the technologies they are already familiar with, namely CSS and Python.

The server-side of KSS is extremely powerful, as it allows full DOM manipulation using python. KSS takes your python code and produces on-the-fly javascript tailor-made to the browser of the end user. It is (fairly) complicated to set up the interactions between python, KSS and your site - especially if your requirements are quite simple.

However, you can achieve quite powerful dynamic effects by simply defining CSS classes which change the properties of elements on your page (colours, visibility etc.) and then using the client-side of KSS to add/remove/toggle these classes on user interaction.

This is much simpler to set up, and allows you to quickly take advantage of the cross-browser javascript support built right into KSS, which is built right into Plone, so there's no need for any external JS libraries or helpers, and no need to manually attach any scripts to your page!

Step 1: Define your CSS

Create your CSS styles, specifying the properties you want to control on your page. For example, I may have a page of headed lists, the contents of which I want to show/hide when the user clicks on the relevant heading:

--- mylists.pt ---

<div class="mylist">
<h2>A few of my favourite things</h2>
<ul>
  <li>Raindrops on roses</li>
  <li>Whiskers on kittens</li>
  <li>Bright copper kettles</li>
  <li>Warm woolen mittens</li>
</ul>
</div>

--- mylists.css ---

div.mylist {
 /* default styles here */
 ...
}
div.mylist.closed ul {
  display: none;
}

Here I have specified that when the outer div has the class 'closed', all lists (ul elements) are hidden. KSS will be used to toggle this class when the user clicks on the 'h2' element.

Step 2: Create your KSS

--- mylists.kss ---

div.mylist h2:click {
   evt-click-preventdefault:      true;
   evt-click-allowbubbling:       true;
   action-client:                      toggleClass;
   toggleClass-kssSelector:    parentnode('div');
   toggleClass-value:             closed;
}

We start by defining a CSS-style selector (div.mylist h2) to specific what elements to apply this KSS action to. We add a ':click' to the end to specify that the action should occur when the user clicks on any element that matches the CSS selector.

The first and second lines of the KSS action are not necessary here, but included for reference. The first line (evt-click-preventdefault) is useful for overriding the action of a page link (a). If we wanted our action to occur when the user clicked on a link, and we didn't want the page to advance to the link href, we would set this value to true. The second line (evt-click-allowbubbling) refers to the event ordering model, which you can probably ignore, or read more about here: http://www.quirksmode.org/js/events_order.html

The third line (action-client) specifies the built in KSS action to execute. Some useful examples are addClass, removeClass and toggleClass. Here we are using 'toggleClass', as we want to toggle the visibility of the lists when we click on the heading.

The fourth line is optional, and defines the element that the 'action-client' should apply to. If we left this blank, then the action would be applied to the element that fired the event (in this case, the 'h2' element). In our example, we want to change the class of the containing div, so we used another KSS built-in function 'parentnode', and pass in the string of 'div' to say that we want the closest parentnode of the source element that is a 'div'.

Finally, the fifth line allows us to provide an argument to the action-client, in this case the name of the class we want to toggle, 'closed'.

Step 3: Register your KSS

In order to get your new KSS to load, we need to add it into the 'portal_kss' tool, either by using the ZMI or through generic setup. To use GS, add the following file to your profile, where the 'id' attribute is the name of your KSS file (if it's in a skin layer, or the resource id if you have registered it as a browser resource) :

--- kssregistry.xml ---

<?xml version="1.0"?>
<object name="portal_kss" meta_type="KSS Registry" autogroup="False">

 <kineticstylesheet
    cacheable="True" compression="safe" cookable="True"
    enabled="True" expression=""
    id="mylists.kss"
    />

</object>

You will then need to reinstall your product, or use 'portal_setup' to import the KSS step and read in your new xml file. You will either need to restart zope, or stick 'portal_kss' into development mode so that your changes can be seen.

Step 4: Go Go Go!

If all has gone well, clicking on the headings of your page should toggle the contents of the lists! If it doesn't go so well, then I'd recommend the following:

Firebug

(http://getfirebug.com/) for inspecting the DOM and SO much more.

Firekiss

(http://kssproject.org/download) for inspecting your KSS files using firebug

KSS Project

(http://kssproject.org/) for more information

Google

(http://www.google.com/) because the KSS project documentation is not exactly comprehensive yet ;)