doc/src/DevelopersGuide/script-spec.xml

<!-- $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 &Map; 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>
</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>
</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 -->

	
</appendix>