README.md 4.08 KB
Newer Older
Thimo Kraemer's avatar
Thimo Kraemer committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
About
=====

**KSS-RPC** (Kinetic Style Sheets RPC) is a framework that allows Ajax development
without writing more Javascript. It uses stylesheets with CSS-compliant syntax to
declare behaviours in the client and a set of well-defined DOM-like commands that
are sent back from the server to manipulate the HTML page. A decided advantage of
KSS is the fact that all the client-side logic can be shifted to the server-side.

The idea of KSS-RPC is based on the original [KSS project][] ([PyPI][]) which is
pretty much dead. So KSS-RPC is a complete rewrite of this library, currently in beta state.
It is also somewhat comparable to [Xajax][], [phery.js][] and [Jaxon][] for PHP or [Sajax][], [Sijax][]
and [Dajax][] for Python. But KSS differs in the way that it is basically independent
from the server-side programming language and all the client-side event bindings
are done through centralized stylesheets.

[KSS project]: http://kssproject.org/
[PyPI]: http://pypi.python.org/pypi/kss.core/
[Xajax]: http://www.xajax-project.org/
[phery.js]: http://phery-php-ajax.net/
[Jaxon]: https://www.jaxon-php.org/
[Sajax]: https://github.com/harkenn/sajax
[Sijax]: https://github.com/spantaleev/sijax-python
[Dajax]: https://github.com/jorgebastida/django-dajax

Features
========

Thimo Kraemer's avatar
Thimo Kraemer committed
29
- Supported protocols: JSON-RPC, XML-RPC and plain JSON- or URL-encoded requests
Thimo Kraemer's avatar
Thimo Kraemer committed
30 31 32 33 34 35 36 37 38 39 40 41
- Supports all modern browsers inclusive IE9+ (IE8 with polyfills)
- Independent from any third-party JavaScript library
- Optional supported selector engines: [Sizzle][] (jQuery) and [Slick][] (MooTools)
- Supported animation libraries: [Velocity][], [GreenSock][], [jQuery][] and [MooTools][]

[Sizzle]: http://sizzlejs.com/
[Slick]: https://github.com/mootools/slick
[Velocity]: http://velocityjs.org/
[GreenSock]: https://greensock.com/docs/#/HTML5/Animation/TweenMax
[jQuery]: http://api.jquery.com/animate
[MooTools]: https://mootools.net/core/docs/1.6.0/Fx/Fx.Morph

Thimo Kraemer's avatar
Thimo Kraemer committed
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
Integration
===========

```html
<script type="text/javascript" src="/path/to/kss.min.js"></script>
```

Activating the MutationObserver:

```html
<script type="text/javascript" src="/path/to/kss.min.js"></script>
<script type="text/javascript">
    kss.useObserver = true;
</script>
```

Using the MutationObserver has the advantage that KSS is notified about all
DOM manipulations even if modified by third-party scripts.
MutationObservers are available from IE11.
There exists a [polyfill for IE9-10](https://github.com/googlearchive/MutationObservers)

Thimo Kraemer's avatar
Thimo Kraemer committed
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
Example
=======

Assume you have the following tiny web application.

A basic HTML document named *index.html*:

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <link type="text/kss" rel="kinetic-stylesheet" href="ajax.kss" />
    <script type="text/javascript" src="kss.min.js"></script>
    <title>KSS example</title>
</head>
<body>
    <p id="result">KSS example</p>
    <form id="myform" data-counter="0">
        <input type="text" name="text" id="text" value="World" />
        <input type="button" id="process" value="Go" />
    </form>
</body>
</html>
```

Some KSS in a file named *ajax.kss*:

```css
@config {
    protocol: url-encoded;
    date-encoding: iso8601;
    timeout: 5000;
}

#process:click,
#myform:submit {
    evt-preventdefault: true;

103
    kss-action-server: service.php;
Thimo Kraemer's avatar
Thimo Kraemer committed
104 105 106
    text: formVar("text");
    counter: dataAttr("counter", true);
}
Thimo Kraemer's avatar
Thimo Kraemer committed
107 108 109 110 111

body:error {
    kss-action-client: alert;
    message: errorAttr("message");
}
Thimo Kraemer's avatar
Thimo Kraemer committed
112 113 114 115 116 117 118 119 120
```

Finally a PHP script named *service.php* that responds with some KSS commands:

```php
<?php

require 'kss.php';

121 122
$counter = $_POST['counter'] + 1;
$message = 'Hello '.$_POST['text'].'! ('.$counter.')';
Thimo Kraemer's avatar
Thimo Kraemer committed
123

124
$kss = new KSSResponse();
Thimo Kraemer's avatar
Thimo Kraemer committed
125

126 127 128
$kss->replaceInnerHTML('#result', array(
    'html'=>$message,
));
Thimo Kraemer's avatar
Thimo Kraemer committed
129

130 131 132 133
$kss->setDataAttr('#myform', array(
    'name'=>'counter',
    'value'=>$counter,
));
Thimo Kraemer's avatar
Thimo Kraemer committed
134

135
$kss->focus('#text');
Thimo Kraemer's avatar
Thimo Kraemer committed
136

137
$kss->send();
Thimo Kraemer's avatar
Thimo Kraemer committed
138 139 140 141 142

?>
```

And [this](http://php.joonis.de/kss/index.html) is what you get ...
Thimo Kraemer's avatar
Thimo Kraemer committed
143 144 145 146 147 148 149


ToDo
====

- Testcase
- Code documentation
Thimo Kraemer's avatar
Thimo Kraemer committed
150
- Make the Drag-n-Drop plugin supporting files