Dynamic Web Development with Seaside

20.2.2Using a Brush

Unlike a normal XHTML brush, we have to explicitly add the JavaScript snippet to the XHTML output stream. There are essentially four different places a JavaScript snippet can be added: (1) right at the current position in the XHTML output stream into a script tag, (2) into a method that will be automatically evaluated when the page has completely loaded, (3) to a DOM element, or (4) as an event handler to a DOM element.

1. Adding to a script tag. You can add the brush right at the current place into the XHTML output stream. This is done by creating a script tag using an expression such as html script: aJavaScriptBrush. This technique is simple and straightforward, however it has the disadvantage that the JavaScript code will be evaluated right away when the web browser parses the file. This might happen even before the whole page is read in the web browser and might cause JavaScript errors, as there are no guarantees that the DOM elements you use are already available. In most cases this is not the preferred way to go.

2. Adding to a list of load-scripts. You can add the brush to a list of load scripts. These load scripts will be evaluated after the page has finished loading. This solution is usually preferred over the previous one. The following expression is an example:

html document addLoadScript: aJavaScriptBrush

3. Adding to a DOM element. Often JavaScript brushes need to know the ID of the element they are supposed to operate on. For example if we want to apply an effect to an element we need to pass the ID of that particular element to the JavaScript brush. Luckily there is an easy way to do this automatically and at the same time add the JavaScript brush to the list of load scripts. Every XHTML brush understands the message script: which will (1) ensure that tag has an unique ID, (2) pass the ID of the tag to the JavaScript brush, and (3) add the JavaScript brush to the list of load scripts. Here’s an example:

html div script: aJavaScriptBrush; with: 'Hello World'

4. Adding as a DOM event handler. So far the JavaScript code is executed unconditionally when it is encountered or after the page has loaded. Luckily one can assign JavaScript snippets to events on XHTML DOM nodes. Similar to the technique above, a JavaScript snippet that has no specific ID will operate on its owning XHTML element.

The most common events are onclick and onchange. For example,

html div onClick: aJavaScriptBrush; with: 'Hello World'

will execute the JavaScript code when the div element is clicked. You can find a full list of DOM events in the table below. Keep in mind that not all events are supported by all XHTML tags. For example the onchange event will never be triggered on a div tag, since it only applies to form elements that can be changed. The support and handling of some of the events (foremost among these are onblur, ondblclick, onfocus, onload, and onunload) differ significantly among the web browser implementations.

DOM Event Seaside Selector Description
onblur onBlur: When the element that is in focus, loses the focus.
onchange onChange: When a select input element has a selection made or when a text input element has a change in the text.
onclick onClick: When the mouse button is clicked over an element.
ondblclick onDoubleClick: When the mouse button is double clicked over an element.
onfocus onFocus: When an element receives focus either by the mouse or by tabbing navigation.
onkeydown onKeyDown: When a key is pressed down over an element.
onkeypress onKeyPress: When a key is pressed and released over an element.
onkeyup onKeyUp: When a key is released over an element.
onload onLoad: When the user agent finishes loading a window.
onmousedown onMouseDown: When the mouse button is pressed over an element.
onmousemove onMouseMove: When the mouse is moved while it is over an element.
onmouseout onMouseOut: When the mouse is moved away from an element.
onmouseover onMouseOver: When the mouse is moved onto an element.
onmouseup onMouseUp: When the mouse button is released over an element.
onreset onReset: When a form is reset.
onselect onSelect: When a user selects some text in a text field.
onsubmit onSubmit: When a form is submitted.
onunload onUnload: When the user agent removes a document from a window.

Copyright © 20 April 2024 Stéphane Ducasse, Lukas Renggli, C. David Shaffer, Rick Zaccone
This book is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 license.

This book is published using Seaside, Magritte and the Pier book publishing engine.