==============
KSS for Django
==============

This document explains how to use KSS with your Django application.


Setting up
==========

Before we can start you need to have a few things setup. The first
thing is setuptools [URL]. After this you can install `kss.django`
with this command:

  $ easy_install kss.django

This will also download and install `kss.base` which is needed because
`kss.django` is only a thin wrapper around `kss.base`.


Configuring your settings
-------------------------

You can now add the `kss.django` app to `INSTALLED_APP` in your
settings file. After this you need to load at least one plugin. We
will just load the `core` plugin now which is shipped with the base
system. Add the following lines somewhere to your settings file::

  from kss.django import load_plugins
  load_plugins('kss-core')

  KSS_BASE_URL = 'http://localhost:8000/ajax/'

The last line set the base url for all Ajax requests. Point this to
your Django application server.

After this you have two possible routes to follow. The steps described
below assume you want to let Django serve the Javascript
files. Another possibility is to put the Javascript into your media or
other folder. To learn how to do this you should read the section on
creating a package with the static files.

Remember to come back here after that tutorial since the rest of this
tutorial also explains how to use KSS, no matter how you deploy your
Javascript.


Urls
----

The next thing to do is to add the KSS views to your
configuration. Add the following line to your urlpatterns::

  (r'^kss/', include('kss.django.urls')),

After this you should be done with the setup process.


KiSSing your application
========================

Now it is time to add some Ajax behaviour to your application. To
start out we first need to make sure that all the KSS scripts are
loaded. These need to be included from the HTML. Therefore you need
open your master template (usually called base.html).

At the top of this template add the following line::

  {% load ksstags  %}

This loads the tags library we need for the next section. Add the
following two lines anywhere within your header (`<head>...</head>`)::

    {% kss_extra_scripts %}
    {% kss_js %}
    {% kss_base_url %}

These generate the script tags to load all the Javascript. The last
tag creates the base url for all the calls to the server. This works
just like a normal base for links. The final step is to include a KSS
file. Do this by adding a link element to your header which looks
something like the one you see below::

    <link type="text/kss" rel="kinetic-stylesheet" 
          href="{{ MEDIA_URL }}/myapp.kss"/>

You can pick any name for `myapp.kss` since we are going to create it.

The KSS file
------------

Create a new file called `myapp.kss` in your media directory. For a
simple example paste in the following code::

h1:click {
    evt-click-preventdefault: true;
    action-server: link_clicked;
}

This is just an example and whill make any `h1` element you click send
a message to the server.


Server side
-----------

A view is needed to handle the requests comming from the browser. Add
a view to url config with the `^ajax/left_clicked` regex.

After this create the view function. In the module where you create
the view add the following import statement::

  from kss.django import kss_view

The view code itself should look something like::

  @kss_view
  def link_clicked(request, commands):
      commands.core.replaceInnerHTML('h1', 'Hello World!')


Next step
---------

Start your Django (if you haven't already done so). Now load a page in
your application and click a `h1` element. You should see the message
from the view appear instead of the text you just clicked!

For more documentation on what you can do with KSS visit the KSS
website at::

  http://kssproject.org/


Creating static Javascript files
================================

It is common to deploy static files using a dedicated server or
service. This section describes how to create a package with all the
files needed to run KSS without Django involved in serving the
scripts.

If you have installed `kss.django` you should also automatically have
gotten the `kss.base` package. This in turn has created a script for
you which can create a folder with all the files you need.

You can execute the script like this::

  $ ksspackage output_dir --plugin=core

This will create an output directory with all the Javascripts you
need::

  output_dir
    kss.js
    base2-dom-fp.js
    sarissa.js

If wou want more plugins to be included run the script with multiple
`--plugin` arguments like::

  $ ksspackage output_dir --plugin=core --plugin=someother

Remember to either compress the files using gzip or setup your
webserver for on the fly compression.