Script Template Specification DTDs

Script template specifications are the odd man out when it comes to Tapestry XML files as they don't use the same DTD as the other specifications .

Script templates are used to dynamically generate JavaScript to support client-side behaviors associated with components. Tapestry is all about dynamically renderered, customized HTML, so it makes sense that dynamically rendered, customize JavaScript to complement that HTML should also be supported.

Script template files are parsed into memory as instances of IScript . These script template objects may be executed to generate the JavaScript.

Many different script template objects may be executed during the course of rendering a page; all the JavaScript from all the executions are organized into two JavaScript blocks in the output page: the main body at the top of the page (just inside the HTML <body> tag), and an initialization block at the bottom of the page, (just before the HTML </body> tag).

Executing a script template requires access to an IScriptProcessor instance; this is usually provided by the Body component. The script processor is responsible for managing the buffers of JavaScript, and assists with generating unique ids for client-side variables and functions.

A script template works with symbols , a set of key/value pairs (implements as a Map). The script operates upon the input symbols and generates new output symbols along the way, while generating JavaScript. In some cases, the output symbols may be used by a component when rendering HTML.

Many of the elements in a script template have a body of parsable character data. In the body of an element, you may reference symbols using the Ant-like ${...} syntax. I.e. ${name} . In fact, the string inside the curly braces is an OGNL expression, so you may create more complex expressions, such as ${field.form.name} .

DOCTYPE

The DOCTYPE for a script template specification is:

<!DOCTYPE script PUBLIC
  "-//Apache Software Foundation//Tapestry Script Specification 3.0//EN"
  "http://jakarta.apache.org/tapestry/dtd/Script_3_0.dtd">

<body> element

Appears in: <script>

Allows a mix of text and control elements. This text is added to the large scripting block just inside the HTML <body> tag.

<body> elements:

(text | <foreach> | <if> | <if-not> | <unique>)*

<foreach> element

Appears in: many

Iterates over a list of items; this is modeled after the For component. No iteration occurs if the value from the expression is null.

Name Type Required ? Default Value Description
key string no Defines the symbol into which each succesive value is stored.
index string no Defines the symbol into which the index of the value of the current iteration is stored.
expression string yes The source of values, as an OGNL expression rooted in the symbols Map.

<foreach> elements:

(text | <foreach> | <if> | <if-not> | <unique>)*

<if> element

Appears in: many

Creates a conditional portion of the script; The body of the element is only included if the expression evaulates to true.

Name Type Required ? Default Value Description
expression string yes The OGNL expression to evaluate.

<if> Elements

(text | <foreach> | <if> | <if-not> | <unique>)*

<if-not> element

Identical to the <if> element, except that the body is only included in the output if the expression evaluates to false .

<include-script> element

Inserts a reference to a static JavaScript file stored on the classpath. A particular file will only be included once per rendering of a page.

For best performance, as much logic as possible should be shifted into static JavaScript library files that are included via this element. The dynamic portion of the JavaScript should really be initialization of code provided by such a static JavaScript library. This optimizes that amount of data that must be sent to the client web browser, as it will be able to cache the content of static library files.

Appears in: <script>

Name Type Required ? Default Value Description
resource-path string yes The path to the script within the classpath.

<initialization> element

Appears in: <script>

Allows a mix of text and control elements. This text is added to the large scripting block just inside the HTML </body> tag. It therefore can refrence HTML objects within the page.

<initialization> elements:

(text | <foreach> | <if> | <if-not> | <unique>)*

<input-symbol> element

Appears in: <script>

Defines an input symbol used by the script. Defining input symbols is optional; it merely enforces that symbols be of a particular type, or enforces that a non-null value be provided. This is handy as defensive programming .

Name Type Required ? Default Value Description
key string yes The name of the symbol to check.
class string no If provided, then the actual value must be assignable to the given type (which may be a Java class or interface name).
required boolean no no If "yes", then a non-null value must be provided.

<let> element

Appears in: <script>

Defines a new symbol in terms of a string (usually with embedded expressions).

When a string is marked as unique, it is passed through a page-wide filter; if the name conflicts with a previous unique string, then a numeric suffix is appended to the string to ensure its uniqueness. This is most useful when defining JavaScript client-side variables and functions, to ensure there are no conflicts between different script templates, or successive executions of the same script template.

Note:

Starting with Tapestry 4.1.2, unique also ensures that the returned string can be safely used as a javascript identifier (by replacing hyphens, colons and periods with underscores).

Name Type Required ? Default Value Description
key string yes The name of the new symbol to create.
unique boolean no no If yes, then the string is made unique.

<let> Elements

(text | <foreach> | <if> | <if-not> | <unique>)*

<script> element

root element

The <script> element is the root element of the document. It contains no attributes.

<script> Elements

(<include-script>*, <input-symbol>*, (<let> | <set>)*, <body>?, <initialization>?)

<set> element

Appears in: many

Creates a new symbol, or overwrites an existing symbol, in terms of an OGNL expression.

Name Type Required ? Default Value Description
key string yes The key for the input symbol to be created (or overwritten).
expression string yes The OGNL expression to evaluate and assign to the input symbol.

<unique> element

Appears in: many

Defines a block of text that is only rendered once per page. This is appropriate to certain kinds of initialization code that should not be duplicated, even if the same script template is executed multiple times.

<script> elements:

(text | <foreach> | <if> | <if-not> | <unique>)*