Tea User Manual

1. Introduction

Tea is a template language with a simple syntax, which supports the notion of having code inside an ordinary html page, like an ASP.

Tea templates are compiled into Java bytecode, and are loaded into the Java Virtual Machine as if they were ordinary Java classes.

This manual is intended as a language reference only, and does not give instruction on template writing techniques.

2. Templates

Tea templates are made up of code regions, which contain simple programming instructions, and text regions, which include no programming and are used to output raw text.

2.1 Code Region

Code regions are delimited by the symbols <% and %>. As the name implies, code regions are for calling functions and performing assorted logical operations, so line entries are expected to be variables, logical operators, or functions. Text and html formatting are included in code regions by enclosing the strings in quotation marks.

Every template must begin with a template declaration, which is defined in a code region. Therefore, every template must begin with a code region.

2.2 Import Directive

Normally, fully qualified Java class names can be used wherever type must be specified. The package qualification can be specified via the import reserved word:

<% 
import org.apache.struts.webapp.example
template subscription()
    form = getRequest().attributes["SubscriptionForm"] as SubscriptionForm
    …
%>

2.3 Template Declaration

The template declaration defines the name of the template and any parameters that must be passed to the template. Tea templates must be saved in a file whose name is the same in the declaration and have the extension ".tea".

<% template TemplateName %>

2.4 Parameter List

The template's formal parameter list follows the template name in the declaration and must be delimited by parentheses. A comma separates each parameter in the list. Formal parameters require a class name followed by an identifier, which names it. This is the only place in a Tea template where a class name is used.

<% template TemplateName (ClassName referenceIdentifier) %> 

2.5 Text Region

Any text not in the code region is output by the template as-is with only one minor conversion. All line break separator codes in text regions are converted to linefeeds '\n' (ASCII 10). Use html
or

tags to add line breaks manually. Text and html in text regions do not need to be enclosed within quotation marks, and reserved characters do not need to be escaped.

2.6 Comments

Single line comments in Tea templates follow a double slash:

//This is a single line comment. 

Multi-line comments are wrapped in slashes and asterisks as follows:

/*
 * This is a multi-line comment.
 * Multi-line comments are often used to
 * provide basic header information,
 * such as the purpose of the template,
 * and the template designer's name.
 */ 

3. Data Types

Tea is designed to work within a Java-based hosting system. All data that is accessible by Tea, provided by those systems, is in a form understood by Java.

Java has two kinds of data representations, objects and primitives, which are also understood by Tea. In Tea, however, all data should be treated as objects.

Tea data types include numbers, strings, booleans, and objects.

3.1 Numbers

Tea uses the Java standards for numbers (see Java Primitive Types and Values), with the following exceptions:

3.1.1 Long Integers

Long integers are not required to append the letter "L" after the number, as in Java code.

Example:

922337203685477580L

This may also be written in Tea as

922337203685477580

3.1.2 Leading Digits

Numbers with decimals (floating-point types) must be written with leading digits before the decimal point.

Example:

.8

This is not a valid number in Tea. The valid number is written as

0.8

3.2 Strings

Templates are usually written to perform textual output, so they often operate on strings, which are simply strings of characters. Tea can automatically convert all data into string representations when an operation is applied that requires it to be a string. These operations include concatenation, printing, and relational tests.

In Tea, strings must be enclosed within quotation marks, even when used as parameters in function calls. Either single quotation marks or double quotation marks may be used, so long as the open quote style matches the close quote style.

3.2.1 Escape Characters

In some situations, you may need to use characters where they don't fit with the syntax of the template. In this case, you need to escape the characters with a backslash.

\0	null character
\b	backspace
\t	tab
\n	newline
\f	formfeed
\r	carriage return
\'	single quote
\"	double quote
\uXXXX	unicode escape, where XXXX is a hexadecimal number
\\	backslash

Example:

"<a href=\"index.html\">"
'The decade of the 1990\'s!'

In the above examples, double quotes are escaped in the first example, a single quote is escaped in the second example. The results of these examples would be:

<a href="index.html"> The decade of the 1990's!

3.3 Booleans

Booleans have values of true or false, and are used to perform logical tests. For more information on performing logical tests, see Relational Tests and Logical Operators.

3.4 Objects

Objects are passed to or used in templates through JavaBeans. Objects contain references to other data, including object properties and other objects.

For more information on working with objects and object properties, see Accessing Properties and Arrays.

Data Operations

4.1 Variables

With the exception of passed-in parameters and variables declared using define or as, the type of a Tea variable is inferred based on assignment. If a variables type is inferred, it can be said that its type is dynamic, and can change after another assignment. Variables explicitly typed cannot change type and are statically typed. Passed-in parameters behave like ordinary local variables in that they can be re-assigned, and they can change type.

Assignments can only be made to variables. Array elements cannot be assigned values, like they can in Java. Assignments of this form are not allowed: a[i] = x. This restriction makes it possible to pass collections to templates without fear of modification.

Examples:

Assign the string literal "Hello" to message:

message = "Hello"

Assign the integer literal 50 to result:

result = 50

Assign the calculated sum of result and 20:

amount = result + 20

Re-assign message with the integer amount:

message = amount

4.2 Accessing Properties and Arrays

Objects are passed to templates through JavaBeans. JavaBeans defines two types of object properties, non-indexed and indexed. Most property accesses are non-indexed.

4.2.1 Non-indexed

Tea can access all non-indexed properties on a JavaBean.

4.2.2 Indexed

JavaBeans defines several different forms for indexed properties, but Tea only understands one kind: unnamed indexed properties.

A property access is called a lookup, and Tea has different syntax for its two supported kinds of lookups. A lookup can be applied to any expression, but it's usually applied to variables or chained to other lookups. Non-indexed properties are looked up from an expression using a dot (.) followed by the property name. Indexed properties are looked up using an expression bounded by square brackets.

Examples:

Access the name object from user:

name = user.name 

Access the first name:

f = name.first 

Access the last name by chaining:

last = user.name.last 

Access an element from the users array, and get the age:

users[10].age 

Lookup a team object by code:

team = allTeams["SEA"] 

Get the last character from a string:

str[str.length - 1]