joonis Logo

Shipped KSS plugins

This part is adapted from the original KSS documentation, written by the KSS contributors.

KSS plugins, the ones that come with the system

In case of the javascript methods, we give the parameters the plugins take. There are both mandatory and optional parameters (with default value).

The commandsets repeat the functionality of all the kss actions, with the same parameter. However since the signature is python, the parameters can be given in a positional way as well. In addition, the "selector" commands have an additional selector parameter, which is not present at "global" commands.

The "core" plugins

Namespace: "core"

Events
Native browser events

With all native browser events, the following event parameters are available. Additional parameters are marked at the corresponding event.

  • evt-[<eventname>-]allowbubbling (default False)

    By default, we only let an event triggered when it happens on the exact node we bound the event to. If the event happens in one of the contained nodes of the bound node, the event is "bubbling up" and occasionally reach the bound node. If this parameter is set to True, all these events will trigger.

    (The basic behaviour with bubbling in KSS is different from that of javascript. in javascript, bubbling events are default triggering. in kss the default is that we suppress these events.)

  • evt-[<eventname>-]preventdefault (default False)

    If set to True, this disables the default behaviour to happen upon succesful completion of an event.

    For example, if we handle the click event on an <A> node, we don't want to link followed as well as it would be the default behaviour of the click.

  • evt-[<eventname>-]preventbubbling (default False)

    When used in combination with allowbubbling on an outer node, this can prevent the bubbling up of events from an inner node that is contained by the outer node. This property itself needs to be set on the inner node. (If the outer node does not have allowbubbling, the parameter has no effect.)

The events themselves:

blur

Triggers when leaving a form field.

focus

Triggers when entering a form field.

resize

Triggers when element is resized.

click

Triggers when element is clicked with the mouse.

dblclick

Triggers when element is double clicked with the mouse.

contextmenu

Triggers when element is right clicked with the mouse. Note: IE8 always prevents the default if there is a contextmenu event defined, with the exception of links.

mousedown

Triggers when mouse button is pressed.

mouseup

Triggers when mouse button is released.

mousemove

Triggers when mouse moves over the element.

mouseover

Triggers when mouse enters the element.

mouseout

Triggers when mouse leaves the element.

change

Triggers when the form field value is changed.

reset

Triggers when form is reset.

select

Triggers when selection box's value is selected.

submit

Triggers when form is submitted.

keydown

Triggers when key is pressed down.

  • evt-keydown-keycodes (default empty)

    If specified, it needs to be a list of comma separated keycodes (specified as a single string), and only the keycodes in the list will trigger the event.

keypress

Triggers when key is pressed.

  • evt-keypress-keycodes (default empty)

    Same as with keydown.

keyup

Triggers when key is released.

  • evt-keyup-keycodes (default empty)

    Same as with keydown.

Special kss events

timeout

Implements a timer that triggers the event when the given period expires.

  • evt-timeout-delay: delay period in milliseconds
  • evt-timeout-repeat (default true): If the event should happen periodically. This is the default, but it can be set to false to let the timeout event happen only once.

load

The event triggers when the bound node gets loaded. That signifies the full loading of the DOM, and may preceed the loading of images for the page.

The event triggers both on the original page load, and when we dynamically insert content from KSS.

  • evt-load-initial (default true): if the event should trigger on the initial page load.
  • evt-load-insert (default true): if the event should trigger on dynamic insertions by KSS.

iload

The event can only be bound to <IFRAME> node. It triggers when the full content of the internal frame gets loaded.

  • evt-iload-autodetect: if set to true, the default mechanism that observes the loading of the iframe will be utilized. If set to false, it is required that the template of the internal template has the _kssReadyForLoadEvent attribute set on the document. (Without this the event will never be triggered.) This method may be more solid then the default one but requires the cooperation of the internal contact.
  • evt-iload-initial (default true): if the event should trigger on the initial page load.
  • evt-iload-insert (default true): if the event should trigger on dynamic insertions by KSS.

spinneron

This event triggers when the "loading..." spinner should be activated.

  • evt-spinneron-laziness (default 0): laziness of the spinner in milliseconds.

spinneroff

This event triggers when the "loading..." spinner should be deactivated.

  • evt-spinneroff-laziness (default 0): laziness of the spinner in milliseconds.
Actions
HTML functions to insert content

All these actions have an optional parameter:

  • withKssSetup: if set to false, prohibits binding uthe nodes in the inserted content. This is plain optimization, normally ve want this wo leave on the default true.

replaceInnerHTML

Replace all children of the given node with the given content.

  • html: the html to insert

replaceHTML

Replace HTML including the given node with the given content.

  • html: the html to use as replacement (only the first node is used in the replace)
  • withKssSetup: if set to false, prohibits binding the nodes in the inserted content.

appendHTML

Add HTML after last child of given node.

  • html: the html to insert

insertHTMLBefore

add HTML before given node.

  • html: the html to insert

insertHTMLAfter

Add HTML after given node.

  • html: the html to insert

insertHTMLAsFirstChild

Add HTML inside the given node, at the beginning.

  • html: the html to insert

insertHTMLAsLastChild

add HTML inside the given node, at the end

  • html: the html to insert
Deleting content

deleteNode

Delete the node.

clearChildNodes

Delete all the children of the node.

deleteNodeAfter

Delete the next node.

deleteNodeBefore

Delete the previous node.
Moving content

moveNodeAfter

Move the node after the node with the given HTML id.

  • html_id: the id of the second node

moveNodeBefore

Move the node before the node with the given HTML id.

  • html_id: the id of the second node

moveNodeAsLastChild

Move the node as last child of the node with the given HTML id.

  • html_id: the id of the second node

copyChildNodesFrom

Copy the child nodes from the given HTML id, under the current node.

  • html_id: the id of the second node

copyChildNodesTo

Copy the child nodes of the given node to the given HTML id.

  • html_id: the id of the second node
Attributes

setAttribute

Sets a given HTML attribute of the node.

  • name: the attribute name. "style" cannot be used.
  • value: the attribute value to set

setKssAttribute

Sets a given KSS attribute of the node, available for reading with the kssAttr() parameter producer function.

  • name: the attribute name.
  • value: the attribute value to set

setStyle

Sets a given style element on the node.

  • name: the name of the style element.
  • value: the style element value to set

addClass

Add a class to the classes of the node, in case it it not there.
  • value: the name of the class

removeClass

Remove a class from the classes of the node, in case it is defined on it.
  • value: the name of the class

toggleClass

Add a class to the classes of the node if it's not there, and remove it if it's there.
  • value: the name of the class
Miscellaneous actions

focus

Focus the given node that is a form input.

setStateVar

Sets a variable that resides on the client, in a global namespace. You can also use namespace-name to separate namespaces. This variable can be sent back to a server action later, as a parameter.

  • varname: the variable name
  • value: the value to set

continueEvent

Trigger continuation event. Event will be triggered on the same node or on all the nodes bound for the current event state.

  • name: the event name
  • allnodes (default false): if set to True, event is triggered on all the nodes that are bound in the current event binder.
Debugging helpers

error

Throws an exception, when executed.

log

Logs an informational message.

  • message: additional message to log

logDebug

Logs a debug message.

  • message: additional message to log

alert

Pops up an alert box. Note that this is not meant to be used for an applications, only for debugging.

  • message: additional message to show in the alert box
Parameter providers
Fetching a given form variable

formVar(formname, varname)

Produces the value of a given variable within a given form.

currentFormVar(varname)

Produces the value of a given variable within the current form, which is the one in which the selected node is. The parameter varname is optional, and if it is ommitted, the current node will be used (in this case it must be a form variable itself).

For submitting an entire form, see the kssSubmitForm action parameter below.

Fetching content

nodeAttr(attrname [, recurseParent])

Produces the value of a given html attribute of the selected node. The optional second parameter is by default false. If set to true, it tries to recursively acquire the attribute from parent nodes as well.

kssAttr(attrname [, recurseParent])

Produces the value of a given kss attribute of the selected node. The optional second parameter is by default false. If set to true, it tries to recursively acquire the attribute from parent nodes as well. The kss attribute may be encoded in the page as a data-* attribute in the form of data-kss-key="value" (only in case of html5) or in a class emulation mode appended at the end of the existing class attribute as class="... kssattr-key1-value1 kssattr-key2-value2 ... kssattr-keyN-valueN"

nodeContent([recursive])

Produces the textual content of the node. Newlines are converted to spaces. If the parameter is false (default), then only the direct text nodes are considered, if the parameter is true, texts are fetched from the whole subtree.
Miscellaneous providers

stateVar(varname)

Produces the value of a state variable, that is, the same that can be set via the setStateVar command.

eventAttr(attrname)

Produces the value of a given event attribute of the current event object. Normalized and therefore cross browser attributes:

  • altKey, ctrlKey, shiftKey
  • keyCode, charCode
  • which, button
  • screenX, screenY
  • clientX, clientY
  • pageX, pageY

test(string, valueTrue, valueFalse)

Conditional statement that acts like a ternary operator. If the string value can be evaluated to true (eg. "true", "True" or "1") then valueTrue is returned, otherwise valueFalse.

pass(key)

It passes the given parameter from defaultparms to the request.

It is only used in advanced cases with specially developed stateful event plugins. This enables the plugin to set additional parameters in defaultparms, and these values are made available for KSS.

Action parameters

There are special parameters that are associated with an action itself. They all start with kss and consequently normal parameters cannot have a name starting with this prefix.

For action-server and action-client

kssPrecondition

The action is executed only if the value can be evaluated to true (eg. a value of "true", "True" or "1"). Otherwise the action is skipped. All parameter providers can be used.
For action-server

kssUrl

Can specify a different url then what would be the page base url and the name of the action concatenated after it. For example, views containing a @@ in the url can be called this way.

kssSubmitForm

Submits an entire form directly onto the request.

The parameter value can be one of the followings:

  • form(formname): Produces the values of all the variables in a given form.
  • currentForm(): Produces the values of all the variables in the form that contains the current node.
  • <string>: equals to form(<string>).
For action-client and the default action

kssSelector

Changes the scope of execution. All selectors can be used as if they were parameter providers. A string value can also be specified, this will be equivalent of css(<string>).

  • htmlid(id)
Selector types

css(selector)

Selects node by the css selector.

htmlid(id)

Selects (zero or) one element that has the givem HTML id. If the passed value contains a hash (#) the value is trimmed up to the occurrence of this character.

samenode()

Selects the same node on which the event was triggered originally.

If used with kssSelector, this is the default, so it has the same effect as not using kssSelector at all.

If used in commands, it will cause the command to select the same node on which the event was triggered.

parentnode([selector])

Return the parent node if the selector argument is omitted or otherwise a list of all nodes that match the css expression in the parent chain of the original node.

passnode(key)

Similarly to passes the given parameter from defaultparms to the request.

It is only used in advanced cases with specially developed stateful event plugins. The event plugin puts a set of nodes as a value on defaultparms, and this will be used as the selection.

Commandset

The following client action are added as "selector" commands (in addition of the action parameters, the first parameter should be the selector).

replaceInnerHTML, replaceHTML, setAttribute, setStyle, insertHTMLAfter, insertHTMLBefore, insertHTMLAsFirstChild, insertHTMLAsLastChild, clearChildNodes, deleteNode, deleteNodeAfter, deleteNodeBefore, copyChildNodesFrom, copyChildNodesTo, moveNodeAfter, toggleClass, addClass, removeClass, focus

The following client action are added as "global" commands:

setStateVar, continueEvent

Can I
  help you?


Just drop me a line at
giraffe@joonis.de