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

Events

Native browser events

All native browser events can be used. With all these 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.)

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.

• spinneron

  This event triggers when the "loading..." spinner should be activated.
  • evt-spinneron-laziness (default 0): laziness of the spinner in milliseconds.
  • evt-spinneron-filter: names of server actions that are observed by this spinner.

• spinneroff

  This event triggers when the "loading..." spinner should be deactivated.
  • evt-spinneroff-laziness (default 0): laziness of the spinner in milliseconds.
  • evt-spinneroff-filter: names of server actions that are observed by this spinner.

• error

  This event triggers when an error occures. Error attributes can be accessed with the parameter provider errorAttr.

Actions

HTML functions to insert content

• replaceInnerHTML
  
  Replace all children of the given node with the given content.
  • html: the html to insert
  • run-scripts: flag if containing script tags shall be executed (default: false)

• replaceHTML
  
  Replace HTML including the given node with the given content.
  • html: the html to use as replacement
  • run-scripts: flag if containing script tags shall be executed (default: false)

• prependHTML
  
  Add HTML inside the given node, at the beginning.
  • html: the html to insert
  • run-scripts: flag if containing script tags shall be executed (default: false)

• appendHTML
  
  Add HTML inside the given node, at the end.
  • html: the html to insert
  • run-scripts: flag if containing script tags shall be executed (default: false)

• insertHTMLBefore
  
  Add HTML before given node.
  • html: the html to insert
  • run-scripts: flag if containing script tags shall be executed (default: false)

• insertHTMLAfter
  
  Add HTML after given node.
  • html: the html to insert
  • run-scripts: flag if containing script tags shall be executed (default: false)

Deleting content

• deleteNode
  
  Delete the node.

Moving content

• moveNodeAfter
  
  Move the node after the specified target node.
  • target: the target node or its selector

• moveNodeBefore
  
  Move the node before the specified target node.
  • target: the target node or its selector

• moveNodeAsLastChild
  
  Move the node as last child of the specified target node.
  • target: the target node or its selector

• moveNodeAsFirstChild
  
  Move the node as first child of the specified target node.
  • target: the target node or its selector

Copying content

• copyNodeAfter
  
  Copy the node after the specified target node.
  • target: the target node or its selector

• copyNodeBefore
  
  Copy the node before the specified target node.
  • target: the target node or its selector

• copyNodeAsLastChild
  
  Copy the node as last child of the specified target node.
  • target: the target node or its selector

• copyNodeAsFirstChild
  
  Copy the node as first child of the specified target node.
  • target: the target node or its selector

Attributes

• setNodeAttr
  
  Sets a given HTML attribute of the node. The attribute is removed if value is null.
  • name: the attribute name
  • value: the attribute value to set

• setNodeAttrs
  
  Sets the given HTML attributes of the node. An attribute is removed if its value is null.
  Requires an arbitrary number of name-value pairs

• setDataAttr
  
  Sets a given HTML data attribute of the node, available for reading with the dataAttr() parameter producer function.
  • name: the attribute name
  • value: the attribute value to set

• setDataAttrs
  
  Sets the given HTML data attributes of the node.
  Requires an arbitrary number of name-value pairs

• setStyle
  
  Sets a given style property on the node.
  • name: the name of the style element
  • value: the style element value to set

• setStyles
  
  Sets the given style properties on the node.
  Requires an arbitrary number of name-value pairs

• addClass
  
  Add a class to the classes of the node, in case it is 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

Variables

• 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 via stateVar().
  • name: the variable name
  • value: the value to set

• setStateVars
  
  Sets all given variables in a global namespace.
  Requires an arbitrary number of name-value pairs.

• setLocalVar
  
  Sets a variable that is stored in the localStorage. This variable can be sent back to a server action later, as a parameter via localVar().
  • name: the variable name
  • value: the value to set

• setLocalVars
  
  Sets all given variables in the localStorage.
  Requires an arbitrary number of name-value pairs

• setSessionVar
  
  Sets a variable that is stored in the sessionStorage. This variable can be sent back to a server action later, as a parameter via sessionVar().
  • name: the variable name
  • value: the value to set

• setSessionVars
  
  Sets all given variables in the sessionStorage.
  Requires an arbitrary number of name-value pairs

Miscellaneous actions

• openURL
  
  Opens a URL in the window specified by target. If the window name does not exist a new window is opened.
  • href: The url to open. You can also navigate through the browser history by passing an integer value.
  • target: The name of a window, frame, iframe or one of the values _self (default), _parent, _top or _blank.
  • redirect: If set to true the current URL will be replaced without creating an additional history entry.
  • width: The width of the new window (defaults to 60%)
  • height: The height of the new window (defaults to 60%)
  • top: The vertical position of the window
  • left: The horizontal position of the window
  • location: [no|yes]
  • menubar: [no|yes]
  • resizable: [no|yes]
  • scrollbars: [no|yes]
  • status: [no|yes]
  • toolbar: [no|yes]

• addHistoryState
  
  Adds a new entry to the browser history. The current HTML state is stored in sessionStorage.

• submit
  
  Submits the given node that must be a form.

• focus
  
  Focus the given node that is a form input.

• blur
  
  Removes the focus of the given node.

• copyToClipboard
  
  Copies the inner text of the given node into the clipboard.

Animation actions

At time KSS supports the following animation libraries: Velocity, GreenSock, jQuery and MooTools

• animate
  
  If KSS detected an animation library, all parameters are forwarded to this library and the animation is executed. Please refer to the documentation of the corresponding library. In addition there is one extra parameter:
  • behaviour: the behaviour of an animation if there is already running another animation. A value of queue (default), ignore, combine, finish and stop.

• scroll
  
  If KSS detected an animation library, all parameters are forwarded to this library and the scroll animation is executed. The target is the current node that triggered the event but can be specified with the action parameter kss-selector.
  • container: a selector specifing the container to scroll. Defaults to the window (html/body).

For both actions a fallback solution is available if no library was found. In this case each style value is set immediately without being animated.

Debugging helpers

• alert
  
  Pops up an alert box.
  • message: the message to show in the alert box

• log
  
  Logs a message.
  • level: the log level to use
  • message: the message to log

• error
  
  Throws an exception, when executed.
  • message: the error message to set

Parameter providers

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.

• dataAttr(attrname [, recurseParent])
  
  Produces the value of a given HTML data 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.

• textContent([selector])
  
  Produces the textual content of the selected node, and all its descendants.

• innerText([selector])
  
  Produces the rendered textual content of the selected node, and all its descendants.

• innerHTML([selector])
  
  Produces the HTML content of all descendants of the selected node.

• outerHTML([selector])
  
  Produces the HTML content of the selected node, and all its descendants.

Fetching element dimensions

• clientWidth([selector])
  
  Produces the inner width of the selected element in pixels. It includes padding but not the scrollbar, border or margin.

• clientHeight([selector])
  
  Produces the inner height of the selected element in pixels. It includes padding but not the scrollbar, border or margin.

• offsetWidth([selector])
  
  Produces the width of the selected element in pixels. It includes padding, scrollbar and border but not the margin.

• offsetHeight([selector])
  
  Produces the height of the selected element in pixels. It includes padding, scrollbar and border but not the margin.

• scrollWidth([selector])
  
  Produces the overall width of the selected element in pixels.

• scrollHeight([selector])
  
  Produces the overall height of the selected element in pixels.

Fetching variables

• stateVar(name)
  
  Produces the value of a state variable, that is, the same that can be set via the setStateVar command.

• localVar(name)
  
  Produces the value of a localStorage variable, that is, the same that can be set via the setLocalVar command.

• sessionVar(name)
  
  Produces the value of a sessionStorage variable, that is, the same that can be set via the setSessionVar command.

Fetching form, event and error data

• formVar([fieldname[, formname]])
  
  Produces the value of a given field within a given form.
  If formname is omitted the field value within the current form is looked up, which is the one in which the selected node is. If fieldname is also ommitted, the current node will be used (in this case it must be a form field itself).
  For submitting an entire form, see the kss-includeform action parameter below.

• eventAttr(name)
  
  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

• errorAttr(name)
  
  Produces the value of a given error attribute of the current error object.

Miscellaneous providers

• styleVal(name[, selector])
  
  Produces the computed style value of the selected node.

• hashTag([url])
  
  Produces the hash tag of the specified url or the hash tag of the current location if omitted.

• url([relative_url])
  
  Produces the absolute url.

• contains(list, value)
  
  Returns a boolean if list contains value. list can be a comma or whitespace separated string or an array.

• confirm(message)
  
  Pops up an dialog box (OK/Cancel) and returns the selection.

• prompt(message[, default])
  
  Pops up an dialog box with an input field (OK/Cancel) and returns the entered value.

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.

Per action

• kss-timeout
  
  Sets an alternative timeout for server actions.

• kss-includeform
  
  Includes the values of an entire form. The parameter value can be one of the followings:
  • formname: Produces the values of all the fields in a given form.
  • @currentform: Produces the values of all the fields in the form that contains the current node.

Per rule or per action

• kss-precondition
  
  The actions are executed only if the value can be evaluated to true. Otherwise the actions are skipped. All parameter providers can be used.

• kss-selector
  
  Changes the scope of execution. All selectors can be used as if they were parameter providers. A string value can also be specified.

Relative selectors

• @samenode
  
  Selects the same node on which the event was triggered originally.
  If used with kss-selector, this is the default, so it has the same effect as not using kss-selector at all.

• @parentnode
  
  Selects the parent node of the node on which the event was triggered originally.

• @firstchild
  
  Selects the first child of the node on which the event was triggered originally.

• @lastchild
  
  Selects the last child of the node on which the event was triggered originally.

• @childnodes / @children
  
  Selects all child nodes of the node on which the event was triggered originally.

• @prevsibling / @previoussibling
  
  Selects the previous sibling of the node on which the event was triggered originally.

• @nextsibling
  
  Selects the next sibling of the node on which the event was triggered originally.

• @currentform
  
  Selects the form that is in the parent chain of the node on which the event was triggered originally.