============
KSS protocol
============

HTTP is used to let a browser and server communicate. Messages from
the browser to the server are send using normal HTTP POST
request. This means that you can use your server side framework just
like you would when you would process a form.

--------
Response
--------

The response from the server should be an XML document. For this there
are is a specific HTTP response header which needs to be set. This
header is the `content-type` and should be set to `text/xml`.

An example of a message body is shown below::

  <kukit xmlns="http://www.kukit.org/commands/1.1">
    <commands>
      <command selector="div#copy" name="copyChildNodesTo"
               selectorType="">
        <param name="html_id">demo</param>
      </command>
      <command selector="div#copy" name="clearChildNodes"
               selectorType="">
      </command>
    </commands>
  </kukit>

All KSS responses should be valid XML documents. This means that
values passed from the server to the browser should be properly
escaped. More on this later in the section `Escaping data`.

The first line from the response is the container element. Next to
this it should also specify the version of the protocol used like in
the example.

Next is the `commands` element. This is the container for all commands
which should be executed by the browser. The sequence of the commands
within this element is significant. Topmost commands are executed
before commands lower in the document.

Each command is represented by a `command` element. There are
currently two types of commands, element bound (command which will be
executed on zero to many nodes) and global command.

For a global command only the name is required. An element bound
command needs a `name` and a `selector`. The `selectorType` is
optional and defaults to the CSS selector.

Parameters for a command are located within the command node. These
can be repeated for each parameter required for the command. A
parameter element should have a `name`. This name is used for creating
a keyword argument. The value of each parameter is its contents. This
contents should be a text or CDATA node.


-------------
Escaping data
-------------

Since the message format of KSS is XML all data send from the sever
should be properly escaped. Next to making sure that the data is valid
there are also a few other concerns. The next few paragraphs will
explain the guidelines for implementing the protocol. Note that these
are not hard requirements but rather a set of know browser issues and
their workarounds or things that have proven usefull in practise.


Readable data
-------------

One thing which is not a hard requirement is having the response XML
as human readable as possible. This is usefull when using tools like
Firebug so one can easy inspect the response XML.

To make the message as readable as possible escape all parameter
values which are (X)HTML with CDATA sections.

All other parameter values should be represented as text nodes. Do not
forget to escape these where appropriate using normal XML escaping
rules.


CDATA for large values
----------------------

Parameter values which exceed 4 kilo byte should always be represented
as CDATA nodes. The reason for this is that there is a bug in Firefox
which causes large text nodes to be split up. This in turn results in
parsing problems for the browser and usually means that commands stop
executing like expected.