You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by hl...@apache.org on 2008/03/19 02:00:20 UTC
svn commit: r638666 - in /tapestry/tapestry5/trunk/tapestry-core/src/site:
apt/guide/env.apt site.xml
Author: hlship
Date: Tue Mar 18 18:00:18 2008
New Revision: 638666
URL: http://svn.apache.org/viewvc?rev=638666&view=rev
Log:
TAPESTRY-1921: Add documentation for Environmental annotation, environmental services
Added:
tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/env.apt
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml
Added: tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/env.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/env.apt?rev=638666&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/env.apt (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/site/apt/guide/env.apt Tue Mar 18 18:00:18 2008
@@ -0,0 +1,139 @@
+ ----
+ Environmental Services
+ ----
+
+Environmental Services
+
+ Environmental services represent yet another, distinct form of injection.
+
+ Unlike service injection (injection via a service implementation's constructor) or
+ normal component injection (directly into component fields, via the @Inject annotation) where the injected value
+ is always the same, with environmental services, the injected value is very late bound and dynamic.
+
+ Environmental services are often a conduit of communication between an outer component
+ and the components it encloses.
+
+ An example of this is form support; the
+ {{{../ref/org/apache/tapestry/corelib/components/Form.html}Form}}
+ component creates an environmental of type
+ {{{../../apidocs/org/apache/tapestry/services/FormSupport.html}FormSupport}}. The FormSupport
+ interface allows enclosed components to participate in both the rendering of the Form
+ and the Form's eventual submission. This is how control names and client-side ids are determined, how fields
+ register callbacks so that they can process their part of the submission, and
+ how fields hook themselves to client-side validation.
+
+Using the @Environmental annotation
+
+ The {{{../../apidocs/org/apache/tapestry/annotations/Environmental.html}Environmental}} annotation
+ is used to dynamically connect to a Environmental service provided by an enclosing component.
+
+ A very common Environmental is
+ {{{../../apidocs/org/apache/tapestry/PageRenderSupport.html}PageRenderSupport}}, used
+ when generating {{{ajax.html}client-side JavaScript}}.
+
++---+
+
+ @Inject @Path("${tapestry.scriptaculous}/dragdrop.js")
+ private Asset _dragDropLibrary;
+
+ @Environmental
+ private PageRenderSupport _pageRenderSupport;
+
+ void setupRender()
+ {
+ _pageRenderSupport.addScriptLink(_dragDropLibrary);
+ }
+
++---+
+
+ Environmental services are, by their nature, per-thread (and therefore per-request).
+
+ Accessing an environmental field causes a lookup, by type, against
+ the {{{../../apidocs/org/apache/tapestry/services/Environment.html}Environment}} service.
+
+ Normally, an environmental of the specified type must be available in the Environment, or an exception
+ is thrown when accessing the field.
+
+ If the value of the Environmental annotation is false, then the environmental value is optional.
+
+
+Placing a value in the environment
+
+ The Environment service has push() and pop() methods to put a value in the Environment, and discard it.
+
+ For example, say you were building a tab-based menu system and you needed to allow an outer TabGroup component
+ to communicate with inner Tab components, to control various aspects of presentation.
+
+ The relevant information could be exposed as an interface, TabModel.
+
++----+
+public class TabGroup
+{
+ @Inject
+ private Environment _environment;
+
+ void beginRender()
+ {
+ _environment.push(TabModel.class, new TabModelImpl(...));
+ }
+
+ void afterRender()
+ {
+ _environment.pop(TabModel.class);
+ }
+}
+
+public class Tab
+{
+ @Environmental
+ private TabModel _model;
+
+ void beginRender(MarkupWriter writer)
+ {
+ ...
+ }
+}
++----+
+
+ Notice that when pushing a value into the Environment, you identify its type as well as the
+ instance. Environment maintains a number of stacks, one for each type. Thus, pushing a TabModel into
+ the environment won't disturb the PageRenderSupport or other environmentals already there.
+
+ What's important here is that the code that pushes a environmental onto a stack should also pop it off.
+
+ The enclosed class, Tab, has full access to whatever object was pushed onto the stack by the TabGroup.
+
+ The reason why Environment is a stack is so that a component can, when it makes sense, easily replace
+ or intercept access to an Environmental.
+
+Fundamental Environmentals
+
+ Not all environmentals are pushed into the Environment by components.
+
+ A number of environmentals are initialized as part of page rendering, even before the first
+ component starts to render. This initialization is accomplished
+ with
+ {{{../../apidocs/org/apache/tapestry/services/MarkupRendererFilter.html}MarkupRendererFilter}}
+ contributions to the
+ {{{../../apidocs/org/apache/tapestry/service/MarkupRenderer.html}MarkupRenderer}} service.
+
+Accessing Environmentals in Services
+
+ The Environmenal annotation only works inside components.
+
+ To access an Environmental inside a service implementation, you must inject the Environment service and obtain values from
+ it using the peek() method.
+
+ If this is something that will occur frequently, it is possible to create a service implementation
+ that is "backed" by the Environment. For example, PageRenderSupport is accessible as a normal injection, because
+ a service is built for it in TapestryModule:
+
++---+
+ public PageRenderSupport buildPageRenderSupport(EnvironmentalShadowBuilder builder)
+ {
+ return builder.build(PageRenderSupport.class);
+ }
++----+
+
+ The EnvironmentShadowBuilder service creates a service implementation that delegates to the proper instance
+ in the environment. The same technique can be used for your own services and environmentals.
Modified: tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml?rev=638666&r1=638665&r2=638666&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml Tue Mar 18 18:00:18 2008
@@ -66,6 +66,7 @@
<item name="Input Validation" href="guide/validation.html"/>
<item name="BeanEditForm Guide" href="guide/beaneditform.html"/>
<item name="Component Events" href="guide/event.html"/>
+ <item name="Environmental Services" href="guide/env.html"/>
<item name="Layout Component" href="guide/layout.html"/>
<item name="CSS" href="guide/css.html"/>
<item name="Ajax" href="guide/ajax.html"/>
Re: svn commit: r638666 - in /tapestry/tapestry5/trunk/tapestry-core/src/site: apt/guide/env.apt site.xml
Posted by Massimo Lusetti <ml...@gmail.com>.
On Wed, Mar 19, 2008 at 2:00 AM, <hl...@apache.org> wrote:
> Author: hlship
> Date: Tue Mar 18 18:00:18 2008
> New Revision: 638666
>
> URL: http://svn.apache.org/viewvc?rev=638666&view=rev
> Log:
> TAPESTRY-1921: Add documentation for Environmental annotation, environmental services
This is really nice! Thanks Howard!
--
Massimo
http://meridio.blogspot.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org