query()

This function creates a new result set, containing the HTML elements in the current section that match the supplied CSS selector. The context (optional) allows you to restrict the search to descendants of one or more context elements.

The new result set is of the type QueryResults, just like the results object which is also the result of a (hidden) query. All functions that can be used with the results object can also be used with this result set; see results.

Note: The query() function can't be used in a Control Script, since Control Scripts don't have access to the DOM.

query(selector)

Creates a new result set containing the HTML elements in the current section that match the supplied CSS selector.

selector

A String containing a CSS selector. See MDN Web Docs - CSS Selectors and combinators for CSS selectors and combinations of CSS selectors.

Examples

Look for an element with a certain ID

This scripts applies a style rule to the queried elements.

query("#test1").css("color", "yellow");

Look for an element in a snippet

The following script loads a snippet. Then it looks up an element in a snippet and sets its text. Finally, it replaces the elements matched by the script's selector by the snippet.

var snippet = loadhtml('snippets/mysnippet.html'); 
query("#foo", snippet).text("bar"); 
results.replaceWith(snippet);

query(selector, context)

Creates a new result set containing the HTML elements that match the supplied CSS selector. The context (optional) allows you to restrict the search to descendants of one or more context elements.

selector

A String containing a CSS selector. See https://www.w3schools.com/cssref/css_selectors.asp for CSS selectors and combinations of CSS selectors.

context

A result set (the result of another query) or an HTML string. If the passed context is not a result set or HTML string it will be coerced to a String and interpreted as HTML.

Examples

This script performs a query in the results of another query.

var table = query("table");
var rows = query("tr", table);
var cells = query("td", rows);

Since the results object also is the result of a query (for elements that match the selector of the script), it can be passed as context. For example in a script with the selector “table”.

var rows = query("tr", results);

query(html)

Creates a new HTML element on the fly from the provided string of raw HTML, and returns the new element.

html

A String containing a HTML element. Tags that can contain other elements should be paired with a closing tag.

Example

The following script adds a paragraph to the results (elements that match the selector of the script).

var div = query( '<div>' );
for ( let i = 0; i < 5; i++ ){    
    var p = query( '<p>' );    
    p.text( 'This is number ' + i );    
    div.append( p );
}
results.after( div );

Tip: The Dynamic Attachment script uses this function to add an attachment to an Email section; see Email attachments.