Adding AJAX to Grok with KSS¶
| Author: | kteague |
|---|
If you want to use Ajax functionality inside a Grok application with an approach that insulates you as much as possible from coding in Javascript, then KSS (kinetic style sheets) is for you.
KSS uses an interpreter, implemented with Javascript, that runs the KSS rules. KSS rules themselves look very much like CSS (Cascading style sheets) rules. So a web developer familiar with CSS feels quite 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:
Create a sample KSS project¶
Create a buildout for your sample kss application with grokproject:
grokproject ksssample
Edit the Configuration file¶
Add megrok.kss to setup.py:
...
install_requires=['setuptools',
'grok',
'megrok.kss', # <---
],
...
Now run buildout with:
$ bin/buildout
Introductory Example¶
Lets first design a very simple example. On a simple web page, add a div with text inside. We want that when the user clicks inside this div, its text is changed into something which comes from the server. This is the classic Ajax server request example.
To begin with this example, we first have to prepare the template to make the page KSS aware:
You add the reference to KSS engine Javascript files in your application template index.pt. (grokproject should have created it in the app_templates subdirectory of src/ksssample.)
In the <head> section of the template, include the following lines:
<tal:kss_javascript replace="structure context/@@kss_javascript" />
Include a kinetic stylesheet with this line of code:
<link tal:attributes="href static/app.kss" rel="kinetic-stylesheet" type="text/kss" />
The kss file is being cached by your browser. So, to be able to work with kss, disable your browser cache to avoid tearing you hair out asking yourself why your kss changes are not picked up!
Include the div somewhere in the body of the template, give it a unique id that you can use to associate with KSS behaviour:
<div id="click-me">hallo</div>
Create a directory called static in the root of your Grok application, if it doesn’t already exist. Then create a file app.kss in this static folder:
#click-me:click {
action-server: welcome url(index/@@welcome);
}
Create a KSSActions view in app.py with code like this:
from megrok.kss import KSS
class AppKSS(KSS):
grok.view(Index)
def welcome(self):
core = self.getCommandSet('core')
core.replaceHTML('#click-me', '<p>ME GROK KISSED !</p>')
Now, you can run your application and test whether KSS is working by clicking the div and seeing whether the text is replaced by ME GROK KISSED, which should occur without the page having to be refreshed!
Client-side action¶
In some cases, modifications of the UI do not need to notify or get information from the server. KSS offers client-side actions: action-client in the KSS rules.
Let’s build an example where clicking on a tag toggles on or off the presence of a class on the given tag (and of its CSS styling).
Add the needed markup in the application template:
<div id="toggle-me">Click me to toggle my border.</div>
Then, in the <head> section, add the style linked to the class that will be toggled:
<style type="text/css">
.border {
border: medium solid rgb(255,0,0);
}
</style>
Finally, add the client-side rule to the KSS (app.kss):
/* Toggle a class on and off */
#toggle-me:click {
action-client: toggleClass;
toggleClass-value: border;
}
Now refresh the page in your browser (you do not need to restart your application since you did not touch Python code) and test how clicking the new text displays or hides a red border around it.
That’s all for now.
Further examples can be found on http://codespeak.net/svn/kukit/kss.core/trunk/kss/core/plugins/core/demo/.
Using the Firebug Javascript debugger for development¶
KSS comes in two modes: production mode and devel mode.
In development mode, KSS logs a lot of messages to the firebug console. They help a lot for debugging during KSS development.
You can use @@kss_devel_mode/ui url to access the UI that sets up the development mode.
