Author: hlship
Date: Mon Nov 21 06:48:37 2005
New Revision: 345912
URL: http://svn.apache.org/viewcvs?rev=345912&view=rev
Log:
Add missing documentation for Tapestry script template specifications
Added:
jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/script.xml
Modified:
jakarta/tapestry/trunk/framework/src/java/org/apache/tapestry/script/Script_3_0.dtd
jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/spec.xml
jakarta/tapestry/trunk/src/documentation/content/xdocs/links.ent
jakarta/tapestry/trunk/src/documentation/content/xdocs/site.xml
jakarta/tapestry/trunk/status.xml
Modified:
jakarta/tapestry/trunk/framework/src/java/org/apache/tapestry/script/Script_3_0.dtd
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/framework/src/java/org/apache/tapestry/script/Script_3_0.dtd?rev=345912&r1=345911&r2=345912&view=diff
==============================================================================
---
jakarta/tapestry/trunk/framework/src/java/org/apache/tapestry/script/Script_3_0.dtd
(original)
+++
jakarta/tapestry/trunk/framework/src/java/org/apache/tapestry/script/Script_3_0.dtd
Mon Nov 21 06:48:37 2005
@@ -4,11 +4,11 @@
DTD for the files used with the ScriptParser class and Script component.
This is recognized with the public identifier:
- -//Apache Software Foundation//Tapestry Script Specification 1.3//EN
+ -//Apache Software Foundation//Tapestry Script Specification 3.0//EN
The canonical location for the DTD is:
- http://jakarta.apache.org/tapestry/dtd/Script_1_3.dtd
+ http://jakarta.apache.org/tapestry/dtd/Script_3_0.dtd
The root element is always script.
@@ -30,8 +30,8 @@
Element: body
Contained by: script
-Allows a mix of text and insert elements. This text is added to
-the large scripting block just before the <body> tag.
+Allows a mix of text and control elements. This text is added to
+the large scripting block just inside the <body> tag.
-->
<!ELEMENT body %full-content;>
<!-- =======================================================
@@ -40,8 +40,8 @@
Appears in: %full-content;
Iterates over a list of items; this is modeled after the
-Foreach component. No iteration occurs if the value
-from the property path is null.
+For component. No iteration occurs if the value
+from the expression is null.
Attributes:
key: Defines the symbol into which each succesive value is stored.
Added:
jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/script.xml
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/script.xml?rev=345912&view=auto
==============================================================================
---
jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/script.xml
(added)
+++
jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/script.xml
Mon Nov 21 06:48:37 2005
@@ -0,0 +1,487 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2005 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.
+-->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN"
+ "http://forrest.apache.org/dtd/document-v13.dtd";
+[
+ <!ENTITY projectroot '../'>
+ <!ENTITY % links.ent SYSTEM "../links.ent">
+ <!ENTITY % common.ent SYSTEM "common.ent">
+ %links.ent;
+ %common.ent;
+
+ <!ENTITY script.body '<link
href="#script.body"><body></link>'>
+ <!ENTITY script.foreach '<link
href="#script.foreach"><foreach></link>'>
+ <!ENTITY script.if '<link
href="#script.if"><if></link>'>
+ <!ENTITY script.if-not '<link
href="#script.if-not"><if-not></link>'>
+ <!ENTITY script.include-script '<link
href="#script.include-script"><include-script></link>'>
+ <!ENTITY script.initialization '<link
href="#script.initialization"><initialization></link>'>
+ <!ENTITY script.input-symbol '<link
href="#script.input-symbol"><input-symbol></link>'>
+ <!ENTITY script.let '<link
href="#script.let"><let></link>'>
+ <!ENTITY script.script '<link
href="#script.script"><script></link>'>
+ <!ENTITY script.set '<link
href="#script.set"><set></link>'>
+ <!ENTITY script.unique '<link
href="#script.unique"><unique></link>'>
+
+ <!ENTITY full-content '(<em>text</em> | &script.foreach; | &script.if;
| &script.if-not; | &script.unique;)*'>
+ ]>
+<document>
+ <header>
+ <title>Script Template Specification DTDs</title>
+ </header>
+ <body>
+
+ <p>
+ 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
+ <link href="spec.html">other specifications</link>.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ Script template files are parsed into memory as
+ instances of &IScript;. These script template <em>objects</em>
+ may be executed to generate the JavaScript.
+ </p>
+
+ <p>
+ 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 <em>main body</em> at the top of the page
+ (just inside the HTML <body> tag), and
+ an <em>initialization block</em> at the bottom of the page,
+ (just before the HTML </body> tag).
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ A script template works with <em>symbols</em>, 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.
+ </p>
+
+ <p>
+ 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. <code>${name}</code>. In fact,
the
+ string inside the curly braces is an &OGNL; expression, so you may
create more
+ complex expressions, such as <code>${field.form.name}</code>.
+ </p>
+
+<section>
+ <title>DOCTYPE</title>
+
+ <p>
+ The DOCTYPE for a script template specification is:
+ </p>
+
+<source><![CDATA[
+<!DOCTYPE script PUBLIC
+ "-//Apache Software Foundation//Tapestry Script Specification 3.0//EN"
+ "http://jakarta.apache.org/tapestry/dtd/Script_3_0.dtd";>]]></source>
+</section> <!-- DOCTYPE -->
+
+ <section id="script.body">
+ <title><body> element</title>
+
+ <p>
+ Appears in: &script.script;
+ </p>
+
+ <p> Allows a mix of text and control elements. This
text is added to
+ the large scripting block just inside the HTML <body> tag.
+ </p>
+
+ <p><body> elements:</p>
+
+ <source>&full-content;</source>
+ </section>
+
+ <section id="script.foreach">
+ <title><foreach> element</title>
+
+ <p>
+ Appears in: <em>many</em>
+ </p>
+
+ <p>
+ Iterates over a list of items; this is modeled after the
+ For component. No iteration occurs if the value
+ from the expression is null.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Required ?</th>
+ <th>Default Value</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+<td>key</td> <td>string</td> <td>no</td> <td></td>
+ <td>
+ Defines the symbol into which each succesive value is
stored.
+ </td>
+ </tr>
+
+ <tr>
+ <td>index</td> <td>string</td> <td>no</td> <td></td>
+ <td>
+ Defines the symbol into which the index of the value
of the current iteration is stored.
+ </td>
+ </tr>
+
+ <tr>
+ <td>expression</td>
+ <td>string</td> <td>yes</td> <td></td>
+ <td>
+ The source of values, as an OGNL expression rooted in
the symbols Map.
+ </td>
+ </tr>
+ </table>
+
+ <p><foreach> elements:</p>
+
+ <source>&full-content;</source>
+ </section>
+
+
+ <section id="script.if">
+ <title><if> element</title>
+
+ <p>
+ Appears in: <em>many</em>
+ </p>
+
+ <p>
+ Creates a conditional portion of the script; The body of the
element
+ is only included if the expression evaulates to true.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Required ?</th>
+ <th>Default Value</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>expression</td> <td>string</td> <td>yes</td> <td></td>
+ <td>
+ The &OGNL; expression to evaluate.
+ </td>
+ </tr>
+
+
+ </table>
+
+ <p>
+ <if> Elements
+ </p>
+
+ <source>&full-content;</source>
+
+ </section>
+
+ <section id="script.if-not">
+ <title><if-not> element</title>
+
+ <p>
+ Identical to the &script.if; element, except that the body
+ is only included in the output if the expression
+ evaluates to <strong>false</strong>.
+ </p>
+ </section>
+
+
+
+ <section id="script.include-script">
+ <title><include-script> element</title>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ Appears in: &script.script;
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Required ?</th>
+ <th>Default Value</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>resource-path</td>
+ <td>string</td>
+ <td>yes</td>
+ <td></td>
+ <td>The path to the script within the classpath.</td>
+ </tr>
+ </table>
+
+ </section>
+ <section id="script.initialization">
+ <title><initialization> element</title>
+
+ <p>
+ Appears in: &script.script;
+ </p>
+
+ <p> 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.
+ </p>
+
+ <p><initialization> elements:</p>
+
+ <source>&full-content;</source>
+ </section>
+
+ <section id="script.input-symbol">
+ <title><input-symbol> element</title>
+
+ <p>
+ Appears in: &script.script;
+ </p>
+
+ <p>
+ 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 <em>defensive programming</em>.
+ </p>
+
+
+ <table>
+
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Required ?</th>
+ <th>Default Value</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>key</td>
+ <td>string</td>
+ <td>yes</td>
+ <td></td>
+ <td>The name of the symbol to check.</td>
+ </tr>
+
+ <tr>
+ <td>class</td>
+ <td>string</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ If provided, then the actual value
+ must be assignable to the given type (which may
+ be a Java class or interface name).
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ required
+ </td>
+ <td>boolean</td>
+ <td>no</td>
+ <td>no</td>
+ <td>
+ If "yes", then a non-null value must be provided.
+ </td>
+ </tr>
+ </table>
+
+ </section>
+
+ <section id="script.let">
+ <title><let> element</title>
+
+ <p>
+ Appears in: &script.script;
+ </p>
+
+ <p>
+ Defines a new symbol in terms of a string
+ (usually with embedded expressions).
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Required ?</th>
+ <th>Default Value</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>key</td> <td>string</td> <td>yes</td> <td></td>
+ <td>The name of the new symbol to create.</td>
+ </tr>
+
+ <tr>
+ <td>unique</td> <td>boolean</td> <td>no</td> <td>no</td>
+ <td>
+ If yes, then the string is made unique.
+ </td>
+ </tr>
+
+</table>
+
+ <p>
+ <let> Elements
+ </p>
+
+ <source>&full-content;</source>
+
+
+ </section>
+
+ <section id="script.script">
+ <title><script> element</title>
+
+ <p>
+ <em>root element</em>
+ </p>
+
+ <p>
+ The <script> element is the root element of the document.
+ It contains no attributes.
+ </p>
+
+ <p>
+ <script> Elements
+ </p>
+ <source>
+(&script.include-script;*, &script.input-symbol;*, (&script.let; |
&script.set;)*, &script.body;?, &script.initialization;?)
+ </source>
+
+ </section> <!-- script -->
+
+
+ <section id="script.set">
+ <title><set> element</title>
+
+ <p>
+ Appears in: <em>many</em>
+ </p>
+
+ <p>
+ Creates a new symbol, or overwrites an existing symbol, in
terms
+ of an &OGNL; expression.
+ </p>
+
+ <table>
+
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Required ?</th>
+ <th>Default Value</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>key</td> <td>string</td> <td>yes</td> <td></td>
+ <td>The key for the input symbol to be created (or
overwritten).</td>
+ </tr>
+
+ <tr>
+ <td>expression</td> <td>string</td>
+ <td>yes</td>
+ <td></td>
+ <td>The &OGNL; expression to evaluate and assign to the
+ input symbol.</td>
+ </tr>
+ </table>
+
+ </section> <!-- script.set -->
+
+ <section id="script.unique">
+ <title><unique> element</title>
+
+ <p>
+ Appears in: <em>many</em>
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+<p><script> elements:</p>
+
+<source>&full-content;</source>
+
+ </section>
+ </body>
+</document>
Modified:
jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/spec.xml
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/spec.xml?rev=345912&r1=345911&r2=345912&view=diff
==============================================================================
--- jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/spec.xml
(original)
+++ jakarta/tapestry/trunk/src/documentation/content/xdocs/UsersGuide/spec.xml
Mon Nov 21 06:48:37 2005
@@ -91,7 +91,9 @@
</table>
<note>
-A fifth type of specification, the Script specification, is described
seperately. In addition, in Tapestry 4.0,
+A fifth type of specification, the script template specification, is
+<link href="script.html">described seperately</link>. In addition, in
Tapestry 4.0,
+a significant
part of an application's behavior is defined by its &HiveMind; module
deployment descriptor.
</note>
Modified: jakarta/tapestry/trunk/src/documentation/content/xdocs/links.ent
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/src/documentation/content/xdocs/links.ent?rev=345912&r1=345911&r2=345912&view=diff
==============================================================================
--- jakarta/tapestry/trunk/src/documentation/content/xdocs/links.ent (original)
+++ jakarta/tapestry/trunk/src/documentation/content/xdocs/links.ent Mon Nov 21
06:48:37 2005
@@ -84,6 +84,7 @@
<!ENTITY IRequestCycle '<link
href="&apiroot;/IRequestCycle.html">IRequestCycle</link>'>
<!ENTITY IRequestDecoder '<link
href="&apiroot;/request/IRequestDecoder.html">IRequestDecoder</link>'>
<!ENTITY IScript '<link
href="&apiroot;/IScript.html">IScript</link>'>
+<!ENTITY IScriptProcessor '<link
href="&apiroot;/IScriptProcessor.html">IScriptProcessor</link>'>
<!ENTITY IScriptSource '<link
href="&apiroot;/engine/IScriptSource.html">IScriptSource</link>'>
<!ENTITY ISpecificationSource '<link
href="&apiroot;/engine/ISpecificationSource.html">ISpecificationSource</link>'>
<!ENTITY ISpecificationResolverDelegate
Modified: jakarta/tapestry/trunk/src/documentation/content/xdocs/site.xml
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/src/documentation/content/xdocs/site.xml?rev=345912&r1=345911&r2=345912&view=diff
==============================================================================
--- jakarta/tapestry/trunk/src/documentation/content/xdocs/site.xml (original)
+++ jakarta/tapestry/trunk/src/documentation/content/xdocs/site.xml Mon Nov 21
06:48:37 2005
@@ -67,6 +67,7 @@
<proprties label="Tapestry Object Properties" href="properties.html"/>
<upgrade label="Upgrading from 3.0" href="upgrade.html"/>
<spec label="Specification DTDs" href="spec.html"/>
+ <script label="Script Template DTD" href="script.html"/>
</UsersGuide>
<Examples label="Examples" href="examples/">
Modified: jakarta/tapestry/trunk/status.xml
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/trunk/status.xml?rev=345912&r1=345911&r2=345912&view=diff
==============================================================================
--- jakarta/tapestry/trunk/status.xml (original)
+++ jakarta/tapestry/trunk/status.xml Mon Nov 21 06:48:37 2005
@@ -63,6 +63,7 @@
<action type="fix" dev="HLS" fixes-bug="TAPESTRY-763">RequestCycle is
not available during page initialization</action>
<action type="fix" dev="HLS" fixes-bug="TAPESTRY-756">FieldLabel's
prerender property should default to true</action>
<action type="fix" dev="HLS"
fixes-bug="TAPESTRY-748">NumberTranslator.js missing semicolon</action>
+ <action type="add" dev="HLS">Add missing documentation for Tapestry
script template specifications</action>
</release>
<release version="4.0-beta-13" date="Nov 12 2005">
<action type="update" dev="HLS">Switch to HiveMind 1.1 (final)</action>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
