Module sciter::dom [−] [src]

DOM access methods via the dom::Element.

Introduction.

Let’s assume you have already integrated Sciter in your application and so you have Sciter window with loaded content.

From Sciter's point of view the loaded document is a tree of DOM elements (elements of Document Object Model). Sciter builds this tree while loading/parsing of input HTML. As a rule each tag in source HTML gets matching DOM element (there are exceptions, see below).

You can change text, attributes, state flags of DOM elements; add new or remove existing DOM elemdoents. You can also attach your own DOM event handlers to DOM elements to receive events and notifications.

Therefore your UI in Sciter is a collection of uniform DOM elements that can be styled by CSS and manipulated by native or script code.

Basic operations

To access the DOM tree we need to get reference of its root element (the root element is the element representing the <html> tag in HTML source).

let root = Element::from_window(hwnd).unwrap();
assert_eq!(root.get_tag(), "html");

TBD: Other ways to access DOM tree.

By having a root element reference we are able to access any other element in the tree using various access and search functions like SciterGetNthChild, SciterSelectElements, … All of them are wrapped into methods of dom::Element. Here is how you would get reference to first <div> element with class "sidebar" using CSS selectors:

let sidebar = root.find_first("div.sidebar").unwrap();

The same in script:

var sidebar = self.select("div.sidebar"); // or
var sidebar = self.$(div.sidebar); // using a stringizer variant of select()

TBD: Other select methods.

DOM element operations

You can change the text or HTML of a DOM element:

if let Some(mut el) = root.find_first("#cancel").unwrap() {
    el.set_text("Abort!");
    el.set_html(br##"<img src="http://lorempixel.com/32/32/cats/" alt="some cat"/>"##, None);
}

The same but in script:

var el = ...;
el.text = "Hello world"; // text
el.html = "Hello <b>wrold</b>!"; // inner html

You can also get or set DOM attributes of any DOM element:

let val = el.get_attribute("class").unwrap();
el.set_attribute("class", "new-class");

To remove an existing DOM element (to detach it from the DOM) you will do this:

el.detach();

and when code will leave the scope where the el variable is defined, the DOM element will be destroyed.

Creation and population of DOM elements looks like this:

let p = Element::with_text("p", "Hello").unwrap(); // create <p> element
el.append(&p); // append it to existing element, or use insert() ...

And in script:

var p = new Element("p", "Hello");
el.append(p);

To change runtime state flags of a DOM element we do something like this:

el.set_state(STATE_VISITED);

And in script:

el.state.visited = true;

(after such call the element will match :visited CSS selector)

Getting and setting values of DOM elements.

By default a value of a DOM element is its text but some DOM elements may have so called behaviors attached to them (see below). <input>’s elements, for example, are plain DOM elements but each input type has its own behavior assigned to the element. The behavior, among other things, is responsible for providing and setting the value of the element.

For example, value of an input type=checkbox> is boolean – true or false, and value of a <form> element is a collection (name/value map) of all named inputs on the form.

In native code values are represented by sciter::Value objects. sciter::Value is a structure that can hold different types of values: numbers, strings, arrays, objects, etc (see documentation).

Here is how to set a numeric value of a DOM element in native code:

if let Some(mut num) = root.find_first("input[type=number]").unwrap() {
    num.set_value( Value::from(12) );  // sciter::Value with T_INT type (i32 in Rust)
    num.set_value(12);  // equivalent but with implicit conversion
}

In script the same will look like:

if (var num = self.select("input[type=number]")) {
    num.value = 12;
}

Children	An iterator over the direct children of a DOM element.
Element	DOM element wrapper. See the module-level documentation also.

Enums

ELEMENT_AREAS	Bounding rectangle of the element.
SCDOM_RESULT	Type of the result value for Sciter DOM functions.
SET_ELEMENT_HTML	`dom::Element.set_html()` options.

Type Definitions

HELEMENT
Result	A specialized `Result` type for DOM operations.