Author: hlship
Date: Mon Apr 19 13:53:07 2010
New Revision: 935570
URL: http://svn.apache.org/viewvc?rev=935570&view=rev
Log:
Bring documentation about libraries and assets up to date
Modified:
tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt
tapestry/tapestry5/trunk/src/site/apt/upgrade.apt
Modified: tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt?rev=935570&r1=935569&r2=935570&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/cookbook/lib.apt Mon Apr 19 13:53:07
2010
@@ -86,11 +86,14 @@ Creating Component Libraries
</repositories>
<properties>
- <tapestry-release-version>5.0.16</tapestry-release-version>
+ <tapestry-release-version>5.2.0</tapestry-release-version>
</properties>
</project>
---
+ You will need to modify the Tapestry release version number ("5.2.0" in the
listing above) to reflect the current
+ version of Tapestry when you create your component library.
+
We'll go into more detail about the relevant portions of this POM in the
later sections.
Step 1: Choose a base package name
@@ -101,7 +104,7 @@ Step 1: Choose a base package name
As with an application, we'll follow the conventions: we'll place the
module for this library
inside the services package, and place pages and components under their
respective packages.
-Step 2: Create your pages and/or components
+Step 3: Create your pages and/or components
Our component is very simple:
@@ -133,15 +136,15 @@ public class HappyIcon
for the file happy.jpg. The path specified with the @Path annotation is
relative to the HappyIcon.class file;
it should be stored in the project under
src/main/resources/org/example/happylib/components.
- Tapestry ensures that asset can be accessed from the web browser; the src
attribute of the \<img\> tag
- will be a URL that directly accesses the image file ... there's no need to
unpackage the happy.jpg file, it's
- all handled by Tapestry.
+ Tapestry ensures that the happy.jpg asset can be accessed from the web
browser; the src attribute of the \<img\> tag
+ will be a URL that directly accesses the image file ... there's no need to
unpackage the happy.jpg file. This works
+ for any asset file stored under the libraries root package.
This component renders out an img tag for the icon.
- Often, a component library will have many different components, or even
pages.
+ Typically, a component library will have many different components and/or
mixins, and may even provide pages.
-Step 3: Choose a virtual folder name
+Step 2: Choose a virtual folder name
In Tapestry, components that have been packaged in a library are referenced
using a virtual folder name.
It's effectively as if the application had a new root-level folder
containing the components.
@@ -157,12 +160,33 @@ Step 3: Choose a virtual folder name
Why "icon" vs. "happyicon"? Tapestry notices that the folder name, "happy"
is a prefix or suffix of the
class name ("HappyIcon") and creates an alias that strips off the prefix (or
suffix). To Tapestry, they are
- completely identical.
+ completely identical: two different aliases for the same component class
name.
+
+ The above naming is somewhat clumsy, and can be improved by introducing an
additional namespace into the template:
+
+---
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd";
+ xmlns:h="tapestry-library:happy">
+
+ ...
+
+ <h:icon/>
+
+ ...
+</html>
+---
+
+ The special namespace mapping for sets up namespace prefix "h:" to mean the
same as "happy/". It then becomes
+ possible to reference components within the happy virtual folder directly.
-Step 4: Configure the virtual folder
+
+Step 3: Configure the library
Tapestry needs to know where to search for your component class. This is
accomplished in your library's IoC module class, by
making a <contribution> to the ComponentClassResolver
{{{../../tapestry-ioc/configuration.html}service configuration}}.
+
+ At application startup, Tapestry will read the library module along with all
other modules and configure the
+ ComponentClassResolver service using information in the module:
----
package org.example.happylib.services;
@@ -181,7 +205,7 @@ public class HappyModule
The ComponentClassResolver service is responsible for mapping libraries to
packages; it takes as a contribution
a collection of these LibraryMapping objects. Every module may make its own
contribution to the ComponentClassResolver service,
- mapping its own package to its own folder.
+ mapping its own package ("org.example.happylib") to its own folder ("happy").
This module class is also where you would define new services that can be
accessed by your components (or other parts
of the application).
@@ -193,7 +217,8 @@ public class HappyModule
Adding to "core" is sometimes reasonable, if there is virtually no chance of
a naming conflict (via different modules contributing
packages to core with conflicting class names).
-Step 5: Configure the module to autoload
+
+Step 4: Configure the module to autoload
For Tapestry to {{{../../tapestry-ioc/autoload.html}autoload}} your module,
it is necessary to put an entry in the
JAR manifest. This is taken care of in the pom.xml above:
@@ -213,58 +238,23 @@ Step 5: Configure the module to autoload
----
-Step 6: Extending Client Access
-
- As of Tapestry 5.2, a new step is needed: {{{../guide/assets.html}extending
access for the assets}}.
-
- This is accomplished in your library's module class, HappyModule:
-
-----
- public static void contributeRegexAuthorizer(Configuration<String>
configuration)
- {
- configuration.add("^org/example/happylib/.*\\.jpg$");
- }
-----
-
- This contribution uses a regular expression to identify that any resource on
the classpath under the
- org/example/happylib folder with a <<<jpg>>> extension is allowed. If you
had a mix of different
- image types, you could replace <<<jpg>>> with <<<(jpg|gif|png)>>>.
-
-Step 7: Versioning Assets
-
- Classpath assets, those packaged in JAR files (such as the happy.jpg asset)
are retrieved by the client web browser
- using a URL that reflects the package name. Tapestry users
a special virtual folder, <<</assets>>>, under
- the context folder for this purpose.
-
- The image file here would exposed to the web browser via the URL
<<</happyapp/assets/org/example/happylib/components/happy.jpg>>> (this assumes
that
- the application was deployed as happyapp.war).
-
- Tapestry uses a far-future expiration date for classpath assets; this allows
browsers to aggresively cache
- the file, but this causes a problem should a later version of the library
change the file. This is discussed
- in detail in
- {{{http://developer.yahoo.com/performance/rules.html#expires}Yahoo's
Performance Best Practices}}.
-
- To handle this problem, you should map your library assets to a versioned
folder. This can be accomplished using
- another contribution from the HappyModule, this time to the
ClasspathAssetAliasManager service
- whose configuration maps a virtual folder underneath /assets
- to a package:
-
-----
- public static void
contributeClasspathAssetAliasManager(MappedConfiguration<String, String>
configuration)
- {
- configuration.add("happylib/1.0", "org/example/happylib");
- }
-----
-
- With this in place, and the library and applications rebuilt and redeployed,
the URL for happy.jpg becomes
- <<</happyapp/assets/happylib/1.0/components/happy.jpg>>>. This is shorter,
but also incorporates a version number ("1.0")
- that can be changed in a later release.
Conclusion
That's it! Autoloading plus the virtual folders for components and for
assets takes care of all the issues related
to components. Just build your JARs, setup the JAR Manifest, and drop them
into your applications.
+A note about Assets
+ Tapestry automatically creates a mapping for assets inside your JAR. In the
above example, the icon image
+ will be exposed as /assets/<application version>/happy/components/happy.jpg
(the application version number
+ is incorporated into the URL). The "happy" portion is a virtual folder that
maps to the librarie's
+ root package (as folder "org/example/happylib" on the Java classpath).
+
+ The application version is {{{../guide/conf.html}a configurable value}}.
+
+ In Tapestry 5.1 and earlier, it was necessary to explicitly create a
mapping,
+ via a contribution to the ClasspathAssetAliasManager service, to expose
library assets.
+ This is no longer necessary in Tapestry 5.2.
Modified: tapestry/tapestry5/trunk/src/site/apt/upgrade.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/upgrade.apt?rev=935570&r1=935569&r2=935570&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/upgrade.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/upgrade.apt Mon Apr 19 13:53:07 2010
@@ -14,6 +14,28 @@ Upgrade Notes
Release 5.2.0
+* Assets
+
+ There have been some changes to how assets operate in Tapestry 5.2. The
previous mechanism
+ for marking assets as public (exposed to the client user agent), introduced
in Tapestry 5.1,
+ have been removed in 5.2. The corresponding services (WhitelistAuthorizer,
RegexAuthorizer)
+ have been deleted outright; you may need to modify your application module
to no longer make
+ contributions to these services.
+
+ Virtual folders, used to define root packages for component libraries, may
no longer
+ contain slashes. The same goes for LibraryMappings.
+
+ Each LibraryMapping contributed to the ComponentClassResolver service
+ is now automatically converted into a matching contribution to
+ the ClasspathAssetAliasManager service. Previously a library author was
encouraged
+ to make contributions to both services. The path prefix of a LibraryMapping
is also
+ now prohibited from containing the slash character.
+
+ It is now quite necessary to configure the application version number: all
assets are exposed via
+ a URL that incorporates the application version number; in previous
releases, each library could
+ configure its own version number. By implication, changing library versions
and nothing else will now
+ require a change to the application version number.
+
* ClassTransformation API changes
The
