stdlib 2.1.2
attr_url()
constructs and modifies a parseable URL from the scoped Attribute.
attr_url()
constructs and modified a parseable URL from the scoped Attribute.
The function takes no arguments.
URL functions called in the created URL block will be applied to the attribute.
The function returns the value of the attribute on exiting the block.
The example below will relativize the first anchor tag found in the document's href attribute.
$("(//a)[1]") { attribute("href") { attr_url() { relativize() } } }
Opens the name scope of the attribute, allowing the name to be changed.
The name
function opens the scope of the selected attribute. It allows you to change the name of an attribute.
To modify the name itself, you need to use the set
function (to change it completely) or the replace function (to replace certain aspects).
The following example changes the class of the selected div
into an ID
.
$("./div[@class='one']") attribute("class") { name() { set("id") } } }
The name
function allows you to change the name of an attribute.
The name
function allows you to change the name of an attribute.
It takes one argument, which is the new %name
for the attribute.
A use case for this function is found in the lateload
function in the functions/main.ts
file of a Moovweb project.
In this case, the name
function is used to change the src
attribute of images to data-ur-ll-src
, which signals to some javascript to load the images when the page has finished.
The following example changes the id
of the selected div to a class.
$("./div") { attribute("id") { name("class") } }
Removes the currently-selected attribute.
The remove
function removes the currently-selected attribute.
Common Uses
- Removing inline styles once the attribute has been selected
The following example will remove the class from the selected div.
$("./div[@class='one']") attribute("class") { remove() } }
Opens the value scope of an attribute, so the value can be modified.
The value
function opens the scope of the selected attribute. This allows you to modify the value of an attribute.
To modify the value itself, you would need to use the set
function (which changes it completely), or the replace function (to replace certain pieces).
Common Uses
- Altering the value of a class
- Modifying the value of an href attribute
In the following example, the class attribute of the selected div
tag will be given a new value of two
.
$("./div[@class='one']") attribute("class") { value() { set("two") } } }
The value
function in the attribute scope changes the value of the attribute.
The value
function allows you to modify the value of an attribute.
The function takes one argument - the %value
for the attribute.
An example of the value
function being used on an attribute can be found in the functions/main.ts
file in the rewrite_links
function.
In this case, the value function is used to modify the href
s of a
tags.
In the following example, the href
attribute of the selected a
tag will be given a new value of http://example.com
.
$("./a") { attribute("href") { value("http://example.com") } }
Query the system for various environmental data.
This function allows the developer to query the system for information about the environment. Currently, the only supported argument is "dev" (for which env
will return "true" or "false") to determine whether the script is executing in development mode. More system information may be made available in the future.
The $
function is a selector that takes XPath as an input. XPath is a syntax for selection notation based on the structure of an HTML DOM.
The $
selector is used to tell Tritium which node(s) you'd like to select to transform. The general process of transformation involves two basic steps: 1) selecting a node, and 2) performing some function on that node. We refer to the process of selecting a node for transformation as "opening a scope" throughout our documentation.
Things to note: If Tritium finds no matching node for the %xpath
selector provided, it simply skips over that block of code. If Tritium finds more than one matching node for the %xpath
selector provided, it will iterate over each element sequentially running the block of code inside the selector on each element.
Common Uses
- Just about anything you want to do with Tritium.
In this example, we select every div
element in the document and open a scope for manipulation.
$("//div") { # Run transformations on these divs one at a time. }
The copy_here
function copies the node specified by the input %xpath to the currently selected node.
The copy_here
function copies the node specified by the input XPath selector to the current scope from which it is called.
Things to note: There is also an optional position variable (%pos
) that can specify where in relation to the current node it should be placed such as: "before", "after", "top" or "bottom".
Common Uses
- Sometimes you can break page functionality by moving elements around so in some cases you might want to copy those elements instead.
- Duplicating useful information
The example below will create a copy the header and move it into the currently-selected div.
$("./div") { copy_here("/html/body/header") }
The copy_to
function copies the currently selected node to the node specified by the input %xpath
.
The copy_to
function copies the currently selected node to the node specified by the input %xpath
.
Things to note: There is also an optional position parameter (%pos
) that can be passed to specify where in relation to the target node it should be copied such as: "before", "after", "top" or "bottom".
Common Uses
- Sometimes you can break page functionality by moving elements around so in some cases you might want to copy those elements instead.
- Duplicating useful information
The example below will copy the currently-selected div into the header of the DOM.
$("./div") { copy_to("/html/body/header") }
Copies the current node.
The dup function copies the current node. The copy is placed immediately after the current node. The function is mostly used within other functions - for example the copy_to function. The example below will copy the currently-selected div.
$("./div") { dup() }
Retrieves information from the node specified.
The fetch
function retrieves the information from the node specified.
The function takes one argument - the node/information you want. This should be specified in XPath.
Common Uses
- Grabbing text from a link in order to use it elsewhere
- Fetching the value of an attribute
The example below fetches any text within the anchor tag and sets it as a variable.
$("./a") { $linktxt = fetch("text()") }
The index
function returns the order of which this node is iterated through when selected by Tritium.
The index
function is used to return the order of which the node is transformed when selected using Tritium. Every time you use a Tritium selector that selects more than a single element, the Moovweb SDK will iterate over each element and run the inner block of code on each element one at a time. The index() function returns the order of that element in the execution queue.
Common Uses
- Giving elements a unique attribute that corresponds to their index number.
- Referencing a certain element based on its order of execution.
- General order based logic, such as giving all odd numbered elements in the queue a certain class so you can style them differently.
The inject
function injects HTML into the current node.
The inject
function injects HTML into the current node.
Things to note: There are a number of comparable functions that perform similar functions but specify a position in their name so you don't have to pass it in as a parameter:
* inject_top(Text %html)
* inject_bottom(Text %html)
* inject_before(Text %html)
* inject_after(Text %html)
Common Uses
- Injecting entire templates of code at once from another file using the
inject()
function in combination with theread()
function. - Fixing broken HTML
The example below will inject an a
tag pointing to site.com into the bottom of the selected div.
$("./div") { inject("<a href="http://site.com">My new link!</a>") }
Injects HTML into the current node at the position specified.
Common Uses
- Injecting a scaffold for a header and/or footer
The example below will inject the section.html
file into the top of the selected div
. Notice how the read
function is used to input the file.
$("./div") { inject_at(position("top"), read("section.html")) }
Moves one node to another node at the position specified.
The move
function moves a certain node to a particular place in another node.
The function takes three arguments: %what
needs to be moved, %where
it needs to be moved, and the %position
at which it needs to be moved.
Important to note is the format in which the arguments must be given. They cannot be specified by a text string, so you cannot use a string of XPath to specify the nodes (e.g. "./div") or a text input for the position (e.g. "top").
Instead of using a string to define the position, you must use the position function to wrap it. For the nodes, you must set a local variable pointing to a particular node using this()
.
Due to the lack of text input, the function is mostly used when defining other functions. For example, most of the move_to
functions are defined around this function.
The example below selects the div
"one" and assigns it a local variable. Then, it selects the div
"two" and moves that div
(this()
) to the top of div
one.
$("./div[@class='one']") { %one = this() $("../div[@class='two']") { move(this(), %one, position("top")) } }
The move_here
function moves the node specified by the input xpath to the currently selected node.
The move_here function moves the node specified by the input xpath to the currently selected node. The function takes one argument - the XPath of the element that is to be moved into the current node. Things to note: There is also an optional position parameter (%pos) that can be passed to specify where in relation to the target node it should be placed such as: "before", "after", "top" or "bottom". * Creating the proper structure for a page by moving the elements you want to keep into the proper place. * Fixing the existing structure of a page by moving elements around. * Creating the structure necessary for Uranium.js so you can use widgets like togglers, tabs, image carousels and more.
The example below will take the span sibling of the div and move it into the div.
$("./div") { move_here("../span") }
The move_to
function moves the currently selected node to the node specified by the %xpath
input.
The move_to command moves the currently selected node to the node specified by the %xpath input. The function takes one argument, the XPath destination of the current node. Things to note: There is also an optional position parameter (%pos) that can be passed to specify where in relation to the target node it should be placed such as: "before", "after", "top" or "bottom".
Common Uses
- Creating the proper structure for a page by moving the elements you want to keep into the proper place.
- Fixing the existing structure of a page by moving elements around.
- Creating the structure necessary for Uranium.js so you can use widgets like togglers, tabs, image carousels and more.
The example below will take the currently-selected div and move it to the span child of its parent (i.e. a span sibling of the div).
$("./div") { move_to("../span") }
Opens a scope to rename the current node.
The name
function opens a scope via which the name of the current tag can be changed.
Common Uses
- Rename table elements to more manipulable tags
The example below will rename the selected div
to an a
tag.
$("./div") { name() { set("a") } }
Renames the current node to the tag specified by the input.
The name
function replaces the name of the currently selected node with the input provided by the parameter %value
. This means you are effectively changing the element that will be rendered in the DOM.
Common Uses
- Changing tables and their inner rows and data cells to
div
s. - Changing anchors that have been wrapped inside anchors to
div
s to avoid broken HTML. - Changing between
div
s andspan
s depending on how you want the page to flow.
Returns the XPath of the current node.
The path
function returns the nodal path to the currently-selected node.
Common Uses
- Debugging by figuring out where in the HTML tree you are
- Setting a variable using the current path, in order to use it later for moving items
The example below will log the path to the selected div
.
$("./div") { log(path()) }
Removes the current node from the tree.
The remove function removes the node that is currently selected. Common uses include (but are not limited to): * Removing empty items on a page * Removing a table once all useful information has been moved out
The example below will select every table in the document and remove it and its contents.
$("//table") { remove() }
Selects all nodes matching the XPath specified.
The select
function searches the HTML tree to match the XPath specified.
The function takes one argument, and that is the %path_selector for the node to select.
Related functions: $(xpath)
Common Uses
- Selecting any HTML element in Tritium using XPath
The example below selects the html
and body
select("/html/body") { remove() }
Replaces the current interior of the node.
The set
function allows you to replace the current value with one specified.
It is commonly used within other functions, such as name()
(see example below).
The function takes one argument - the %value
which will replace the current one.
The example below will take the div
and set the name to "span" (i.e. change the div
to a span
).
$("./div") { name() { set("span") } }
Opens the contents of the current node to text modification or retrieves the text of the current node.
The text
function opens up the text scope or retrieves the text contained within the current scope.
Without any further functions, the text
function - when performed on an XMLNode - will return any text within that node, removing all the HTML
tags.
A further function can be used (such as set
) to replace anything inside the current node with text.
Important to note is that anything within the argument will be inserted as text. So using text("<a></a>")
will insert the text rather than the HTML
tag.
Common Uses
- Grabbing text from unnecessarily-nested nodes
- Opening a text scope to then replace a word in a paragraph
- Fetching text from a tag to put into a variable
The example below will set the interior of the current div
to be "New".
$("./div") { text() { set("New") } }
Returns the currently-selected node.
The this
function is used to point to the current node.
The function is mostly used in the context of defining other functions. Most of the time, you can write an XPath to point to the correct node - but sometimes you have to specify the node itself. Here is where the this
function is useful.
The example below uses the function twice. Once to set a variable as the current node (the anchor tag) and once to specifiy the current node (the span
) in a function. Node that we are using the move function here, which can only take nodes as arguments (i.e. not a string corresponding to XPath).
$("./a") { %link = this() $("../span") { move(%link, this(), position("top")) } }
The append
function adds the input %text_to_append
to the end of the text scope from which it is called.
The append
function is used to insert text at the end of a text scope.
Common Uses
- Adding instructions following content.
- Elaborating on content without resetting it.
In this example, we append a sentence onto the end of the text node inside my_div
.
$$("#my_div") { text() { append("This is how you append text to the end of the existing text in #my_div.") } }
The capture
function grabs all instances of the regular expression specified.
The capture
function is used to grab a specific block of text, which is matched via a regular expression.
Common Uses
- Grabbing specific items from a string of text
- Separating out capture groups in a regular expression
In this example, the capture function will grab any string of 8 characters and log it the terminal.
$$("#my_div") { text() { capture(/(\w{8})/) { log("Words with more than 8 letters: " + %1) } } }
Similar to remove()
but works in a text scope.
The clear
function is used to remove text from inside a text scope.
Related functions: remove()
Common Uses
- Clearing extra white space inside nodes
- Clearing text links to turn them into icons
In the following example, we simply clear any existing text inside the node with an ID of my_div
.
$$("#my_div") { text() { clear() } }
The convert_encoding
function is used to convert from one encoding to another.
The convert_encoding
function is used to convert text from one encoding to another.
Common Uses
- Converting incorrectly encoded text
In this example, we convert from gbk
to utf-8
encoding.
text() { convert_encoding("gbk", "utf-8") }
The guess_encoding
function is used to guess the encoding from the input, the response header, and the HTML meta
tag.
The guess_encoding
function is used to guess the text encoding of the current scope. The function uses information from the input, the response header, and the HTML meta
tags.
Common Uses
- When you need to figure out the current encoding.
In this example, we guess the encoding of the current text node.
text() { $encoding = guess_encoding() log(concat("I'm guessing your encoding is ", $encoding)) }
Parses the document into HTML, from and to the encodings specified.
The html
function parses the document as HTML. This means the document - which is plain text - is converted into a tree-like structure. At this point, we can use XPath and other selectors to navigate the document.
The html
function can take from 0-2 arguments:
* 0 arguments: the function guesses the HTML encoding when parsing it, then opens it.
* 1 argument: the function parses the HTML with the specified encoding, then opens it.
* 2 arguments: the function converts the HTML from %from_enc
to %to_enc
, then opens it.
Things to note: as part of the parsing, the function will add <html>
tags and a DOCTYPE
to the document. If you only want to parse a fragment of HTML, use the html_framgment() function.
An example of the html
function can be found in the scripts/main.ts
file of your project, where it parses every page as HTML.
The following example will parse the HTML as gbk
, convert it to utf-8
, then print a log
statement if there is a root HTML
node with a body
child.
html("gbk", "utf-8") { $("/html/body") { log("found an /html/body tag!") } }
Parses the document as HTML.
The html_doc
function parses the document as HTML. This means the document - which is plain text - is converted into a tree-like structure. At this point, we can use XPath and other selectors to navigate the document.
The encoding must be specified with two arguments, used to specify the "to" and "from" encodings (%input_encoding
and %output_encoding
). html_doc("x", "y")
would parse the document from encoding x
into encoding y
.
Important to note is that as part of the parsing, the function will add <html>
tags and a DOCTYPE
to the document. If you only want to parse a fragment of HTML, use the html_fragment() function.
The html
function can be found in the scripts/main.ts
file of your project, where it parses every page as HTML.
The example below will parse the HTML from gbk
encoding to utf-8
encoding, allowing selectors to point to nodes of the document.
html_doc("gbk", "utf-8") { $("/html/body") }
Parses a fragment of the document as HTML
Same as the 1-argument version of html_fragment(), except this version guesses the HTML encoding.
html_fragment() { $("/div") }
Parses a fragment of the document as HTML with the encoding specified.
Same as the 2-argument version of html_fragment(), except this version parses the document with the specified encoding, then opens it for modification.
html_fragment("utf-8")
Parses a fragment of the document as HTML, using the encodings specified.
The html_fragment
function parses a fragment of the document as HTML. It converts raw html-as-text into a document fragment, which is searchable by Xpath.
One thing to note is that this fragment is 'floating' -- its not attached to the root document at all. For this reason selectors that operate from a document
root (e.g. //div
or /html/body/div
) won't return any results.
This particular function parses the document with the %from_enc
encoding, converts it to the %to_enc
encoding, then opens it.
Common Uses
- Only a small section of the request being processed is HTML, and that fragment must be parsed without adding an
HTML
tag and aDOCTYPE
.
The example below will parse a gbk
-encoded fragment of HTML, convert it to utf-8
, then find all div
nodes within the document.
html_fragment("gbk", "utf-8") { $(".//div") { log("found a div tag!") } }
Parses a fragment as HTML.
The html_fragment_doc
function parses a fragment of the document as HTML. This means the document - which is plain text - is converted into a tree-like structure. At this point, we can use XPath and other selectors to navigate the document.
Just as for the html_doc
function, html_fragment_doc
takes two arguments, specifing the %input_encoding
and %output_encoding
. html_fragment_doc("x", "y")
would parse the document from encoding x
into encoding y
.
Common Uses
- Only a small section of the request being processed is HTML, and that fragment must be parsed without adding a
HTML
tag andDOCTYPE
.
The following example will parse a fragment of HTML from gbk
to utf-8
encoding, allowing selectors to point to nodes of the document.
html_fragment_doc("gbk", "utf-8")
Returns the length of the item in characters. This includes whitespace and return characters.
The length
function is used to return the length of the current text node or the provided input string.
Common Uses
- Validating an input string to make sure it is either a minimum or maximum number of characters.
- Finding the length of a string.
In the following example, we log the length of the current text inside the div with an ID of my_div
.
$$("#my_div") { text() { log(length()) } }
The prepend function adds the input text to the beginning of the text scope from which it is called.
The prepend function is used to insert text at the beginning of a text scope.
Common Uses
- Categorizing content by attaching labels or other forms of organized tags.
- Numbering content using the prepend() function in combination with the index() function.
In this example, we prepend a sentence onto the beginning of the text node inside "my_div".
$$("#my_div") { text() { prepend("This is how you prepend text in front of the existing text in #my_div.") } }
Opens a scope to all instances of the regular expression provided that you can then replace using the set()
function.
The replace
function is used to alter existing text nodes by replacing them based on either regular expressions or specific strings.
Things to note: Unless otherwise specified by the Regular Expression, all matches found by the %search
parameter will be replaced.
Common Uses
- Replacing desktop instructions like "click" to mobile instructions like "tap"
- Removing extra or unnecessary text
- Rewriting attributes based on some standard
set
via a regular expression.
In this example we are replacing the text "Replace Me" inside #my_div
with the text "Replaced!".
$$("#my_div") { text() { replace(/Replace Me/) { set("Replaced!") } } }
Replaces the regular expression specified with the text provided.
The replace
function is used to alter existing text nodes by replacing them based on either regular expressions or specific strings.
Things to note: Unless otherwise specified by the Regular Expression, all matches found by the %search
parameter will be replaced.
Related functions: text(), inner()
Common Uses
- Replacing desktop instructions like "click" to mobile instructions like "tap"
- Removing extra or unnecessary text
- Rewriting attributes based on some standard set via a regular expression.
In the following example, we replace the text "Replace Me" inside #my_div
with the text "Replaced!".
$$("#my_div") { text() { replace(/Replace Me/, "Replaced!") } }
Opens a scope to all instances of the regular expression provided that you can then replace
using the set()
function.
The replace
function is used to alter existing text nodes by replacing them based on either regular expressions or specific strings.
Things to note: Unless otherwise specified by the Regular Expression, all matches found by the %search
parameter will be replaced.
Common Uses
- Replacing desktop instructions like "click" to mobile instructions like "tap"
- Removing extra or unnecessary text
- Rewriting attributes based on some standard
set
via a regular expression.
In this example we are replacing the text "Replace Me" inside #my_div
with the text "Replaced!".
$$("#my_div") { text() { replace("Replace Me") { set("Replaced!") } } }
Replaces the regular expression specified with the text provided.
The replace
function is used to alter existing text nodes by replacing them based on either regular expressions or specific strings.
Things to note: Unless otherwise specified by the Regular Expression, all matches found by the %search
parameter will be replaced.
Common Uses
- Replacing desktop instructions like "click" to mobile instructions like "tap"
- Removing extra or unnecessary text
- Rewriting attributes based on some standard set via a regular expression.
In the following example, we replace the text "Replace Me" inside #my_div
with the text "Replaced!".
$$("#my_div") { text() { replace("Replace Me", "Replaced!") } }
Reverses the text in which this function is called.
This function reverses the string text in which it is called.
The example below will replace the text contained in the div with id reverse_me
.
$("//div[@id='reverse_me']") { text() { reverse() } }
The set
function is used to replace the entire current scope with the provided %value
.
The set
function is used to override any existing content in the current scope and set it to the %value
provided.
Things to note: when used in an XMLNode scope, the entire inner HTML will be set -- overriding any child nodes and content.
Common Uses
- Setting the content of text scopes
- Setting the value of attribute scopes
In this example, we set the text node inside "my_div" to "I've been set!".
$$("#my_div") { text() { set("I've been set!") } }
Opens the current node for text modification. Should be used when the manipulation is on text only.
The text()
function is used to either set the text of the current node or to open the text scope of the current node for modification.
Things to note: The text()
function is different from the inner()
function in that it will only return an array of the text nodes inside the element from which it is called. inner()
, on the other hand, will return the entire inner HTML of the node from which it is called.
Related functions: inner()
Common Uses
- Opening the scope for the use of text scope functions such as
replace
,set
,length
,append
,prepend
,clear
and more. - Setting the text of the current node.
In the example, we open the text scope of the div with an ID of "my_div".
$$("#my_div") { text() { # run code on the text scope } }
Returns the current Text scope value as a string.
The this
function is used to point to the current value of the text scope.
This is handy when you want to save / output the currently selected text scope.
text() { log(this()) }
Removes all leading and trailing whitespace, including non-breaking whitespaces.
Removes all leading and trailing whitespace, including non-breaking whitespaces. The example below will become "I am an example". Note there are non-breaking spaces surrounding.
text("   I'm an example             ") text() { trim() }
Parses the document as XML.
The xml
function parses the document as XML. Parsing is essential to enable selection of XML nodes using Tritium.
The example below will parse the document as XML, allowing the selection of nodes with XPath.
xml() { $("/xml") }
absolutize()
attempts to absolutize the scoped URL.
absolutize()
attempts to absolutize the scoped URL.
The function takes no arguments.
Related functions: relativize()
$absoluteURL = url("/query") { absolutize() }
comp(%url_component)
fetches the specified component in the scoped URL.
domain()
fetches the domain of the scoped URL.
domain()
fetches the domain of the scoped URL.
The function takes no arguments.
Note that domain
does not include the URL's port, if one exists.
Related functions: domain(val)
url("http://www.google.com:8080/query") { $old_domain = domain() # www.google.com }
domain(val)
sets the domain of the scoped URL.
domain(val)
sets the domain of the scoped URL.
The function takes one argument, which is the value to set the URL's domain to.
Note that domain
includes the port, if one exists.
Related functions: domain()
url("http://www.google.com:8080/query") { domain("search.google.com:8080") }
fragment()
fetches the fragment of the scoped URL.
fragment()
fetches the fragment of the scoped URL.
The function takes no arguments.
Related functions: fragment(val)
url("http://www.google.com/query#header") { $old_fragment = fragment() # header }
fragment(val)
sets the fragment of the scoped URL.
fragment(val)
sets the fragment of the scoped URL.
The function takes one argument, which is the value to set the URL's fragment to.
Related functions: fragment()
url("http://www.google.com:8080/query#header") { fragment("footer") }
host()
fetches the host of the scoped URL.
host()
fetches the host of the scoped URL.
The function takes no arguments.
Note that host
includes the URL's port, if one exists.
Related functions: host(val)
url("http://www.google.com:8080/query") { $old_host = host() # www.google.com:8080 }
host(val)
sets the host of the scoped URL.
host(val)
sets the host of the scoped URL.
The function takes one argument, which is the value to set the URL's host to.
Note that host
does not include the URL's port, if one exists.
Related functions: host()
url("http://www.google.com:8080/query") { host("search.google.com") }
param(%key)
fetches the query parameter value for the key in the scoped URL.
param(%key)
fetches the query parameter value for the key in the scoped URL.
The function takes one argument, which is the query parameter key for which the value is to be retrieved.
Related functions: param(key, val), remove_param(key)
url("http://www.google.com/query?s=my+text") { $s = param("s") # my+text }
param(key, val)
sets a query parameter in the scoped URL.
param(key, val)
sets a query parameter in the scoped URL.
The function takes two arguments, which are the key and value of the query parameter to be added to the URL.
Related functions: param(key), remove_param(key)
url("http://www.google.com:8080/query?s=my+text") { param("s", "my+new+text") }
password()
fetches the password of the scoped URL.
password()
fetches the password of the scoped URL.
The function takes no arguments.
Related functions: password(val)
url("http://foo:bar@www.google.com/query") { $old_password = password() # bar }
password(val)
sets the password of the scoped URL.
password(val)
sets the password of the scoped URL.
The function takes one argument, which is the value to set the URL's password to.
Related functions: password()
url("http://foo:bar@www.google.com/query") { password("new_bar") }
path()
fetches the path of the scoped URL.
path()
fetches the path of the scoped URL.
The function takes no arguments.
Related functions: path(val)
url("http://www.google.com/query") { $old_path = path() # /query }
path(val)
sets the path of the scoped URL.
path(val)
sets the path of the scoped URL.
The function takes one argument, which is the value to set the URL's path to.
Related functions: path()
url("http://www.google.com:8080/query") { path("new_query") }
port()
fetches the port of the scoped URL.
port()
fetches the port of the scoped URL.
The function takes no arguments.
Related functions: port(val)
url("http://www.google.com:8080/query") { $old_port = port() # 8080 }
port(val)
sets the port of the scoped URL.
port(val)
sets the port of the scoped URL.
The function takes one argument, which is the value to set the URL's port to.
Related functions: port()
url("http://www.google.com:8080/query") { port("80") }
relativize()
attempts to relativize the scoped URL.
relativize()
attempts to relativize the scoped URL.
The function takes no arguments.
Related functions: absolutize()
$relativeURL = url("www.google.com/query") { relativize() # /query }
remove_param(%key)
removes the query parameter for the specified key.
remove_param(%key)
removes the URL parameter for the specified key.
The function takes one argument, which is the key of the query parameter to be removed.
Related functions: param(key), param(key, val)
$url_without_param = url("http://www.google.com/query?s=my+text") { remove_param("s") }
scheme()
fetches the scheme of the scoped URL.
scheme()
fetches the scheme of the scoped URL.
The function takes no arguments.
Related functions: scheme(val)
url("http://www.google.com/query") { $old_scheme = scheme() # http }
scheme(val)
sets the scheme of the scoped URL.
scheme(val)
sets the scheme of the scoped URL.
The function takes one argument, which is the value to set the URL's scheme to.
Related functions: scheme()
url("http://www.google.com/query") { scheme("https") }
userinfo()
fetches the userinfo of the scoped URL.
userinfo()
fetches the userinfo of the scoped URL.
The function takes no arguments.
Related functions: userinfo(val)
url("http://foo:bar@www.google.com/query") { $old_userinfo = userinfo() # foo:bar }
userinfo(val)
sets the userinfo of the scoped URL.
userinfo(val)
sets the userinfo of the scoped URL.
The function takes one argument, which is the value to set the URL's userinfo to.
Related functions: userinfo()
url("http://foo:bar@www.google.com/query") { userinfo("baz:bar") }
username()
fetches the username of the scoped URL.
username()
fetches the username of the scoped URL.
The function takes no arguments.
Related functions: username(val)
url("http://foo:bar@www.google.com/query") { $old_username = username() # foo }
username(val)
sets the username of the scoped URL.
username(val)
sets the username of the scoped URL.
The function takes one argument, which is the value to set the URL's username to.
Related functions: username()
url("http://foo:bar@www.google.com/query") { username("baz") }
The $$
selects elements with a CSS-style selector.
$$
selects an element of HTML using a CSS-style selector. It is used as an alternative selector to the single-dollar sign (which selects via XPath).
The function takes one argument, which is the item to be selected.
People usually find the $$
easier to use - at least in the beginning - as it requires no knowledge of XPath.
Things to note: the $$
converts the CSS selector to an XPath-style selector. It converts it into a local deep search, so could potentially be slower than an XPath selector.
For example, the selector $$("#one")
will be converted into $(".//*[id='one']")
. The double-forward-slash deep search could affect performance.
Related functions: css(selector)
Common Uses
- Selecting many element types based on attributes rather than tag names
- Selecting items without being familiar with XPath
The following example selects every item with the ID
"one".
$$("#one")
The absolutize
function ensures that attribute values are not relative paths.
The absolutize
function takes paths of sources for images and scripts and ensures that they contain a hostname.
Instead of the source being /images/icon.png
, it would be http://example.com/images/icon.png
. This ensures that no unnecessary files are directed through the proxy, increasing performance.
The function can be used in three ways:
* 0 arguments: the function will find all img
and script
child nodes (of the parent scope) and absolutize their src
attribute.
* 1 argument: the %xpath
selector for the node(s) you wish to absolutize.
* 2 arguments: (1) the %xpath
selector for the node(s) you wish to absolutize; and (2) the %attribute
that you want to absolutize (e.g. src
or href
).
#
Absolutizing URLs is often done in projects at the top of the scripts/html.ts
file.
The following examples show the three different the absolutize
function can be used.
$("/html") { absolutize("head/script") # absolutize all scripts inside of the `head` node $("body") { absolutize() # absolutize all images and scripts within the `body` node absolutize(".//img", "data-src") # also absolutize the `data-src` attribute of all images within the `body` node } }
The add_class
function adds a class to the current node.
The add_class
function is used to add a class to the current node.
The function takes one argument - the %class
to be added.
What the function does is takes the current node and appends any existing classes with a space, followed by the class specified.
The add_class
function will therefore not overwrite any existing classes that are present on the node. Contrast this with the attribute
function, which would obliterate any existing classes.
Note that the stdlib version of the add_class
function also normalizes the class.
Common Uses
- Adding a class to the body of the page for page-specific styling
- Keeping existing classes (and associated styles) while adding your own on top
The example below will take the selected div
and add a class of "one" to it.
$("./div") { add_class("one") }
The add_class
function adds a class to the current node.
The add_class
function is used to add a class to the current node.
The function takes one argument - the %class
to be added.
What the function does is takes the current node and appends any existing classes with a space, followed by the class specified.
The add_class
function will therefore not overwrite any existing classes that are present on the node. Contrast this with the attribute
function, which would obliterate any existing classes.
Common Uses
- Adding a class to the body of the page for page-specific styling
- Keeping existing classes (and associated styles) while adding your own on top
The example below will take the selected div
and add a class of "one" to it.
$("./div") { add_class("one") }
Inserts an image tag at the bottom of the current node.
@example add_image_asset("kitten.png")
Inserts an external script tag at the bottom of the current node.
@example add_javascript_asset("hello.js")
Inserts an external stylesheet link at the bottom of the current node.
@example add_sass_asset("main")
Opens the selected attribute for modification.
The attr
function is a shortened form of the attribute
function. It opens the scope of the %name
d attribute.
Common use examples include:
- Opening the scope of the attribute to replace certain characters
The example below will open the scope of the class attribute.
$("./div[@class='one']") { attr("class") {} }
The attr
function sets a value for any attribute (it is like the attribute() function).
The attr
function is a shortened form of the attribute
function, which is used a lot in Tritium. It allows you to modify any attribute on the current node.
The function takes two arguments - the first being the attribute %name
and the second its %value
.
If the attribute already exists on the tag, it will be overwritten by the new %value
specified.
Common Uses
- Overwriting existing classes with your own class
- Adding attributes to enable Uranium
The following example will add an href
of http://example.com
to the selected a
tag.
$("./a") { attr("href", "http://example.com") }
attr_url(attribute_name)
constructs and modifies a parseable URL from the specified Attribute of an XMLNode.
attr_url(attribute_name)
constructs and modifies a parseable URL from the specified Attribute of an XMLNode.
The function takes one argument, the name of the attribute to construct a parseable URL from.
URL functions called in the created URL block will be applied to the attribute.
The function returns the value of the attribute on exiting the block.
The example below will
$("(//a)[1]"){ attr_url("href") { relativize() } }
Opens the selected attribute for modification.
The attribute
function opens the scope of the %name
d attribute.
Common use examples include:
- Opening the scope of the attribute to replace certain characters
The example below will open the scope of the class attribute.
$("./div[@class='one']") { attribute("class") {} }
The attribute
function sets a value for any attribute.
The attribute
function is used a lot in Tritium. It allows you to modify any attribute on the current node.
The function takes two arguments - the first being the attribute %name
and the second its %value
.
If the attribute already exists on the tag, it will be overwritten by the new %value
specified.
Common Uses
- Overwriting existing classes with your own class
- Adding attributes to enable Uranium
The following example will add an href
of http://example.com
to the selected a
tag.
$("./a") { attribute("href", "http://example.com") }
The attributes
function allows you to set multiple attributes on an element.
The attributes
function allows you to set multiple attributes for an element.
It is commonly used instead of the attribute
function, as it leaves open the possibility to add more attributes later on.
The function can take an arbitrary number of arguments in the format name: "value"
Common Uses
- Assigning multiple attributes for Uranium - such as a
data-ur-id
and adata-ur-component
type. - Adding a class while also setting the value of an input.
The following example gives the selected div
two attributes - a class
of "one" and an id
of "two".
$("./div") { attributes(class: "one", id: "two") }
Replaces the current node contents with a CDATA
block.
The cdata
function allows you to insert chunks of CDATA
on your page.
CDATA
is information that is not parsed by the XML parser. Therefore, it can include characters that may break XML (for example, <
). It is often used for inserting JavaScript.
The function takes one argument - the %content
which needs to be passed into the CDATA
block.
The example below will replace the contents of the selected div with a CDATA
block containing the JavaScript alert('Boo')
.
$("./div") { cdata("//<![CDATA[\n alert('Boo!') \n//]]>") }
Removes every node that is not on the path to matches for the supplied xpath.
Using the passed xpath selector, it removes everything under the currently scoped node that does not match and is not on the path to a match. Note it will also remove every node under the match(es), but preserves text directly in the matched nodes. The example below will remove everything under the first ul tag that is not on the path to the first 3 li elements. It will also remove every node under the first 3 li elements.
$("(//ul)[1]") { filter(".//li[position() < 3]") }
Takes all text from under the current node and places it in this node.
Flattens the current node by taking all text under the current node and placing it in this one. The example below will flatten a list. This will destroy the list structure, but preserve all the text within the list.
$("//ul") { flatten() }