Basic principles, ElementList

All built-in Sciter methods produce lists of  Element instances - array of class ElementList that contain Element's.

As any other built-in classes the ElementList is extendable and q.tis implementation (partial) of the jQuery is simply a set of functions extending ElementList class.

Therefore these functions return ready to use query object:

Note that provided ElementList extends standard Array object so all methods of arrays are also available in ElementList's.

The q() function

q.tis defines q() function that is an equivalent of $() in jQuery realm. q() accepts following parameters and returns array of type ElementList:

DOM operations

add

add(selector, [context])  ⇒ collection

Add elements satifying the selector to the list of elements. returns new, updated collection.

addClass

addClass(name)  ⇒ self
addClass(function(index, oldClassName){ ... })  ⇒ self

Add class[es] to elements in the list. name can contain multiple, space separated names.

removeClass

removeClass()  ⇒ self
removeClass(name)  ⇒ self

removeClass(function(index, oldClassName){ ... })  ⇒ self

Remove class[es] from elements in the list. name can contain multiple, space separated names. If no name is given removes "class" attribute from elements.

toggleClass

toggleClass(name)  ⇒ self
toggleClass(function(index, oldClassName){ ... })  ⇒ self

Toggles (add or remove) class[es] from elements in the list. name can contain multiple, space separated names.

after

after(content)  ⇒ self

Add content after each element in the list. The content can be html string, DOM element or array of elements.

q("form input").after("<span>A note after the input</span>");
before

before(content)  ⇒ self

Add content after each element in the list. The content can be html string, DOM element or array of elements.

q("form input").before("<label>field:</label>");
replaceWith

replaceWith(content)  ⇒ self

Replace each element in the collection by the new content. The content can be html string, DOM element or array of elements.

append

append(content)  ⇒ self

Append content of each element in the list. The content can be html string, DOM element or array of elements.

q("ul").append("<li>New list item</li>");
appendTo, $appendTo

appendTo(target)  ⇒ self
$appendTo(selector)  ⇒ self

Append content from this list to the target. Same as append but with reversed operands.

q("ol>li").appendTo("ul");
attr

attr(name)  ⇒ string
attr(name, value)  ⇒ self
attr(name, function(index, oldValue){ ... })  ⇒ self
attr({ name: value, name2: value2, ... })  ⇒ self

Read or set attributes of DOM elements. attr(name) reads the attribute from first element in the list. All other variants set attribute value in each element in the list.

var form = q("form");
form.attr("action");                 //=> read value
form.attr("action", "/create.php");  //=> set value
form.attr("action", undefined);      //=> remove attribute

// multiple attributes at once:
form.attr {
  action: "/create.php",
  method: "post"
};
removeAttr

removeAttr(name)  ⇒ self

Remove the attribute in each element of the list.

children, $children

children(["selector"])  ⇒ collection
$children(selector)  ⇒ collection

Get immediate children of each element in the current list. Returns new list.

q("ol").children("li:nth-child(2n)"); // returns list of
$$(ol).$children(li:nth-child(2n));   // every even items in the <ol>
closest, $closest

closest(["selector"]) ⇒ collection
closest(collection) ⇒ collection
closest(element) ⇒ collection
closest(function(){}) ⇒ collection
$closest(selector)  ⇒ collection

Gets closest parents of elements in the list. Returns new list.

var input = q("input[type=text]");
var itsForm = input.closest("form");
contents

contents()  ⇒ list (array) of nodes

Returns array of content nodes - combined list of all child nodes of all elements in the list.

css

css(property)  ⇒ value
css(property, value)  ⇒ self
css({property: value, property2: value2, ... })  ⇒ self

Get or set style properties on DOM elements in the list.

var elem = q("h1");
elem.css("background-color");                         // read property
elem.css("background-color", "#369");                 // set property
elem.css("background-color", color(0x33,0x66,0x99));  // set property
elem.css("background-color", undefined);              // remove property

// set multiple properties:
elem.css { background-color: "#8EE",
           opacity: 0.75,
           font-size: 28pt };
each

each(function(index, item){ ... })  ⇒ self

Call the function for each element in the list. this variable in each call is set to the current element.

q("form input").each(function(index){
  stdout.println("input at ",index," is ", this);
});

note that the above can be written simply as this:

for(var (idx,el) in q("form input"))
  stdout.println("input at ",idx," is ", el);

- less brackets and no function calls on each iteration.

empty

empty()  ⇒ self

Clears content of each element in the list.

eq

eq(index)  ⇒ collection

Get the item at index position in the list.

q("li").eq(0);  // gets first item
q("li").eq(-1); // gets last item
filter, $filter

filter("selector")  ⇒ collection
filter(function(index){ ... })  ⇒ collection

$filter(selector)  ⇒ collection

Filter the list of elements so it contains only elements satisfying the selector or those that passed through the filter function that returns true for passed element.

find, $find

find("selector")  ⇒ collection
find(collection)  ⇒ collection
find(element)  ⇒ collection

$find(selector)  ⇒ collection

Find descendants of elements in the list satisfying the selector. If the collection (list of elements) is given then the result is the list (subset) of that collection - all elements that contianed inside the self.

var form = $$(#myform);
var inputs = form.$find(input,textarea,select,widget,button);
first

first()  ⇒ collection

Get the first element from the list, returns list of single element,  or empty list if self one was empty by itself.

var form = q("form").first();
get

get()  ⇒ array
get(index)  ⇒ DOM element

Get element at index from the list, or if no index is given - the whole list as a plain array.

var items = q("li");
var li2 = items.get(2);

Note: you can always use indexed access for the same purpose:

var li2 = items[2];
has, $has

has("selector")  ⇒ collection
has(element)  ⇒ collection
$has(selector)  ⇒ collection

Filter the list to include only elements that have descendants that match selector, or that contain specific DOM element.

q("dl > dd").has("a[href]")
//=> get only DD elements that contain links
hasClass

hasClass("name")  ⇒ true/false

Checks if any element in the list has specified class name.

hide

hide()  ⇒ self

Here it simply does this.addClass("hidden"). So in order this method to work your CSS should have *.hidden { display:none; } or similar declaration.

Note this implementation is conceptually different from what jQuery or Zepto do in that case. The hide() there do el.style.display = "none" making show() impossible to implement reliably.

show

show()  ⇒ self

Here it simply does this.removeClass("hidden"). In order this method to work your CSS should have *.hidden { display:none; } or similar declaration.

toggle

toggle()  ⇒ self
toggle(onoff)  ⇒ self

Calls show() or hide() for each element depending on presence of hidden class in it. If onoff is present then it acts self.show() or self.hide().

html

html() ⇒ string
html("content") ⇒ collection
html(function(index, oldHtml){ ... }) ⇒ collection

First method gets HTML content of the first element in the list. Other methods set HTML content of elements in the collection.

g(".comment:empty").html("<em>no comments yet!</em>");
index

index([element])  ⇒ integer | undefined

Get position of the element in the list or -1 if the element is not in the list. If no element is given, returns position of the first element among its siblings.

g("li:nth-child(2)").index() //=> 1
insertAfter, insertBefore

insertAfter(target)  ⇒ self
insertBefore(target)  ⇒ self

Insert elements from the list after/before the target element in the DOM.  Same as after() or before() but with reversed operands.

var fields = q("form input");
q("<em>Required field</em>").insertAfter(fields.filter(".required"));
is, $is

is("selector")  ⇒ true/false
$is(selector)  ⇒ true/false

Check if the first element matches the selector.

last

last()  ⇒ collection

Get the last element from the list, returns list of single element,  or empty list if the self was empty.

var form = q("form").last();
next, $next

next()  ⇒ collection
next("selector")  ⇒ collection
$next(selector)  ⇒ collection

Get the next sibling element for each element in the list.

var dd = q("dl > dt").next(); // all elements next to DTs
not, $not

not("selector")  ⇒ collection
not(collection)  ⇒ collection
not(function(index){ ... })  ⇒ collection
$not(selector)  ⇒ collection

Filter the current collection to get a new collection of elements that don’t match the CSS selector. If another list is given instead of selector, return only elements not present in it. If a function is given, return only elements for which the function returns false. Inside the function, the this refers to the current element.

For the opposite, see filter().

parent, $parent

parent()  ⇒ collection
parent("selector")  ⇒ collection
$parent(selector)  ⇒ collection

Get immediate parents of each element in the collection. If CSS selector is given, it returns only immediate parents that satisfy the selector.

parents, $parents

parents()  ⇒ collection
parents("selector")  ⇒ collection
$parents(selector)  ⇒ collection

Get all ancestors of each element in the collection. If CSS selector is given, filter results to include only ones satisfying the selector.

To get only immediate parents, use parent(). To get only first ancestor matches the selector, use closest()

var all_parents = $('h1').parents();
prepend

prepend(content)  ⇒ self

Prepend content of each element in the list. The content can be html string, DOM element or array of elements.

q("ul").prepend("<li>New list item</li>");
prependTo, $prependTo

proependTo(target)  ⇒ self
$prependTo(selector)  ⇒ self

Prepend content from this list to the target. Same as prepend() but with reversed operands.

q("ol>li").prependTo("ul");
prev, $prev

prev()  ⇒ collection
prev("selector")  ⇒ collection
$prev(selector)  ⇒ collection

Get the previous sibling element for each element in the list.

var dd = q("dl > dd").prev(); // all elements prior to DTs
remove

remove()  ⇒ self

Remove elements in the current collection from their parent nodes detaching them from the DOM.

siblings, $siblings

siblings()  ⇒ collection
siblings("selector")  ⇒ collection
$siblings(selector)  ⇒ collection

Get sibling elements of each element in the list. If selector is provided it returns only matched siblings.

size

size()  ⇒ integer

Reports number of elements in the list. Note that you can use the length property instead of this method.

unwrap

unwrap()  ⇒ self

Remove immediate parent of each element in the collection and put their children in their place.

q("body").append("<div id=wrapper><p>Content</p></div>")
q("#wrapper p").unwrap().parent()  //=> [<body>]
wrap

wrap("html")  ⇒ self
wrap(element)  ⇒ self
wrap(function(index){ ... })  ⇒ self

Wrap each element of the collection separately in a DOM structure. The html can contain single element or several nested elements. If function provided then it is called for each element and returns html or element reference.

// wrap each <a> in .buttons in a separate span:
q(".buttons a").wrap("<span/>");

// wrap each code block in a div and pre:
q("code").wrap("<div class=code><pre></pre></div>");

// wrap all inputs in a span with classname
// corresponding to input type:
q("input").wrap( :: "<span class=" + this.attributes["type"] + "-field />" );
//=> <span class=text-field><input type=text /></span>,
//   <span class=search-field><input type=search /></span>

Events

List of standard supported events that ara bound with Sciter native events:

List of Sciter specific events:

The event types may contain namespace in "event.namespace" notation. Please read Namespaced Events chapter in jQuery docs.

Custom events are supported: you may subscribe on something like "dosomething.mylib" and trigger() that event in your code.

on, Element.on
on(type, [selector], function(event){ ... })  ⇒ self
on({ type: handler, type2: handler2, ... }, [selector])  ⇒ self

Add event handlers to all elements in the list. Multiple event types can be passed in a space-separated string, or as an object where event types are keys and handlers are values. If a CSS selector is given, the handler function will only be called when an event originates from an element that matches the selector.

Event handlers are executed in the context of the element to which the handler is attached, or the matching element in case a selector is provided.

Note #1: when an event handler function returns false it means that event is "consumed" and its normal propagation is stopped. That is different from normal Sciter practice where return true; in event handlers means "event consumed".

Note #2: for a while the event passed to event handlers is a raw Event object used in Sciter.

var elem = q("#content");
// observe all clicks inside #content:
elem.on("click", function(e){ ... });
// observe clicks inside navigation links in #content
elem.on("click", "nav a", function(e){ ... });
// all clicks inside links in the document
self.on("click", "a", function(e){ ... });
off, Element.off
off(type, [selector], function(e){ ... })  ⇒ self
off({ type: handler, type2: handler2, ... }, [selector])  ⇒ self
off(type, [selector])  ⇒ self
off()  ⇒ self

Detach event handlers added with on() method. To detach a specific event handler, the same function must be passed that was used for on(). Otherwise, just calling this method with an event type with detach all handlers of that type. To unsubscribe all events from a namespace use off(".mylib"); form - no name but namespace only. When called without arguments, it detaches all event handlers registered on current elements.

var elem = q("#content");
// detach all click handlers from the element:
elem.off("click");
// detach all event handlers set with .mylib namespace:
elem.off(".mylib");
one, Element.one
one(type, [selector], function(event){ ... })  ⇒ self
one({ type: handler, type2: handler2, ... }, [selector])  ⇒ self

Similar to on() but attached event handlers will be fired only once - detached about first invocation.

trigger, Element.trigger
trigger(event[, param1, param2,...])  ⇒ true/false

Trigger the specified event on elements of the list. Event here is a string that contains event name and optionally namespace.

If addition parameters are presented then they will be passed as they are to the handler function after the first event parameter.

The method returns true if any one of event handlers "consumes" the event returning precisely false value.

// subscribing for the custom event:
q("#content").on("show-alert.myapp", function(evt,msg) { view.msgbox(#alert,msg) } );
// invoke the event with additional parameter:
q("#content > a").trigger("show-alert.myapp", "Red alert!");
// note the even will be bubbled up to the container

Note: the t.tis module adds on(), off(), one()  and trigger() methods to the Element class too. For the convenience and uniform event handling.