You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by hl...@apache.org on 2003/08/19 00:25:19 UTC
cvs commit: jakarta-tapestry/doc/src/common TapestryLinks.xml
hlship 2003/08/18 15:25:19
Modified: doc/src/UsersGuide state.xml spec.xml TapestryUsersGuide.xml
doc/src/common TapestryLinks.xml
Added: doc/src/UsersGuide template.xml
Log:
Update UsersGuide with start of information about templates.
Revision Changes Path
1.8 +9 -9 jakarta-tapestry/doc/src/UsersGuide/state.xml
Index: state.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/state.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- state.xml 1 Jun 2003 05:05:15 -0000 1.7
+++ state.xml 18 Aug 2003 22:25:19 -0000 1.8
@@ -192,7 +192,7 @@
<programlisting>
<![CDATA[
<application name="Tapestry Component Workbench">
- <property name="org.apache.tapestry.visit-class" value="tutorial.workbench.Visit"/>
+ <property name="org.apache.tapestry.visit-class" value="org.apache.tapestry.workbench.Visit"/>
...
]]>
@@ -366,8 +366,8 @@
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE page-specification PUBLIC
- "-//Howard Lewis Ship//Tapestry Specification 3.0//EN"
- "http://tapestry.sf.net/dtd/Tapestry_1_4.dtd">
+ "-//Apache Software Foundation//Tapestry Specification 3.0//EN"
+ "http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd">
<page-specification class="MyPage">
@@ -481,9 +481,9 @@
</para>
<para>
-This notification takes the form of an invocation of the method
-<function>fireObservedChange()</function>. This method is provided by &AbstractComponent;
-and is overloaded for all the scalar types, and for &Object;.
+This notification takes the form of an invocation of the static method
+<function>fireObservedChange()</function> in the <classname>Tapestry</classname> class.
+This method is overloaded for all the scalar types, and for &Object;.
</para>
<example>
@@ -502,7 +502,7 @@
{
_itemsPerPage = itemsPerPage;
- fireObservedChange("itemsPerPage", itemsPerPage);
+ Tapestry.fireObservedChange(this, "itemsPerPage", itemsPerPage);
}
protected void initialize()
@@ -561,7 +561,7 @@
{
_myProperty = myProperty;
- fireObservedChange("myProperty", myProperty);
+ Tapestry.fireObservedChange(this, "myProperty", myProperty);
}
public String getMyProperty()
1.8 +23 -1 jakarta-tapestry/doc/src/UsersGuide/spec.xml
Index: spec.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/spec.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- spec.xml 1 Jun 2003 05:05:15 -0000 1.7
+++ spec.xml 18 Aug 2003 22:25:19 -0000 1.8
@@ -373,6 +373,18 @@
component will be copied to this component.
</entry>
</row>
+
+<row>
+ <entry>inherit-informal-parameters</entry>
+ <entry><literal>yes|no</literal></entry>
+ <entry>no</entry>
+ <entry><literal>no</literal></entry>
+ <entry>
+ If <literal>yes</literal>, then any informal parameters of the containing
+ component will be copied into this component.
+ </entry>
+</row>
+
</tbody>
</tgroup>
</informaltable>
@@ -1316,6 +1328,16 @@
component is not rendering.
</para>
</entry>
+</row>
+
+<row>
+ <entry>default-value</entry>
+ <entry>OGNL expression</entry>
+ <entry>no</entry>
+ <entry/>
+ <entry>
+ Specifies the default value for the parameter, if the parameter is not bound.
+ </entry>
</row>
</tbody>
1.7 +6 -1 jakarta-tapestry/doc/src/UsersGuide/TapestryUsersGuide.xml
Index: TapestryUsersGuide.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/TapestryUsersGuide.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- TapestryUsersGuide.xml 1 Jun 2003 05:05:15 -0000 1.6
+++ TapestryUsersGuide.xml 18 Aug 2003 22:25:19 -0000 1.7
@@ -9,6 +9,7 @@
<!-- Each chapter is in its own file -->
<!ENTITY chap-intro SYSTEM "intro.xml">
+<!ENTITY chap-template SYSTEM "template.xml">
<!ENTITY chap-state SYSTEM "state.xml">
<!ENTITY chap-configuration SYSTEM "configuration.xml">
@@ -65,6 +66,8 @@
<!ENTITY WEB-INF '<filename>WEB-INF</filename>'>
+<!ENTITY jwc '<literal>jwc</literal>'>
+
]>
<!-- Conventions:
@@ -89,6 +92,8 @@
</bookinfo>
&chap-intro;
+
+ &chap-template;
&chap-state;
1.1 jakarta-tapestry/doc/src/UsersGuide/template.xml
Index: template.xml
===================================================================
<!-- $Id: template.xml,v 1.1 2003/08/18 22:25:19 hlship Exp $ -->
<chapter id="template">
<title>Tapestry Page and Component Templates</title>
<para>
Unlike many other web frameworks, such as
&Struts; or &WebWork;,
Tapestry does not "plug into" an external templating system such as JavaServer Pages or
&Velocity;. Instead, Tapestry integrates its own templating system.
</para>
<para>
Tapestry templates are designed to look like valid HTML files (component HTML templates
will just be snippets). Tapestry "hides" its extensions into special attributes of ordinary HTML elements.
</para>
<para>
Don't be fooled by the terminology; we say "HTML templates" because that is the prevalent use of Tapestry ... but
Tapestry is equally adept at WML or XML.
</para>
<section id="template.locations">
<title>Template locations</title>
<para>
The general rule of thumb is that a page's HTML template is simply an HTML file, stored in the context root directory.
That is, you'll have a <filename><replaceable>MyPage</replaceable>.html</filename> HTML template,
a <filename>WEB-INF/<replaceable>MyPage</replaceable>.page</filename> page specification,
and a <classname>MyPage</classname> class, in some Java package.
</para>
<para>
Tapestry always starts knowing the name of the page and the location of the page's specification when it
searches for the page's HTML template. Starting with this, it performs the following search:
</para>
<itemizedlist>
<listitem>
<para>
In the same location as the specification
</para>
</listitem>
<listitem>
<para>
In the web application's context root directory (if the page is an application page, not a page from a library)
</para>
</listitem>
</itemizedlist>
<para>
In addition, any HTML template in the web application context is considered a page, even if there is no matching
page specification. For simple pages that don't need to have any page-specific logic or properties, there's no need
for a page specification. Such a page may still use the special Tapestry attributes (described in the following sections).
</para>
<para>
Finally, with some <link linkend="configuration.search-path">minor configuration</link>
it is possible to change the extension searched for, which is appropriate if you are, for example,
building a WML application using Tapestry.
</para>
</section> <!-- template.locations -->
<section id="template.contents">
<title>Template Contents</title>
<para>
Tapestry templates contain a mix of the following elements:
</para>
<itemizedlist>
<listitem>
<para>Static HTML markup</para>
</listitem>
<listitem>
<para>Tapestry components</para>
</listitem>
<listitem>
<para>Localized messages</para>
</listitem>
<listitem>
<para>Special template directives</para>
</listitem>
</itemizedlist>
<para>
Usually, about 90% of a template is ordinary HTML markup. Hidden inside that markup are particular tags that
are placeholders for Tapestry components; these tags are recognized by the presence of the &jwc; attribute. "JWC"
is short for "Java Web Component", and was chosen as the "magic" attribute so as not to conflict with any real HTML attribute.
</para>
<para>
Tapestry's parser is quite flexible, accepting all kinds of invalid HTML markup. That is, attributes don't <emphasis>have</emphasis> to be
quoted. Start and end tags don't have to balance. Case is ignored when matching start and end tags. Basically,
the kind of ugly HTML you'll find "in the field" is accepted.
</para>
</section> <!-- template.contents -->
<section id="template.components">
<title>Components in Templates</title>
<para>
Components can be placed anywhere inside a template, simply by adding the &jwc; attribute to
any existing tag. For example:
<example>
<title>Example HTML template containing components</title>
<programlisting><![CDATA[
<html>
<head>
<title>Example HTML Template</title>
</head>
<body>]]>
<span jwcid="border"> <co id="template.components.border"/>
Hello,
<span jwcid="@&Insert;" value="ognl:user.name">Joe User</span> <co id="template.components.insert"/>
<![CDATA[
</span>
</body>
</html>]]>
</programlisting>
</example>
<calloutlist>
<callout arearefs="template.components.border">
<para>
This is a reference to a <emphasis>declared component</emphasis>; the type and parameters
of the component are in the page's specification.
</para>
</callout>
<callout arearefs="template.components.insert">
This is a <emphasis>implicit component</emphasis>; the type of the component is &Insert;. The
value parameter is bound to the &OGNL; expression <literal>user.name</literal>.
</callout>
</calloutlist>
</para>
<para>
The point of all this is that the HTML template should preview properly in a WYSIWYG HTML editor. Unlike
&Velocity; or JSPs, there are no strange directives to get in the way of a preview (or necessitate
a special editting tool), Tapestry hides what's needed inside existing tags; at worst, it adds
a few non-standard attributes (such as &jwc;) to tags. This rarely causes a problem with most HTML editors.
</para>
<para>
Templates may contain components using two different styles. <emphasis>Declared components</emphasis> are
little more than a placeholder; the type of the component is defined elsewhere, in the page (or component)
specification.
</para>
<para>
Alternately, an <emphasis>implicit component</emphasis> can be defined in place, by preceding
the component type with an "@" symbol. Tapestry includes over forty components with the framework, additional components
may be created as part of your application, or may be provided inside a component library.
</para>
<para>
In the above example, a <sgmltag class="starttag">span</sgmltag> was used for both components. Tapestry
doesn't care what tag is used for a component, as long as the start and end tags for components balance (it doesn't
even care if the case of the start tag matches the case of the end tag). The example could just
as easily use <sgmltag class="starttag">div</sgmltag> or <sgmltag class="starttag">fred</sgmltag>, the
rendered page sent back to the client web browser will be the same.
</para>
<section id="templates.components.ids">
<title>Component Ids</title>
<para>
Every component in Tapestry has its own id. In the above example, the first component has the id "border". The second component
is anonymous; the framework provides a unique id for the component since one was not supplied in the HTML template. The
framework provided id is built from the component's type; this component would have an id of
<literal>$Insert</literal>; other &Insert; components
would have ids <literal>$Insert$0</literal>, <literal>$Insert$1</literal>, etc.
</para>
<para>
A component's id must only be unique within its immediate container. Pages are top-level containers, but
components can also contain other components.
</para>
<para>
Implicit components can also have a specific id, by placing the id in front of the "@" symbol:
<informalexample>
<programlisting>
<span jwcid="insert@&Insert;" value="ognl:user.name">Joe User</span>
</programlisting>
</informalexample>
</para>
<para>
The component is still implicit; nothing about the component would go in the specification, but the id
of the component would be "insert".
</para>
<para>
Each component may only appear <emphasis>once</emphasis> in the template. You simply can't use the same component
repeatedly ... but you can duplicate a component fairly easily; make the component a declared component,
then use the <literal>copy-of</literal> attribute of the &spec.component; element to create clones of
the component with new ids.
</para>
</section> <!-- templates.components.ids -->
<section id="templates.components.parameters">
<title>Specifying Parameters</title>
<para>
Using either style, parameters of the component may be bound by adding attributes to the tag.
Most attributes bind static parameters, equivalent to using
the &spec.static-binding; element in the specification.
</para>
<para>
Prefixing an attribute value with <literal>ognl:</literal> indicates that the value
is really an &OGNL; expression, equivalent to using the &spec.binding; element in the specification.
</para>
<para>
Finally, prefixing an attribute value with <literal>message:</literal> indicates that the value
is really a key used to get a localized message, equivalent to the &spec.message-binding; element
in the specification.
</para>
</section> <!-- templates.components.parameters -->
<section id="template.components.formal">
<title>Formal and Informal Parameters</title>
<para>
Components may accept two types of parameters: <emphasis>formal</emphasis>
and <emphasis>informal</emphasis>. Formal parameters are those defined in the
component specification, using the &spec.parameter; element.
Informal parameters are <emphasis>additional</emphasis> parameters, beyond those
known when the component was created.
</para>
<para>
The majority of components that accept informal parameters simply emit the informal
parameters as additional attributes. Why is that useful? Because it allows you to
specify common HTML attributes such as <literal>class</literal> or <literal>id</literal>,
or JavaScript event handlers, without requiring that each component define each possible
HTML attribute (a list which expands all the time).
</para>
<para>
Informal and formal parameters can be specified in either the specification or in the template.
Informal parameters <emphasis>are not</emphasis> limited to literal strings, you may use
the <literal>ognl:</literal> and <literal>message:</literal> prefixes with them as well.
</para>
<para>
Not all components allow informal parameters; this is controlled by the
<literal>allow-informal-parameters</literal> attribute of the
&spec.component-specification; element. Many components do not map directly to an HTML element,
those are the ones that do not allow informal parameters. If a component forbids informal parameters,
then any informal parameters in the specification or the template will result in errors, with one exception:
static strings in the HTML template are simply ignored when informal parameters are forbidden; they
are presumed to be there only to support WYSIWYG preview.
</para>
<para>
Each component declares a list of reserved names using the &spec.reserved-parameter; element; these
are names which are not allowed as informal parameters, because the component generates the
the named attribute itself, and doesn't want the value it writes to be overriden by an informal
parameters. For example, the &DirectLink; component reserves the name "href" ... putting an
<literal>href</literal> attribute in the HTML template is simply ignored (again, presumed to
be there to support WYSIWYG preview). Case is ignored when comparing attribute names to reserved names.
</para>
</section> <!-- template.components.formal -->
</section> <!-- template.components -->
</chapter>
1.29 +23 -20 jakarta-tapestry/doc/src/common/TapestryLinks.xml
Index: TapestryLinks.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/common/TapestryLinks.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- TapestryLinks.xml 1 Jul 2003 20:49:35 -0000 1.28
+++ TapestryLinks.xml 18 Aug 2003 22:25:19 -0000 1.29
@@ -118,27 +118,30 @@
<!-- External links -->
-<!ENTITY Ant '<ulink url="http://jakarta.apache.org/ant">Ant</ulink>'>
-<!ENTITY BSF '<ulink url="http://jakarta.apache.org/bsf">BSF</ulink>'>
-<!ENTITY BCEL '<ulink url="http://jakarta.apache.org/bcel">BCEL</ulink>'>
-<!ENTITY DocBook '<ulink url="http://docbook.sourceforge.net/">DocBook</ulink>'>
-<!ENTITY Eclipse '<ulink url="http://www.eclipse.org">Eclipse</ulink>'>
-<!ENTITY Fop '<ulink url="http://xml.apache.org/fop">FOP</ulink>'>
-<!ENTITY Log4J '<ulink url="http://jakarta.apache.org/log4j">Log4J</ulink>'>
-<!ENTITY Jakarta '<ulink url="http://jakarta.apache.org">Jakarta</ulink>'>
-<!ENTITY JBoss '<ulink url="http://www.jboss.org">JBoss</ulink>'>
-<!ENTITY Jetty '<ulink url="http://sf.net/projects/jetty">Jetty</ulink>'>
-<!ENTITY JUnit '<ulink url="http://www.junit.org">JUnit</ulink>'>
-<!ENTITY Jython '<ulink url="http://www.jython.org">Jython</ulink>'>
-<!ENTITY OGNL '<ulink url="http://www.ognl.org">OGNL</ulink>'>
-<!ENTITY Saxon '<ulink url="http://sf.net/projects/saxon">Saxon</ulink>'>
-<!ENTITY TapestryHomePage '<ulink url="http://jakarta.apache.org/proposals/tapestry">Tapestry Home Page</ulink>'>
+<!ENTITY Ant '<ulink url="http://ant.apache.org/">Ant</ulink>'>
+<!ENTITY BSF '<ulink url="http://jakarta.apache.org/bsf/">BSF</ulink>'>
+<!ENTITY BCEL '<ulink url="http://jakarta.apache.org/bcel/">BCEL</ulink>'>
+<!ENTITY DocBook '<ulink url="http://docbook.sourceforge.net/">DocBook</ulink>'>
+<!ENTITY Eclipse '<ulink url="http://www.eclipse.org">Eclipse</ulink>'>
+<!ENTITY Fop '<ulink url="http://xml.apache.org/fop/">FOP</ulink>'>
+<!ENTITY Log4J '<ulink url="http://jakarta.apache.org/log4j/">Log4J</ulink>'>
+<!ENTITY Jakarta '<ulink url="http://jakarta.apache.org">Jakarta</ulink>'>
+<!ENTITY JBoss '<ulink url="http://www.jboss.org">JBoss</ulink>'>
+<!ENTITY Jetty '<ulink url="http://sf.net/projects/jetty/">Jetty</ulink>'>
+<!ENTITY JUnit '<ulink url="http://www.junit.org">JUnit</ulink>'>
+<!ENTITY Jython '<ulink url="http://www.jython.org">Jython</ulink>'>
+<!ENTITY OGNL '<ulink url="http://www.ognl.org">OGNL</ulink>'>
+<!ENTITY Saxon '<ulink url="http://sf.net/projects/saxon/">Saxon</ulink>'>
-<!-- Other useful stuff -->
+<!ENTITY Struts '<ulink url="http://jakarta.apache.org/struts/">Struts</ulink>'>
+<!ENTITY WebWork '<ulink url="http://opensymphony.com/webwork/">WebWork</ulink>'>
+<!ENTITY Velocity '<ulink url="http://jakarta.apache.org/velocity/">Velocity</ulink>'>
-<!ENTITY TapestryFrameworkJar "<filename>tapestry-<replaceable>x.x</replaceable>.jar</filename>">
-<!ENTITY TapestryContribJar "<filename>tapestry-contrib-<replaceable>x.x</replaceable>.jar</filename>">
+<!ENTITY TapestryHomePage '<ulink url="http://jakarta.apache.org/tapestry/">Tapestry Home Page</ulink>'>
-<!ENTITY HowardLewisShipEmail '<ulink url="mailto:hlship@apache.org">Howard M. Lewis Ship</ulink>'>
+<!-- Other useful stuff -->
+<!ENTITY TapestryFrameworkJar "<filename>tapestry-3.0.jar</filename>">
+<!ENTITY TapestryContribJar "<filename>tapestry-contrib-3.0.jar</filename>">
+<!ENTITY HowardLewisShipEmail '<ulink url="mailto:hlship@apache.org">Howard M. Lewis Ship</ulink>'>