simple-mobile 1.0.224
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")) } }
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")
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 ur_tabs
function is used to setup a tabs widget using the Uranium.js framework. Once you have your DOM structure setup properly, just call the ur_tabs
function while inside the element you want to be your tabs, and pass it the XPath selectors for the corresponding buttons and content.
Related functions: ur_toggler(button, content), ur_carousel(items)
Common uses include:
- Setting up a Tabs Widgets
@exampletext Tritium Tester Example
The regexp
function is used to parse regular expressions.
The regexp
function is used to parse expressions and turn them into regular expressions. Regular Expressions are incredibly powerful for selecting and modifying groups of text.
Related functions: match(target, comparitor), with(text), not(text)
Common Uses
- Removing extra text when transitioning from desktop to mobile sites.
- Modifying text to be more clear and concise to fit a smaller viewport.
- Changing instructions such as "click" to "tap" for mobile devices.
- Fixing malformed HTML before the document is parsed so your selectors work properly.
In the following example, we set a variable then try to match four digits in a row. When run, the first log message should be printed. Note that we escape the forward slash.
$var = "123456" match($var, regexp("\d{4}")) { log("My regular expression matched four digits in a row") } match($var, regexp("\d{9}")) { log("My regular expression matched nine digits in a row") }
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() }
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() }
Inserts a tag with the (optional) content at the bottom of the current node.
The insert
function adds the specified %tag
into the currently-selected node.
The function has one obligatory argument - the %tag
name - and one optional argument - the %content
.
There can also be an arbitrary number of extra arguments, specifying attributes for the new element: insert("div", "Content", class: "one")
will add a class of "one" to the new div
node.
There are a number of comparable functions that perform similar functions but specify a position in their name:
* insert_top(Text %tag, Text %inner)
* insert_bottom(Text %tag, Text %inner)
* insert_before(Text %tag, Text %inner)
* insert_after(Text %tag, Text %inner)
Common use examples include:
- Adding an
a
tag to link to the desktop site - Inserting a header or footer on a page
The example below will insert a div
with the content "Content" into the bottom of the current node.
insert("div", "Content")
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 \ } }
Converts the inside of the current node into plain text (i.e. stripping it of all HTML).
The inner_text
function converts the entirety of the current node into text.
The function essentially removes all HTML
nodes and returns the text of the element.
Common Uses
- Extracting text from a table
- Grabbing the text of an anchor while removing its tag
The example below will "flatten" the table, leaving only the text of the table in the tag.
$("./table") { inner_text }
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 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") }
Moves the current element's children to the node specified.
The move_children_to
function is used to move children of the current node into another node.
The function takes two arguments:
* %tag_name
: The new node that the children will be moved into
* %pos
: The position at which the children will be moved
Things to note: the arguments can not be strings; entering XPath selectors will not work. To enter the node argument, you must select that node and assign a local variable to the node (using %
). For the position, you must use the position function as in the following example.
Because of the complexity of setting a variable, this function is mainly used in function definitions - e.g., the inner_wrap
function.
In the example below, the div
with class one
is selected, and a local variable %one
is set. The variable is then used later, once we have selected div
with class two
. That div
's children will be moved to the top of the former div
.
$("./div[@class='one']") { %one = this() $("../div[@class='two']") { move_children_to(%one, position("top")) } }
Wraps the current node in a new tag.
The wrap
function takes the current node and wraps it in a new tag.
The function requires one argument - the new %tag
. It also takes an arbitrary number of additional arguments specifying attributes and their values.
For example, you can specify a class using class: "my_class"
as a second argument.
Common Uses
- Wrapping elements in an
li
tag to form a list - Wrapping an element in an
a
tag to make a link
The example below will wrap the selected a
tag in a div with the class "one".
$("./a") { wrap("div", class: "one") }
The match
function is used for logic to check against the content of strings and variables.
The match
function is used for pseudo-logic in Tritium. With match()
, you have the equivalent of if-else
and case
statements in many other programming languages. Match
is used to test the content of variables with strings, regular expressions, and other variables, and then run code according to whether or not the match is successful.
Things to note: If you have more than one variable or regular expression to test againt, you can simply provide the match
function with the variable in question, and then use embedded with()
statements for each case. You can also provide a final else()
statement to serve as a catchall for all unsuccessful matches.
Related functions: with(text), else(), not(text), match_not(target, comparitor)
Common Uses
- Matching on the
$path
of the response to@import
page-specific Tritium scripts. - Matching attributes with specific content to change them in some way.
- Simulating
if-then-else
statements and boolean (true/false
) logic to evaluate different Tritium. - Matching the
$status
,$content-type
, or other information from the incoming response headers.
In the following example, we match the $path
variable to see if it matches the string product
. Since it does, the log "Match successful!" will output to the terminal.
$path = "product" match($path, "product") { log("Match successful!") }
Specifies positional information.
For some functions, you cannot enter a position as a text string. In these cases, you need to enter a position using the position
function.
The function takes one argument, which is the %position
you wish to specify. Possible positions include "top", "bottom", "before" and "after".
The example below will move the div
to the top of the body node.
$("./div") { move_to("/html/body", position("top")) }
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() } }
The ur_component
function is used to set component types for the Uranium.js framework. Types include: button
, content
and more.
Things to note: Once you have your DOM structure setup properly, you can actually just call higher level functions such as ur_toggler
, ur_tabs
, and ur_carousel
to setup all the proper attributes and types at once.
Related functions: ur_toggler(button, content), ur_tabs(button, content), ur_carousel(items)
Common uses include:
- Setting up Uranium Widgets
@exampletext Tritium Tester Example
The ur_carousel
function is used to setup a carousel widget using the Uranium.js framework. Once you have your DOM structure setup properly, just call the ur_carousel
function while inside the element you want to be your carousel, and pass it the XPath selectors for the corresponding image %items
.
Related functions: ur_toggler(button, content), ur_tabs(button, content), ur_map(addresses, descriptions, canvas)
Common uses include:
- Setting up a Maps Widget
Common uses include:
- Setting up a Carousel Widget
@exampletext Tritium Tester Example
The with
function is used with match()
to match a variable with multiple possibilities.
The match
function is used for pseudo-logic in Tritium. With match()
, you have the equivalent of if-else
and case
statements in many other programming languages. The with()
statement is used inside a match()
statement to match the variable with certain strings or regular expressions. If the input %text
is contained in the matched variable, then the code block inside the with()
statement is executed.
Things to note: You can have multiple with()
statements inside a single match
statement. They are executed sequentially, and as soon as one with()
statement is matched successfully, the rest will be skipped over.
Common Uses
- Matching the
$path
of the incoming request and@import
a corresponding Tritium script. - Matching attributes with certain content to determine if they need to be changed in some way.
- Simulating
if-then-else
statements and boolean (true-false
) logic to run differing Tritium. - Matching the
$status
,$content-type
, or other information from the incoming headers.
In this example, we match the $var
variable with the string "Match Me". Since the match is successful, the log
is then executed.
$var = "Match Me" match($var) { with("Match Me") { log("Match successful!") } }
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 match
function is used for logic to check against the content of strings and variables.
The match
function is used for pseudo-logic in Tritium. With match()
, you have the equivalent of if-else
and case
statements in many other programming languages. match
is used to test the content of variables with strings, regular expressions, and other variables, then run code according to whether or not the match is successful.
Things to note: If you have more than one variable or regular expression to test againt, you can simply provide the match function with the variable in question and then use embeded with() statements for each case. You can also provide a final else() statement to serve as a catchall for all unsuccessful matches.
Common Uses
- Matching the
$path
of the incoming request and@import
a corresponding Tritium script. - Matching attributes with certain content to determine if they need to be changed in some way.
- Simulating
if-then-else
statements and boolean (true-false
) logic to run differing Tritium. - Matching the
$status
,$content-type
, or other information from the incoming headers.
In the following example, we match the $path
variable to see if it matches the regular expression /product/
. Since it does, the log "Match successful!" will output to the terminal.
$path = "product" match($path) { with(/product/) { log("Match successful!") } else() { log("Match unsuccessful.") } }
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!") } }
The ur_maps
function is used to setup a maps widget using the Uranium.js framework. Once you have your DOM structure setup properly, just call the ur_maps
function while inside the element you want to be your maps, and pass it the XPath selectors for the corresponding %addresses
, %descriptions
, and %canvas
.
Related functions: ur_toggler(button, content), ur_tabs(button, content), ur_carousel(items)
Common uses include:
- Setting up a Maps Widget
@exampletext Tritium Tester Example
Removes children nodes that contain text.
The remove_text_nodes
function takes all text that is a direct child of the current node and removes it.
Any non-text nodes (e.g. anchor tags, image tags, etc.) will remain intact.
Common Uses
- Removing blank text nodes in between elements
The following example will remove only text nodes from the div
.
$("./div") { remove_text_nodes() }
The ur_toggler
function is used to setup a toggler widget using the Uranium.js framework. Once you have your DOM structure setup properly, just call the ur_toggler
function while inside the element you want to be your toggler, and pass it the XPath selectors for the corresponding buttons and content.
Related functions: ur_tabs(button, content), ur_carousel(items)
Common uses include:
- Setting up a Toggler Widgets
@exampletext Tritium Tester Example
Inserts javascript in the current node at the position specified.
The insert_javascript_at
function wraps the specified JavaScript (%js
) in a script
tag and inserts it in the specified position (%pos
) of the current node.
Things to note: this version of the function accepts a text argument denoting the position.
Acceptable positions: top
, bottom
, before
and after
.
The following example inserts a script
tag containing alert('Boo')
at the top of the selected element.
insert_javascript_at("top", "alert('Boo')")
Inserts javascript in the current node at the position specified.
The insert_javascript_at
function wraps the specified JavaScript (%js
) in a script
tag and inserts it in the specified position (%pos
) of the current node.
Things to note: the first argument has to be in the position scope, meaning that plain text is not valid. You must place the text within the position function, as in the example.
Acceptable positions: top
, bottom
, before
and after
.
The following example inserts a script
tag containing alert('Boo')
at the top of the selected element.
insert_javascript_at(position("top"), "alert('Boo')")
The var
function allows you to set global variables.
The var
function is used to set global variables that can be used for various logic throughout your code.
Common Uses
- True/False logic
- Storing fetched text and attributes
- Using stored values in a
match()
statement to run different Tritium scripts.
The following example simply illustrates how to set a variable manually to whatever %name
and value you desire.
var("my_var") { set("is set") } log($my_var)
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") }
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.
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 text
function with an argument replaces the current node's interior with the text.
The text
function behaves slightly differently when an argument is passed into it.
The function takes one argument, which is the %value
that will appear in the element.
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.
Compare this to the inner
function, which will insert the tag itself.
The example below will replace the interior of the div
with the text "NewText".
$("./div") { text("NewText") }
The encode64
function encodes the specified string using a base64 encoder.
The encode64
function encodes the specified string using a base64 encoder.
In the following example, we encode %password
.
$encoded_password = encode64(%password)
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!") \ } } }
The position
function is used to return a position type.
The position
function is used to return a position type. Positions include: before
, after
, above
, below
, top
and bottom
.
Things to note: by default, the position type returned is "bottom". You can also specify which position type you'd like to return by passing it in as a parameter.
Common Uses
- Some functions require position inputs as parameters. You can call
position()
to fulfill this requirement. - When defining custom functions you may want to use a
position
type in your definition.
In this example, we move the current node to the bottom of its parent.
move_to("..", position())
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") } }
The upcase
function is used to return the %input_string
in all uppercase letters.
The upcase
function is used to return the provided %input_string
in all uppercase letters.
Common Uses
- Making buttons more prominent such as SIGN IN or SIGN UP NOW.
In this example, we fetch the ID
of the div with the ID
"my_div", then we log
a concat
statement using uppercase letters for the name of the div.
$$("#my_div") { $name = fetch("./@id") log(concat("I've reached ", upcase($name), "!")) }
This function allows you to easily set Uranium attributes.
The ur_attribute
function is used to set attributes for the Uranium.js framework. The framework then adds event listeners based on the structure and attributes you have set so users can interact with your amazing mobile widgets!
Things to note: Once you have your DOM structure setup properly, you can actually just call higher level functions such as ur_toggler
, ur_tabs
, and ur_carousel
to setup all the proper attributes at once.
Related functions: ur_toggler(button, content), ur_tabs(button, content), ur_carousel(items)
Common uses include:
- Setting up Uranium Widgets
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 with
function is used with match()
to match a variable with multiple possibilities.
The match
function is used for pseudo-logic in Tritium. With match()
, you have the equivalent of if-else
and case
statements in many other programming languages. The with()
statement is used inside a match()
statement to match the variable with certain strings or regular expressions. If the input %text
is contained in the matched variable, then the code block inside the with()
statement is executed.
Things to note: You can have multiple with()
statements inside a single match statement. They are executed sequentially, and as soon as one with()
statement is matched successfully, the rest will be skipped over.
Common Uses
- Matching the
$path
of the incoming request and@import
a corresponding Tritium script. - Matching attributes with certain content to determine if they need to be changed in some way.
- Simulating
if-then-else
statements and boolean (true-false
) logic to run differing Tritium. - Matching the
$status
,$content-type
, or other information from the incoming headers.
In this example, we match the $var
variable with the regular expression "Match Me". Since the match is successful, the log
is then executed.
$var = "Match Me" match($var) { with(/Match Me/) { log("Match successful!") } }
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.") } }
Returns true
or false
depending on whether the nodes are equal.
The equal
function takes two nodes and compares them to see if they are equal.
Things to note: you cannot use text as input for this function. You should set a variable using this()
on your current node, then use that variable as an argument.
This function takes two arguments - the two nodes (%a
and %b
) you wish to equate.
Common use examples include:
- Ensuring that a function is not performed on itself, potentially avoiding a loop.
The following example will compare the div
node twice: first to its anchor child (where the log
will return false
, because the two nodes are not equal), then with itself (where the log message will be true
).
$("./div") { %div = this() $("./a") { log(equal(%div, this())) \ $("..") { log(equal(%div, this())) } } }
The var
function allows you to set global variables.
The var
function is used to set global variables that can be used for various logic throughout your code.
Common Uses
- True/False logic
- Storing fetched text and attributes
- Using stored values in a
match()
statement to run different Tritium scripts.
The following example simply illustrates how to set a variable manually to whatever %name
and %value
you desire.
var("my_var", "is set") log($my_var)
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()) }
Inserts javascript in a script tag in the current node.
The insert_javascript
function inserts javascript into the currently-selected node. It wraps the specified JavaScript (%js
) in a script
tag and inserts it into the current node.
By default, the script is inserted in the bottom of the node.
There are a number of comparable functions that perform similar functions and specify a position in their name:
* insert_javascript_top(Text %js)
* insert_javascript_bottom(Text %js)
* insert_javascript_before(Text %js)
* insert_javascript_after(Text %js)
Common use examples include:
- Javascript needs to be added to a specific node rather than globally
In the following example, the JavaScript alert('Boo')
will be inserted at the bottom of the current node.
insert_javascript("alert('Boo')")
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 decode64
function decodes the specified string using a base64 decoder.
The decode64
function decodes the specified string using a base64 decoder.
In the following example, we decode %encoded_password
.
$decoded_password = decode64(%encoded_password)
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!") } }
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") }
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 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") }
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() }
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!") \ } } }
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") \ } }
The not
function is used with match()
as an opposite to with()
.
The not
function is used inside a match()
statement as an opposite to the with()
statement. In other words, if the match is not successful, the code inside the not()
block will run, whereas if the match is successful, the code will be skipped over.
Common Uses
- When the page is structured such that you only know which scripts you want to run when certain content does not exist.
- When you are mapping URL paths to page types and you know what content must not exist in the path to fulfill a mapping requirement.
In the following example, we match the variable $var
with the not()
statement of "Match You". Since that statement does not exist in the variable, the log
inside the not
statement will be executed.
$var = "Match Me" match($var) { not("Match You") { log("The $var variable does not contain the string Match You!") } }
This function allows you to easily set Uranium widget types.
The ur_set
function is used to set widget types for the Uranium.js framework. Types include: toggler
, tabs
, carousel
and more.
Things to note: Once you have your DOM structure setup properly, you can actually just call higher level functions such as ur_toggler
, ur_tabs
, and ur_carousel
to setup all the proper attributes and types at once.
Related functions: ur_toggler(button, content), ur_tabs(button, content), ur_carousel(items)
Common uses include:
- Setting up Uranium Widgets
Sets a cookie on the site.
The add cookie function adds a cookie to the site. The function can take anywhere from one to seven arguments. The function is most commonly used with three: the name of the cookie, its value, and the domain. The domain argument should be entered as if it were from an upstream response (i.e. use "example.com", not "m.example.com"). The cookie domain will be rewritten as per the host_map rules. Other optional arguments include (add them in this order): - the path of the cookie - when the cookie will expire - whether the cookie is secure (given as "true" or "false") - whether the cookie is HTTP only or not (given as "true" or "false") The example below will set a cookie with the name "favouritedog", the value "joe" and the domain "www.example.com".
add_cookie("favoritedog", "joe", "www.example.com")
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") } } }
Wraps the selected node(s) in a specific tag.
The wrap together function takes the nodes specified and wraps them in a tag specified. The function takes two arguments. The first is the tag (or tags) that you want to be wrapped. The second is the tag in which you want to wrap them. An arbitrary number of extra arguments can be added specifying attributes for the wrapper tag. They should be in the format name: "value". For example, class: "New Class". In the example below, all the a tag children of the selected div will be wrapped in a single span.
$("./div") { wrap_together("./a", "span") }
The else
function completes the pseudo-logic of with()
in your match()
statements, allowing the specification of a catchall alternative.
The else()
function is used inside your match()
statements to serve as a catchall for when none of your with()
statements find a successful match. The else()
function will then serve as your default behavior for unanticipated match cases.
Common Uses
- Serving as a catchall for common errors, such as unrecognized URL mappings.
- Completing
if-else
pseudo logic whenmatch
ing variables, attributes, and other traits of the current DOM. - Generally providing a default behavior for your Tritium scripts.
In the following example, the $var
value does not match the existing with()
statement, which means the else()
statement will run its inner code block.
$var = "Match me." match($var) { with("No match.") { log("This log won't be run...") } else() { log("Because the else statement was matched this time!") } }
The export
function is used to set response header information such as content-type
, cache-time
, and more.
The export
function is used when you want to change the outgoing response header.
Things to note: You cannot currently export the status of the response header (i.e. 200, 302, etc.).
Common Uses
- Malformed HTML or Javascript with the wrong
content-type
set. - Setting the
Cache-Time
of the page. - Setting the
Location
for a redirect.
In this example, we are setting the Content-Type
to "text/html".
html() { export("Content-Type", "text/html") }
$$("#my_div") { text() { # run code on the text scope } }
Removes the node specified.
The remove
function deletes the element specified by the selector.
The function takes one argument - the %xpath_selector
which specifies the location of the node to be removed.
As you can select attributes using XPath, it is possible to delete attributes using the remove()
function. Select an attribute using the @
sign - for example @class
will select a class.
Common Uses
- Removing all the
<br>
tags in a paragraph - Removing
style
attributes from tags
The example below will remove all span
children of the div
.
$("./div") { remove("./span") }
The match_not
function is used opposite the match
function to check that strings and variables do not contain certain content.
The match_not
function is used for pseudo-logic in Tritium. With match()
, you have the equivalent of if-else
and case
statements in many other programming languages. Match
is used to test the content of variables with strings, regular expressions, and other variables, then run code according to whether or not the match is successful. Match_not()
essentially inverts what you would expect from the match
function. This means that if a match is not successful, then the block of code inside that match_not()
or with()
statement will run.
Things to note: If you have more than one variable or regular expression to test againt, you can simply provide the match_not
function with the variable in question and then use embeded with()
statements for each case. You can also provide a final else()
statement to serve as a catchall for all unsuccessful matches.
Related functions: with(text), else(), not(text), match(target)
Common Uses
- Matching on the
$path
of the response to@import
page-specific Tritium scripts. - Matching attributes with specific content to change them in some way.
- Simulating
if-then-else
statements and boolean (true/false
) logic to evaluate different Tritium. - Matching the
$status
,$content-type
, or other information from the incoming response headers.
In the following example, we match the $path
variable to see if it matches the string "price". Since it does not, the log "Match successful!" will output to your terminal.
$path = "product" match_not($path, /price/) { log("Match successful!") }
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") } }
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") }
Rewrites links to point to the correct domain.
The rewrite link function takes links on the regular site and rewrites them to modified links. On a mobile site, you do not want the links to point to the desktop site. This function fixes that. For most projects, link rewriting is done automatically via the "rewrite_links()" function found in html.ts.
rewrite_link()
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") }
The concat
function is used to concatenate two or more strings.
The concat function is used to combine two or more strings into a single string. Things to note: The concat function takes at least two strings and up to ten strings as input parameters. These parameters will be combined in the order in which they are provided.
Common Uses
- In
log
statements when outputting some combination of variables and description of those variables. - When selecting elements based on variables or attributes, they may need to be formatted properly using the concat function.
- When manipulating text scopes and combining the content of several scopes.
In this example, we fetch the ID
of the div with the ID
"my_div", then we log
a concat
statement to the terminal output.
$$("#my_div") { $name = fetch("./@id") log(concat("Did I reach ", $name, "?")) }
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")) } }
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")) }
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 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") }
Wraps the content of the currently-selected node in the tag specified.
The inner_wrap
function takes all the content of the current node and wraps it.
The function takes one argument and that is the %tag_name into which you want to wrap the content of the current node.
Common Uses
- Wrapping all interior content into an anchor tag
- Wrapping a mixture of text and nodes into one tag
The following example will take the contents of the div
and wrap them in a span
.
$("./div") { inner_wrap("span") }
Returns the current iteration of the function being performed.
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 MoovSDK 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.
Note that the function does not necessarily give the index of the current node in relation to its siblings. It is the number of iterations the previous selection has gone through.
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 example below will assign a class to every div
. The first div
that is encountered will have a class of "div_number_1". The second div
found will be "div_number_2" etc.
$("./div") { attribute("class", "div_number_" + index(this())) }
References a Sass stylesheet in the stylesheets folder.
The sass
function points to the stylesheets directory of your project, allowing for easy reference to your stylesheets.
The function takes one argument, which is the %filename
of the stylesheet. The file should be referenced in relation to the assets/stylesheets
folder.
As the function is mainly used to reference stylesheets in the project, this function is usually only found once. Most projects only inject one stylesheet.
In the functions/main.ts
file, you can see the sass
function being used in the add_assets
function, which inserts a link to the main stylesheet.
Related functions: asset(name)
The following example will insert a link
tag with an href
pointing to the assets/stylesheets/.css/main.css
file of the project.
insert("link", rel: "stylesheet", type: "text/css", href: sass("main")
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() } }
Returns the length of the %input
.
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 this example, we log
the length of the %input
string "text".
$$("#my_div") { text() { log(length("text")) } }
The log
function is used to write out a string to the console. It's often useful for debugging Tritium.
The log
function is used to output information to the terminal.
Common Uses
- Checking the value of environment variables
- Displaying status messages as the result of certain matches or logic
- Debugging Tritium that isn't working in development
The following example shows the typical use case for debugging Tritium that isn't working. This is often done by setting logs throughout your code to see if you selectors and logic is executing the proper statements.
log("I've reached this point in the code!")
The match_not
function is used opposite the match
function to check that strings and variables do not contain certain content.
The match_not
function is used for pseudo-logic in Tritium. With match()
, you have the equivalent of if-else
and case
statements in many other programming languages. Match
is used to test the content of variables with strings, regular expressions, and other variables, then run code according to whether or not the match is successful. Match_not()
essentially inverts what you would expect from the match
function. This means that if a match is not successful, then the block of code inside a match_not()
or with()
statement will run.
Things to note: If you have more than one variable or regular expression to test againt, you can simply provide the match_not
function with the variable in question, then use embedded with()
statements for each case. You can also provide a final else()
statement to serve as a catchall for all unsuccessful matches.
Related functions: with(text), else(), not(text), match(target)
Common Uses
- Matching on the
$path
of the response to@import
page-specific Tritium scripts. - Matching attributes with specific content to change them in some way.
- Simulating
if-then-else
statements and boolean (true/false
) logic to evaluate different Tritium. - Matching the
$status
,$content-type
, or other information from the incoming response headers.
In the following example, we match the $path
variable to see if it matches the string "price". Since it does not, the log "Match successful!" will output to your terminal.
$path = "product" match_not($path, "price") { log("Match successful!") }
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)) }
Selects the element specified with a CSS-style selector.
The css
function selects elements on a page using a CSS-style selector.
The function takes one argument, the item to be selected. The argument is written as a standard CSS selector - for example #one
to search for an id
.
Things to note: the css()
function converts the CSS selector to an XPath-style selector. It converts it into a local deep search, so it will usually be slower than an XPath selector.
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 example below will remove any element on the page with an id
of "one".
css("#one") { remove() }
Wraps text children inside a new tag.
The wrap_text_children
function takes all the children of the current node and wraps them in a %tag_name
node.
The function takes one argument: the %tag_name
for the node in which you want to wrap the text children.
Things to note: the function will wrap all text children -- including whitespace. This often results in empty tags being generated.
Common use examples include:
- Wrapping all text children in tags so that they can then be subsequently removed
- From a mixture of text nodes and HTML nodes, wrapping text children in a tag allows for easier manipulation
The example below will take all the text node children of the span and wrap them in div
s.
$("./span") wrap_text_children("div") }
Opens the inside of the current node for modification.
The inner
function replaces the inside of the current node with the specified %html
.
Things to note: the interior of the current node will be obliterated and replaced with the input.
If the %html
contains tags, these will be rendered as HTML elements.
Compare to the text()
function, which replaces the content with text only.
Common uses cases:
- Setting the inside of a node with both text and a new node
The example below will replace all of the content of the current div with "New Content".
$("./div") { inner("New Content") }
The downcase
function is used to return the %input_string
in all lowercase letters.
The downcase
function is used to return the provided %input_string
in all lowercase letters.
Common Uses
- Making text less prominent.
In this example, we fetch the ID
of the div with the ID
"my_div", then we log
a concat
statement using lowercase letters for the name of the div.
$$("#my_div") { $name = fetch("./@id") log(concat("I've reached ", downcase($name), "!")) }
Inserts a tag with the (optional) content at the location given.
The insert_at
function inserts a new node of type %tag
into the document at the position %pos
containing %content
. The %content
parameter is optional.
Things to note: the position (%pos
) is relative to the current node.
There can also be an arbitrary number of extra arguments, specifying attributes for the new element: for example, insert_at("top", "div", "Hello, Tritium!", class: "one")
will add a class of "one" to the new div
node.
Common use examples include:
- Creating a button/content element for Uranium
The following example will insert a div
tag at the top of the current node. The tag will have the content "Hello, Tritium!".
insert_at("top", "div", "Hello, Tritium!")
The set
function, when given two arguments, assigns an attribute to the selected element.
The set
function allows you to set an attribute on an element.
The function takes two arguments. The first is the %name
of the attribute and the second is the %value
for that attribute.
Related functions: attribute(name, value)
The following example will take the a
tag and set an href
attribute with the value http://example.com
.
$("./a") { set("href", "http://example.com") }
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!") \ } }
The export
function is used to set response header information such as content-type, cache-time, and more.
The export
function is used when you want to change the outgoing response header.
Things to note: You cannot currently export the status of the response header (e.g. 200, 302, etc.).
Common Uses
- Malformed HTML or Javascript with the wrong
content-type
set. - Setting the Cache-Time of the page.
- Setting the Location for a redirect.
In the following example, we set Content-Type
to text/html
.
html() { export("Content-Type", "text/html") }
Opens the current node for modification, overwriting anything that is already present.
The inner
function opens the scope of the current node for manipulation.
Related functions: inner(html)
Common Uses
- Opening the inner scope to replace contents
The following example will open the scope of the current div
and replace everything with "NEW".
$("./div") { inner() { set("NEW") } }
The time
function returns the time it has taken to reach that point thus far.
The time
function returns the time-to-execute the Tritium code up until it hits the function call.
Things to note: The time taken varies for each implementation, so to have an accurate sense of time, several trials should be run.
Common Uses
- Optimizing Tritium script performance.
In the following example, we display how to log the time()
output to the terminal using the log()
function.
log(time())
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") }
Opens the current node for text modification or retrieves text.
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.
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 inside of the div to be "NewText".
$("./div") { text() { set("NewText") } }
Allows you to pass in external files as a string.
The read function allows you to insert a file or external HTML document into existing markup. The function takes one argument - the file to be read. It should be referenced relative to the current file.
Common Uses
- Injecting a header scaffold on a page
- Add radically different markup for a page
In the example below, we inject the contents of the header.html file at the top of the body.
$("./body") { inject_top(read("header.html")) }
The bm
function prints in the terminal output the time a block took to run.
The bm
function is used to test the performance of your code by the proxy. From our experience, the majority of your performance boost will come from optimizing the images, scripts, and stylesheets of the proxied website. However, there are ways to improve performance of the execution of the proxy, such as using XPath selectors instead of CSS selectors and avoiding deep searches for content in the DOM.
Things to note: The bm()
measurements vary between trials, so you may have to run several samples to get an accurate representation of execution speed.
Related functions: time()
Common Uses
- Measuring the time it takes for a block of code to run.
$("./body") { bm("TIME") }
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!") \ } }
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>") }
Parses a fragment of the document as HTML, using the encodings specified.
The html_fragment
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
function, html_fragment
can take up to two arguments:
* 0 arguments: the function guesses the HTML encoding, then opens it.
* 1 argument: the function parses the document with the specified encoding, then opens it for modification.
* 2 arguments: the 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!") } }
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.
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[ alert('Boo!') //]]>") }
# first example @func XMLNode.foo { $a = "dog" yield() \ log($a) } # second example foo() { $a = $a + "cat" } @func XMLNode.foo { $a = "dog" log($a) yield() } foo() { $a = $a + "cat" }
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") } }
Rewrites javascript to the correct domain.
The rewrite js function ensures that all javascript points to the correct domain - rewriting anything from a regular desktop link to a modified link. For example, the domain example.com will be rewritten as m.example.com on a mobile site in the javascript.
rewrite_js()
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 match
function is used for logic to check against the content of strings and variables.
The match
function is used for pseudo-logic in Tritium. With match()
, you have the equivalent of if-else
and case
statements in many other programming languages. Match
is used to test the content of variables with strings, regular expressions, and other variables, then run code according to whether or not the match is successful.
Things to note: If you have more than one variable or regular expression to test against, you can simply provide the match function with the variable in question and then use embedded with()
statements for each case. You can also provide a final else()
statement to serve as a catchall for all unsuccessful matches.
Related functions: with(text), else(), not(text), match_not(target, comparitor)
Common Uses
- Matching on the
$path
of the response to@import
page-specific Tritium scripts. - Matching attributes with specific content to change them in some way.
- Simulating
if-then-else
statements and boolean (true/false
) logic to evaluate different Tritium. - Matching the
$status
,$content-type
, or other information from the incoming response headers.
In the following example, we match the $path
variable to see if it matches the string product
. Since it does, the log "Match successful!" will output to the terminal.
$path = "product" match($path, /product/) { log("Match successful!") }
The regexp
function is used to parse regular expressions.
The regexp
function is used to parse %expressions
and turn them into regular expressions. Regular Expressions are incredibly powerful for selecting and modifying groups of text.
Things to note: The %options
input provides flags for the regular expression such as i
, which indicates it should be case insensitive.
Common Uses
- Removing extra text when transitioning from desktop to mobile sites.
- Modifying text to be more clear and concise to fit a smaller viewport.
- Changing instructions such as "click" to "tap" for mobile devices.
- Fixing malformed HTML before the document is parsed so your selectors work properly.
In the following example, we use the string "true" and turn it into a regular expression to use in a match-with
statement. We are also accepting any combination of upper and lower case because of the i
flag. If the string "true" is anywhere in the text we are matching, the code in the with()
statement will run.
with(regexp("true", "i")) { # run this code if your text matches the string "true" # the "i" indicates that the match is case insensitive }
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") } }
The not
function is used with match()
as an opposite to with()
.
The not
function is used inside a match()
statement as an opposite to the with()
statement. In other words, if the match is not successful, the code inside the not()
block will run, whereas if the match is successful, the code will be skipped over.
Common Uses
* When the page is structured such that you only know what scripts you want to run when certain content does not exist.
* When you are mapping URL paths to page types and you know what content must not exist in the path to fulfill a mapping requirement.
In the following example, we match the variable $var
with the not()
regular expression "Match You". Since that statement does not exist in the variable, the log
inside the not
statement will be executed.
$var = "Match Me" match($var) { not(/Match You/) { log("The $var variable does not successfully match the regex Match You!") } }