[KSS-checkins] r51213 - kukit/kss.base/trunk/docs

[jvloothuis at codespeak.net]

Author: jvloothuis
Date: Sat Feb  2 16:59:30 2008
New Revision: 51213

Added:
   kukit/kss.base/trunk/docs/protocol.txt
Log:

Added a doc about the protocol


Added: kukit/kss.base/trunk/docs/protocol.txt
==============================================================================
--- (empty file)
+++ kukit/kss.base/trunk/docs/protocol.txt	Sat Feb  2 16:59:30 2008
@@ -0,0 +1,94 @@
+============
+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.
\ No newline at end of file