Tellurium Tutorial Series: the power of Tellurium UI templates

[John.Ji...@gmail.com]

Table and List are two objects that can hold UI elements and you can
access each of them by index/indices. Table is two dimension and List
is one dimension. Templates usually are defined for them. Template has
special UIDs such as "2", "all", or "row: 1, column: 2". There are two
purposes to use templates:

1) There are many identical UI elements, you can use one template to
represent them
2) There are variable/dynamic size of UI elements at runtime, you know
the patterns, but not the size. Here, template is also a perfect fit
for it.

Let us look at case 1), we have the following HTML source

<ul class="a">
<li>
<A HREF="site?tcid=a"
class="b">AA
</A>
</li>
<li>
<A HREF="site?tcid=b"
class="b">BB
</A>
</li>
<li>
<A HREF="site?;tcid=c"
class="b">CC
</A>
</li>
<li>
<A HREF="site?tcid=d"
class="b">DD
</A>
</li>
<li>
<A HREF="site?tcid=e"
class="b">EE
</A>
</li>
<li>
<A HREF="site?tcid=f"
class="b">FF
</A>
</li>
</ul>

You have six links there. Without templates, you have to write six
UrlLinks. Look at how simple by using the template

ui.List(uid: "list", clocator: [tag: "ul", class: "a"], separator:"li")
{
UrlLink(uid: "all", clocator: [class: "b"])
}

For case 2, one use case is data grid. Look at our Tellurium Issues
page the "issueResult" data grid, which shows the issues.

ui.Table(uid: "issueResult", clocator: [id: "resultstable", class:
"results"], group: "true") {
//define table header
//for the border column
TextBox(uid: "header: 1", clocator: [:])
UrlLink(uid: "header: 2", clocator: [text: "%%ID"])
UrlLink(uid: "header: 3", clocator: [text: "%%Type"])
UrlLink(uid: "header: 4", clocator: [text: "%%Status"])
UrlLink(uid: "header: 5", clocator: [text: "%%Priority"])
UrlLink(uid: "header: 6", clocator: [text: "%%Milestone"])
UrlLink(uid: "header: 7", clocator: [text: "%%Owner"])
UrlLink(uid: "header: 9", clocator: [text: "%%Summary + Labels"])
UrlLink(uid: "header: 10", clocator: [text: "%%..."])

//define table elements
//for the border column
TextBox(uid: "row: *, column: 1", clocator: [:])
//For the rest, just UrlLink
UrlLink(uid: "all", clocator: [:])
}

Ingore the header portion, aren't the definitions very simple and
cool?

At runtime, you can use

int mcolumn = getTableMaxRowNum("issueResult")

to get the actual row number.

You may wonder how to use the templates if you have multiple templates
such the "issueResult" table as shown above. The rule to apply the
templates is "specific one first, general one later".

For List, you only have templates for index "i" and for "all", the
rule applying chain will be

List[i] -> template for index "i" -> template for "all"

Table is more complicated since it has templates for cell, whole row,
whole column, and "all". The rule applying chain will be

Table[i][j] -> template for cell [i][j] -> template for any row and
column [j] -> template for row[i] and any column -> template for "all"

Along the search chain, once a template is found, Tellurium will stop
and use that template. If none could be found, Tellurium will treat
the UI element as a TextBox without a tag so that you can get some
information about it.

Let me show you how it works, look at the "issueResult" Table.

"issueResult[1][1]" -> found template template TextBox(uid: "row: *,
column: 1", clocator: [:]) -> return TextBox
"issueResult[1][2]" -> no matching template for "row:1, column: 2" ->
found template for "all" -> return UrlLink
"issueResult[2][2]" -> no matching template for "row:2, column: 2" ->
found template for "all" -> return UrlLink

Look at a more complicate example to better illustrate the procedure
(ignore the clocator contents here)

ui.Table(uid: "table", clocator: [:]){
InputBox(uid: "row: 1, column: 1", clocator: [:])
Selector(uid: "row: *, column: 2", clocator: [:])
UrlLink(uid: "row: 3, column: *", colocator: [:])
TextBox(uid: "all", clocator: [:])
}

Let us see the procedure as follows,

"table[1][1]" -> found InputBox(uid: "row: 1, column: 1", clocator:
[:]) -> return InputBox
"table[1][2]" -> no matching template for "row: 1, column: 2" -> found
template Selector(uid: "row: *, column: 2", clocator: [:]) -> return
Selector
"table[1][3]" -> no matching template for "row: 1, column: 3" -> no
matching template for "row: *, column: 3"
-> no matching template for "row: 1, column: *" -> found
template for "all" -> return TextBox
"table[2][1]" -> no matching template for "row: 2, column: 1" -> no
matching template for "row: *, column: 1"
-> no matching template for "row: 2, column: *" -> found
template for "all" -> return TextBox
"table[2][2]" -> no matching template for "row: 2, column: 2" -> found
template for "row: *, column: 2" -> return Selector
"table[2][3]" -> no matching template for "row: 2, column: 3" -> no
matching template for "row: *, column: 3"
-> no matching template for "row: 2, column: *" -> found
template for "all" -> return TextBox
"table[3][1]" -> no matching template for "row: 3, column: 1" -> no
matching template for "row: *, column: 3"
-> found template for "row: 3, column: *" -> return
UrlLink
"table[3][2]" -> no matching template for "row: 3, column: 2" -> found
template for "row: *, column: 2" -> return Selector
"table[3][3]" -> no matching template for "row: 3, column: 3" -> no
matching template for "row: *, column: 3"
-> found template for "row: 3, column: *" -> return
UrlLink

As a result the table will look as follows

1 2 3

1 InputBox Selector TextBox

2 TextBox Selector TextBox

3 UrlLink Selector UrlLink

As you can see, the seach chain is very flexible to define and use.