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:
http://kssproject.org
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:
.. code-block:: python
...
install_requires=['setuptools',
'grok',
'megrok.kss', # <---
],
...
Now run `buildout` with:
.. code-block:: bash
$ 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 `` section of the template, include the following lines:
.. code-block:: html
Include a kinetic stylesheet with this line of code:
.. code-block:: html
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:
.. code-block:: html
hallo
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:
.. code-block:: css
#click-me:click {
action-server: welcome url(index/@@welcome);
}
Create a `KSSActions` view in `app.py` with code like this:
.. code-block:: python
from megrok.kss import KSS
class AppKSS(KSS):
grok.view(Index)
def welcome(self):
core = self.getCommandSet('core')
core.replaceHTML('#click-me', '
ME GROK KISSED !
')
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:
.. code-block:: html
Click me to toggle my border.
Then, in the `` section, add the style linked to the class that will be toggled:
.. code-block:: html
Finally, add the client-side rule to the KSS (`app.kss`):
.. code-block:: css
/* 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.