You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by jk...@apache.org on 2006/07/15 23:25:04 UTC
svn commit: r422293 - in /tapestry/tapestry4/trunk: support/
tapestry-annotations/src/documentation/ tapestry-annotations/src/site/
tapestry-annotations/src/site/xdoc/ tapestry-portlet/src/documentation/
tapestry-portlet/src/site/ tapestry-portlet/src/...
Author: jkuhnert
Date: Sat Jul 15 14:25:03 2006
New Revision: 422293
URL: http://svn.apache.org/viewvc?rev=422293&view=rev
Log:
Documentation conversions
Added:
tapestry/tapestry4/trunk/tapestry-annotations/src/site/
tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/
tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml (with props)
tapestry/tapestry4/trunk/tapestry-portlet/src/site/
tapestry/tapestry4/trunk/tapestry-portlet/src/site/site.xml (with props)
tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/
tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/coding-issues.xml (with props)
tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/configuration.xml (with props)
tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/index.xml (with props)
Removed:
tapestry/tapestry4/trunk/tapestry-annotations/src/documentation/
tapestry/tapestry4/trunk/tapestry-portlet/src/documentation/
Modified:
tapestry/tapestry4/trunk/support/build.xml
Modified: tapestry/tapestry4/trunk/support/build.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/support/build.xml?rev=422293&r1=422292&r2=422293&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/support/build.xml (original)
+++ tapestry/tapestry4/trunk/support/build.xml Sat Jul 15 14:25:03 2006
@@ -30,7 +30,7 @@
<property name="work.dir" value="${export.dir}/${module}"/>
<target name="convert-docs" >
- <xslt basedir="../tapestry-framework/src/documentation/content/xdocs/tapestry/ComponentReference" destdir="tmp"
+ <xslt basedir="../tapestry-portlet/src/documentation/content/xdocs/tapestry-portlet" destdir="tmp"
extension=".xml" includes="**/*.xml"
excludes="**/site.xml,**/*.ent,**/*.aart,**/tabs.xml"
style="forrest2maven-xdoc.xsl" >
Added: tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml?rev=422293&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml (added)
+++ tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml Sat Jul 15 14:25:03 2006
@@ -0,0 +1,683 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Tapestry Annotations</title>
+ </properties>
+ <body>
+
+
+ <section name="Tapestry Annotations">
+ <p>
+ This library does not contain components; instead it provides Tapestry specific
+ <em>annotations</em>
+ (annotations are a a
+ <a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html">
+ new feature in JDK 1.5
+ </a>
+ ). These annotations allow you to perform some operations inside Java code that
+ otherwise would be specified in the page or component specification. This is very
+ useful when using inheritance, because base classes can provide annotations that are
+ inherited by subclasses.
+ </p>
+
+ <p>The annotations are all in the package org.apache.tapestry.annotations.</p>
+
+ <p>
+ Remember that a single method should only have, at most, one of these annotations!
+ Having multiple annotations, or conflicts between method annotations and directives
+ in the specification, will result in runtime exceptions. In addition, annotations
+ don't provide the kind of line precise location data that the XML specifications or
+ the templates do (but most exceptions will clearly identify the class and method,
+ which should be sufficient).
+ </p>
+
+ <subsection name="Asset">
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/Asset.html">Asset</a>
+ annotation is the equivalent of the
+ <a href="#spec.asset"><asset></a>
+ element in a specification. The value attribute is the path to the asset
+ (possibly prefixed to indicate the domain for the path):
+ </p>
+
+ <source xml:space="preserve">
+ @Asset("/style/global.css")
+ public abstract IAsset getGlobalStylesheet();
+</source>
+
+ <p>
+ The asset will be available using the property name using the "asset:" binding
+ prefix.
+ </p>
+
+
+ </subsection>
+
+
+ <subsection name="Bean">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/Bean.html">Bean</a>
+ annotation is the equivalent of the
+ <a href="#spec.bean"><bean></a>
+ element in a specification.
+ </p>
+
+ <p>
+ The property type will be used as the Java class to instantiate for the bean;
+ alternately, the value attribute may be specified (this is useful when, for
+ example, the property type is an interface).
+ </p>
+
+ <p>The examples below both define a bean of type HashMap:</p>
+
+ <source xml:space="preserve">
+ @Bean
+ public abstract HashMap getHashMapBean();
+
+ @Bean(HashMap.class)
+ public abstract Map getMapBean();
+</source>
+
+ <p>
+ A bean defined this way will be stored into the component's beans property,
+ exactly as if specified using XML; its name will be the property name.
+ </p>
+
+ <p>
+ An additional attribute, lifecycle, controls the bean's lifecycle. The default
+ is
+ <a href="apidocs/org/apache/tapestry/annotations/Lifecycle.html">Lifecycle</a>
+ .REQUEST, and additional values are NONE, PAGE, and RENDER:
+ </p>
+
+ <source xml:space="preserve">
+ @Bean(lifecycle = Lifecycle.RENDER)
+ public abstract Map getRenderLifecycleBean();
+</source>
+
+ <p>
+ Lastly, for
+ <em>simple</em>
+ configuration of the bean, there's the initializer attribute. This allows
+ <em>lightweight initialization</em>
+ , where the string is a series of name=value properties, seperated by commas
+ (for boolean properties, the value is optional).
+ </p>
+
+ <source xml:space="preserve">
+ @Bean(initializer = "maxRetries=3")
+ public abstract LoginController getController();
+</source>
+
+ </subsection>
+
+ <subsection name="Component">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/Component.html">Component</a>
+ annotation is attached to an accessor method and allows a component type to be
+ defined in place, as with the
+ <a href="#spec.component"><component></a>
+ element.
+ </p>
+
+ <p>
+ The type must be specified. By default, the component id will match the property
+ name:
+ </p>
+
+ <source xml:space="preserve">
+ @Component(type = "TextField")
+ public abstract TextField getEmail();
+</source>
+
+ <p>When the two must differ, then the id attibute can be specified:</p>
+
+
+ <source xml:space="preserve">
+ @Component(id = "email" type = "TextField")
+ public abstract TextField getEmailField();
+</source>
+
+ <p>
+ Component bindings are specified with an array of strings. The individual
+ strings identify the parameter name and the binding reference:
+ </p>
+
+ <source xml:space="preserve">
+ @Component(type = "Conditional", bindings =
+ { "condition=message", "element=div" })
+ public abstract IComponent getIfMessage();
+</source>
+
+ </subsection>
+
+ <subsection name="ComponentClass">
+
+
+ <p>
+
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/ComponentClass.html">
+ ComponentClass
+ </a>
+ annotation is used to mark a Java class as a component, and allows several
+ properties normally specified using the
+ <a href="#spec.component-specification"><component-specification></a>
+ element.
+ </p>
+
+ <source xml:space="preserve">
+@ComponentClass
+public abstract class MyComponent extends BaseComponent
+{
+...
+</source>
+
+ <p>
+ The defaults for allowBody and allowInformalParameters are true; components may
+ override:
+ </p>
+
+ <source xml:space="preserve">
+@ComponentClass(allowBody = false, allowInformalParameters = false)
+{
+...
+</source>
+
+ <p>
+ Note that simply having a @ComponentClass annotation will
+ <em>override</em>
+ those two properties.
+ </p>
+
+ <p>If a component has reserved parameters, they can be specified as well:</p>
+
+ <source xml:space="preserve">
+@ComponentClass(reservedParameters = "href,name")
+public abstract class LinkWriter extends BaseComponent
+{
+...
+</source>
+
+ <p>
+ Finally, the presence of the @Deprecated annotation will mark the component as
+ deprecated (and cause a warning to be output whenever the component is
+ referenced):
+ </p>
+
+ <source xml:space="preserve">
+@ComponentClass @Deprecated
+public abstact class YeOldeComponent extends AbstractComponent
+{
+...
+</source>
+
+
+ </subsection>
+
+ <subsection name="InitialValue">
+
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InitialValue.html">
+ InitialValue
+ </a>
+ annotation allows a default value to be specified for a property. The property
+ may also be persistent (via the
+ <a href="#Persist">@Persist</a>
+ annotation).
+ </p>
+
+ <p>
+ The value is a binding reference; the reference will be evaluated when the page
+ is first loaded, and again when the page is detached and returned to the page
+ pool. The default binding prefix is "ognl:".
+ </p>
+
+ <p>The annotation is attached to an accessor method:</p>
+
+ <source xml:space="preserve">
+ @InitialValue("request.serverName")
+ public abstract String getServerName();
+ </source>
+
+
+ <p>
+ In many cases, where the initial value is a constant, a better approach is to
+ set the initial value from the component's finishLoad() method.
+ </p>
+
+
+ <source xml:space="preserve">
+ public abstract int getMaxAttempts();
+
+ public abstract void setMaxAttempts(int maxAttempts);
+
+ protected void finishLoad()
+ {
+ setMaxAttempts(5);
+ }
+ </source>
+
+
+ </subsection>
+
+ <subsection name="InjectAsset">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectAsset.html">
+ InjectAsset
+ </a>
+ annotation allows assets defined in the page or component specification to be
+ exposed as read-only properties. It is attached to an accessor method:
+ </p>
+
+ <source xml:space="preserve">
+ @InjectAsset("stylesheet")
+ public abstract IAsset getStylesheet();
+</source>
+
+ <p>
+ This is equivalent to specifying the property attribute of the
+ <a href="#spec.asset"><asset></a>
+ element.
+ </p>
+
+ </subsection>
+
+ <subsection name="InjectComponent">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectComponent.html">
+ InjectComponent
+ </a>
+ annotation allows nested components to be injected as read-only properties. It
+ is attached to an accessor method:
+ </p>
+
+ <source xml:space="preserve">
+ @InjectComponent("inputUserName")
+ public abstract TextField getUserInput();
+</source>
+
+ <p>
+ This is functionally the same as providing the property attribute of the
+ <a href="#spec.component"><component></a>
+ element.
+ </p>
+
+ </subsection>
+
+ <subsection name="InjectMeta">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectMeta.html">InjectMeta</a>
+ annotation allows meta data from the specification (
+ <a href="#spec.meta"><meta> elements)</a>
+ to be exposed as properties.
+ </p>
+
+ <source xml:space="preserve">
+ @InjectMeta("page-title")
+ public abstract String getPageTitle();
+</source>
+
+ <p>
+ The new property does not have to be type String; an automatic type conversion
+ takes place.
+ </p>
+
+ </subsection>
+
+ <subsection name="InjectObject">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectObject.html">
+ InjectObject
+ </a>
+ annotation allows HiveMind objects to be injected. It is attached to an accessor
+ method:
+ </p>
+
+ <source xml:space="preserve">
+ @InjectObject("infrastructure:request")
+ public abstract WebRequest getRequest();
+</source>
+
+ <p>
+ The end result is the same as using the
+ <a href="#spec.inject"><inject></a>
+ element, with the default type of "object".
+ </p>
+
+ </subsection>
+
+ <subsection name="InjectPage">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectPage.html">InjectPage</a>
+ annotation allows a page to be injected into another page or component. It is
+ attached to an accessor method:
+ </p>
+
+ <source xml:space="preserve">
+ @InjectPage("Details")
+ public abstract Details getDetailsPage();
+</source>
+
+ <p>Injecting other pages is most commonly used as part of a listener method.</p>
+
+ </subsection>
+
+ <subsection name="InjectScript">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectScript.html">
+ InjectScript
+ </a>
+ annotation allows JavaScript templates to be exposed as properties. The
+ annotation's value is the path to the script (relative to the page or component
+ specification, if it exists, or relative to the template otherwise).
+ </p>
+
+ <source xml:space="preserve">
+ @InjectScript("scripts/VerifyAccountId.script")
+ public abstract IScript getVerifyAccountIdScript();
+</source>
+
+ </subsection>
+
+ <subsection name="InjectState">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectState.html">
+ InjectState
+ </a>
+ annotation allows an Application State Object to be injected and a read/write
+ property. It is attached to an accessor method:
+ </p>
+
+ <source xml:space="preserve">
+ @InjectState("visit")
+ public abstract MyAppVisit getVisit();
+</source>
+
+ <p>
+ The end result is equivalent to using the
+ <a href="#spec.inject"><inject></a>
+ element, with a type of "state".
+ </p>
+
+ </subsection>
+
+ <subsection name="InjectStateFlag">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/InjectStateFlag.html">
+ InjectStateFlag
+ </a>
+ annotation implements a read-only boolean property that returns true if the
+ identified application state object exists. This is useful for avoiding the
+ accidental creation of the ASO, which helps avoid the unneccessary creation of
+ the HttpSession.
+ </p>
+
+ <source xml:space="preserve">
+ @InjectStateFlag("visit")
+ public abstract boolean getVisitExists();
+ </source>
+
+ <p>
+ The end result is equivalent to using the
+ <a href="#spec.inject"><inject></a>
+ element, with a type of "state-flag".
+ </p>
+
+ </subsection>
+
+ <subsection name="Message">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/Message.html">Message</a>
+ annotation provides easy access to localized messages. It is attached to a
+ method that returns a String, and takes any number of parameters. In its most
+ basic form, it is used alone:
+ </p>
+
+ <source xml:space="preserve">
+ @Message
+ public abstract String getPageTitle();
+</source>
+
+ <p>
+ As used here, the method name is converted into a message property key:
+ <code>page-title</code>
+ :
+ </p>
+
+ <ul>
+ <li>The prefix "get" is stripped off (if present)</li>
+ <li>The letter following "get" is converted to lower case</li>
+ <li>
+ Other capitalized letters are converted to lower case and preceded with a
+ dash ("-")
+ </li>
+ </ul>
+
+ <p>The end result is equivalent to:</p>
+
+ <source xml:space="preserve">
+ public String getPageTitle()
+ {
+ return getMessages().getMessage("page-title");
+ }
+</source>
+
+ <p>
+ When these method-name to property key conversion rules don't yield the correct
+ key, it may be specified explicitly:
+ </p>
+
+ <source xml:space="preserve">
+ @Message("get-a-life")
+ public abstract String getALife();
+</source>
+
+ <p>
+ The method may take parameters as well; these parameter will be converted into
+ message arguments, which can be referenced inside the message as {0}, {1}, etc.
+ </p>
+
+ <source xml:space="preserve">
+ @Message
+ public abstract String getLineTotal(BigDecimal total);
+</source>
+
+ <p>This is equivalent to:</p>
+
+ <source xml:space="preserve">
+ public String getLineTotal(BigDecimal total)
+ {
+ return getMessages().format("line-total", new Object[] { total });
+ }
+</source>
+
+ <p>
+ Primitive types passed in as parameters are automatically converted to wrapper
+ types.
+ </p>
+ </subsection>
+
+ <subsection name="Meta">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/Meta.html">Meta</a>
+ annotation is used to define a meta data value on a page or component class, as
+ with the
+ <a href="#spec.meta"><meta></a>
+ element in an XML component or page specification.
+ </p>
+
+ <p>
+ Meta data from base classes is merged into subclasses; when there's a name
+ conflict, the subclass overrides the base class. This allows a base class to set
+ a default that can be naturally overriden in a subclass.
+ </p>
+
+ <source xml:space="preserve">
+@Meta({ "requires-login=false", "show-ad-banner=true" })
+public abstract class AppBasePage extends BasePage
+{
+...
+</source>
+
+ <p>
+ Subclasses of AppBasePage could provide a @Meta annotatioun that defines new
+ meta data, or overrides either of these values.
+ </p>
+
+ <p>
+ Often, you only want to define a single meta value; the compiler allows you to
+ omit the curly braces for this case:
+ </p>
+
+ <source xml:space="preserve">
+@Meta("org.apache.tapestry.jwcid-attribute-name=id")
+public abstract class MyComponent extends BaseComponent
+{
+...
+</source>
+ </subsection>
+
+ <subsection name="Parameter">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/Parameter.html">Parameter</a>
+ annotation defines a new property, as with
+ <a href="#spec.parameter"><parameter></a>
+ element in an XML component specification.
+ </p>
+
+ <p>
+ This most simple use of this annotation is to simply mark a property as an
+ optional parameter:
+ </p>
+
+ <source xml:space="preserve">
+ @Parameter
+ public abstract void MyType getMyParameter();
+</source>
+
+ <p>
+ The parameter name will generally match the property name (as determined from
+ the method to which the annotation is attached). This can be overriden with the
+ name attribute:
+ </p>
+
+ <source xml:space="preserve">
+ @Parameter(name = "page")
+ public abstract String getTargetPage();
+</source>
+
+ <p>
+ Parameters may be marked as deprecated if the method is marked deprecated (using
+ the java.lang.Deprecated annotation):
+ </p>
+
+ <source xml:space="preserve">
+ @Deprecated @Parameter
+ public abstract int getRows();
+</source>
+
+ <p>
+ The annotation supports several additional attributes, consult its
+ <a href="apidocs/org/apache/tapestry/annotations/Parameter.html">JavaDoc</a>
+ for the full details.
+ </p>
+
+ </subsection>
+
+ <subsection name="Persist">
+
+
+ <p>
+ The
+ <a href="apidocs/org/apache/tapestry/annotations/Persist.html">Persist</a>
+ annotation allows a property to be marked as persistent. Remember that any
+ otherwise unclaimed abstract property will become a
+ <em>transient</em>
+ property automatically (in Tapestry 4.0), so Persist is only needed to mark a
+ property as persistent.
+ </p>
+
+ <p>The value of the Persist annotation defaults to "session":</p>
+
+ <source xml:space="preserve">
+ @Persist
+ public abstract int getSessionPersistentProperty();
+
+ @Persist("client")
+ public abstract double getClientPersistentProperty();
+</source>
+
+ <p>
+ This annotation works exactly like a
+ <a href="#spec.property"><property></a>
+ element, except that the initial-value attribute can't be specified. Use the
+ <a href="#InitialValue">@InitialValue</a>
+ annotation to set the property's initial value.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/tapestry-portlet/src/site/site.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-portlet/src/site/site.xml?rev=422293&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-portlet/src/site/site.xml (added)
+++ tapestry/tapestry4/trunk/tapestry-portlet/src/site/site.xml Sat Jul 15 14:25:03 2006
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<project name="Tapestry">
+ <bannerLeft>
+ <name>Tapestry Web Application Framework</name>
+ <href>http://tapestry.apache.org/</href>
+ <src>images/tapestry_banner.gif</src>
+ </bannerLeft>
+ <bannerRight>
+ <name>Apache Software Foundation</name>
+ <href>http://www.apache.org</href>
+ <src>images/asf_logo_wide.gif</src>
+ </bannerRight>
+
+ <skin>
+ <groupId>org.apache.tapestry</groupId>
+ <artifactId>maven-skin</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ </skin>
+
+ <publishDate format="dd MMM yyyy" />
+
+ <body>
+ <links>
+ <item name="Tapestry" href="http://tapestry.apache.org/" />
+ <item name="Hivemind" href="http://jakarta.apache.org/hivemind/" />
+ <item name="Apache" href="http://www.apache.org/" />
+ </links>
+
+ <head>
+ <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+ <script type="text/javascript">_uacct = "UA-400821-1"; urchinTracker();</script>
+ <link rel="shortcut icon" href="http://tapestry.apache.org/tapestry4.1/favicon.ico" />
+ </head>
+
+ <menu ref="parent" />
+
+ <menu name="Quick Links" inherit="top" >
+ <item name="Home" href="/index.html" />
+ <item name="Download" href="http://tapestry.apache.org/tapestry4.1/download.html" />
+ <item name="Wiki" href="http://wiki.apache.org/tapestry/" />
+ </menu>
+
+ <menu name="Documentation" >
+
+ <item name="Overview" href="/index.html" />
+ <item name="Configuration" href="/configuration.html" />
+ <item name="Coding Issues" href="/coding-issues.html" />
+
+ </menu>
+
+ ${reports}
+ </body>
+
+</project>
Propchange: tapestry/tapestry4/trunk/tapestry-portlet/src/site/site.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/coding-issues.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/coding-issues.xml?rev=422293&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/coding-issues.xml (added)
+++ tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/coding-issues.xml Sat Jul 15 14:25:03 2006
@@ -0,0 +1,313 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Coding Issues</title>
+ </properties>
+ <body>
+
+ <section name="Coding Issues">
+
+ <subsection name="Loss of Transient State">
+
+
+ <p>
+ For developers experienced at servlet Tapestry, this one issue takes quite some
+ getting used to.
+ </p>
+
+ <p>
+ In servlet Tapestry, a request comes in (such as a form submission). As part of
+ processing the request, pages will be obtained from the page pool and will have
+ persistent state rolled back. Other page and component properties will contain
+ <em>transient</em>
+ state; information that will be discarded at the end of the request ... but
+ that's ok, because a response page will be rendered before that information is
+ lost.
+ </p>
+
+ <p>
+ In portlet Tapestry, much is the same,
+ <em>except for transient state</em>
+ . The Portlet API splits the scenario into two completely distrinct parts: the
+ action request and the render request. These are two completely seperate
+ requests, and all transient state will be lost between them. Further, the render
+ request may occur many times. This is because a single portlet within a page
+ <em>may</em>
+ (depending on the Portlet container and configuration of the portlet) have to
+ re-render itself due to an action request for some entirely different portlet.
+ </p>
+
+ <p>
+ The solution is to define more properties as
+ <em>persistent</em>
+ . This is done using the <property> element of the page and component
+ specifications, such as:
+ </p>
+
+ <source xml:space="preserve">
+ <property name="itemId" persist="session"/>
+</source>
+
+ <p>
+ Commonly, the interface is used to obtain a database object, bootstrapping from
+ an id stored as a persistent property:
+ </p>
+
+ <source xml:space="preserve">
+public abstract class MyPage
+ extends BasePage
+ implements PageBeginRenderListener
+{
+ /** Persistent */
+ public abstract long getItemId();
+ public abstract void setItemId(long itemId);
+
+ /** Transient */
+ public abstract Item getItem();
+ public abstract void setItem(Item item);
+
+ /** Injected */
+ public abstract ItemSource getItemSource();
+
+ public void pageBeginRender(PageEvent event)
+ {
+ long itemId = getItemId();
+
+ Item item = getItemSource().findItemById(itemId);
+
+ setItem(item);
+ }
+}
+
+</source>
+
+ <p>
+ One of the most common problems related to loss of transient state concerns
+ <a href="../UsersGuide/validation.html">user input validation</a>
+ . By
+ <em>default</em>
+ , validation data is stored transiently. The end result is that when a validated
+ form is submitted with errors and re-rendered, the error messages and field
+ decorations do not appear!
+ </p>
+
+ <p>
+ A good technique for handling this properly is to make the validation delegate
+ an
+ <a href="../UsersGuide/state.html">application state object</a>
+ that persists in the session, and then
+ <em>inject</em>
+ that ASO into each page that contains a form.
+ </p>
+
+ <p>
+ Start by defining an ASO for the validation delegate. The goes into your
+ application's hivemodule.xml module descriptor:
+ </p>
+
+ <source xml:space="preserve">
+<contribution configuration-id="hivemind.state.ApplicationObjects">
+ <state-object name="validation-delegate" scope="session">
+ <create-instance class="org.apache.tapestry.valid.ValidationDelegate"/>
+ </state-object>
+</contribution>
+</source>
+
+ <p>
+ Next, in each page that needs the validation delegate, inject it as a property.
+ This is done in the page's specification:
+ </p>
+
+ <source xml:space="preserve">
+<inject name="delegate" type="state" object="validation-delegate"/>
+</source>
+
+ <p>When using a component, override the default validation delegate:</p>
+
+ <source xml:space="preserve">
+ <component id="form" type="Form">
+ <binding name="delegate" value="delegate"/>
+ <binding name="listener" value="doSubmit"/>
+ </component>
+</source>
+
+ <p>
+ The delegate parameter's default binding prefix is "ognl", so
+ <code>value="delegate"</code>
+ refers to the delegate property of the page, a read-only property created by the
+ <inject> element.
+ </p>
+
+ <p>
+ And that's it ... the validation delegate will be created when first needed. A
+ single instance will be shared by many pages. It will be necessary to invoke the
+ clear() method on the validation delegate when switching pages (otherwise, you
+ could see decorations one one page that are really caused by form input errors
+ on some other page). This is an extra step to be done inside your listener
+ methods.
+ </p>
+
+ </subsection>
+
+ <subsection name="Partial Pages">
+
+
+ <p>
+ A fundamental part of developing Portlets (with our without Tapestry) is that
+ each Portlet within a Portal Page produces just a portion of the HTML. This
+ means you will not, and should not, use the or components.
+ </p>
+
+ <p>
+ The latter seems problematic ... no component normally means no client-side
+ JavaScript! Fortunately, your components can still create JavaScript, using
+ Tapestry script templates, and the JavaScript will still be collected as if
+ there was a component. You may also see the namespace, provided by the portlet
+ container, integrated into the names of client-side variables and methods ...
+ this prevents any name collisions when multiple Tapestry portlets exist on the
+ same page.
+ </p>
+
+ </subsection>
+
+ <subsection name="Accessing the Portlet API">
+
+
+ <p>
+ In very rare circumstances, you may need to directly access the PortletRequest
+ object. For example, you may make part of your page conditional based on the
+ current window mode.
+ </p>
+
+ <p>
+ If you are just interseted in query parameters, you can access those via the
+ object.
+ </p>
+
+ <p>
+ Most other standard information can be injected as the infrastructure:request
+ object. This object is API neutral (neither servlet nor portlet, but a kind of
+ least-common-denominator abstraction). It can easily be injected into any page
+ or component using the specification's <inject> element:
+ </p>
+
+ <source xml:space="preserve">
+ <inject property="request" object="infrastructure:request"/>
+</source>
+
+
+ <p>
+ The type of object injected will be . There's also an infrastructure:response
+ object that implements the interface.
+ </p>
+
+ <span class="info">
+ <strong>Note:</strong>
+ <p>
+ This may look odd; you are injecting something that looks like an
+ application global. Don't worry ... what's actually injected is a proxy
+ object that implements the interface, but ultimately delegates all of its
+ behavior to a per-request (and therefore, per-thread) object. It just works.
+ </p>
+ </span>
+
+ <p>
+ Properties such as portletMode or windowState are
+ <em>not</em>
+ part of , you'll want to inject a portlet-specific object instead:
+ </p>
+
+ <table>
+ <tr>
+ <th>Object</th>
+ <th>Interface</th>
+ </tr>
+ <tr>
+ <td>service:tapestry.portlet.ActionResponse</td>
+ <td>javax.portlet.ActionResponse</td>
+ </tr>
+ <tr>
+ <td>service:tapestry.portlet.PortletRequest</td>
+ <td>javax.portlet.PortletRequest</td>
+ </tr>
+ <tr>
+ <td>service:tapestry.portlet.RenderResponse</td>
+ <td>javax.portlet.RenderResponse</td>
+ </tr>
+
+ </table>
+
+ <p>
+ Care should be taken to only invoke methods on the ActionResponse and
+ RenderResponse objects when in the correct phase.
+ </p>
+
+ </subsection>
+
+ <subsection name="User Attributes">
+
+
+ <p>
+ Part of the <portlet> definition within the portlet.xml deployment
+ descriptor is a definition of user attributes. User attributes are configuration
+ data stored for each user (this is part of the infrastructure provided by the
+ Portal: user authentication and attributes). User attribute names are strings,
+ usually in the form of a dotted sequence of terms (such as "user.name.given").
+ User attribute values are simple strings.
+ </p>
+
+ <p>
+ User attributes are stored persistently in a database; values will be available
+ in later sessions, not just later requests.
+ </p>
+
+ <p>A special binding prefix, "user:", is used to access user attributes.</p>
+
+ <p>So, a particular portlet may define an attribute:</p>
+
+ <source xml:space="preserve">
+ <user-attribute>
+ <description>User Given Name</description>
+ <name>user.name.given</name>
+ </user-attribute>
+</source>
+
+ <p>Inside a page template, this value can be read and displayed:</p>
+
+ <source xml:space="preserve">
+ <span jwcid="@Insert" value="user:user.name.given">User Name</span>
+</source>
+
+ <p>
+ These values can just as easily be used with form element components, such as ,
+ to read
+ <em>and update</em>
+ attributes:
+ </p>
+
+ <source xml:space="preserve">
+ <input jwcid="userName@ValidField" value="user:user.name.given"
+ displayName="User Name" validator="string,required"/>
+</source>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/coding-issues.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/configuration.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/configuration.xml?rev=422293&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/configuration.xml (added)
+++ tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/configuration.xml Sat Jul 15 14:25:03 2006
@@ -0,0 +1,305 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Configuration</title>
+ </properties>
+ <body>
+
+ <section name="Configuration">
+
+ <p>
+ Configuration for Tapestry portlet applications is quite similar to configuration of
+ Tapestry servlet applications. In both cases, the WEB-INF/lib folder of the web
+ application should include the Tapestry libraries and dependencies. For portlet
+ applications, WEB-INB/lib should also include the tapestry-portlet-
+ <em>x.y</em>
+ .jar library.
+ </p>
+
+
+ <subsection name="portlet.xml">
+
+
+ <p>
+ The file WEB-INF/portlet.xml define the portlets packaged inside a web
+ application. As with servlet Tapestry, we will use a framework-supplied Portlet
+ class:
+ </p>
+
+ <source xml:space="preserve">
+<portlet-app version="1.0"
+ xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">
+ <portlet>
+ <description xml:lang="EN"></description>
+ <portlet-name>myportlet</portlet-name>
+ <display-name xml:lang="EN">My Tapestry Portlet</display-name>
+ <portlet-class>org.apache.tapestry.portlet.ApplicationPortlet</portlet-class>
+ <expiration-cache>-1</expiration-cache>
+ <supports>
+ <mime-type>text/html</mime-type>
+ <portlet-mode>view</portlet-mode>
+ <portlet-mode>help</portlet-mode>
+ <portlet-mode>edit</portlet-mode>
+ </supports>
+ <supported-locale>en</supported-locale>
+ <portlet-info>
+ <title>My Tapestry Portlet</title>
+ <short-title>tapestry-portlet</short-title>
+ <keywords></keywords>
+ </portlet-info>
+ </portlet>
+</portlet-app>
+</source>
+
+
+
+ <p>
+ The class
+ <code>org.apache.tapestry.portlet.ApplicationPortlet</code>
+ is always the class for Tapestry Portlets.
+ </p>
+
+ <p>
+ Tapestry applications can support any reasonable <mime-type>, though the
+ available components make HTML and WML the most likely candidates.
+ </p>
+
+ <p>
+ Different portlet containers interpret the <portlet-mode> element
+ differently. For example, assumes that every Portlet will support the "view"
+ mode, and adding such an entry will result in a confusing duplication of the
+ view icons on the Portlet's control tab. On the other hand, makes no
+ assumptions, so you really should provide the "view" mode.
+ </p>
+
+ <p>
+ Later, we'll see how the combination of mime-type and portlet mode is used to
+ select a Tapestry page.
+ </p>
+
+ <p>
+ Tapestry supports the other <portlet> elements, such as
+ <portlet-preferences> and <user-attribute>.
+ </p>
+
+
+ </subsection>
+
+ <subsection name="hivemodule.xml">
+
+
+ <p>
+ Each Tapestry portlet application within a web application will construct its
+ <em>own</em>
+ Registry on initialization. The Registry will reflect all the libraries on the
+ portlet's classpath (that is, including the Tapestry and HiveMind JARs in
+ WEB-INF/lib). In addition, two
+ <em>optional</em>
+ module descriptors will be parsed and used, if present:
+ </p>
+
+ <ul>
+ <li>
+ WEB-INF/
+ <em>name</em>
+ /hivemodule.xml
+ </li>
+ <li>WEB-INF/hivemodule.xml</li>
+ </ul>
+
+ <p>
+ The
+ <em>name</em>
+ , in the above, is the portlet name, from the <portlet-name> element of
+ the portlet.xml descriptor. This allows different Tapestry portlets, even within
+ the same WAR, to precisely control their individual configuration.
+ </p>
+
+ <p>
+ The two primary reasons for a Tapestry portlet application to have its own
+ hivemodule.xml are:
+ </p>
+
+ <ul>
+ <li>To control the mapping of requests to Tapestry pages</li>
+ <li>To define portlet-specific services needed by the portlet application</li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="web.xml">
+
+
+
+ <p>
+ By specification, portlet applications are a specialized kind of web
+ application; as such, they require a web.xml as well as a portlet.xml.
+ </p>
+
+ <p>
+ For Tapestry, it is necessary to define a single Tapestry application servlet
+ for each WAR.
+ </p>
+
+ <source xml:space="preserve">
+<!DOCTYPE web-app
+ PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+<web-app>
+ <display-name>app</display-name>
+ <servlet>
+ <servlet-name>ApplicationServlet</servlet-name>
+ <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>ApplicationServlet</servlet-name>
+ <url-pattern>/app</url-pattern>
+ </servlet-mapping>
+</web-app>
+</source>
+
+ <span class="info">
+ <strong>Note:</strong>
+ <p>
+ Some portals, such as , require additional configuration in the web.xml
+ deployment descriptor.
+ </p>
+ </span>
+
+ <p>
+ Note that just
+ <em>one</em>
+ ApplicationServlet is needed, regardless of the number of Tapestry portlet
+ applications within the WAR. This Tapestry servlet instance is primarily needed
+ to support the use of the asset service, which is the mechanism by which private
+ assets stored within the framework's JARs (such as images and stylesheets) can
+ be provided to client web browsers.
+ </p>
+
+
+ <p>
+ In the above example, the default servlet mapping, to the /app URL, was used.
+ You may use alternate mappings, but additional
+ <a href="site:friendly-urls">configuration</a>
+ is needed.
+ </p>
+
+ </subsection>
+
+ <subsection name="Mapping Requests to Pages">
+
+
+ <p>
+ Tapestry has to bridge between the operation-centric organization of Portlets,
+ and the page/component-centric organization of Tapestry itself. This is most
+ visible when the a Tapestry Portlet first starts up, or when a user changes the
+ window state or portlet mode by using the portlet's toolbar (to be specific: the
+ toolbar provided by the Portal page).
+ </p>
+
+ <p>
+ In all these cases, a request is recieved by the Tapestry ApplicationPortlet
+ that includes no real information in the request, just an indication of the
+ desired window state and portlet mode.
+ </p>
+
+ <p>
+ Tapestry uses a set of
+ <em>rules</em>
+ to determine what to do in these cases. Each rule identifies
+ <em>up-to</em>
+ three
+ <em>factors</em>
+ used to select a page. These factors are mime-type, portlet-mode, and
+ window-state.
+ </p>
+
+ <p>
+ The rules are sorted and consulted in order. The first match defines the page to
+ activate and render. Omitting a factor means that the factor is not used when
+ checking a rule against an incoming request.
+ </p>
+
+ <p>
+ The rules are defined by the configuration point
+ <code>tapestry.portlet.resolver.PageResolverRules</code>
+ . Contributions to this configuration point consist of <match> elements:
+ </p>
+
+ <source xml:space="preserve">
+<match [portlet-mode="..."] [mime-type="..."] [window-state="..."] page="..."/>
+</source>
+
+ <p>The default rules are:</p>
+
+ <source xml:space="preserve">
+ <match portlet-mode="edit" page="Edit"/>
+ <match portlet-mode="help" page="Help"/>
+</source>
+
+ <p>Any rules you define will be mixed in with these two default rules.</p>
+
+ <p>
+ So, by contributing additional <match> rules to this configuration point,
+ it is possible to precisely control which page should be rendered for each
+ request; for example, you could have different pages for the "edit"
+ portlet-mode, depending on whether the window state was normal or maximized:
+ </p>
+
+ <source xml:space="preserve">
+
+<contribution configuration-id="tapestry.portlet.resolver.PageResolverRules">
+ <match portlet-mode="edit" window-state="maximized" page="EditLarge"/>
+</contribution>
+
+</source>
+
+ <p>
+ Here, the Edit page would be used (as per the default rules) unless the window
+ state was maximized, in which case the EditLarge page would be used.
+ </p>
+
+ <p>
+ What happens when none of the rules match? In that case, the View page is
+ activated and rendered. The View page, in portlet Tapestry, is the equivalent of
+ the Home page, in servlet Tapestry.
+ </p>
+
+ <p>
+ <strong>For advanced developers</strong>
+ : the process for determing the page for a request is ultimately based on a
+ extensible chain of command. The
+ <code>tapestry.portlet.resolver.PageResolvers</code>
+ configuration point defines the commands in the chain; by providing services
+ that implement the
+ <a href="apidocs/org/apache/tapestry/portlet/PortletPageResolver.html">
+ PortletPageResolver
+ </a>
+ interfaces, you can add even more sophisticated and precise control over the
+ mapping between requests and pages.
+ </p>
+
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/configuration.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/index.xml?rev=422293&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/index.xml (added)
+++ tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/index.xml Sat Jul 15 14:25:03 2006
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Tapestry Portlet Support</title>
+ </properties>
+ <body>
+
+ <section name="Tapestry Portlet Support">
+
+ <p>
+ An add-on module for Tapestry that enables the use of Tapestry to create
+ <a href="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlets</a>
+ . Portlet support is new in Tapestry 4.0. To a large degree, Tapestry has been
+ re-architected to support portlets.
+ </p>
+
+ <p>
+ Portlet support in Tapestry is
+ <em>native</em>
+ . This means that Tapestry is, under the covers, using the true Portlet API as it is
+ intended to be used. Some portal services support bridging ... allowing servlet
+ applications to operate as portlet applications unchanged; such an approach is
+ possible as well, but is not necessary.
+ </p>
+
+ <p>
+ The pattern of development for Tapestry portlet applications is to create a
+ (generally) small application, consisting of just a few pages. Each Tapestry portlet
+ within a portal page will be a completely separate instance of not just the portlet,
+ but all the Tapestry services behind it.
+ </p>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/tapestry-portlet/src/site/xdoc/index.xml
------------------------------------------------------------------------------
svn:eol-style = native