This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/main by this push:
new 82878e354 docs: value on form tags is a String attribute; Alt Syntax
page is history (#338)
82878e354 is described below
commit 82878e354fa2cfccb27f2c1cbabaf48f39ff8f5d
Author: Lukasz Lenart <[email protected]>
AuthorDate: Wed Sep 16 08:56:28 2026 +0200
docs: value on form tags is a String attribute; Alt Syntax page is history
(#338)
* docs: value on form tags is a String attribute, not an expression
The "value is an Object!" section claimed that a textfield with
value="ca" looks up a getCa property. It does not: UIBean resolves
value through findValue(expr, String.class), which returns the literal
unless it contains the %{} notation. Only checkbox (Boolean) and file
(Object) evaluate value as an expression. The section contradicted the
three-rule summary on the same page and prompted WW-3338.
Also drops the pointer to the altSyntax option, removed in 2.6.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
* docs: rewrite the Alt Syntax page as history
The option was removed in 2.6 (WW-3877), but the page still described
it in the present tense, including a per-request useAltSyntax flag that
no longer exists. Keeps the before/after example as the explanation of
why the %{} notation exists, and notes that pre-altSyntax examples of a
bare property in a form tag's value survive in old documentation.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
---
source/tag-developers/alt-syntax.md | 46 +++++++++++++++----------------------
source/tag-developers/tag-syntax.md | 29 +++++++++++------------
2 files changed, 32 insertions(+), 43 deletions(-)
diff --git a/source/tag-developers/alt-syntax.md
b/source/tag-developers/alt-syntax.md
index f7887aafb..59d678a54 100644
--- a/source/tag-developers/alt-syntax.md
+++ b/source/tag-developers/alt-syntax.md
@@ -8,21 +8,15 @@ parent:
# Alt Syntax
-> Note: As from Struts 2.6 option to disable the AltSyntax has been removed
and now using %{...} is the only way
-> to create an expression as stated below.
+> Note: This page is history. The `%{ ... }` notation described here is the
only tag syntax since Struts 2.6, when the
+> option to disable it was removed (WW-3877). See [Tag Syntax](tag-syntax) for
how tag attributes are evaluated today.
-The _altSyntax_ is an option that can be defined in `struts.xml`. By default
it is set to true and it is **strongly**
-recommend you do not change that unless you are upgrading from WebWork 2.1.7
or previous versions.
+The _altSyntax_ was an option introduced in WebWork 2.1.4 that changed how tag
attributes are interpreted. Before it,
+every tag attribute was evaluated against the value stack as an expression, so
string literals had to be marked with
+single quotes. With the altSyntax, only expressions enclosed in `%{}` are
evaluated and everything else is taken
+literally.
-> You can also turn on the altSyntax on a per-page basis by using the _set_
tag. Simply set the name _useAltSyntax_
-> to the value _true_ . From this point on, all tags will use the altSyntax
for the rest of the request.
-
-The altSyntax changes the behavior of how tags are interpreted. Instead of
evaluating each tag parameter against
-the value stack and needing single quotes to mark string literals, only marked
expressions are evaluated.
-
-Example:
-
-the following code uses the [Tag Syntax](tag-syntax):
+The old syntax:
```jsp
<s:iterator value="cart.items">
@@ -33,8 +27,8 @@ the following code uses the [Tag Syntax](tag-syntax):
</s:iterator>
```
-this is somewhat counter intuitive to normal HTML tag behaviour, and you get
loads of single quotes. Now the same example
-in altSyntax:
+This was counter-intuitive next to normal HTML tag behaviour and produced
loads of single quotes. The same example in
+the altSyntax, which is the syntax Struts uses today:
```jsp
<s:iterator value="cart.items">
@@ -45,19 +39,15 @@ in altSyntax:
</s:iterator>
```
-Only expressions enclosed with `%{}` are evaluated. The code is shorter and
clearer, very similar to JSTL EL usage.
-Quoting problems, eg. with javascript function calls, are avoided.
-
-In order to fully understand why this option exists and what the differences
are, it is best to get a bit of history
-about WebWork.
-
-> If you are _not_ upgrading from WebWork 2.1.7 or previous versions and you
don't care about the history of WebWork's
-> evolution, you can skip this section. See the [Tag Syntax](tag-syntax)
section for more information
-> on the standard tag syntax support
-
+The code is shorter and clearer, very similar to JSTL EL usage, and quoting
problems, e.g. with JavaScript function
+calls, are avoided.
## History
-In WebWork 2.1.4, the altSyntax option was introduced. The book, WebWork in
Action, while based around WebWork 2.1.7,
-was entirely written with the assumption that the altSyntax was enabled. As of
WebWork 2.2, the altSyntax is turned
-on by default and eventually the old syntax will no longer be supported and
will be removed from the code.
+The book WebWork in Action, while based around WebWork 2.1.7, was entirely
written with the assumption that the
+altSyntax was enabled. As of WebWork 2.2 it was turned on by default, with a
`struts.xml` constant and a per-request
+`useAltSyntax` flag to switch back to the old syntax. Struts 2.6 removed both,
and with them the old syntax.
+
+Documentation written for the old syntax survives in places. If you meet an
example where a plain property name is
+passed to `value` on a form tag and expected to be evaluated, it predates the
altSyntax; today that requires
+`value="%{property}"`.
diff --git a/source/tag-developers/tag-syntax.md
b/source/tag-developers/tag-syntax.md
index 8b20ddc50..6316d4274 100644
--- a/source/tag-developers/tag-syntax.md
+++ b/source/tag-developers/tag-syntax.md
@@ -74,31 +74,32 @@ Since it's easy to forget which attributes are String and
which are non-String,
<s:select key="state.label" name="state" multiple="%{allowMultiple}"/>
```
-## value is an Object!
+## The value attribute of form tags
-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**.
+Most often, the `value` attribute is set automatically, since the `name`
attribute tells the framework which
+property to read. If there is a reason to set `value` directly, be advised
that on the form tags — `textfield`,
+`password`, `textarea`, `hidden`, `select` and the like — `value` **is a
String attribute**: it is parsed for the
+`%{ ... }` notation, and anything outside that notation is used literally.
-> NOTE: Since `value` is not a String, whatever is passed to `value` is
evaluated as an expression - **NOT** a String literal.
-
-## Probably wrong!
+## Passing a literal value
```html
<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
+The field is rendered with the literal text `ca`; the framework does **not**
look for a `getCa` property.
-## Passing a literal value the right way
+## Reading a property
```html
-<s:textfield key="state.label" name="state" value="%{'ca'}" />
+<s:textfield key="state.label" name="state" value="%{selectedState}"/>
```
-Another approach would be to use the idiom `value="'ca'"`, but, in this case,
using the expression notation is recommended.
+To read a property, wrap it in the expression notation. The same goes for
`hidden` and the other form tags.
+
+Two form tags are the exception: `checkbox` evaluates `value` as a Boolean and
`file` as an Object, so on those it
+is always an expression (rule 2 below). The generic tags — `property`, `set`,
`if`, `iterator` — take an expression
+in `value` as well.
Boiled down, the tag attributes are evaluated using three rules.
@@ -107,8 +108,6 @@ Boiled down, the tag attributes are evaluated using three
rules.
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](alt-syntax)
-
## Expression Language Notations
- A JavaBean object in a standard context in Freemarker, Velocity, or JSTL EL
(Not OGNL).
