http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/iterator-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/iterator-tag.md b/source/tag-developers/iterator-tag.md new file mode 100644 index 0000000..97a3646 --- /dev/null +++ b/source/tag-developers/iterator-tag.md @@ -0,0 +1,109 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# iterator + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + + +The id attribute is deprecated in Struts 2.1.x, and has been replaced by the var attribute. + +| + +The begin, end and step attributes are only available from 2.1.7 on + +> + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/iterator.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example1description|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example1code|lang=xml|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example2description|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example2code|lang=xml|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example3description|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example3code|lang=xml|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example4description|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example4code|lang=xml|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example5description|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example5code|lang=xml|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example6description|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example6code|lang=xml|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example7description|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example7code|lang=xml|javadoc=true|url=org.apache.struts2.components.IteratorComponent} +~~~~~~~
http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/jsp-tags.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/jsp-tags.md b/source/tag-developers/jsp-tags.md new file mode 100644 index 0000000..55d9851 --- /dev/null +++ b/source/tag-developers/jsp-tags.md @@ -0,0 +1,25 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# JSP Tags + +JSP tags are extensions of the generic tags provided by the framework. You can get started almost immediately by simply +knowing the generic structure in which the tags can be accessed: `<s:tag> ... </s:tag>`, where tag is any of the tags +supported by the framework. + +## Tag Library Definition (TLD) + +The JSP TLD is included in the `struts-core.jar`. To use, just include the usual red-tape at the top of your JSP. + +```jsp +<%@ taglib prefix="s" uri="/struts-tags" %> +<html> + <body> + <p>Now you can use the tags, like so:</p> + <s:iterator value="people"> + <s:property value="lastName"/>, <s:property value="firstName"/> + </s:iterator> + ... +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/jsp.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/jsp.md b/source/tag-developers/jsp.md new file mode 100644 index 0000000..5b6b3a1 --- /dev/null +++ b/source/tag-developers/jsp.md @@ -0,0 +1,97 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# JSP +{:.no_toc} + +* Will be replaced with the ToC, excluding a header +{:toc} + +The default configuration (`struts-default.xml`) configures the `Dispatcher Result` as the default result, which works +well with JavaServer Pages. Any JSP 1.2+ container can work with Struts 2 JSP tags immediately. + +## Getting Started + +Because JSP support occurs through the `Dispatcher Result`, which is the default result type, you don't need to specify +the type attribute when configuring `struts.xml`: + +```xml +<action name="test" class="com.acme.TestAction"> + <result name="success">test-success.jsp</result> +</action> +``` + +Then in **test-success.jsp**: + +```jsp +<%@ taglib prefix="s" uri="/struts-tags" %> + +<html> +<head> + <title>Hello</title> +</head> +<body> + +Hello, <s:property value="name"/> + +</body> +</html> +``` + +Where **name** is a property on your action. That's it! + +## Servlet / JSP Scoped Objects + +The following are ways to obtain Application scope attributes, Session scope attributes, Request scope attributes, +Request parameters and framework Context scope parameters: + +### Application Scope Attribute + +Assuming there's an attribute with name `myApplicationAttribute` in the Application scope. + +```jsp +<s:property value="%{#application.myApplicationAttribute}" /> +``` + +### Session Scope Attribute + +Assuming there's an attribute with name `mySessionAttribute` in the Session scope. + +```jsp +<s:property value="%{#session.mySessionAttribute}" /> +``` + +### Request Scope Attribute + +Assuming there's an attribute with name `myRequestAttribute` in the Request scope. + +```jsp +<s:property value="%{#request.myRequestAttribute}" /> +``` + +### Request Parameter + +Assuming there's a request parameter `myParameter` (e.g. [http://host/myApp/myAction.action?myParameter=one]). + +```jsp +<s:property value="%{#parameters.myParameter}" /> +``` + +### Context Scope Parameter + +Assuming there's a parameter with the name `myContextParam` in our context. + +```jsp +<s:property value="%{#myContextParam}" /> +``` + +## Tag Support + +See the [JSP Tags](jsp-tags.html) documentation for information on how to use the generic [Struts Tags](struts-tags.html) +provided by the framework. + +## Exposing the ValueStack + +There are a couple of ways to obtain [Access to ValueStack from JSPs](access-to-valuestack-from-jsps.html). http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/merge-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/merge-tag.md b/source/tag-developers/merge-tag.md new file mode 100644 index 0000000..8adaf05 --- /dev/null +++ b/source/tag-developers/merge-tag.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# merge + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.MergeIterator} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/merge.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=javacode|lang=java|javadoc=true|url=org.apache.struts2.components.MergeIterator} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.MergeIterator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ognl-basics.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ognl-basics.md b/source/tag-developers/ognl-basics.md new file mode 100644 index 0000000..1990e35 --- /dev/null +++ b/source/tag-developers/ognl-basics.md @@ -0,0 +1,124 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# OGNL Basics +{:.no_toc} + +* Will be replaced with the ToC, excluding a header +{:toc} + +## Struts-specific language features + +The biggest addition that Struts provides on top of OGNL is the support for the ValueStack. While OGNL operates under +the assumption there is only one "root", Struts's ValueStack concept requires there be many "roots". + +For example, suppose we are using standard OGNL (not using Struts) and there are two objects in the OgnlContext map: +"foo" -> foo and "bar" -> bar and that the foo object is also configured to be the single **root** object. +The following code illustrates how OGNL deals with these three situations: + +``` +#foo.blah // returns foo.getBlah() +#bar.blah // returns bar.getBlah() +blah // returns foo.getBlah() because foo is the root +``` + +What this means is that OGNL allows many objects in the context, but unless the object you are trying to access is the root, +it must be prepended with a namespaces such as @bar. Now let's talk about how Struts is a little different... + +> In Struts, the entire ValueStack is the root object in the context. Rather than having your expressions get the object +> you want from the stack and then get properties from that (ie: peek().blah), Struts has a special OGNL PropertyAccessor +> that will automatically look at the all entries in the stack (from the top down) until it finds an object with the property +> you are looking for. + +For example, suppose the stack contains two objects: Animal and Person. Both objects have a "name" property, Animal has +a "species" property, and Person has a "salary" property. Animal is on the top of the stack, and Person is below it. +The follow code fragments help you get an idea of what is going on here: + +``` +species // call to animal.getSpecies() +salary // call to person.getSalary() +name // call to animal.getName() because animal is on the top +``` + +In the last example, there was a tie and so the animal's name was returned. Usually this is the desired effect, but +sometimes you want the property of a lower-level object. To do this, XWork has added support for indexes on the ValueStack. +All you have to do is: + +``` +[0].name // call to animal.getName() +[1].name // call to person.getName() +``` + +With expression like `[0] ... [3]` etc. Struts will cut the stack and still return back a CompoundRoot object. To get +the top of that particular stack cut, use `[0].top` + +|ognl expression|description| +|---------------|-----------| +|`[0].top`|would get the top of the stack cut starting from element 0 in the stack (similar to top in this case)| +|`[1].top`|would get the top of the stack cut starting from element 1 in the stack| + +### Accessing static properties + +OGNL supports accessing static properties as well as static methods. + +By default, Struts 2 is configured to disallow this - to enable OGNL's static member support you must set the +`struts.ognl.allowStaticMethodAccess` constant to `true` via any of the [Constant Configuration](../core-developers/constant-configuration.html) methods. + +OGNL's static access looks like this: + +``` +@some.package.ClassName@FOO_PROPERTY +@some.package.ClassName@someMethod() +``` + +However, Struts allows you to avoid having to specify the full package name and call static properties and methods of your +action classes using the "vs" prefix: + +``` +<at:var at:name="vs" />FOO_PROPERTY +<at:var at:name="vs" />someMethod() + +<at:var at:name="vs1" />FOO_PROPERTY +<at:var at:name="vs1" />someMethod() + +<at:var at:name="vs2" />BAR_PROPERTY +<at:var at:name="vs2" />someOtherMethod() +``` + +"vs" stands for "value stack". The important thing to note here is that if the class name you specify is just "vs", +the class for the object on the top of the stack is used. If you specify a number after the "vs" string, an object's +class deeper in the stack is used instead. + +### Differences from the WebWork 1.x EL + +Besides the examples and descriptions given above, there are a few major changes in the EL since WebWork 1.x. The biggest +one is that properties are no longer accessed with a forward slash (/) but with a dot (.). Also, rather than using ".." +to traverse down the stack, we now use "[n]" where n is some positive number. Lastly, in WebWork 1.x one could access +special named objects (the request scope attributes to be exact) by using "@foo", but now special variables are accessed +using "#foo". However, it is important to note that "#foo" does NOT access the request attributes. Because XWork is not +built only for the web, there is no concept of "request attributes", and thus "#foo" is merely a request to another +object in the OgnlContext other than the root. + +|Old Expression|New Expression| +|--------------|--------------| +|foo/blah|foo.blah| +|foo/someMethod()|foo.someMethod()| +|../bar/blah|[1].bar.blah| +|@baz|not directly supported, but #baz is similar| +|.|'top' or [0]| + +### Struts 2 Named Objects + +Struts 2 places request parameters and request, session, and application attributes on the OGNL stack. They may be accessed +as shown below. + +|name|value| +|----|-----| +|#action['foo'] or #action.foo|current action getter (getFoo())| +|#parameters['foo'] or #parameters.foo|request parameter ['foo'] (request.getParameter())| +|#request['foo'] or #request.foo|request attribute ['foo'] (request.getAttribute())| +|#session['foo'] or #session.foo|session attribute 'foo'| +|#application['foo'] or #application.foo|ServletContext attributes 'foo'| +|#attr['foo'] or #attr.foo|Access to PageContext if available, otherwise searches request/session/application respectively| http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ognl-expression-compilation.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ognl-expression-compilation.md b/source/tag-developers/ognl-expression-compilation.md new file mode 100644 index 0000000..caf72bc --- /dev/null +++ b/source/tag-developers/ognl-expression-compilation.md @@ -0,0 +1,338 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# OGNL Expression Compilation + +This document is meant as a development/integration guide for anyone wanting to use the new OGNL 2.7 features for doing +byte code runtime enhancements on OGNL statements. This is _not_ meant for general user reference as it covers what +are mostly internal API development concerns. + +## Basic Usage + +By default there isn't much you have to do to use the new compilation abilities in OGNL. Following is an example of compiling +a simple property expression and invoking it. + +```java +SimpleObject root = new SimpleObject(); +OgnlContext context = (OgnlContext) Ognl.createDefaultContext(null); + +Node node = (Node) Ognl.compileExpression(context, root, "user.name"); +String userName = node.getAccessor().get(context, root); +``` + +You'll notice that this example references the new `ognl.enhance.ExpressionAccessor` class. This is the interface used +to create the enhanced expression versions of any given expression via javassist and should be used to set/get expression +values from the compiled versions of the code. Although the old `Ognl.getValue(node, context, root)` method of getting/setting +values will correctly detect a compiled expression and use the accessor directly as well, it's not going to be as fast +as you doing it directly. + +## ognl.enhance.OgnlExpressionCompiler + +The core class involved in doing the management of these expression compilations by default is `ognl.enhance.ExpressionCompiler`, +which implements `ognl.enhance.OgnlExpressionCompiler`. Although you can in theory use this default implementation it +is not recommended for more robust integration points - such as being incorporated within a web framework. The majority +of examples here are going to be based around the strategy that Tapestry has used to integrate these new features. + +### Tapestry OGNL Integration + +There are only small handful of classes/services involved in the Tapestry implementation of these features, so hopefully +using them as a reference will help anyone trying to get started with this: + +- [org.apache.tapestry.services.impl.HiveMindExpressionCompiler](http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/java/org/apache/tapestry/services/impl/HiveMindExpressionCompiler.java?view=markup) + The Tapestry implementation of `ognl.enhance.OgnlExpressionCompiler` - which is a subclass + of the `ognl.enhance.ExpressionCompiler` default implementation. +_ [org.apache.tapestry.services.impl.ExpressionEvaluatorImpl](http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/java/org/apache/tapestry/services/impl/ExpressionEvaluatorImpl.java?view=markup) + Main service point involved in compiling/evaluating OGNL expressions. This is the core service that the rest of Tapestry + uses when dealing with OGNL expressions. +- [org.apache.tapestry.services.impl.ExpressionCacheImpl](http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/java/org/apache/tapestry/services/impl/ExpressionCacheImpl.java?view=markup) + Service responsible for caching OGNL statements where appropriate. +- [org.apache.tapestry.binding.ExpressionBinding](http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/java/org/apache/tapestry/binding/ExpressionBinding.java?view=markup) + Wrapper class which represents a single OGNL binding expression within Tapestry templates/annotations/html/etc. + Anything formally specified in an html attribute for components in Tapestry is represented by a specific type of `IBinding`, + `ExpressionBinding` represents the type of bindings for OGNL expressions. +- [org.apache.tapestry.bean.BeanProviderPropertyAccessor](http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/java/org/apache/tapestry/bean/BeanProviderPropertyAccessor.java?view=markup) + One of the custom `PropertyAccessor` classes Tapestry registers with OGNL. This will be a good reference for the new + source code generation methods you will need to implement for your `PropertyAccessor` classes if you want to compile + expressions. + +### ExpressionEvaluator + +If you look at the `ExpressionEvaluator` source you'll see a block of initialization where the `HiveMindExpressionCompiler` +and `OgnlContext` pools are setup: + +```java +OgnlRuntime.setCompiler(new HiveMindExpressionCompiler(_classFactory)); + +_contextPool = new GenericObjectPool(new PoolableOgnlContextFactory(_ognlResolver, _typeConverter)); + +_contextPool.setMaxActive(-1); +_contextPool.setMaxIdle(-1); +_contextPool.setMinEvictableIdleTimeMillis(POOL_MIN_IDLE_TIME); +_contextPool.setTimeBetweenEvictionRunsMillis(POOL_SLEEP_TIME); +``` + +Some things like null handlers/property accessor configuration has been left out but you should have enough there to get +a good idea of what is going on. Because creating new OgnlContext objects for every expression evaluation can be needlessly +expensive Tapestry uses the Apache commons-pool library to manage pooling of these instances. It is recommended that +you do the same where you can. You will also notice in other portions of the source some new method calls made on +`OgnlRuntime`: + +```java +OgnlRuntime.clearCache(); +Introspector.flushCaches(); +``` + +The OgnlRuntime class stores static `Map`-like instances of reflection meta cache information for all objects evaluated +in OGNL expressions. The new `clearCache` method clears these caches out as the memory footprint can get quite large +after a while. How often/when to call this will largely depend on how your framework works - just keep in mind that +calling it too often will have a big impact on runtime performance of your app if you are doing normal application +development sort of things with it. + +### HiveMindExpressionCompiler + +Perhaps the most important class to examine is Tapestrys implementation of `OgnlExpressionCompiler`. This class still +extends the default `ExpressionCompiler` provided by OGNL - but does a few more things that can't be made generic enough +to live in the default implementation. + +One of these important differences is how Javassist is used to compile the expressions and the ClassLoader/ClassResolver +it uses. Because these expressions are being compiled against what are already Javassist enhanced Tapestry component +class instances this implementation needed to re-use existing hivemind Javassist services so that these enhanced classes +could be correctly resolved while OGNL is evaluating them. + +If you don't have a need to provide this kind of classloading functionality you will probably still need to modify +at least how the javassist `ClassPool` is being managed in your own implementations. The internal functionality of that +library is such that the memory consumption of the pool is very large and will get unwieldy especially in development +of web apps. Tapestry has a special state that users are used to which is known as "disable caching" - more or less +meaning that javassist enhancements happen for every request instead of only once. + +Another very important piece of logic that this class handles is the generation of "fail safe" getters/setters when +expressions just can't be compiled because of either internal errors or a specific syntax type used isn't yet able to support +javassist compilations. This logic can sometimes get tricky in that in many instances OGNL expressions won't be compilable +because the full expression contains a null reference. The basic idea is that the compiler keeps trying to compile these +kinds of expressions until it either gets a fatal exception thrown or the full expression is able to be resolved. +For example, the following expression would throw a `UnsupportedCompilationException` if the "user" object returned +was null - resulting in no direct compilation being done at all: + +``` +"user.firstName" +``` + +That doesn't mean that the user object might not be resolvable the next time this expression is invoked though, +so the next time the compiler tries it may succeed in which case the whole expression is enhanced and the new `ExpressionAccessor` +instance is attached to the root `Node` object by calling `SimpleNode.setAccessor(newInstance)`. + +The fail safe logic is there for expressions that are likely to never be resolvable for one reason or another. In these +instances a `ExpressionAccessor` class instance is still created - with the major difference being that instead of pure +java object expressions being compiled the get/set methods on the instance just call back to the standard OGNL +getValue/setValue methods: + +```java +public Object get(OgnlContext context, Object root) +{ + return _node.getValue($1, $2); +} +``` + +The `$1, $2` references are Javassist constructs which allow you to specify the first and second argument passed in +to the calling method. + +### ExpressionBinding + +As stated previously, this class represents a single OGNL expression in Tapestry when used directly in html templates +- such as: + +```html +<div jwcid="@Input" value="ognl:user.firstName" /> +``` + +What you will want to examine in this class is how it deals with incrementally attempting expression evaluations using +the local members `_writeFailed, _accessor`. Looking through the source of this implementation will probably be the best +documentation available - but keep in mind that in many instances this object also has to deal with the possibility +that a write statement may never happen. + +### BeanProviderPropertyAccessor / Custom PropertyAccessor implementations + +Besides the `OgnlExpressionCompiler` logic this will probably be the second most impactual area people will have to deal +with in terms of having to write new code. In this specific instance there are three new `PropertyAccessor` methods +you must implement in order to compile your expressions: + +```java +public Class getPropertyClass(OgnlContext context, Object target, Object name) +{ + IBeanProvider provider = (IBeanProvider)target; + String beanName = ((String)name).replaceAll("\"", ""); + + if (provider.canProvideBean(beanName)) + return provider.getBean(beanName).getClass(); + + return super.getPropertyClass(context, target, name); +} + +public String getSourceAccessor(OgnlContext context, Object target, Object name) +{ + IBeanProvider provider = (IBeanProvider)target; + String beanName = ((String)name).replaceAll("\"", ""); + + if (provider.canProvideBean(beanName)) { + + Class type = OgnlRuntime.getCompiler().getInterfaceClass(provider.getBean(beanName).getClass()); + + ExpressionCompiler.addCastString(context, "((" + type.getName() + ")"); + + context.setCurrentAccessor(IBeanProvider.class); + context.setCurrentType(type); + + return ".getBean(" + name + "))"; + } + + return super.getSourceAccessor(context, target, name); +} + +public String getSourceSetter(OgnlContext context, Object target, Object name) +{ + throw new UnsupportedCompilationException("Can't set beans on IBeanProvider."); +} +``` + +Although this example may not provide with all of the possible use cases you may need to learn to properly implement +these methods in your own `PropertyAccessor` implementations - the built in OGNL versions like `ObjectPropertyAccessor`, +`MapPropertyAccessor`, `ListPropertyAccessor`, etc should provide more than enough data to work from. + +The most important part of the above logic you will want to look at is in how the new `OgnlContext` methods for setting +object/accessor types are being set: + +```java +context.setCurrentAccessor(IBeanProvider.class); +context.setCurrentType(type); +``` + +This meta information is used by the `OgnlExpressionCompiler` to correctly cast your specific expression object types +during compilation. This process of casting/converting in to and out of native types is the most complicated part of this +new logic and also the source of the greatest number of bugs reported in the OGNL jira. + +In this property accessor example the goal is to turn general statements like `beans.emailValidator` in to their pure +source form - which would look something like this when all is said and done: + +```java +((ValidatingBean)beanProvider.getBean("emailValidator")) +``` + +There is also the ever important cast handling which you must do: + +```java +Class type = OgnlRuntime.getCompiler().getInterfaceClass(provider.getBean(beanName).getClass()); + +ExpressionCompiler.addCastString(context, "((" + type.getName() + ")"); +``` + +In this example the `PropertyAccessor` is trying to determine the class type and manually adding the cast string for +the specific type to the overall statement by invoking the utility method `addCastString(OgnlContext, String)` on +`ExpressionCompiler`. In many instances of expression compilation you might also be dealing with unknown method calls, +where the more preferred way to do this kind of logic would be something like this: (taken from the OGNL +`ObjectPropertyAccessor` implementation) + +```java +Method m = ...(various reflection gynamistics used to find a java.reflect.Method instance) + +context.setCurrentType(m.getReturnType()); +context.setCurrentAccessor(OgnlRuntime.getCompiler().getSuperOrInterfaceClass(m, m.getDeclaringClass())); +``` + +When dealing with method calls it is very important that you do this specific kind of type setting on the `OgnlContext` +class so that the casting done on your statements (which happens outside of the `ObjectPropertyAccessor` in this instance) +can be done on the highest level interface defining that method. This becomes important when you are dealing with expressions +that you would like to re-use against different object instances. For example, suppose we had an ognl expression like +this (for Tapestry): + +``` +user.firstName +``` + +and the object it was compiled against was an instance of something looking like this: + +```java +public abstract LoginPage extends BasePage implements UserPermissions { + + public abstract User getUser(); + +} + +.. +/** + * Interface for any page/component that holds references to the current system + * User. + */ +public interface UserPermissions { + User getUser(); +} +``` + +`BasePage` is a Tapestry specific class which is unimportant in this example. What is important to know is that if we +had done something like this in the previous context setting example: + +```java +context.setCurrentType(m.getReturnType()); +context.setCurrentAccessor(m.getDeclaringClass()); +``` + +It would have resulted in a compiled expression of: + +```java +public void get(OgnlContext context, Object root) { + return ((LoginPage)root).getUser(); +} +``` + +This is undesirable in situations where you would like to re-use OGNL expressions across many different class instances +(which is what Tapestry does via the `ExpressionCacheImpl` listed above). The better/more re-usable compiled version +should really look like: + +```java +public void get(OgnlContext context, Object root) { + return ((UserPermissions)root).getUser(); +} +``` + +These are the more delicate parts of the compiler API that the majority of people will need to worry about during any +integration efforts. + +## Known Issues / Limitations + +### Compiler Errors + +Despite the substantially large number of unit tests set up and thorough usage of many different +types of expressions Tapestry users are still currently running in to fatal/non caught runtime errors when some of their +OGNL expressions are compiled. In some instances these errors are blockers and they must either wait for someone +to fix the bug (after being posted to [http://jira.opensymphony.com/browse/OGNL](http://jira.opensymphony.com/browse/OGNL) +correctly) or re-work their expression to get around the error. I (jesse) generally try to fix these reported errors +within a day or two (or sooner) when I can and immediately deploy the fixes to the OGNL snapshot maven2 repository. +This doesn't mean that the vast majority of expressions won't compile fine, but it is something to keep in mind when +you decide how to integrate the compiler logic in to your own framework. + +### Compile vs. normal expression evaluation + +The current Tapestry implementation compiles OGNL expressions in both development AND production modes. This has +the undesirable side effect of causing needless multiple method invocations on objects when compiling as well as the general +overhead of performing compilations at all when people are just developing applications and not serving them in production +environments. It is hoped that when OGNL becomes final this special development mode can go back to using normal OGNL +expression evaluation during development and save compilation for production environments, but until then we've been +worried about giving people false positives when testing their applications. Meaning - something may evaluate just fine +when using + +```java +Ognl.getValue(OgnlContext, Object root, String expression +``` + +but fail completely when they deploy their app to production and the compiler kicks in. If you framework doesn't handle +separate modes or have this kind of state set up it is something to keep in mind. The number of JIRA issues reported +has gone way down since this all started but they do still trickle in which is enough to know that things aren't yet 100% +reliable. I'm sure the plethora of Struts/WebWork/etc users available should be enough to iron out any remaining issues +found but it's something to keep in mind. + +### Snapshot Repository + +The current maven2 location of the OGNL development/snapshot release are all made to [http://opencomponentry.com/repository/m2-snapshot-repo/](http://opencomponentry.com/repository/m2-snapshot-repo/), +while releases go out to ibiblio as per normal. If someone has a better place for these release to be made please feel free to contact jesse ( jkuhnert at gmail.com) with accessor information / instructions. + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ognl.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ognl.md b/source/tag-developers/ognl.md new file mode 100644 index 0000000..0fd1136 --- /dev/null +++ b/source/tag-developers/ognl.md @@ -0,0 +1,143 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# OGNL +{:.no_toc} + +* Will be replaced with the ToC, excluding a header +{:toc} + +OGNL is the Object Graph Navigation Language (see [http://commons.apache.org/proper/commons-ognl/] for the full +documentation of OGNL). Here, we will cover a few examples of OGNL features that co-exist with the framework. To review +basic concepts, refer to [OGNL Basics](ognl-basics.html). + +The framework uses a standard naming context to evaluate OGNL expressions. The top level object dealing with OGNL is +a Map (usually referred as a context map or context). OGNL has a notion of there being a root (or default) object within +the context. In expression, the properties of the root object can be referenced without any special "marker" notion. +References to other objects are marked with a pound sign (`#`). + +The framework sets the OGNL context to be our ActionContext, and the value stack to be the OGNL root object. +(The value stack is a set of several objects, but to OGNL it appears to be a single object.) Along with the value stack, +the framework places other objects in the ActionContext, including Maps representing the application, session, +and request contexts. These objects coexist in the ActionContext, alongside the value stack (our OGNL root). + +``` + | + |--application + | + |--session + context map---| + |--value stack(root) + | + |--action (the current action) + | + |--request + | + |--parameters + | + |--attr (searches page, request, session, then application scopes) + | +``` + +The Action instance is always pushed onto the value stack. Because the Action is on the stack, and the stack is +the OGNL root, references to Action properties can omit the `#` marker. But, to access other objects in the ActionContext, +we must use the `#` notation so OGNL knows not to look in the root object, but for some other object in the ActionContext. + +**Referencing an Action property** + +```jsp +<s:property value="postalCode"/> +``` + +Other (non-root) objects in the ActionContext can be rendered use the `#` notation. + +```jsp +<s:property value="#session.mySessionPropKey"/> or +<s:property value="#session['mySessionPropKey']"/> or +<s:property value="#request['myRequestPropKey']"/> +``` + +The ActionContext is also exposed to Action classes via a static method but you **should not** use this approach. +Safer is to use one of the `*Aware` interafces. + +```java +ActionContext.getContext().getSession().put("mySessionPropKey", mySessionObject); +``` + +You can also put expression for attributes that don't support dynamic content, like below: + +```jsp +<c:set var="foo" value="bar" scope="request"/> +<s:textfield name="username" label="%{#request.foo}" /> +``` + +## Collections (Maps, Lists, Sets) + +Dealing with Collections (Maps, Lists, and Sets) in the framework comes often, so below please there are a few examples +using the select tag. The [OGNL documentation](http://commons.apache.org/proper/commons-ognl/language-guide.html#Collection_Construction) +also includes some examples. + +Syntax for list: `{e1,e2,e3}`. This idiom creates a List containing the String "name1", "name2" and "name3". It also +selects "name2" as the default value. + +```jsp +<s:select label="label" name="name" list="{'name1','name2','name3'}" value="%{'name2'}" /> +``` + +Syntax for map: `#{key1:value1,key2:value2}`. This idiom creates a map that maps the string "foo" to the string +"foovalue" and "bar" to the string "barvalue": + +```jsp +<s:select label="label" name="name" list="#{'foo':'foovalue', 'bar':'barvalue'}" /> +``` + +To determine if an element exists in a Collection, use the operations `in` and `not in`. + +```jsp +<s:if test="'foo' in {'foo','bar'}"> + muhahaha +</s:if> +<s:else> + boo +</s:else> + +<s:if test="'foo' not in {'foo','bar'}"> + muhahaha +</s:if> +<s:else> + boo +</s:else> +``` + +To select a subset of a collection (called projection), use a wildcard within the collection. + +- `?` - All elements matching the selection logic +- `^` - Only the first element matching the selection logic +- `$` - Only the last element matching the selection logic + +To obtain a subset of just male relatives from the object person: + +``` +person.relatives.{? #this.gender == 'male'} +``` + +## Lambda Expressions + +OGNL supports basic lamba expression syntax enabling you to write simple functions. +(Dedicated to all you math majors who didn't think you would ever see this one again.) + +Fibonacci: if n==0 return 0; elseif n==1 return 1; else return fib(n-2)+fib(n-1); + fib(0) = 0 + fib(1) = 1 + fib(11) = 89 + +**How the expression works** + +> The lambda expression is everything inside the square brackets. The `#this` variable holds the argument to the expression, +> which in the following example is the number 11 (the code after the square-bracketed lamba expression, `#fib(11)`). + +```jsp +<s:property value="#fib =:[#this==0 ? 0 : #this==1 ? 1 : #fib(#this-2)+#fib(#this-1)], #fib(11)" /> +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/param-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/param-tag.md b/source/tag-developers/param-tag.md new file mode 100644 index 0000000..f103259 --- /dev/null +++ b/source/tag-developers/param-tag.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# param + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Param} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/param.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.Param} +~~~~~~~ + + +~~~~~~~ +{snippet:id=exampledescription|javadoc=true|url=org.apache.struts2.components.Param} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/property-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/property-tag.md b/source/tag-developers/property-tag.md new file mode 100644 index 0000000..709266a --- /dev/null +++ b/source/tag-developers/property-tag.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# property + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Property} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/property.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.Property} +~~~~~~~ + + +~~~~~~~ +{snippet:id=exampledescription|lang=none|javadoc=true|url=org.apache.struts2.components.Property} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/push-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/push-tag.md b/source/tag-developers/push-tag.md new file mode 100644 index 0000000..f94c1b5 --- /dev/null +++ b/source/tag-developers/push-tag.md @@ -0,0 +1,70 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# push + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/push.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example1|lang=xml|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example1description|lang=none|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example2|lang=xml|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example2description|lang=none|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example3|lang=xml|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example3description|lang=none|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example4|lang=xml|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example4description|lang=none|javadoc=true|url=org.apache.struts2.components.Push} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/selecting-template-directory.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/selecting-template-directory.md b/source/tag-developers/selecting-template-directory.md new file mode 100644 index 0000000..057867a --- /dev/null +++ b/source/tag-developers/selecting-template-directory.md @@ -0,0 +1,51 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Selecting Template Directory + +Template directory can be selected using several different rules, in this order: + +1. The + +~~~~~~~ +templateDir +~~~~~~~ + attribute on the specific tag + +2. The page-scoped attribute named + +~~~~~~~ +templateDir +~~~~~~~ + +3. The request-scoped attribute named + +~~~~~~~ +templateDir +~~~~~~~ + +4. The session-scoped attribute named + +~~~~~~~ +templateDir +~~~~~~~ + +5. The application-scoped attribute named + +~~~~~~~ +templateDir +~~~~~~~ + +6. The + +~~~~~~~ +struts.ui.templateDir +~~~~~~~ + property in _struts.properties_ (defaults to _template_ ) + +__Tips__ + ++ To change the template directory for the entire application, modify the _struts.properties_ . + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/selecting-themes.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/selecting-themes.md b/source/tag-developers/selecting-themes.md new file mode 100644 index 0000000..4a0f3ae --- /dev/null +++ b/source/tag-developers/selecting-themes.md @@ -0,0 +1,48 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Selecting Themes + +Themes can be selected using several different rules, in this order: + +1. The + +~~~~~~~ +theme +~~~~~~~ + attribute on the specific tag + +2. The + +~~~~~~~ +theme +~~~~~~~ + attribute on a tag's surrounding [form](#PAGE_14201) tag + +3. The page-scoped attribute named "theme" + +4. The request-scoped attribute named "theme" + +5. The session-scoped attribute named "theme" + +6. The application-scoped attribute named "theme" + +7. The + +~~~~~~~ +struts.ui.theme +~~~~~~~ + property in _struts.properties_ (defaults to _xhtml_ ) + +See "_Can I change theme on a per-page basis_ " page for using scoped "theme" attribute. + +__Tips__ + ++ To override an entire form's theme, change the "theme" attribute of the form. (Convenient for using the [ajax theme](#PAGE_14205) for specific forms, for example.) + ++ To support user-selected themes, set the theme in the user's session. + ++ To change the theme for the entire application, modify the _struts.properties_ . + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/set-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/set-tag.md b/source/tag-developers/set-tag.md new file mode 100644 index 0000000..7c2e4b5 --- /dev/null +++ b/source/tag-developers/set-tag.md @@ -0,0 +1,35 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# set + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Set} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/set.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.Set} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/simple-theme.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/simple-theme.md b/source/tag-developers/simple-theme.md new file mode 100644 index 0000000..866e473 --- /dev/null +++ b/source/tag-developers/simple-theme.md @@ -0,0 +1,37 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# simple theme + +The simple theme renders "bare bones" HTML elements. The simple theme is most often used as a starting point for other themes. (See [Extending Themes](#PAGE_13962) for more.) + +For example, the [textfield](#PAGE_13912) tag renders the HTML + +~~~~~~~ +<input/> +~~~~~~~ + tag without a label, validation, error reporting, or any other formatting or functionality. + + + +| Both the [xhtml theme](#PAGE_13834) and [css_xhtml theme](#PAGE_14215) extend the simple theme. Look to them for examples of how to build on the foundation laid by the simple theme. + +| + +__Head Tag__ + +The simple theme [head](#PAGE_13997) template prints out a javascript include required for the [datetimepicker](#PAGE_14274) tag to render properly. + +__simple head template__ + +The [simple theme](#PAGE_14291)[head](#PAGE_13997) template only does one thing: it loads the minimal Ajax/Dojo support so that tags can import Dojo widgets easily. + +The source of the simple head.ftl template is: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/simple/head.ftl} +~~~~~~~ + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/sort-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/sort-tag.md b/source/tag-developers/sort-tag.md new file mode 100644 index 0000000..b5ffc89 --- /dev/null +++ b/source/tag-developers/sort-tag.md @@ -0,0 +1,35 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# sort + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SortIteratorTag} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|url=struts2-tags/sort.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SortIteratorTag} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/struts-tags.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/struts-tags.md b/source/tag-developers/struts-tags.md new file mode 100644 index 0000000..6741c50 --- /dev/null +++ b/source/tag-developers/struts-tags.md @@ -0,0 +1,39 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Struts Tags + +The framework provides a tag library decoupled from the view technology. In this section, we describe each tag in general +terms, such as the attributes it supports, what the behaviors are, and so forth. Most tags are supported in all template +languages (see [JSP Tags](jsp-tags.html), [Velocity Tags](velocity-tags.html), and [FreeMarker Tags](freemarker-tags.html)), +but some are currently only specific to one language. Whenever a tag doesn't have complete support for every language, +it is noted on the tag's reference page. + +The types of tags can be broken in to two types: generic and UI. Besides function and responsibility, the biggest +difference between the two is that the HTML tags support _templates_ and _themes_ . In addition to the general tag +reference, we also provide examples for using these generic tags in each of the support languages. + +> Be sure to read the [Tag Syntax](tag-syntax.html) document to learn how tag attribute syntax works. + +## FAQs + ++ _Why do the form tags put table tags around controls_ ? + ++ _How can I put a String literal in a Javascript call, for instance in an onChange attribute_ ? + ++ _Why won't the 'if' tag evaluate a one char string_ ? + ++ _Why does FreeMarker complain that there's an error in my user-directive when I used JSP Tag_ ? + ++ _Can an action tag run another method apart from the default execute method_ ? + ++ _Why didn't my action tag get executed when I have validation errors_ ? + ++ _Why are request parameters appended to our hyperlinks_ ? + +## Resources + +- [Creating a UI Component in Struts 2](http://www.vitarara.org/cms/struts_2_cookbook/creating_a_ui_component) (Mark Menard) +- [Struts 2 Tags](http://www.roseindia.net/struts/struts2/struts-2-tags.shtml) (Rose India) http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/subset-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/subset-tag.md b/source/tag-developers/subset-tag.md new file mode 100644 index 0000000..25378c0 --- /dev/null +++ b/source/tag-developers/subset-tag.md @@ -0,0 +1,55 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# subset + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SubsetIteratorTag} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/subset.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=action|lang=java|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SubsetIteratorTag} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example1|lang=xml|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SubsetIteratorTag} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example2|lang=xml|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SubsetIteratorTag} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example3|lang=xml|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SubsetIteratorTag} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example4|lang=xml|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SubsetIteratorTag} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example5|lang=xml|javadoc=true|url=org.apache.struts2.views.jsp.iterator.SubsetIteratorTag} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/tag-reference.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/tag-reference.md b/source/tag-developers/tag-reference.md new file mode 100644 index 0000000..2509e5b --- /dev/null +++ b/source/tag-developers/tag-reference.md @@ -0,0 +1,11 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Tag Reference### + +[Generic Tags](generic-tags.html) + +[UI Tags](ui-tags.html) + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/tag-syntax.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/tag-syntax.md b/source/tag-developers/tag-syntax.md new file mode 100644 index 0000000..6bd430f --- /dev/null +++ b/source/tag-developers/tag-syntax.md @@ -0,0 +1,257 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Tag Syntax + +The tags are designed to display dynamic data. To create a input field that displays the property "postalCode", we'd pass the String "postalCode" to the textfield tag. + +**Creating a dynamic input field** + + +~~~~~~~ + +<s:textfield name="postalCode"/> + +~~~~~~~ + +If there is a "postalCode" property on the value stack, its value will be set to the input field. When the field is submitted back to the framework, the value of the control will be set back to the "postalCode" property. + +Sometimes, we want to pass the dynamic data to a tag. For example, we might want to display a label with the input field, and we might want to obtain the label from the application's messages resources. Accordingly, the framework will parse expressions found in the tag attributes, so that we can merge dynamic data into the tag attributes at runtime. The expression escape sequence is "%{ ... }". Any text embedded in the escape sequence is evalulated as an expression. + +**Using an expression to set the label** + + +~~~~~~~ + +<s:textfield key="postalCode.label" name="postalCode"/> + +~~~~~~~ + +The expression language ([OGNL](#PAGE_14198)) lets us call methods and evaluate properties. The method + +~~~~~~~ +getText +~~~~~~~ + is provided by ActionSupport, which is the base class for most Actions. Since the Action is on the stack, we can call any of its methods from an expression, including + +~~~~~~~ +getText +~~~~~~~ +. + +####Non-String Attributes#### + +The HTTP protocol is text-based, but some tags have non-String attribute types, like + +~~~~~~~ +bool +~~~~~~~ + or + +~~~~~~~ +int +~~~~~~~ +. To make using non-String attributes intuitative, the framework evaulates **all** non-String attributes as an expression. In this case, you do not need to use the escape notation. (But, if you do anyway , the framework will just strip it off.) + +**Evaluating booleans** + + +~~~~~~~ + +<s:select key="state.label" name="state" multiple="true"/> + +~~~~~~~ + +Since the attribute + +~~~~~~~ +multiple +~~~~~~~ + maps to a boolean property, the framework does not interpret the value as a String. The value is evaluated as an expression and automtically converted to a boolean. + +Since it's easy to forget which attributes are String and which are non-String, you can still use the escape notation. + +**Evaluating booleans (verbose)** + + +~~~~~~~ + +<s:select key="state.label" name="state" multiple="%{true}"/> + +~~~~~~~ + +**Evaluating booleans (with property)** + + +~~~~~~~ + +<s:select key="state.label" name="state" multiple="allowMultiple"/> + +~~~~~~~ + +**Evaluating booleans (verbose with property)** + + +~~~~~~~ + +<s:select key="state.label" name="state" multiple="%{allowMultiple}"/> + +~~~~~~~ + +####value is an Object!#### + +Most often, the + +~~~~~~~ +value +~~~~~~~ + attribute is set automatically, since + +~~~~~~~ +name +~~~~~~~ + attribute usually tells the framework which property to call to set the + +~~~~~~~ +value +~~~~~~~ +. But, if there is a reason to set the + +~~~~~~~ +value +~~~~~~~ + directly, be advised that + +~~~~~~~ +value +~~~~~~~ +**is an Object****_NOT_ ****a String**. + + (!) Since + +~~~~~~~ +value +~~~~~~~ + is not a String, whatever is passed to + +~~~~~~~ +value +~~~~~~~ + is evaluated as an expression - **NOT** a String literal. + +**Probably wrong!** + + +~~~~~~~ + +<s:textfield key="state.label" name="state" value="ca"/> + +~~~~~~~ + +If a + +~~~~~~~ +textfield +~~~~~~~ + is passed the value attribute + +~~~~~~~ +"ca" +~~~~~~~ +, the framework will look for a property named + +~~~~~~~ +getCa +~~~~~~~ +. Generally, this is not what we mean. What we mean to do is pass a literal String. In the expression language, literals are placed within quotes + +**Passing a literal value the right way** + + +~~~~~~~ + +<s:textfield key="state.label" name="state" value="%{'ca'}" /> + +~~~~~~~ + +Another approach would be to use the idiom + +~~~~~~~ +value="'ca'" +~~~~~~~ +, but, in this case, using the expression notation is recommended. + +Boiled down, the tag attributes are evaluated using three rules. + +1. All _String_ attribute types are _parsed_ for the "%{ ... }" notation. + +2. All _non-String_ attribute types are **not** parsed, but evaluated directly as an expression + +3. The exception to rule #2 is that if the _non-String_ attribute uses the escape notion "%{}", the notation is ignored as redundant, and the content evaluated. + + +Please remember about _altSyntax_ option that can change when value is evaluated as an expression - _Alt Syntax_ + +| + +####Expression Language Notations#### + +|<p>Username: \${user.username}</p>| A JavaBean object in a standard context in Freemarker, Velocity, or JSTL EL (Not OGNL). | +|-----------------------------------------|------------------------------------------------------------------------------------------| +|<s:textfield name="username"/>| A username property on the Value Stack. | +|<s:url id="es" action="Hello">\ + <s:param name="request_locale">\ + es\ + </s:param>\ +</s:url>\ +<s:a href="%{es}">Espanol</s:a>| Another way to refer to a property placed on the Value Stack. | +|<s:property\ + value="#session.user.username" />| The username property of the User object in the Session context. | +|<s:select\ + label="FooBar" name="foo"\ + list="#{'username':'trillian',\ + 'username':'zaphod'}" />| A static Map, as in put("username","trillian"). | + +####Disallowed property names#### + +The following names of property are disallowed: + ++ parameters + ++ application + ++ session + ++ struts + ++ request + ++ servletRequest + ++ servletResponse + +The below code will not work: + + +~~~~~~~ + +<s:iterator value="parameters"/> + +~~~~~~~ + + +~~~~~~~ + +public class MyAction { + + private String[] parameters; + + public String[] getParameters() { + return parameters; + } + +} + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/template-loading.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/template-loading.md b/source/tag-developers/template-loading.md new file mode 100644 index 0000000..912e270 --- /dev/null +++ b/source/tag-developers/template-loading.md @@ -0,0 +1,111 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Template Loading + + +Templates are loaded first by searching the application and then by searching the classpath. If a template needs to be overridden, an edited copy can be placed in the application, so that is found first. + +**(i) One for all** + + +> + +> + +> FreeMarker is the default templating engine. The FreeMarker templates are used regardless of what format the view may use. Internally, the JSP, FTL, Velocity tags are all rendered using FreeMarker. + +> + +__Template and Themes__ + +Templates are loaded based the template directory and theme name (see [Selecting Themes](#PAGE_14016)). The template directory is defined by the + +~~~~~~~ +struts.ui.templateDir +~~~~~~~ + property in _struts.properties_ (defaults to + +~~~~~~~ +template +~~~~~~~ +). If a tag is using the + +~~~~~~~ +xhtml +~~~~~~~ + theme, the following two locations will be searched (in this order): + +|In the application|/template/xhtml/template.ftl| +|------------------|-----------------------------| +|In the classpath|/template/xhtml/template.ftl| + + (!) For performance reasons, you may want to prefer the first location, although the second one is more flexible. See _Performance Tuning_ for a discussion on this topic. + +__Overriding Templates__ + +The default templates provided in the + +~~~~~~~ +struts-core.jar +~~~~~~~ + should suit the needs of many applications. However, if a template needs to be modified, it's easy to plug in a new version. Extract the template you need to change from the + +~~~~~~~ +struts-core.jar +~~~~~~~ +, make the modifications, and save the updated copy to + +~~~~~~~ +/template/$theme/$template.ftl +~~~~~~~ +. If you are using the xhmtl theme and need to change how the select tags render, edit that template and save it to + +~~~~~~~ +/template/xhtml/select.ftl +~~~~~~~ +. + + (!) It is easier and better to edit and override an existing template than provide a new one of your own. + +__Altering Template Loading Behaviour__ + +It is possible to load template from other locations, like the file system or a URL. Loading templates from alternate locations can be useful not only for tags, but for custom results. For details, see the [FreeMarker](#PAGE_14078) documentation and consult the section on extending the FreeMarkerManager. + +__Alternative Template Engines__ + +The framework provides for template rendering engines other than FreeMarker. (Though, there is rarely a need to use another system!) + +**(!) Don't try this at home!** + + +> + +> + +> Alternative template engines are best left to advanced users with special needs! + +> + +The framework supports three template engines, which can be controlled by the + +~~~~~~~ +struts.ui.templateSuffix +~~~~~~~ + in _struts.properties_ . + +|ftl (default)|[FreeMarker](#PAGE_14078)-based template engine| +|-------------|------------------------------------------------| +|vm|[Velocity](#PAGE_13894)-based template engine| +|jsp|[JSP](#PAGE_14141)-based template engine| + +The only set of templates and themes provided in the distribution is for FreeMarker. In order to use another template engine, you must provide your own template and theme for that engine. + + + +| Don't feel that you need to rewrite the templates to match your view format. If you need to customize the template, try copying and modifying the FreeMarker template first. Most changes should be obvious. + +| + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/text-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/text-tag.md b/source/tag-developers/text-tag.md new file mode 100644 index 0000000..eb3a4e4 --- /dev/null +++ b/source/tag-developers/text-tag.md @@ -0,0 +1,85 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# text + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.Text} +~~~~~~~ + +For more details on using resource bundles with Struts 2 read the _localization guide_ . + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/text.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=exdescription|lang=none|javadoc=true|url=org.apache.struts2.components.Text} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.Text} +~~~~~~~ + +Other example + + +~~~~~~~ + +<s:text name="format.money"><s:param name="value" value="myMoneyValue"/></s:text> + +~~~~~~~ + +where the following is in a regular (possibly locale-specific) properties file: + + +~~~~~~~ + +format.money={0,number,currency} + +~~~~~~~ + +For more about formatting text, see + +1. [http://java.sun.com/j2se/1.4.2/docs/api/java/text/MessageFormat.html](http://java.sun.com/j2se/1.4.2/docs/api/java/text/MessageFormat.html) + +2. [http://java.sun.com/docs/books/tutorial/i18n/format/decimalFormat.html](http://java.sun.com/docs/books/tutorial/i18n/format/decimalFormat.html) + +__If you wish to use i18n in your tag attributes__ + +This will **not** work: + + +~~~~~~~ + +<s:textfield name="lastName" label="<s:text name="person.lastName"/>" ../> + +~~~~~~~ + +Instead, you should use the getText() method that you inherit when your Action extends XWork's ActionSupport: + + +~~~~~~~ + +<s:textfield name="lastName" label="getText('person.lastName')" ../> + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/themes-and-templates.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/themes-and-templates.md b/source/tag-developers/themes-and-templates.md new file mode 100644 index 0000000..472fca0 --- /dev/null +++ b/source/tag-developers/themes-and-templates.md @@ -0,0 +1,33 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Themes and Templates + +The notions of "themes" and "templates" are at the core of the HTML [Struts Tags](struts-tags.html) provided by the framework. + +## Definitions + +| tag | A small piece of code executed from within [JSP](jsp.html), [FreeMarker](freemarker.html), or [Velocity](velocity.html). | +|-----|------------------------------------------------------------------------------------------------------------------------| +| template | A bit of code, usually written in [FreeMarker](freemarker.html), that can be rendered by certain tags (HTML tags) | +| theme | A collection of _templates_ packaged together to provide common functionality | + +> See [Struts Tags](struts-tags.html) for more about the HTML and other tags provided by the framework. + +## Template Basics + +|[Template Loading](template-loading.html)| How templates are loaded | +|-------------------------------|--------------------------| +|[Selecting Template Directory](selecting-template-directory.html)| How the template directories are loaded | +|[Selecting Themes](selecting-themes.html)| How you can pick a theme when writing your results | +|[Extending Themes](extending-themes.html)| How to create your own themes based on existing themes | + +## More About Themes + +|[simple theme](simple-theme.html)| A minimal theme with no "bells and whistles" | +|---------------------------|----------------------------------------------| +|[xhtml theme](xhtml-theme.html)| The default theme that uses common HTML practices | +|[css_xhtml theme](css-xhtml-theme.html)| The [xhtml theme](xhtml-theme.html) re-implemented using strictly CSS for layout | +|[ajax theme](ajax-theme.html)| A theme based on the [xhtml theme](xhtml-theme.html) that provides advanced AJAX features | http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ui-tag-reference.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ui-tag-reference.md b/source/tag-developers/ui-tag-reference.md new file mode 100644 index 0000000..766839a --- /dev/null +++ b/source/tag-developers/ui-tag-reference.md @@ -0,0 +1,58 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# UI Tag Reference + +Struts UI Tags display data in rich and reusable HTML. + +## Form Tags + +- [checkbox](checkbox-tag.html) +- [checkboxlist](checkboxlist-tag.html) +- [combobox](combobox-tag.html) +- [datetextfield](datetextfield-tag.html) +- [doubleselect](doubleselect-tag.html) +- [head](head-tag.html) +- [file](file-tag.html) +- [form](form-tag.html) +- [hidden](hidden-tag.html) +- [inputtransferselect](inputtransferselect-tag.html) +- [label](label-tag.html) +- [optiontransferselect](optiontransferselect-tag.html) +- [optgroup](optgroup-tag.html) +- [password](password-tag.html) +- [radio](radio-tag.html) +- [reset](reset-tag.html) +- [select](select-tag.html) +- [submit](submit-tag.html) +- [textarea](textarea-tag.html) +- [textfield](textfield-tag.html) +- [token](token-tag.html) +- [updownselect](updownselect-tag.html) + +## Non-Form UI Tags + +- [actionerror](actionerror-tag.html) +- [actionmessage](actionmessage-tag.html) +- [component](component-tag.html) +- [div](div-tag.html) +- [fielderror](fielderror-tag.html) + +## Ajax Tags + +- [a](a-tag.html) +- [autocompleter](autocompleter-tag.html) +- [bind](bind-tag.html) +- [datetimepicker](datetimepicker-tag.html) +- [div](div-tag.html) +- [head](head-tag.html) +- [submit](submit-tag.html) +- [tabbedPanel](tabbed-tag.html) +- [textarea](textarea-tag.html) +- [tree](tree-tag.html) +- [treenode](treenode-tag.html) + +> For detailed descriptions of each tag, including usage examples, see the [Tag Reference](tag-reference.html) + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/ui-tags.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/ui-tags.md b/source/tag-developers/ui-tags.md new file mode 100644 index 0000000..c33c4ba --- /dev/null +++ b/source/tag-developers/ui-tags.md @@ -0,0 +1,35 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# UI Tags + +Unlike _generic tags_, UI tags do not provide much control structure or logic. Rather, they are focused on using data, +either from your action/value stack or from the Data Tags, and displaying data in rich and reusable HTML. All UI tags +are driven by _templates_ and _themes_ . While generic tags simply output some content directly from the tag (if there +is any content to output), the UI tags defer to a template, often grouped together as a theme, to do the actual rendering. + +Template support allows UI tags to build a rich set of reusable HTML components that can be customized to fit exact +requirements. For details, see [Themes and Templates](themes-and-templates.html). + +|[Themes and Templates](themes-and-templates.html)| A must-read explanation of how themes and templates are used when rendering UI tags. | +|-----------------------------------|----------------------------------------------------------------------------------------| +|[Form Tags](form-tags.html)| provide all form-related UI output, such as _form_ , _textfield_ , and _select_ . | +| Non Form Tags | provide all non-form-related UI output, such as _a_ , _div_ , and _tabbedPanel_ . | + +## Language Specific Tag Support + +The framework strives to support multiple development environments. The framework does not impose a single template language. +Almost any common language can be used, and there are hooks for new languages. By default, almost every single tag is +supported in JSP, Velocity, and FreeMarker. In each of these sections, you'll find examples and techniques for applying +the generic tag reference toward your specific language or template choice. + +- [JSP Tags](jsp-tags.html) +- [Velocity Tags](velocity-tags.html) +- [FreeMarker Tags](freemarker-tags.html) + +Please make sure you have read the [Tag Syntax](tag-syntax.html) document and understand how tag attribute syntax works. + +Within the form tags, there are two classes of tags: the form tag itself, and all other tags, which make up the individual +form elements. The behavior of the form tag is different than the elements enclosed within it. http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/url-tag.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/url-tag.md b/source/tag-developers/url-tag.md new file mode 100644 index 0000000..1590482 --- /dev/null +++ b/source/tag-developers/url-tag.md @@ -0,0 +1,68 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# url + + +Please make sure you have read the [Tag Syntax](#PAGE_13927) document and understand how tag attribute syntax works. + +| + + +The id attribute is deprecated in Struts 2.1.x, and has been replaced by the var attribute. + +| + +__Description__ + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.components.URL} +~~~~~~~ + +__Setting a default value for includeParams__ + +The property _struts.url.includeParams_ can be used to set the default value of the _includeParams_ attribute. + +**Setting the default value of includeParams** + + +~~~~~~~ + +<struts> + ... + <constant name="struts.url.includeParams" value="none" /> + ... +</struts> + +~~~~~~~ + +See _Constant Configuration_ for further information. + + +> + +> + +> As of Struts 2.1.3 the includeParams constant defaults to "none". + +> + +__Parameters__ + + + +~~~~~~~ +{snippet:id=tagattributes|javadoc=false|url=struts2-tags/url.html} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.components.URL} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/velocity-tags.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/velocity-tags.md b/source/tag-developers/velocity-tags.md new file mode 100644 index 0000000..3a94990 --- /dev/null +++ b/source/tag-developers/velocity-tags.md @@ -0,0 +1,43 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Velocity Tags + +Velocity tags are extensions of the generic [Struts Tags](#PAGE_14248) provided by the framework. You can get jump right in just by knowing the structure in which the tags can be accessed: **#s\*****tag** **\*(...) ... #end**, where **tag** is any of the [Struts Tags](#PAGE_14248) supported by the framework. + +For example, in JSP you might create a form using Struts tags. + +**JSP Form** + + +~~~~~~~ + +<s:form action="updatePerson"> + <s:textfield label="First name" name="firstName"/> + <s:submit value="Update"/> +</s:form> + +~~~~~~~ + +In Velocity, the same form can also be built using macros. + +**VM Form** + + +~~~~~~~ + +#sform ("action=updatePerson") + #stextfield ("label=First name" "name=firstName") + #ssubmit ("value=Update") +#end + +~~~~~~~ + +####Block and Inline Tags#### + +Some VM tags require an #end statement while others do not. The inconsistency arises from a limitation in Velocity where tags must declare if they are a _block_ or _inline_ tag up front. As such, by default all tags are _inline_ except for a few key ones, such as the [form](#PAGE_14201) tag. + +####Back To:#### + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/velocity.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/velocity.md b/source/tag-developers/velocity.md new file mode 100644 index 0000000..26798b6 --- /dev/null +++ b/source/tag-developers/velocity.md @@ -0,0 +1,121 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# Velocity + +Velocity is a templating language for Java. + +For more information on Velocity itself, please visit the [Velocity website](http://velocity.apache.org/)^[http://velocity.apache.org/]. + + +> + +> + +> Velocity is similar to [FreeMarker](#PAGE_14078), as both are template languages that can be used outside of a Servlet container. The framework uses FreeMarker internally since it has better error reporting. Developers may also like that FreeMarker supports JSP taglibs. However, both are good alternatives to JSP. + +> + +####Getting Started#### + +Getting started with Velocity is as simple as ensuring all the dependencies are included in your project's classpath. Other than that, _struts-default.xml_ already configures the _Velocity Result_ . + +**struts.xml** + + +~~~~~~~ + +<action name="test" class="com.acme.TestAction"> + <result name="success" type="velocity">test-success.vm</result> +</action> + +~~~~~~~ + +**test-success.vm** + + +~~~~~~~ + +<html> +<head> + <title>Hello</title> +</head> +<body> + +Hello, ${name} + +</body> +</html> + +~~~~~~~ + +Where + +~~~~~~~ +name +~~~~~~~ + is a property on the Action class. That's it! + +There are few more details of interest, such as how templates are loaded and variables are resolved. + +####Template Loading#### + +The framework looks for Velocity templates in two locations (in this order): + +1. Web application + +2. Class path + +The ordering is designed so that a default set of templates can be placed in a JAR (perhaps shared between applications). If a template needs to be overridden, a different version can be placed in the web application. + + + +| Unlike JSPs, templates can be loaded from a JAR. Templates are a great way to support "plugins", since the entire module can be delivered in a single JAR, and the views easily customized by the host application. + +| + +####Variable Resolution#### + +In Velocity, there are three sources for variables, searched in a specific order. + +1. The value stack + +2. The action context + +3. Built-in variables + +Since the action context is resolved after the value stack, you can reference the variable without the typical preceding marker (#) that has to be used with the JSP + +~~~~~~~ +s:property +~~~~~~~ + tag. Omitting the marker can be convenient, but it can also trip you up, if used carelessly. + + +~~~~~~~ + +#surl "id=url" "value=http://www.yahoo.com"; +Click <a href="${url}">here</a>! + +~~~~~~~ + +The Stuts2-Velocity integration layer provides several implicit variables. + +| Variable | Description | +|----------|-------------| +| stack | The value stack itself, useful for calls like \${stack.findString('ognl expr')} | +| action | The action most recently executed | +| response | The HttpServletResponse | +| res | Same as response | +| request | The HttpServletRequest | +| req | Same as request | +| session | The HttpSession | +| application | The ServletContext | +| base | The request's context path | + +####Configuring Velocity#### + +You can configure Velocity by placing configuration items in _velocity.properties_ . + http://git-wip-us.apache.org/repos/asf/struts-site/blob/46a2618c/source/tag-developers/xhtml-theme.md ---------------------------------------------------------------------- diff --git a/source/tag-developers/xhtml-theme.md b/source/tag-developers/xhtml-theme.md new file mode 100644 index 0000000..fcd954e --- /dev/null +++ b/source/tag-developers/xhtml-theme.md @@ -0,0 +1,214 @@ +--- +layout: default +title: Tag Developers Guide (WIP) +--- + +# xhtml theme + +The xhtml provides all the basics that the [simple theme](#PAGE_14291) provides and adds several features. + ++ Standard two-column table layout for the HTML [Struts Tags](#PAGE_14248) ([form](#PAGE_14201), [textfield](#PAGE_13912), [select](#PAGE_14127), and so forth) + ++ Labels for each of the HTML [Struts Tags](#PAGE_14248) on the left hand side (or top, depending on the + +~~~~~~~ +labelposition +~~~~~~~ + attribute) + ++ _Validation_ and error reporting + ++ _Pure JavaScript Client Side Validation_ using 100% JavaScript on the browser + +__Wrapping the Simple Theme__ + +The xhtml theme uses the "wrapping" technique described by [Extending Themes](#PAGE_13962). Let's look at how the HTML tags are wrapped by a standard header and footer. For example, in the + +~~~~~~~ +text.ftl +~~~~~~~ + template, the + +~~~~~~~ +controlheader.ftl +~~~~~~~ + and + +~~~~~~~ +controlfooter.ftl +~~~~~~~ + templates are wrapped around the simple template. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/text.ftl} +~~~~~~~ + + (?) The + +~~~~~~~ +controlheader.ftl +~~~~~~~ + is referenced using \${parameters.theme} so that the code can be reused by the [ajax theme](#PAGE_14205). + +__XHTML Theme Header__ + +Now let's look at the + +~~~~~~~ +controlheader.ftl +~~~~~~~ + and + +~~~~~~~ +controlheader-core.ftl +~~~~~~~ +. Again, these are split up for easy re-use with the [ajax theme](#PAGE_14205)) contents: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/controlheader.ftl} +~~~~~~~ + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/controlheader-core.ftl} +~~~~~~~ + +The header used by the HTML tags in the xhtml theme is complicated. However, a close look reveals that the logic produces two behaviors: either a two-column format or a two-row format. Generally the two-column approach is what we want, so that is the default option. To use the two-row approach, change the + +~~~~~~~ +labelposition +~~~~~~~ + parameter to + +~~~~~~~ +top +~~~~~~~ +. + + + +| The fieldErrors, usually caused by _Validation_ , are printed out as a row above the HTML form element. Some people prefer that the errors display elsewhere, such as in a third column. If you wish to place these elsehwere, overriding the headers is easy, allowing you to continue to use the other features provided by this theme. See [Template Loading](#PAGE_13817) for more information on how to do this. + +| + +__XHTML Theme Footer__ + +The primary objective of + +~~~~~~~ +controlfooter.ftl +~~~~~~~ + is to close the table. But, before the table closes, the template checks for an + +~~~~~~~ +after +~~~~~~~ + parameter. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/controlfooter.ftl} +~~~~~~~ + +While "after" isn't an attribute supported by any of the [Struts Tags](#PAGE_14248), if you are using [FreeMarker Tags](#PAGE_14294), [Velocity Tags](#PAGE_13950), or the [param](#PAGE_13825) tag in any template language, you can add an + +~~~~~~~ +after +~~~~~~~ + parameter to place any content you like after the [simple theme](#PAGE_14291) template renders. The + +~~~~~~~ +after +~~~~~~~ + attribute makes it easier to fine-tune HTML forms for your specific environment. + +__Special Interest__ + +Two xhtml templates of special interest are + +~~~~~~~ +head +~~~~~~~ + and + +~~~~~~~ +form +~~~~~~~ +. + +__head template__ + +The xhtml [head](#PAGE_13997) template extends the _simple head template_ and provides an additional CSS that helps render the form elements. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/head.ftl} +~~~~~~~ + +The head template imports a style sheet. + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/styles.css} +~~~~~~~ + +__form template__ + +The xhtml form template sets up the wrapping table around all the other form elements. In addition to creating this wrapping table, the opening and closing templates also, if the + +~~~~~~~ +validate +~~~~~~~ + parameter is set to true, enable _Pure JavaScript Client Side Validation_ . + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/form.ftl} +~~~~~~~ + +The closing template, + +~~~~~~~ +form-close.ftl* +~~~~~~~ +: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/form-close.ftl} +~~~~~~~ + +__xhtml form template__ + +The xhtml form template sets up the wrapping table around all the other [xhtml theme](#PAGE_13834) form elements. In addition to creating this wrapping table, the opening and closing templates also, if the _validate_ parameter is set to true, enable _Pure JavaScript Client Side Validation_ . See the **form.ftl** contents: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/form.ftl} +~~~~~~~ + +The closing template, **form-close.ftl**: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/template/xhtml/form-close.ftl} +~~~~~~~ + +__xhtml head template__ + +The xhtml [head](#PAGE_13997) template extends the _simple head template_ and provides an additional CSS that helps render the [xhtml theme](#PAGE_13834) form elements. The contents of **head.ftl** are: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=webwork/src/java/template/xhtml/head.ftl} +~~~~~~~ + +The contents of **styles.css** are: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=webwork/src/java/template/xhtml/styles.css} +~~~~~~~ +
