Module sciter::dom

Expand description

DOM access methods via the dom::Element.

Introduction.

Let’s assume you have already integrated Sciter in your application and so you have a Sciter window with the 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 the source HTML is matching with a DOM element (there are exceptions, see below).

You can change the text, attributes, state flags of DOM elements; add new or remove existing DOM elements. You can also attach your own DOM event handlers to DOM elements in order 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 a 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, etc. All of them are wrapped into methods of dom::Element.

Here is how you would get a reference to the 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 the 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 the code leaves 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 the 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(ELEMENT_STATE_BITS::STATE_VISITED);

And in script:

el.state.visited = true;

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

Getting and setting values of DOM elements.

By default the value of a DOM element is its text but some DOM elements may have so called behaviors attached to them (see below). <input> 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, the value of an <input type=checkbox> is boolean – true or false, and the 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;
}

.

Element

DOM element wrapper. See the module-level documentation also.

Enums

ELEMENT_AREAS

Bounding rectangle of the element.

ELEMENT_STATE_BITS

Collection of states (runtime flags) of a DOM element.

SCDOM_RESULT

Type of the result value for Sciter DOM functions.

SET_ELEMENT_HTML

dom::Element.set_html() options.

Type Definitions

HELEMENT

Element native handle.

Result

A specialized Result type for DOM operations.