Grok Newbie KSS Tutorial

This tutorial is outdated !

See last version at

http://grok.zope.org/documentation/how-to/adding-ajax-with-kss-to-grok

Introduction

If you want to use Ajax functionality inside a grok application grok uses an approach that separates you from coding in javascript as much as possible. KSS (kinetic style sheets) realizes just this with help of an in javascript implemented interpreter that runs the KSS rules. KSS rules themselves look like css rules. So a web developer that is familiar with css feel quit comfortable with the KSS syntax.

KSS is an independent project which can be used with different web frameworks. You can find information, documentation and tutorial about KSS on

http://kssproject.org

To use KSS inside grok you has to install KSS into a working grok project.

Installation

Create a sample kss project

Create a buildout for our sample kss application with grokproject:

grokproject ksssample

Install kss.core and megrok.kss

Install the kss.core and the megrok.kss packages into your ksssample buildout.

Go to the grok application directory (ksssample) and checkout the current svn trunks:

svn co http://codespeak.net/svn/kukit/kss.core/trunk kss.core
svn co svn://svn.zope.org/repos/main/megrok.kss/trunk megrok.kss

Edit the Configuration files

Add kss.core and megrok.kss to buildout.cfg:

[buildout]
develop = . kss.core megrok.kss

Add megrok.kss to setup.py:

...
install_requires=['setuptools',
                  'grok',
                  'megrok.kss', # <---
                  ],
...

Add megrok.kss to your app configure.zcml (located in src/ksssample):

<include package="megrok.kss" />

The file configure.zcml should look like this:

<configure xmlns="http://namespaces.zope.org/zope"
        xmlns:grok="http://namespaces.zope.org/grok">
   <include package="grok" />
   <include package="megrok.kss" />
   <grok:grok package="." />
</configure>

Now run buildout with:

bin/buildout

Introductory Example

Lets first design a very simple example. On a simple web page there should be a div with text inside. if the user clicks inside this div it changes the text into something which comes from the server. It is the classical Ajax server request stuff.

To solve this problem we have to prepare the template to make it KSS aware first:

Include the reference to KSS javascript files in your application template. The application template index.pt should be created by grokproject in a subdirectory of src/ksssample with name app_templates. Include in the <head>-section of this template the following lines:

<tal:kss_javascript replace="structure context/@@kss_javascript" />

Include a kinetic stylesheet with code like:

<link tal:attributes="href static/app.kss" rel="kinetic-stylesheet" type="text/kss" />

Include the div somewhere in the body of the template:

<div id="click-me">hallo</div>

Create a static directory in your grok root (sibling of app_templates).

Create a file app.kss in folder static:

#click-me:click {
     action-server: welcome;
}

Create a KSSActions view in app.py with code like:

from megrok.kss import KSSActions

class AppKSS(KSSActions):

    def welcome(self):
        core = self.getCommandSet('core')
        core.replaceHTML('#click-me', '<p>ME GROK KISSED !</p>')

Further examples can be found on http://codespeak.net/svn/kukit/kss.core/trunk/kss/core/plugins/core/demo/. (But they are not grokked ;-) yet.

Using the Firebug Javascript debugger for development

KSS comes in two modes: production mode and devel mode. In the devel mode there will be a lot of helpful messages on the firebug console generated that help a lot for finding bugs in the KSS development.

You can use @@kss_devel_mode/ui url to access the UI that sets up the devel mode.