From eea8ee2165d694165364692bfd1ad761bb7fc09d Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Thu, 5 Oct 2017 14:22:26 -0400 Subject: [PATCH] Migrate JSP tag library appendix reference to Javadoc. The Javadoc on tag classes now has all the information including a list of all tags at the package level, HTML tables listing tag attributes in each tag class, and class level description that is as good or in many cases better than what was in the reference. Issue: SPR-16045 --- .../web/servlet/tags/ArgumentTag.java | 24 +- .../web/servlet/tags/BindErrorsTag.java | 36 +- .../web/servlet/tags/BindTag.java | 39 +- .../web/servlet/tags/EscapeBodyTag.java | 29 +- .../web/servlet/tags/EvalTag.java | 54 +- .../web/servlet/tags/HtmlEscapeTag.java | 26 +- .../web/servlet/tags/MessageTag.java | 90 +- .../web/servlet/tags/NestedPathTag.java | 27 +- .../web/servlet/tags/ParamTag.java | 28 +- .../web/servlet/tags/ThemeTag.java | 85 +- .../web/servlet/tags/TransformTag.java | 51 +- .../web/servlet/tags/UrlTag.java | 65 +- .../web/servlet/tags/form/ButtonTag.java | 45 +- .../web/servlet/tags/form/CheckboxTag.java | 184 +- .../web/servlet/tags/form/CheckboxesTag.java | 204 +- .../web/servlet/tags/form/ErrorsTag.java | 146 +- .../web/servlet/tags/form/FormTag.java | 193 +- .../web/servlet/tags/form/HiddenInputTag.java | 39 +- .../web/servlet/tags/form/InputTag.java | 207 +- .../web/servlet/tags/form/LabelTag.java | 144 +- .../web/servlet/tags/form/OptionTag.java | 152 +- .../web/servlet/tags/form/OptionsTag.java | 158 +- .../servlet/tags/form/PasswordInputTag.java | 214 +- .../web/servlet/tags/form/RadioButtonTag.java | 181 +- .../servlet/tags/form/RadioButtonsTag.java | 205 +- .../web/servlet/tags/form/SelectTag.java | 202 +- .../web/servlet/tags/form/TextareaTag.java | 193 +- .../web/servlet/tags/form/package-info.java | 21 +- .../web/servlet/tags/package-info.java | 26 +- .../appendix/appx-spring-form-tld.adoc | 2050 ----------------- .../asciidoc/appendix/appx-spring-tld.adoc | 496 ---- src/docs/asciidoc/web/webmvc-view.adoc | 13 +- 32 files changed, 3014 insertions(+), 2613 deletions(-) delete mode 100644 src/docs/asciidoc/appendix/appx-spring-form-tld.adoc delete mode 100644 src/docs/asciidoc/appendix/appx-spring-tld.adoc diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentTag.java index 8cd0923af1..b22fb26854 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentTag.java @@ -22,11 +22,31 @@ import javax.servlet.jsp.tagext.BodyTagSupport; import org.springframework.lang.Nullable; /** - * JSP tag for collecting arguments and passing them to an {@link ArgumentAware} - * ancestor in the tag hierarchy. + * The {@code } tag is based on the JSTL {@code fmt:param} tag. + * The purpose is to support arguments inside the message and theme tags. * *

This tag must be nested under an argument aware tag. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
value

false

true

The value of the argument.

+ * * @author Nicholas Williams * @since 4.0 * @see MessageTag diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindErrorsTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindErrorsTag.java index 4526b0bca4..b170711c3e 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindErrorsTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindErrorsTag.java @@ -24,9 +24,39 @@ import org.springframework.lang.Nullable; import org.springframework.validation.Errors; /** - * JSP tag that evaluates content if there are binding errors - * for a certain bean. Exports an "errors" variable of type - * {@link org.springframework.validation.Errors} for the given bean. + * This {@code } tag provides an {@link Errors} instance in case of + * bind errors. The HTML escaping flag participates in a page-wide or + * application-wide setting (i.e. by HtmlEscapeTag or a "defaultHtmlEscape" + * context-param in web.xml). + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
htmlEscape

false

true

Set HTML escaping for this tag, as boolean value. + * Overrides the default HTML escaping setting for the current page.

name

true

true

The name of the bean in the request that needs to be inspected for errors. + * If errors are available for this bean, they will be bound under the + * 'errors' key.

* * @author Rod Johnson * @author Juergen Hoeller diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindTag.java index 91f81a845e..3d55665678 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/BindTag.java @@ -26,7 +26,7 @@ import org.springframework.validation.Errors; import org.springframework.web.servlet.support.BindStatus; /** - * Bind tag, supporting evaluation of binding errors for a certain + * The {@code } tag supports evaluation of binding errors for a certain * bean or bean property. Exposes a "status" variable of type * {@link org.springframework.web.servlet.support.BindStatus}, * to both Java expressions and JSP EL expressions. @@ -42,6 +42,43 @@ import org.springframework.web.servlet.support.BindStatus; * as the bean property that this errors object applies to. Nested tags * such as the {@link TransformTag} can access those exposed properties. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description

htmlEscape

false

true

Set HTML escaping for this tag, as boolean value. Overrides the default + * HTML escaping setting for the current page.

ignoreNestedPath

false

true

Set whether to ignore a nested path, if any. + * Default is to not ignore.

path

true

true

The path to the bean or bean property to bind status information for. + * For instance account.name, company.address.zipCode or just employee. The status + * object will exported to the page scope, specifically for this bean or bean + * property

+ * * @author Rod Johnson * @author Juergen Hoeller * @see #setPath diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EscapeBodyTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EscapeBodyTag.java index aac60380a8..0fd6044e97 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EscapeBodyTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EscapeBodyTag.java @@ -26,7 +26,7 @@ import org.springframework.util.Assert; import org.springframework.web.util.JavaScriptUtils; /** - * Custom JSP tag to escape its enclosed body content, + * The {@code } tag is used to escape its enclosed body content, * applying HTML escaping and/or JavaScript escaping. * *

Provides a "htmlEscape" property for explicitly specifying whether to @@ -37,6 +37,33 @@ import org.springframework.web.util.JavaScriptUtils; *

Provides a "javaScriptEscape" property for specifying whether to apply * JavaScript escaping. Can be combined with HTML escaping or used standalone. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
htmlEscape

false

true

Set HTML escaping for this tag, as boolean value. + * Overrides the default HTML escaping setting for the current page.

javaScriptEscape

false

true

Set JavaScript escaping for this tag, as boolean value. + * Default is false.

+ * * @author Juergen Hoeller * @since 1.1.1 * @see org.springframework.web.util.HtmlUtils diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EvalTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EvalTag.java index 4a514bbe4a..e23c61fbf4 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EvalTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/EvalTag.java @@ -39,9 +39,59 @@ import org.springframework.web.util.JavaScriptUtils; import org.springframework.web.util.TagUtils; /** - * JSP tag for evaluating expressions with the Spring Expression Language (SpEL). - * Supports the standard JSP evaluation context consisting of implicit variables and scoped attributes. + * The {@code } tag evaluates a Spring expression (SpEL) and either prints + * the result or assigns it to a variable. Supports the standard JSP evaluation + * context consisting of implicit variables and scoped attributes. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
expression

true

true

The expression to evaluate.

htmlEscape

false

true

Set HTML escaping for this tag, as a boolean value. + * Overrides the default HTML escaping setting for the current page.

javaScriptEscape

false

true

Set JavaScript escaping for this tag, as a boolean value. + * Default is false.

scope

false

true

The scope for the var. 'application', 'session', 'request' and 'page' + * scopes are supported. Defaults to page scope. This attribute has no effect + * unless the var attribute is also defined.

var

false

true

The name of the variable to export the evaluation result to. + * If not specified the evaluation result is converted to a String and written + * as output.

+ * * @author Keith Donald * @author Juergen Hoeller * @since 3.0.1 diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/HtmlEscapeTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/HtmlEscapeTag.java index 4262f865a6..8b87d294ea 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/HtmlEscapeTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/HtmlEscapeTag.java @@ -19,12 +19,34 @@ package org.springframework.web.servlet.tags; import javax.servlet.jsp.JspException; /** - * Sets default HTML escape value for the current page. The actual value - * can be overridden by escaping-aware tags. The default is "false". + * The {@code } tag sets default HTML escape value for the current + * page. The actual value can be overridden by escaping-aware tags. + * The default is "false". * *

Note: You can also set a "defaultHtmlEscape" web.xml context-param. * A page-level setting overrides a context-param. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
defaultHtmlEscape

true

true

Set the default value for HTML escaping, to be put into the current + * PageContext.

+ * * @author Juergen Hoeller * @since 04.03.2003 * @see HtmlEscapingAwareTag#setHtmlEscape diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/MessageTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/MessageTag.java index bbdbf5f69b..e63624bbf9 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/MessageTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/MessageTag.java @@ -34,8 +34,9 @@ import org.springframework.web.util.JavaScriptUtils; import org.springframework.web.util.TagUtils; /** - * Custom JSP tag to look up a message in the scope of this page. Messages are - * resolved using the ApplicationContext and thus support internationalization. + * The {@code } tag looks up a message in the scope of this page. + * Messages are resolved using the ApplicationContext and thus support + * internationalization. * *

Detects an HTML escaping setting, either on this tag instance, the page level, * or the {@code web.xml} level. Can also apply JavaScript escaping. @@ -46,6 +47,91 @@ import org.springframework.web.util.TagUtils; *

Message arguments can be specified via the {@link #setArguments(Object) arguments} * attribute or by using nested {@code } tags. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
arguments

false

true

Set optional message arguments for this tag, as a (comma-)delimited + * String (each String argument can contain JSP EL), an Object array (used as + * argument array), or a single Object (used as single argument).

argumentSeparator

false

true

The separator character to be used for splitting the arguments string + * value; defaults to a 'comma' (',').

code

false

true

The code (key) to use when looking up the message. + * If code is not provided, the text attribute will be used.

htmlEscape

false

true

Set HTML escaping for this tag, as boolean value. + * Overrides the default HTML escaping setting for the current page.

javaScriptEscape

false

true

Set JavaScript escaping for this tag, as boolean value. + * Default is false.

message

false

true

A MessageSourceResolvable argument (direct or through JSP EL). + * Fits nicely when used in conjunction with Spring’s own validation error + * classes which all implement the MessageSourceResolvable interface. + * For example, this allows you to iterate over all of the errors in a form, + * passing each error (using a runtime expression) as the value of this + * 'message' attribute, thus effecting the easy display of such error + * messages.

scope

false

true

The scope to use when exporting the result to a variable. This attribute + * is only used when var is also set. Possible values are page, request, session + * and application.

text

false

true

Default text to output when a message for the given code could not be + * found. If both text and code are not set, the tag will output null.

var

false

true

The string to use when binding the result to the page, request, session + * or application scope. If not specified, the result gets outputted to the writer + * (i.e. typically directly to the JSP).

+ * * @author Rod Johnson * @author Juergen Hoeller * @author Nicholas Williams diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/NestedPathTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/NestedPathTag.java index 28dfbf3848..8a0007e2bc 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/NestedPathTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/NestedPathTag.java @@ -25,9 +25,9 @@ import org.springframework.beans.PropertyAccessor; import org.springframework.lang.Nullable; /** - *

Nested-path tag, to support and assist with nested beans or bean properties - * in the model. Exports a "nestedPath" variable of type String in request scope, - * visible to the current page and also included pages, if any. + *

The {@code } tag supports and assists with nested beans or + * bean properties in the model. Exports a "nestedPath" variable of type String + * in request scope, visible to the current page and also included pages, if any. * *

The BindTag will auto-detect the current nested path and automatically * prepend it to its own path to form a complete path to the bean or bean property. @@ -35,7 +35,26 @@ import org.springframework.lang.Nullable; *

This tag will also prepend any existing nested path that is currently set. * Thus, you can nest multiple nested-path tags. * - *

Thanks to Seth Ladd for the suggestion and the original implementation! + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
path

true

true

Set the path that this tag should apply. E.g. 'customer' to allow bind + * paths like 'address.street' rather than 'customer.address.street'.

* * @author Juergen Hoeller * @since 1.1 diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ParamTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ParamTag.java index b8c8370675..7d7cad5601 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ParamTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ParamTag.java @@ -22,11 +22,37 @@ import javax.servlet.jsp.tagext.BodyTagSupport; import org.springframework.lang.Nullable; /** - * JSP tag for collecting name-value parameters and passing them to a + * The {@code } tag collects name-value parameters and passes them to a * {@link ParamAware} ancestor in the tag hierarchy. * *

This tag must be nested under a param aware tag. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
name

true

true

The name of the parameter.

value

false

true

The value of the parameter.

+ * * @author Scott Andrews * @author Nicholas Williams * @since 3.0 diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ThemeTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ThemeTag.java index 3ef0bb84f2..e4d3241236 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ThemeTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ThemeTag.java @@ -20,7 +20,7 @@ import org.springframework.context.MessageSource; import org.springframework.context.NoSuchMessageException; /** - * Custom tag to look up a theme message in the scope of this page. + * The {@code } tag looks up a theme message in the scope of this page. * Messages are looked up using the ApplicationContext's ThemeSource, * and thus should support internationalization. * @@ -30,9 +30,88 @@ import org.springframework.context.NoSuchMessageException; *

If "code" isn't set or cannot be resolved, "text" will be used * as default message. * - *

Message arguments can be specified via the {@link #setArguments(Object) arguments} - * attribute or by using nested {@code } tags. + *

Message arguments can be specified via the {@link #setArguments(Object) + * arguments} attribute or by using nested {@code } tags. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
arguments

false

true

Set optional message arguments for this tag, as a (comma-)delimited + * String (each String argument can contain JSP EL), an Object array (used as + * argument array), or a single Object (used as single argument).

argumentSeparator

false

true

The separator character to be used for splitting the arguments string + * value; defaults to a 'comma' (',').

code

false

true

The code (key) to use when looking up the message. If code is not + * provided, the text attribute will be used.

htmlEscape

false

true

Set HTML escaping for this tag, as boolean value. Overrides the default + * HTML escaping setting for the current page.

javaScriptEscape

false

true

Set JavaScript escaping for this tag, as boolean value. + * Default is false.

message

false

true

A MessageSourceResolvable argument (direct or through JSP EL).

scope

false

true

The scope to use when exporting the result to a variable. This attribute + * is only used when var is also set. Possible values are page, request, session + * and application.

text

false

true

Default text to output when a message for the given code could not be + * found. If both text and code are not set, the tag will output null.

var

false

true

The string to use when binding the result to the page, request, session + * or application scope. If not specified, the result gets outputted to the + * writer (i.e. typically directly to the JSP).

+ * * @author Jean-Pierre Pawlak * @author Juergen Hoeller * @see org.springframework.ui.context.Theme diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/TransformTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/TransformTag.java index 7e752f47f6..d0ec461322 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/TransformTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/TransformTag.java @@ -25,14 +25,59 @@ import org.springframework.lang.Nullable; import org.springframework.web.util.TagUtils; /** - * Tag for transforming reference data values from form controllers and - * other objects inside a {@code spring:bind} tag (or a data-bound - * form element tag from Spring's form tag library). + * The {@code } tag provides transformation for reference data values + * from controllers and other objects inside a {@code spring:bind} tag (or a + * data-bound form element tag from Spring's form tag library). * *

The BindTag has a PropertyEditor that it uses to transform properties of * a bean to a String, usable in HTML forms. This tag uses that PropertyEditor * to transform objects passed into this tag. * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Attribute Summary
AttributeRequired?Runtime Expression?Description
htmlEscape

false

true

Set HTML escaping for this tag, as boolean value. Overrides the default HTML + * escaping setting for the current page.

scope

false

true

The scope to use when exported the result to a variable. This attribute + * is only used when var is also set. Possible values are page, request, session + * and application.

value

true

true

The value to transform. This is the actual object you want to have + * transformed (for instance a Date). Using the PropertyEditor that is currently + * in use by the 'spring:bind' tag.

var

false

true

The string to use when binding the result to the page, request, session + * or application scope. If not specified, the result gets outputted to the + * writer (i.e. typically directly to the JSP).

+ * * @author Alef Arendsen * @author Juergen Hoeller * @since 20.09.2003 diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/UrlTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/UrlTag.java index 1c8f7b6bec..e3d23d7222 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/UrlTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/UrlTag.java @@ -38,8 +38,8 @@ import org.springframework.web.util.TagUtils; import org.springframework.web.util.UriUtils; /** - * JSP tag for creating URLs. Modeled after the JSTL c:url tag with backwards - * compatibility in mind. + * The {@code } tag creates URLs. Modeled after the JSTL c:url tag with + * backwards compatibility in mind. * *

Enhancements to the JSTL functionality include: *