shipped-plugins.md

+**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
+
+replaceHTML
+
+    Replace HTML including the given node with the given
+    content.
+
+    - html: the html to use as replacement
+
+prependHTML
+
+    Add HTML inside the given node, at the beginning.
+          
+    - html: the html to insert
+    
+appendHTML
+
+    Add HTML inside the given node, at the end.
+    
+    - 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
+
+
+
+Deleting content
+----------------
+
+deleteNode
+
+    Delete the node.
+
+
+Moving content (currently not implemented!)
+-------------------------------------------
+
+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
+
+moveNodeAsFirstChild
+
+    Move the node as first 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
+----------
+
+setNodeAttr
+
+    Sets a given HTML attribute of the node.
+
+    - name: the attribute name
+    - value: the attribute value to set
+
+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
+
+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.
+
+
+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-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.