5  Document elements

An HTML element is the content between a pair of HTML tags. Each HTML element in a MysterX document is accessible as a Scheme value. To retrieve an element, use the find-element method of mx-document%, which takes an HTML tag name and an ``id'' name. To retrieve the button we defined earlier:

(define button (send doc find-element "BUTTON" "ok-button"))

The HTML in a MysterX document might contain more than one element with the same tag and id. The find-element method can take an additional number argument indicating an occurrence of the element. The argument uses zero-based indexing, so the first occurrence has index 0. By default, the method returns the first occurrence with the given tag and id.

MysterX elements are instances of the class mx-element%. You cannot create such instances directly; they can only be ``extracted'' from a MysterX document. You can modify element style properties with Scheme code. There are over eighty style properties, so we won't list them here (lookup ``mysterx'' in Help Desk to find a complete list). Most style properties show up as a quadruple of mx-element% methods, two to ``get'' the property, and two others to ``set'' it. The two getters and the two setters differ by the style of values involved. A ``native'' getter (or setter) will typically return (or be passed) a string. We call these methods native because the data is sent directly to or returned directly from the underlying browser implementation. The non-native getters and setters use more typical Scheme representations of style data.

For a sample of what you can do with style properties, let's change the color of the text in the button we've created:

(send button set-color! "green")

The corresponding native method is set-color-native!. In this case, the native and non-native method can both take string arguments.

We can spread out the letters in the button with

(send button set-letter-spacing! (make-css-length 4 'pt))

which also has the effect of widening the button. The equivalent native method call is

(send button set-letter-spacing-native! "4pt")

While this call is more concise, it is also more prone to error, since the string can contain arbitrary data. As you can see, the ability to modify the HTML in documents is quite powerful.

We saw that documents have the methods insert-html, append-html, and replace-html. The class mx-element% has methods with the same names. Instead of affecting the entire document, these methods affect just a single HTML element. So in mx-element%, the method insert-html inserts HTML before a given element, append-html places HTML after the element, while replace-html replaces an element with new HTML.