Skip to content

kss in general · Changes

Page history
Update kss in general authored by Thimo Kraemer's avatar Thimo Kraemer
Hide whitespace changes
Inline Side-by-side
kss-in-general.md
View page @ a2ab7bb3
......@@ -233,30 +233,30 @@ At-config rule
The main configuration is done within an @config rule:
```css
@config {
protocol: json-rpc;
date-encoding: iso8601;
timeout: 5000;
endpoint: /path/to/service;
}
@config {
protocol: json-rpc;
date-encoding: iso8601;
timeout: 5000;
endpoint: /path/to/service;
}
```
protocol
* protocol
The protocol to use. A value of "json-rpc" (default), "json-rpc-v1",
"json-rpc-v2" (synonym for "json-rpc"), "xml-rpc" or "url-encoded".
The latter can be used if there is no RPC service available.
date-encoding
* date-encoding
How dates should be encoded. A value of "iso8601" (default),
"@timestamp@", "class-hinting" or "asp.net".
timeout
* timeout
The timeout for server actions (defaults to 10000).
endpoint
* endpoint
The endpoint url to the RPC service.
......@@ -271,9 +271,9 @@ specifies the "actions" to happen when this event occurs.
A simple example is this:
```css
#title_save:click {
kss-action-server: saveTitle;
}
#title_save:click {
kss-action-server: saveTitle;
}
```
This binds the node selected by the CSS selector ``#title_save`` to the
......@@ -284,10 +284,10 @@ action must be the name of a remote RPC method.
Another example:
```css
#sportlet-main:timeout {
evt-timeout-delay: 5000;
kss-action-server: refreshPortlet;
}
#sportlet-main:timeout {
evt-timeout-delay: 5000;
kss-action-server: refreshPortlet;
}
```
This binds the ``timeout`` event to the HTML node selected by the
......@@ -330,33 +330,33 @@ define:
A rule follows the following syntax:
```css
[<CSS> <CSS> <CSS> ...] <CSS_SELECTOR>:<KSS_EVENT_NAME> {
[<CSS> <CSS> <CSS> ...] <CSS_SELECTOR>:<KSS_EVENT_NAME> {
/* event parameters */
...
/* event parameters */
...
/* actions (server or client) */
...
}
/* actions (server or client) */
...
}
```
Consider the following example:
```css
div#thisnode a:timeout {
div#thisnode a:timeout {
/* event parameters */
evt-timeout-delay: 3000;
/* event parameters */
evt-timeout-delay: 3000;
/* actions */
/* actions */
kss-action-server: updateInfo;
remark: 'Updating from timeout';
color: red;
kss-action-server: updateInfo;
remark: 'Updating from timeout';
color: red;
kss-action-client: log;
message: 'Updating from timeout';
}
kss-action-client: log;
message: 'Updating from timeout';
}
```
A ``timeout`` event is bound; in this case the ``div#thisnode a`` CSS
......@@ -393,8 +393,8 @@ The full event rule
The name of the event follow the CSS selector after a colon:
```css
div#recent-portlet:click { ... }
div.banner:timeout { ... }
div#recent-portlet:click { ... }
div.banner:timeout { ... }
```
The event name in KSS must be preceded by a normal CSS selector.
......@@ -409,30 +409,30 @@ Specifying parameters
The general schema for the parameter specification:
```css
.... {
evt[-<eventname>]-preventdefault: [true|false];
evt[-<eventname>]-preventbubbling: [true|false];
evt[-<eventname>]-allowbubbling: [true|false];
evt-<eventname>-<key>: <value>;
kss-selector: <selector>;
kss-precondition: [true|false];
...
kss-action-[server|client]: <actionname>;
kss-selector: <selector>;
kss-precondition: [true|false];
kss-includeform: [<form_name>|@currentform];
<key1>: <value1>;
<key2>: <value2>;
...
kss-action-[server|client]: <actionname>;
kss-selector: <selector>;
kss-precondition: [true|false];
kss-includeform: [<form_name>|@currentform];
<key1>: <value1>;
<key2>: <value2>;
...
}
... {
evt[-<eventname>]-preventdefault: [true|false];
evt[-<eventname>]-preventbubbling: [true|false];
evt[-<eventname>]-allowbubbling: [true|false];
evt-<eventname>-<key>: <value>;
kss-selector: <selector>;
kss-precondition: [true|false];
...
kss-action-[server|client]: <actionname>;
kss-selector: <selector>;
kss-precondition: [true|false];
kss-includeform: [<form_name>|@currentform];
<key1>: <value1>;
<key2>: <value2>;
...
kss-action-[server|client]: <actionname>;
kss-selector: <selector>;
kss-precondition: [true|false];
kss-includeform: [<form_name>|@currentform];
<key1>: <value1>;
<key2>: <value2>;
...
}
```
The keys and action names can be in camelcase (CamelCase). Although
......@@ -443,10 +443,10 @@ identifier, they are allowed in KSS.
binding itself. There are different possibilities to declare them:
```css
evt-preventdefault: true;
evt-preventdefault: false;
evt-click-preventdefault: true;
evt-submit-preventdefault: true;
evt-preventdefault: true;
evt-preventdefault: false;
evt-click-preventdefault: true;
evt-submit-preventdefault: true;
```
Declarations with omitted event names are applied to all event types
......@@ -457,14 +457,14 @@ action must be a server or a client action. It is possible to
have more than one event action within a rule:
```css
#thisnode:timeout {
kss-action-server: updateInfo;
remark: 'Updating from timeout';
color: red;
kss-action-client: log;
message: 'Updating from timeout';
}
#thisnode:timeout {
kss-action-server: updateInfo;
remark: 'Updating from timeout';
color: red;
kss-action-client: log;
message: 'Updating from timeout';
}
```
Parameter producer functions
......@@ -474,11 +474,11 @@ A value simply represents a value. Quotes are optional, but as seen
in this example, both single and double quotes can be used also:
```css
... {
size: 12pt;
typeface: "Bitstream Vera Sans";
typeface: 'Bitstream Vera Sans';
}
... {
size: 12pt;
typeface: "Bitstream Vera Sans";
typeface: 'Bitstream Vera Sans';
}
```
It is possible to create extensions to acquire a parameter in another
......@@ -489,10 +489,10 @@ consideration. We show some examples here, and we will give the
complete list of the selectors, too, later:
```css
... {
node_id: nodeAttr(id);
rownum: dataAttr("rownum", true);
}
... {
node_id: nodeAttr(id);
rownum: dataAttr("rownum", true);
}
```
The parameter producer functions operate on the scope of the
......@@ -521,10 +521,10 @@ the event was triggered. With ``kss-selector``, we can execute
the action on a different or multiple nodes:
```css
... {
kss-action-client: actionName;
kss-selector: selector;
}
... {
kss-action-client: actionName;
kss-selector: selector;
}
```
### kss-precondition
......@@ -533,10 +533,10 @@ the action on a different or multiple nodes:
in a rule if its value evaluates to ``false``:
```css
... {
kss-action-server: actionName;
kss-precondition: confirm('Are you sure?');
}
... {
kss-action-server: actionName;
kss-precondition: confirm('Are you sure?');
}
```
### kss-includeform
......@@ -547,10 +547,10 @@ action: all field variables of the form are added with their
name as they appear in the form:
```css
... {
kss-action-server: actionName;
kss-includeform: formname;
}
... {
kss-action-server: actionName;
kss-includeform: formname;
}
```
The value of the declaration can specify to submit a given form
......@@ -558,8 +558,8 @@ or the current form (in which the event has been triggered).
Variations can be seen in the next example:
```css
kss-includeform: formname;
kss-includeform: @currentform;
kss-includeform: formname;
kss-includeform: @currentform;
```
Summarizing the rule definition basics
......@@ -568,12 +568,12 @@ Summarizing the rule definition basics
A complete example rule follows here:
```css
div#portlet-recent:timeout {
evt-timeout-delay: 2000;
kss-action-server: replaceMacro;
selector: #portlet-recent;
macropath: portlet_recent/macros/portlet;
}
div#portlet-recent:timeout {
evt-timeout-delay: 2000;
kss-action-server: replaceMacro;
selector: #portlet-recent;
macropath: portlet_recent/macros/portlet;
}
```
Here, ``delay="2000"`` is used as a parameter for the binding of the
......@@ -586,12 +586,12 @@ server.
Another example:
```css
div.menu-item:load {
kss-action-server: replaceWithRenderedText;
text: textContent();
size: 12pt;
typeface: "Bitstream Vera Sans";
}
div.menu-item:load {
kss-action-server: replaceWithRenderedText;
text: textContent();
size: 12pt;
typeface: "Bitstream Vera Sans";
}
```
How rule merging is done
......@@ -609,10 +609,10 @@ It is possible to attach error handlers to server actions.
This is implemented as an additional event type ``error``:
```css
body:error {
kss-action-client: alert;
message: errorAttr('message');
}
body:error {
kss-action-client: alert;
message: errorAttr('message');
}
```
The error actions can accept the special parameters provider ``errorAttr``
......@@ -666,10 +666,10 @@ A parameter provider looks like a function with a number of
parameters, and can stand in place of the value of a parameter:
```css
... {
kss-action-server: doIt;
whatisit: parmProvider(arg1, arg2, ... argN);
}
... {
kss-action-server: doIt;
whatisit: parmProvider(arg1, arg2, ... argN);
}
```
There are two standard examples used most often.
......@@ -678,16 +678,16 @@ In the first case, we want to take an attribute of a node.
HTML:
```html
<div id='our-node'>The content</div>
<div id='our-node'>The content</div>
```
KSS:
```css
div#our-node:click {
kss-action-server: doIt;
id: nodeAttr('id');
}
div#our-node:click {
kss-action-server: doIt;
id: nodeAttr('id');
}
```
We won't examine this line-by-line, at this point, but the important
......@@ -705,16 +705,16 @@ the ``dataAttr`` parameter provider.
HTML:
```html
<div id='our-node' data-marker='marker-id'>The content</div>
<div id='our-node' data-marker='marker-id'>The content</div>
```
KSS:
```css
div#our-node:click {
kss-action-server: doIt;
marker: dataAttr('marker');
}
div#our-node:click {
kss-action-server: doIt;
marker: dataAttr('marker');
}
```
The value 'marker-id' is marshalled to the doIt action. We can
......@@ -731,20 +731,20 @@ happens anywhere inside the widget.
HTML:
```html
<div id='our-node' data-widgetid="widget2000">
<a class='link' href='firstpage.htm'>First page</a>
<a class='link' href='secondpage.htm'>Second page</a>
</div>
<div id='our-node' data-widgetid="widget2000">
<a class='link' href='firstpage.htm'>First page</a>
<a class='link' href='secondpage.htm'>Second page</a>
</div>
```
KSS:
```css
a.link:click {
kss-action-server: doIt;
href: nodeAttr(href);
widgetid: dataAttr('widgetid', true);
}
a.link:click {
kss-action-server: doIt;
href: nodeAttr(href);
widgetid: dataAttr('widgetid', true);
}
```
The second parameter in ``dataAttr('widgetid', true)`` tells KSS to look
......@@ -787,14 +787,14 @@ Commands are constructed on the server side. To demonstrate a complete
example, let's examine an example. Look at the doIt action:
```python
from kss import KSSResponse
@rpcmethod
def doIt(widgetid, href):
kss = KSSResponse()
kss.replaceInnerHTML('div#result',
html='<p>Parameters: %s, %s</p>' % (widgetid, href))
return kss.response
from kss import KSSResponse
@rpcmethod
def doIt(widgetid, href):
kss = KSSResponse()
kss.replaceInnerHTML('div#result',
html='<p>Parameters: %s, %s</p>' % (widgetid, href))
return kss.response
```
The doIt action, as implemented above, commits a single command
......@@ -806,15 +806,15 @@ returned in RPC format (either JSON or XML). This is the raw JSON
result to be sent back to the client:
```json
{
"commands": [
{
"commands": [
{
"selector": "div#result",
"action": "replaceInnerHTML",
"params": {
"html": "<p>Parameters: widget2000, firstpage.html<\/p>"
}
}
]
"selector": "div#result",
"action": "replaceInnerHTML",
"params": {
"html": "<p>Parameters: widget2000, firstpage.html<\/p>"
}
}
]
}
```