| <!-- $Id$ --> |
| <!-- |
| Copyright 2004 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <appendix id="script-spec"> |
| <title>Tapestry Script Specification DTD</title> |
| |
| <para> |
| Tapestry Script Specifications are frequently used with the &Script; |
| component, to create dynamic JavaScript functions, typically for use |
| as event handlers for client-side logic. |
| </para> |
| |
| <para> |
| The root element is &script-spec.script;. |
| </para> |
| |
| <para> |
| A script specifcation is a kind of specialized template that |
| takes some number of input symbols and combines and manipulates |
| them to form output symbols, as well as |
| body and initialization. Symbols may |
| be simple strings, but are also frequently objects or components. |
| </para> |
| |
| <para> |
| Script specifications use an Ant-like syntax to insert dynamic values |
| into text blocks. <literal>${<replaceable>OGNL expression</replaceable>}</literal>. |
| The expression is evaluated relative to a ⤅ of symbols. |
| </para> |
| |
| <section id="script-spec.body"> |
| <title><sgmltag class="starttag">body</sgmltag> element</title> |
| |
| <para> |
| Appears in: &script-spec.script; |
| </para> |
| |
| <para> |
| Specifies the main body of the JavaScript; this is where |
| JavaScript variables and methods are typically declared. |
| This body will be passed to the &Body; component for inclusion |
| in the page. |
| </para> |
| |
| <figure> |
| <title><sgmltag class="starttag">body</sgmltag> Elements</title> |
| <literallayout> |
| (&script-spec.full-content;) * |
| </literallayout> |
| </figure> |
| </section> <!-- script-spec.body --> |
| |
| |
| <section id="script-spec.foreach"> |
| <title><sgmltag class="starttag">foreach</sgmltag> element</title> |
| |
| <para> |
| Appears in: <emphasis>many</emphasis> |
| </para> |
| |
| <para> |
| An element that renders its body repeatedly, much like a &Foreach; component. |
| An expression supplies a collection or array of objects, and its body is |
| rendered for each element in the collection. |
| </para> |
| |
| <figure> |
| <title><sgmltag class="starttag">foreach</sgmltag> Attributes</title> |
| <informaltable> |
| <tgroup cols="5"> |
| <thead> |
| <row> |
| <entry>Name</entry> |
| <entry>Type</entry> |
| <entry>Required ?</entry> |
| <entry>Default Value</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>key</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The symbol to be updated with each successive value.</entry> |
| </row> |
| <row> |
| <entry>expression</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The OGNL expression which provides the source of elements.</entry> |
| </row> |
| <row> |
| <entry>index</entry> |
| <entry>string</entry> |
| <entry>no</entry> |
| <entry/> |
| <entry>If specified, then the named symbol is updated with each successive index.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </figure> |
| |
| <figure> |
| <title><sgmltag class="starttag">foreach</sgmltag> Elements</title> |
| <literallayout> |
| (&script-spec.full-content;) * |
| </literallayout> |
| </figure> |
| |
| |
| </section> <!-- script-spec.foreach --> |
| |
| |
| <section id="script-spec.if"> |
| <title><sgmltag class="starttag">if</sgmltag> element</title> |
| |
| |
| <para> |
| Appears in: <emphasis>many</emphasis> |
| </para> |
| |
| <para> |
| Conditionally renders its body, if a supplied OGNL |
| expression is true. |
| </para> |
| |
| <figure> |
| <title><sgmltag class="starttag">if</sgmltag> Attributes</title> |
| <informaltable> |
| <tgroup cols="5"> |
| <thead> |
| <row> |
| <entry>Name</entry> |
| <entry>Type</entry> |
| <entry>Required ?</entry> |
| <entry>Default Value</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>expression</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The OGNL expression to be evaluated.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </figure> |
| |
| <figure> |
| <title><sgmltag class="starttag">if</sgmltag> Elements</title> |
| <literallayout> |
| (&script-spec.full-content;) * |
| </literallayout> |
| </figure> |
| |
| </section> <!-- script-spec.if --> |
| |
| |
| <section id="script-spec.if-not"> |
| <title><sgmltag class="starttag">if-not</sgmltag> element</title> |
| |
| |
| <para> |
| Appears in: <emphasis>many</emphasis> |
| </para> |
| |
| <para> |
| Conditionally renders its body, if a supplied OGNL |
| expression is false. |
| </para> |
| |
| <figure> |
| <title><sgmltag class="starttag">if-not</sgmltag> Attributes</title> |
| <informaltable> |
| <tgroup cols="5"> |
| <thead> |
| <row> |
| <entry>Name</entry> |
| <entry>Type</entry> |
| <entry>Required ?</entry> |
| <entry>Default Value</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>expression</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The OGNL expression to be evaluated.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </figure> |
| |
| <figure> |
| <title><sgmltag class="starttag">if-not</sgmltag> Elements</title> |
| <literallayout> |
| (&script-spec.full-content;) * |
| </literallayout> |
| </figure> |
| |
| </section> <!-- script-spec.if-not --> |
| |
| |
| <section id="script-spec.include-script"> |
| <title><sgmltag class="starttag">include-script</sgmltag> element</title> |
| |
| <para> |
| Appears in: &script-spec.script; |
| </para> |
| |
| <para> |
| Used to include a static JavaScript library. A library will only be included once, regardless of |
| how many different scripts reference it. Such libraries are located on the classpath. |
| </para> |
| |
| |
| <figure> |
| <title><sgmltag class="starttag">include-script</sgmltag> Attributes</title> |
| <informaltable> |
| <tgroup cols="5"> |
| <thead> |
| <row> |
| <entry>Name</entry> |
| <entry>Type</entry> |
| <entry>Required ?</entry> |
| <entry>Default Value</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>resource-path</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The location of the JavaScript library.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </figure> |
| </section> <!-- script-spec.include-script --> |
| |
| |
| <section id="script-spec.initialization"> |
| <title><sgmltag class="starttag">initialization</sgmltag> element</title> |
| |
| <para> |
| Appears in: &script-spec.script; |
| </para> |
| |
| <para> |
| Defines initialization needed by the remainder of the script. Such initialization |
| is placed inside a method invoked from the HTML <sgmltag class="starttag">body</sgmltag> |
| element's <literal>onload</literal> event handler ... that is, whatever is placed inside |
| this element will not be executed until the entire page is loaded. |
| </para> |
| |
| |
| |
| <figure> |
| <title><sgmltag class="starttag">initialization</sgmltag> Elements</title> |
| <literallayout> |
| (&script-spec.full-content;) * |
| </literallayout> |
| </figure> |
| |
| |
| </section> <!-- script-spec.initialization --> |
| |
| |
| |
| <section id="script-spec.input-symbol"> |
| <title><sgmltag class="starttag">input-symbol</sgmltag> element</title> |
| |
| <para> |
| Appears in: &script-spec.script; |
| </para> |
| |
| <para> |
| Defines an input symbol for the script. Input symbols can be thought of as parameters to the script. |
| As the script executes, it uses the input symbols to create new output symbols, redefine input symbols |
| (not a recommended practice) and define the body and initialization. |
| </para> |
| |
| <para> |
| This element allows the script to make input symbols required and to restrict their type. Invalid input symbols |
| (missing when required, or not of the correct type) will result in runtime exceptions. |
| </para> |
| |
| <figure> |
| <title><sgmltag class="starttag">input-symbol</sgmltag> Attributes</title> |
| <informaltable> |
| <tgroup cols="5"> |
| <thead> |
| <row> |
| <entry>Name</entry> |
| <entry>Type</entry> |
| <entry>Required ?</entry> |
| <entry>Default Value</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>key</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The input symbol to be checked.</entry> |
| </row> |
| <row> |
| <entry>class</entry> |
| <entry>string</entry> |
| <entry>no</entry> |
| <entry/> |
| <entry>If specified, this is the complete, qualified class name for the symbol. |
| The provided symbol must be assignable to this class (be a subclass, or implement |
| the specified class if the specified class is actually an interface). |
| </entry> |
| </row> |
| <row> |
| <entry>required</entry> |
| <entry><literal>yes | no</literal></entry> |
| <entry>no</entry> |
| <entry><literal>no</literal></entry> |
| <entry>If <literal>yes</literal>, then a non-null value must be specified for |
| the symbol. |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </figure> |
| |
| </section> <!-- script-spec.input-symbol --> |
| |
| |
| <section id="script-spec.let"> |
| <title><sgmltag class="starttag">let</sgmltag> element</title> |
| |
| |
| |
| <para> |
| Appears in: &script-spec.script; |
| </para> |
| |
| <para> |
| Used to define (or redefine) a symbol. The symbol's value is taken from |
| the body of element (with leading and trailing whitespace removed). |
| </para> |
| |
| <figure> |
| <title><sgmltag class="starttag">let</sgmltag> Attributes</title> |
| <informaltable> |
| <tgroup cols="5"> |
| <thead> |
| <row> |
| <entry>Name</entry> |
| <entry>Type</entry> |
| <entry>Required ?</entry> |
| <entry>Default Value</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>key</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The key of the symbol to define.</entry> |
| </row> |
| <row> |
| <entry>unique</entry> |
| <entry>boolean</entry> |
| <entry><literal>yes|no</literal></entry> |
| <entry>no</entry> |
| <entry>If yes, then the string is ensured to be unique (by possibly adding |
| a suffix) before being assigned to the symbol.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </figure> |
| |
| |
| |
| <figure> |
| <title><sgmltag class="starttag">let</sgmltag> Elements</title> |
| <literallayout> |
| (&script-spec.full-content;) * |
| </literallayout> |
| </figure> |
| |
| </section> <!-- script-spec.let --> |
| |
| |
| <section id="script-spec.script"> |
| <title><sgmltag class="starttag">script</sgmltag> element</title> |
| |
| <para> |
| <emphasis>Root element</emphasis> |
| </para> |
| |
| <para> |
| The root element of a Tapestry script specification. |
| </para> |
| |
| <figure> |
| <title><sgmltag class="starttag">script</sgmltag> Elements</title> |
| <literallayout> |
| &script-spec.include-script; *, &script-spec.input-symbol; *, |
| (&script-spec.let; | &script-spec.set;) *, |
| &script-spec.body; ?, &script-spec.initialization; ? |
| </literallayout> |
| </figure> |
| |
| </section> <!-- script-spec.script --> |
| |
| |
| <section id="script-spec.set"> |
| <title><sgmltag class="starttag">set</sgmltag> element</title> |
| |
| <para> |
| Appears in: &script-spec.script; |
| </para> |
| |
| <para> |
| A different way to define a new symbol, or redefine an existing one. The new symbol |
| is defined using an OGNL expression. |
| </para> |
| |
| |
| <figure> |
| <title><sgmltag class="starttag">set</sgmltag> Attributes</title> |
| <informaltable> |
| <tgroup cols="5"> |
| <thead> |
| <row> |
| <entry>Name</entry> |
| <entry>Type</entry> |
| <entry>Required ?</entry> |
| <entry>Default Value</entry> |
| <entry>Description</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>key</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The key of the symbol to define.</entry> |
| </row> |
| <row> |
| <entry>expression</entry> |
| <entry>string</entry> |
| <entry>yes</entry> |
| <entry/> |
| <entry>The OGNL expression to evaluate.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </figure> |
| </section> <!-- script-spec.set --> |
| |
| <section id="script-spec.unique"> |
| <title><sgmltag class="starttag">unique</sgmltag> element</title> |
| |
| <para> |
| Appears in: <emphasis>many</emphasis> |
| </para> |
| |
| <para> |
| Creates a block whose contents are contributed only once, no matter how many times |
| the block is evaluated during the rendering of a single page. |
| </para> |
| |
| |
| <figure> |
| <title><sgmltag class="starttag">unique</sgmltag> Elements</title> |
| <literallayout> |
| (&script-spec.full-content;) * |
| </literallayout> |
| </figure> |
| |
| </section> <!-- script-spec.unique --> |
| |
| </appendix> |