Hi,
I would like to propose an improvement to the ref-doc for wildcards.
I was talking with Michael (mck) by email and he kindly suggested that I
submit my changes to this mailing list.
Please find attached the file
"/tiles-parent/src/site/apt/tutorial/advancedwildcard.apt" .
Cheers,
Michael.
~~ $Id: wildcard.apt 1310865 2012-04-07 21:01:22Z nlebas $
~~
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements. See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership. The ASF licenses this file
~~ to you 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.
~~
-----------
Wildcard support
-----------
Wildcard support
By default, Tiles supports wildcards in definition names. Wilcards help a
lot in writing less code to declare your definitions.
* Default configuration
Note: default configuration only works if you do not use
<<<CompleteAutoloadTilesContainerFactory>>>. If you are using this setting, you
can move to the next section.
Let us start with a simple example. When not using wildcards, you might end
up with such tiles definitions:
-----------------------------------
<definition name="bank/user" template="/layout.jsp">
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/user.jsp"/>
</definition>
<definition name="bank/account" template="/layout.jsp">
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/account.jsp"/>
</definition>
<definition name="bank/customer" template="/layout.jsp">
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/customer.jsp"/>
</definition>
------------------------------------
The above definitions are pretty verbose as you need to create one definition
per JSP that you're adding to your application.
You could use definition inheritance to reduce the number of lines but you
would still need one definition per JSP.
** Single star '\*'
Let's see how to improve that using wildcards. You would then have:
------------------------------------
<definition name="bank/*" template="/layout.jsp">
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/{1}.jsp"/>
</definition>
------------------------------------
Calling a view named "bank/user" matches the above definition name. Inside
the "body" attributes, \{1\} refers to the star's value which is "user" in that
case.
** Multiple stars such as in '\*/\*'
Let's now consider another case. As you can see, the sample below uses 2
stars '\*'.
------------------------------------
<definition name="bank/*/*" template="/layout.jsp">
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/{1}-{2}.jsp"/>
</definition>
------------------------------------
Calling a view named "/bank/customer/account" matches the above definition
name.
Inside the 'body' attribute, \{1\} refers to the first star and \{2\} refers
to the second one.
The "body" JSP name will be "customer-account.jsp".
Here is another example which shows that you can use package-style definition
names:
------------------------------------
<definition name="WILDCARD:test.definition*.message*" template="/layout{1}.jsp">
<put-attribute name="title" value="This definition has a message: {2}."/>
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/body.jsp"/>
</definition>
------------------------------------
* Using prefixes
** Enabling CompleteAutoloadTilesContainerFactory
As a prerequisite for using prefixes, you need to have
CompleteAutoloadTilesContainerFactory enabled.
If you haven't enabled it yet, here is a quick checklist for you to use.
The library tiles-extras is required. If you're using Maven, you need to add
this dependency to you POM file:
------------------------------------
<dependency>
<groupId>org.apache.tiles</groupId>
<artifactId>tiles-extras</artifactId>
<version>2.2.2</version>
</dependency>
------------------------------------
If you are using Spring, you should add the 'completeAutoload'
attribute to your TilesConfigurer bean.
------------------------------------
<bean id="tilesConfigurer"
class="org.springframework.web.servlet.view.tiles2.TilesConfigurer">
<property name="completeAutoload" value="true"/>
</bean>
------------------------------------
** Using prefixes for wildcards and Regular Expressions
When using completeAutoload, you can use wildcard expressions and/or regexp.
Each of them should be enabled using the dedicated prefix as follows.
*** WILDCARD
------------------------------------
<definition name="WILDCARD:test.definition*.message*" template="/layout{1}.jsp">
<put-attribute name="title" value="This definition has a message: {2}."/>
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/body.jsp"/>
</definition>
<definition name="WILDCARD:bank/*" template="/layout.jsp">
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/{1}.jsp"/>
</definition>
------------------------------------
And, if you want to use Regular Expressions:
*** REGEXP
------------------------------------
<definition name="REGEXP:test\.definition(.*)\.message(.*)"
template="/layout{1}.jsp">
<put-attribute name="title" value="This definition has a message: {2}."/>
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/body.jsp"/>
</definition>
------------------------------------
*** tiles:insertDefinition
In both cases, if you insert a definition that matches the definition, for
example:
------------------------------------
<tiles:insertDefinition name="test.definitionOne.messageThisIsAMessage" />
------------------------------------
The definition is automatically mapped, replacing placeholders, marked by
curly brackets, with the value of matched definitions. In this case:
------------------------------------
<definition name="test.definitionOne.messageThisIsAMessage"
template="/layoutOne.jsp">
<put-attribute name="title" value="This definition has a message:
ThisIsAMessage."/>
<put-attribute name="header" value="/header.jsp"/>
<put-attribute name="body" value="/body.jsp"/>
</definition>
------------------------------------
