From a77846877158077b169ecd02f28cd9523c384f6a Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Wed, 28 Oct 2015 18:31:17 +0100 Subject: [PATCH] Consistent JSP tag documentation Issue: SPR-13520 --- .../web/servlet/tags/ArgumentAware.java | 3 +- .../web/servlet/tags/ArgumentTag.java | 44 ++--- .../web/servlet/tags/ParamTag.java | 56 +++--- .../web/servlet/tags/form/FormTag.java | 28 ++- .../main/resources/META-INF/spring-form.tld | 159 ++++++++++++------ .../src/main/resources/META-INF/spring.tld | 137 +++++++-------- src/asciidoc/appx-spring-form-tld.adoc | 115 ++++++++----- src/asciidoc/appx-spring-tld.adoc | 138 +++++++++------ 8 files changed, 390 insertions(+), 290 deletions(-) diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentAware.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentAware.java index 03701501f4a..29ef295ad94 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentAware.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentAware.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -33,4 +33,5 @@ public interface ArgumentAware { * @param argument the result of the nested {@code spring:argument} tag */ void addArgument(Object argument) throws JspTagException; + } 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 bf3a398b1ec..821e5e5e976 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 @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,8 +20,8 @@ import javax.servlet.jsp.JspException; import javax.servlet.jsp.tagext.BodyTagSupport; /** - * JSP tag for collecting arguments and passing them to an {@link ArgumentAware} ancestor - * in the tag hierarchy. + * JSP tag for collecting arguments and passing them to an {@link ArgumentAware} + * ancestor in the tag hierarchy. * *

This tag must be nested under an argument aware tag. * @@ -37,7 +37,17 @@ public class ArgumentTag extends BodyTagSupport { private boolean valueSet; - // tag lifecycle + + /** + * Set the value of the argument (optional). + * - * Optional. If not set, the tag's body content is evaluated. - * - * @param value the parameter value - */ - public void setValue(Object value) { - this.value = value; - this.valueSet = true; - } - @Override public void release() { super.release(); 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 29b1f5084c7..ea5e3dc39ac 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 @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -40,7 +40,22 @@ public class ParamTag extends BodyTagSupport { private boolean valueSet; - // tag lifecycle + + /** + * Set the name of the parameter (required). + */ + public void setName(String name) { + this.name = name; + } + + /** + * Set the value of the parameter (optional). + */ + public void setValue(String value) { + this.value = value; + this.valueSet = true; + } + @Override public int doEndTag() throws JspException { @@ -50,16 +65,14 @@ public class ParamTag extends BodyTagSupport { param.setValue(this.value); } else if (getBodyContent() != null) { - // get the value from the tag body + // Get the value from the tag body param.setValue(getBodyContent().getString().trim()); } - // find a param aware ancestor - ParamAware paramAwareTag = (ParamAware) findAncestorWithClass(this, - ParamAware.class); + // Find a param aware ancestor + ParamAware paramAwareTag = (ParamAware) findAncestorWithClass(this, ParamAware.class); if (paramAwareTag == null) { - throw new JspException( - "The param tag must be a descendant of a tag that supports parameters"); + throw new JspException("The param tag must be a descendant of a tag that supports parameters"); } paramAwareTag.addParam(param); @@ -67,33 +80,6 @@ public class ParamTag extends BodyTagSupport { return EVAL_PAGE; } - // tag attribute accessors - - /** - * Sets the name of the parameter - * - *

- * Required - * - * @param name the parameter name - */ - public void setName(String name) { - this.name = name; - } - - /** - * Sets the value of the parameter - * - *

- * Optional. If not set, the tag's body content is evaluated - * - * @param value the parameter value - */ - public void setValue(String value) { - this.value = value; - this.valueSet = true; - } - @Override public void release() { super.release(); diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/form/FormTag.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/form/FormTag.java index 1dfbe7ecebe..5aa9d23218c 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/form/FormTag.java +++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/tags/form/FormTag.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2014 the original author or authors. + * Copyright 2002-2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -194,15 +194,18 @@ public class FormTag extends AbstractHtmlElementTag { } /** - * Set the value of the '{@code action}' attribute. + * Set the value of the '{@code action}' attribute through a value + * that is to be appended to the current servlet path. *

May be a runtime expression. + * @since 3.2.3 */ - public void setServletRelativeAction(String servletRelativeaction) { - this.servletRelativeAction = (servletRelativeaction != null ? servletRelativeaction : ""); + public void setServletRelativeAction(String servletRelativeAction) { + this.servletRelativeAction = (servletRelativeAction != null ? servletRelativeAction : ""); } /** - * Get the value of the '{@code action}' attribute. + * Get the servlet-relative value of the '{@code action}' attribute. + * @since 3.2.3 */ protected String getServletRelativeAction() { return this.servletRelativeAction; @@ -322,7 +325,19 @@ public class FormTag extends AbstractHtmlElementTag { /** * Get the name of the request param for non-browser supported HTTP methods. + * @since 4.2.3 + */ + @SuppressWarnings("deprecation") + protected String getMethodParam() { + return getMethodParameter(); + } + + /** + * Get the name of the request param for non-browser supported HTTP methods. + * @deprecated as of 4.2.3, in favor of {@link #getMethodParam()} which is + * a proper pairing for {@link #setMethodParam(String)} */ + @Deprecated protected String getMethodParameter() { return this.methodParam; } @@ -334,6 +349,7 @@ public class FormTag extends AbstractHtmlElementTag { return ("get".equalsIgnoreCase(method) || "post".equalsIgnoreCase(method)); } + /** * Writes the opening part of the block '{@code form}' tag and exposes * the form object name in the {@link javax.servlet.jsp.PageContext}. @@ -359,7 +375,7 @@ public class FormTag extends AbstractHtmlElementTag { if (!isMethodBrowserSupported(getMethod())) { assertHttpMethod(getMethod()); - String inputName = getMethodParameter(); + String inputName = getMethodParam(); String inputType = "hidden"; tagWriter.startTag(INPUT_TAG); writeOptionalAttribute(tagWriter, TYPE_ATTRIBUTE, inputType); diff --git a/spring-webmvc/src/main/resources/META-INF/spring-form.tld b/spring-webmvc/src/main/resources/META-INF/spring-form.tld index 7977f2e821c..872f240ba04 100644 --- a/spring-webmvc/src/main/resources/META-INF/spring-form.tld +++ b/spring-webmvc/src/main/resources/META-INF/spring-form.tld @@ -10,7 +10,8 @@ http://www.springframework.org/tags/form - Renders an HTML 'form' tag and exposes a binding path to inner tags for binding. + Renders an HTML 'form' tag and exposes a binding path to inner tags + for binding. form org.springframework.web.servlet.tags.form.FormTag JSP @@ -124,14 +125,14 @@ Name of the model attribute under which the form object is exposed. - Defaults to 'command'. + Defaults to 'command'. modelAttribute false true Name of the model attribute under which the form object is exposed. - Defaults to 'command'. + Defaults to 'command'. commandName false true @@ -143,7 +144,7 @@ true - HTML Required Attribute + Action reference to be appended to the current servlet path servletRelativeAction false true @@ -167,7 +168,10 @@ true - Specifies the list of character encodings for input data that is accepted by the server processing this form. The value is a space- and/or comma-delimited list of charset values. The client must interpret this list as an exclusive-or list, i.e., the server is able to accept any single character encoding per entity received. + Specifies the list of character encodings for input data that is accepted + by the server processing this form. The value is a space- and/or comma-delimited list of + charset values. The client must interpret this list as an exclusive-or list, i.e. the + server is able to accept any single character encoding per entity received. acceptCharset false true @@ -191,7 +195,8 @@ true - The parameter name used for HTTP methods other then GET and POST. Default is '_method' + The parameter name used for HTTP methods other then GET and POST. + Default is '_method'. methodParam false true @@ -229,7 +234,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -265,7 +271,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -379,7 +386,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will make the HTML element readonly. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will make the HTML element readonly. readonly false true @@ -423,7 +431,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -459,7 +468,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -573,7 +583,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will make the HTML element readonly. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will make the HTML element readonly. readonly false true @@ -623,7 +634,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -659,7 +671,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -728,7 +741,8 @@ - Renders an HTML 'select' element. Supports databinding to the selected option. + Renders an HTML 'select' element. Supports data binding to the + selected option. select org.springframework.web.servlet.tags.form.SelectTag JSP @@ -757,7 +771,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -793,7 +808,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -883,19 +899,22 @@ true - The Collection, Map or array of objects used to generate the inner 'option' tags + The Collection, Map or array of objects used to generate the + inner 'option' tags items false true - Name of the property mapped to 'value' attribute of the 'option' tag + Name of the property mapped to 'value' attribute of the + 'option' tag itemValue false true - Name of the property mapped to the inner text of the 'option' tag + Name of the property mapped to the inner text of the + 'option' tag itemLabel false true @@ -916,7 +935,8 @@ - Renders a single HTML 'option'. Sets 'selected' as appropriate based on bound value. + Renders a single HTML 'option'. + Sets 'selected' as appropriate based on bound value. option org.springframework.web.servlet.tags.form.OptionTag JSP @@ -926,8 +946,9 @@ java.lang.Object - The String representation of thr value bound to the 'value' attribute, taking into consideration - any PropertyEditor associated with the enclosing 'select' tag. + The String representation of thr value bound to the 'value' + attribute, taking into consideration any PropertyEditor associated with + the enclosing 'select' tag. displayValue java.lang.String @@ -962,7 +983,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -998,7 +1020,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -1067,7 +1090,8 @@ - Renders a list of HTML 'option' tags. Sets 'selected' as appropriate based on bound value. + Renders a list of HTML 'option' tags. Sets 'selected' as appropriate + based on bound value. options org.springframework.web.servlet.tags.form.OptionsTag empty @@ -1078,7 +1102,9 @@ true - The Collection, Map or array of objects used to generate the inner 'option' tags. This attribute is required unless the containing select's property for data binding is an Enum, in which case the enum's values are used. + The Collection, Map or array of objects used to generate the inner + 'option' tags. This attribute is required unless the containing select's property + for data binding is an Enum, in which case the enum's values are used. items false true @@ -1108,7 +1134,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -1144,7 +1171,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' (without the quotes) will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -1242,7 +1270,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -1278,7 +1307,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -1412,7 +1442,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -1448,7 +1479,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -1538,31 +1570,37 @@ true - The Collection, Map or array of objects used to generate the 'input' tags with type 'radio'. This attribute is required unless the property for data binding is an Enum, in which case the enum's values are used. + The Collection, Map or array of objects used to generate the 'input' + tags with type 'radio'. This attribute is required unless the property for data + binding is an Enum, in which case the enum's values are used. items false true - Name of the property mapped to 'value' attribute of the 'input' tags with type 'radio' + Name of the property mapped to 'value' attribute of the 'input' + tags with type 'radio' itemValue false true - Value to be displayed as part of the 'input' tags with type 'radio' + Value to be displayed as part of the 'input' tags with type + 'radio' itemLabel false true - Delimiter to use between each 'input' tag with type 'radio'. There is no delimiter by default. + Delimiter to use between each 'input' tag with type 'radio'. + There is no delimiter by default. delimiter false true - Specifies the HTML element that is used to enclose each 'input' tag with type 'radio'. Defaults to 'span'. + Specifies the HTML element that is used to enclose each 'input' + tag with type 'radio'. Defaults to 'span'. element false true @@ -1600,7 +1638,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -1636,7 +1675,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -1770,7 +1810,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -1806,7 +1847,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -1896,31 +1938,36 @@ true - The Collection, Map or array of objects used to generate the 'input' tags with type 'checkbox' + The Collection, Map or array of objects used to generate the + 'input' tags with type 'checkbox' items true true - Name of the property mapped to 'value' attribute of the 'input' tags with type 'checkbox' + Name of the property mapped to 'value' attribute of the 'input' + tags with type 'checkbox' itemValue false true - Value to be displayed as part of the 'input' tags with type 'checkbox' + Value to be displayed as part of the 'input' tags with type + 'checkbox' itemLabel false true - Delimiter to use between each 'input' tag with type 'checkbox'. There is no delimiter by default. + Delimiter to use between each 'input' tag with type 'checkbox'. + There is no delimiter by default. delimiter false true - Specifies the HTML element that is used to enclose each 'input' tag with type 'checkbox'. Defaults to 'span'. + Specifies the HTML element that is used to enclose each 'input' + tag with type 'checkbox'. Defaults to 'span'. element false true @@ -1958,7 +2005,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used when the bound field has errors. + Equivalent to "class" - HTML Optional Attribute. + Used when the bound field has errors. cssErrorClass false true @@ -1994,7 +2042,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true @@ -2102,7 +2151,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' will make the HTML element readonly. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will make the HTML element readonly. readonly false true @@ -2138,7 +2188,8 @@ true - Delimiter for displaying multiple error messages. Defaults to the br tag. + Delimiter for displaying multiple error messages. + Defaults to the HTML br tag. delimiter false true @@ -2284,7 +2335,8 @@ true - Equivalent to "class" - HTML Optional Attribute. Used only when errors are present. + Equivalent to "class" - HTML Optional Attribute. + Used only when errors are present. cssErrorClass false true @@ -2406,7 +2458,8 @@ true - HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. + HTML Optional Attribute. Setting the value of this attribute to 'true' + will disable the HTML element. disabled false true diff --git a/spring-webmvc/src/main/resources/META-INF/spring.tld b/spring-webmvc/src/main/resources/META-INF/spring.tld index d25232e5298..a9b3744c22c 100644 --- a/spring-webmvc/src/main/resources/META-INF/spring.tld +++ b/spring-webmvc/src/main/resources/META-INF/spring.tld @@ -10,16 +10,14 @@ http://www.springframework.org/tags - - Sets default HTML escape value for the current page. - Overrides a "defaultHtmlEscape" context-param in web.xml, if any. - + Sets default HTML escape value for the current page. + Overrides a "defaultHtmlEscape" context-param in web.xml, if any. htmlEscape org.springframework.web.servlet.tags.HtmlEscapeTag JSP Set the default value for HTML escaping, to be put - into the current PageContext. + into the current PageContext. defaultHtmlEscape true true @@ -27,11 +25,9 @@ - - Escapes its enclosed body content, applying HTML escaping and/or JavaScript escaping. - 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). - + Escapes its enclosed body content, applying HTML escaping and/or JavaScript + escaping. 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). escapeBody org.springframework.web.servlet.tags.EscapeBodyTag JSP @@ -44,7 +40,7 @@ Set JavaScript escaping for this tag, as boolean value. - Default is false. + Default is 'false'. javaScriptEscape false true @@ -52,22 +48,19 @@ - - Retrieves the message with the given code, or text if code isn't resolvable. - 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). - + Retrieves the message with the given code, or text if code isn't resolvable. + 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). message org.springframework.web.servlet.tags.MessageTag JSP 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. + 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. message false true @@ -80,11 +73,10 @@ 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). You can additionally use nested spring:argument - tags. + 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). + You can additionally use nested spring:argument tags. arguments false true @@ -128,7 +120,8 @@ true - Set JavaScript escaping for this tag, as boolean value. Default is false. + Set JavaScript escaping for this tag, as boolean value. + Default is 'false'. javaScriptEscape false true @@ -136,11 +129,9 @@ - - Retrieves the theme message with the given code, or text if code isn't resolvable. - 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). - + Retrieves the theme message with the given code, or text if code isn't + resolvable. 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). theme org.springframework.web.servlet.tags.ThemeTag JSP @@ -158,11 +149,10 @@ 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). You can additionally use nested spring:argument - tags. + 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). + You can additionally use nested spring:argument tags. arguments false true @@ -206,7 +196,8 @@ true - Set JavaScript escaping for this tag, as boolean value. Default is false. + Set JavaScript escaping for this tag, as boolean value. + Default is 'false'. javaScriptEscape false true @@ -214,9 +205,8 @@ - Argument tag based on the JSTL fmt:param tag. The purpose is to - support arguments inside the spring:message and spring:theme - tags. + Argument tag based on the JSTL fmt:param tag. The purpose is to + support arguments inside the spring:message and spring:theme tags. argument org.springframework.web.servlet.tags.ArgumentTag JSP @@ -230,11 +220,9 @@ - - Provides 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). - + Provides 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). hasBindErrors org.springframework.web.servlet.tags.BindErrorsTag JSP @@ -260,9 +248,7 @@ - - Sets a nested path to be used by the bind tag's path. - + Sets a nested path to be used by the bind tag's path. nestedPath org.springframework.web.servlet.tags.NestedPathTag JSP @@ -281,11 +267,9 @@ - - Provides BindStatus object for the given bind path. - 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). - + Provides BindStatus object for the given bind path. 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). bind org.springframework.web.servlet.tags.BindTag JSP @@ -297,13 +281,14 @@ 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 + specifically for this bean or bean property. path true true - Set whether to ignore a nested path, if any. Default is to not ignore. + Set whether to ignore a nested path, if any. + Default is to not ignore. ignoreNestedPath false true @@ -318,12 +303,10 @@ - - Provides transformation of variables to Strings, using an appropriate - custom PropertyEditor from BindTag (can only be used inside BindTag). - 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). - + Provides transformation of variables to Strings, using an appropriate + custom PropertyEditor from BindTag (can only be used inside BindTag). 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). transform org.springframework.web.servlet.tags.TransformTag JSP @@ -361,22 +344,22 @@ - URL tag based on the JSTL c:url tag. This variant is fully - backwards compatible with the standard tag. Enhancements include support + URL tag based on the JSTL c:url tag. This variant is fully + backwards compatible with the standard tag. Enhancements include support for URL template parameters. url org.springframework.web.servlet.tags.UrlTag JSP - The URL to build. This value can include template place holders - that are replaced with the URL encoded value of the named parameter. Parameters + The URL to build. This value can include template place holders + that are replaced with the URL encoded value of the named parameter. Parameters must be defined using the param tag inside the body of this tag. value true true - Specifies a remote application context path. The default is the + Specifies a remote application context path. The default is the current application context path. context false @@ -389,8 +372,8 @@ true - The scope for the var. 'application', 'session', 'request' and - 'page' scopes are supported. Defaults to page scope. This attribute has no + 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. scope false @@ -405,7 +388,7 @@ Set JavaScript escaping for this tag, as a boolean value. - Default is false. + Default is 'false'. javaScriptEscape false true @@ -413,7 +396,7 @@ - Parameter tag based on the JSTL c:param tag. The sole purpose is to + Parameter tag based on the JSTL c:param tag. The sole purpose is to support params inside the spring:url tag. param org.springframework.web.servlet.tags.ParamTag @@ -433,7 +416,8 @@ - Evaluates a Spring expression (SpEL) and either prints the result or assigns it to a variable. + Evaluates a Spring expression (SpEL) and either prints the result + or assigns it to a variable. eval org.springframework.web.servlet.tags.EvalTag JSP @@ -450,8 +434,8 @@ true - The scope for the var. 'application', 'session', 'request' and - 'page' scopes are supported. Defaults to page scope. This attribute has no + 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. scope false @@ -465,7 +449,8 @@ true - Set JavaScript escaping for this tag, as a boolean value. Default is false. + Set JavaScript escaping for this tag, as a boolean value. + Default is 'false'. javaScriptEscape false true diff --git a/src/asciidoc/appx-spring-form-tld.adoc b/src/asciidoc/appx-spring-form-tld.adoc index 7693346dcf7..db450ed01b9 100644 --- a/src/asciidoc/appx-spring-form-tld.adoc +++ b/src/asciidoc/appx-spring-form-tld.adoc @@ -33,6 +33,41 @@ This appendix describes the `spring-form.tld` tag library. +[[spring-form.tld.button]] +== The button tag + +Renders a form field label in an HTML 'button' tag. + +[[spring-form.tld.button.table]] +[cols="1,1,1,3"] +.Attributes +|=== +| Attribute| Required?| Runtime Expression?| Description + +| disabled +| false +| true +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. + +| id +| false +| true +| HTML Standard Attribute + +| name +| false +| true +| The name attribute for the HTML button tag + +| value +| false +| true +| The name attribute for the HTML button tag +|=== + + + + [[spring-form.tld.checkbox]] == The checkbox tag @@ -72,8 +107,7 @@ Renders an HTML 'input' tag with type 'checkbox'. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -218,8 +252,7 @@ Renders multiple HTML 'input' tags with type 'checkbox'. | delimiter | false | true -| Delimiter to use between each 'input' tag with type 'checkbox'. There is no delimiter - by default. +| Delimiter to use between each 'input' tag with type 'checkbox'. There is no delimiter by default. | dir | false @@ -229,14 +262,12 @@ Renders multiple HTML 'input' tags with type 'checkbox'. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | element | false | true -| Specifies the HTML element that is used to enclose each 'input' tag with type - 'checkbox'. Defaults to 'span'. +| Specifies the HTML element that is used to enclose each 'input' tag with type 'checkbox'. Defaults to 'span'. | htmlEscape | false @@ -256,14 +287,12 @@ Renders multiple HTML 'input' tags with type 'checkbox'. | items | true | true -| The Collection, Map or array of objects used to generate the 'input' tags with type - 'checkbox' +| The Collection, Map or array of objects used to generate the 'input' tags with type 'checkbox' | itemValue | false | true -| Name of the property mapped to 'value' attribute of the 'input' tags with type - 'checkbox' +| Name of the property mapped to 'value' attribute of the 'input' tags with type 'checkbox' | lang | false @@ -490,8 +519,8 @@ Renders an HTML 'form' tag and exposes a binding path to inner tags for binding. | true | Specifies the list of character encodings for input data that is accepted by the server processing this form. The value is a space- and/or comma-delimited list of - charset values. The client must interpret this list as an exclusive-or list, i.e., the - server is able to accept any single character encoding per entity received. + charset values. The client must interpret this list as an exclusive-or list, i.e., + the server is able to accept any single character encoding per entity received. | action | false @@ -501,8 +530,7 @@ Renders an HTML 'form' tag and exposes a binding path to inner tags for binding. | commandName | false | true -| Name of the model attribute under which the form object is exposed. Defaults to - 'command'. +| Name of the model attribute under which the form object is exposed. Defaults to 'command'. | cssClass | false @@ -544,11 +572,15 @@ Renders an HTML 'form' tag and exposes a binding path to inner tags for binding. | true | HTML Optional Attribute +| methodParam +| false +| true +| The parameter name used for HTTP methods other then GET and POST. Default is '_method'. + | modelAttribute | false | true -| Name of the model attribute under which the form object is exposed. Defaults to - 'command'. +| Name of the model attribute under which the form object is exposed. Defaults to 'command'. | name | false @@ -615,6 +647,11 @@ Renders an HTML 'form' tag and exposes a binding path to inner tags for binding. | true | HTML Event Attribute +| servletRelativeAction +| false +| true +| Action reference to be appended to the current servlet path + | target | false | true @@ -708,8 +745,7 @@ Renders an HTML 'input' tag with type 'text' using the bound value. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -809,8 +845,7 @@ Renders an HTML 'input' tag with type 'text' using the bound value. | readonly | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will make the HTML element readonly. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will make the HTML element readonly. | size | false @@ -985,8 +1020,7 @@ Renders a single HTML 'option'. Sets 'selected' as appropriate based on bound va | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -1111,8 +1145,7 @@ Renders a list of HTML 'option' tags. Sets 'selected' as appropriate based on bo | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -1257,8 +1290,7 @@ Renders an HTML 'input' tag with type 'password' using the bound value. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -1358,8 +1390,7 @@ Renders an HTML 'input' tag with type 'password' using the bound value. | readonly | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will make the HTML element readonly. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will make the HTML element readonly. | showPassword | false @@ -1424,8 +1455,7 @@ Renders an HTML 'input' tag with type 'radio'. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -1570,8 +1600,7 @@ Renders multiple HTML 'input' tags with type 'radio'. | delimiter | false | true -| Delimiter to use between each 'input' tag with type 'radio'. There is no delimiter by - default. +| Delimiter to use between each 'input' tag with type 'radio'. There is no delimiter by default. | dir | false @@ -1581,14 +1610,12 @@ Renders multiple HTML 'input' tags with type 'radio'. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | element | false | true -| Specifies the HTML element that is used to enclose each 'input' tag with type 'radio'. - Defaults to 'span'. +| Specifies the HTML element that is used to enclose each 'input' tag with type 'radio'. Defaults to 'span'. | htmlEscape | false @@ -1608,8 +1635,7 @@ Renders multiple HTML 'input' tags with type 'radio'. | items | true | true -| The Collection, Map or array of objects used to generate the 'input' tags with type - 'radio' +| The Collection, Map or array of objects used to generate the 'input' tags with type 'radio' | itemValue | false @@ -1744,8 +1770,7 @@ Renders an HTML 'select' element. Supports databinding to the selected option. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -1915,8 +1940,7 @@ Renders an HTML 'textarea'. | disabled | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will disable the HTML element. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will disable the HTML element. | htmlEscape | false @@ -2011,8 +2035,7 @@ Renders an HTML 'textarea'. | readonly | false | true -| HTML Optional Attribute. Setting the value of this attribute to 'true' (without the - quotes) will make the HTML element readonly. +| HTML Optional Attribute. Setting the value of this attribute to 'true' will make the HTML element readonly. | rows | false diff --git a/src/asciidoc/appx-spring-tld.adoc b/src/asciidoc/appx-spring-tld.adoc index c3bb117fbd0..54131008a4f 100644 --- a/src/asciidoc/appx-spring-tld.adoc +++ b/src/asciidoc/appx-spring-tld.adoc @@ -29,6 +29,26 @@ This appendix describes the `spring.tld` tag library. +[[spring.tld.argument]] +== The argument tag + +Argument tag based on the JSTL fmt:param tag. The purpose is to support arguments +inside the message and theme tags. + +[[spring.tld.argument.table]] +[cols="1,1,1,3"] +.Attributes +|=== +| Attribute| Required?| Runtime Expression?| Description + +| value +| false +| true +| The value of the argument. + + + + [[spring.tld.bind]] == The bind tag @@ -92,6 +112,51 @@ HtmlEscapeTag or a "defaultHtmlEscape" context-param in web.xml). +[[spring.tld.eval]] +== The eval tag + +Evaluates a Spring expression (SpEL) and either prints the result or assigns it to a +variable. + +[[spring.tld.eval.table]] +[cols="1,1,1,3"] +.Attributes +|=== +| Attribute| Required?| 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. +|=== + + + + [[spring.tld.hasBindErrors]] == The hasBindErrors tag @@ -238,6 +303,31 @@ Sets a nested path to be used by the bind tag's path. +[[spring.tld.param]] +== The param tag + +Parameter tag based on the JSTL c:param tag. The sole purpose is to support params +inside the url tag. + +[[spring.tld.param.table]] +[cols="1,1,1,3"] +.Attributes +|=== +| Attribute| Required?| Runtime Expression?| Description + +| name +| true +| true +| The name of the parameter. + +| value +| false +| true +| The value of the parameter. + + + + [[spring.tld.theme]] == The theme tag @@ -365,7 +455,7 @@ escaping. Modeled after the JSTL c:url tag with backwards compatibility in mind. |=== | Attribute| Required?| Runtime Expression?| Description -| url +| value | true | true | The URL to build. This value can include template {placeholders} that are replaced @@ -402,49 +492,3 @@ escaping. Modeled after the JSTL c:url tag with backwards compatibility in mind. | true | Set JavaScript escaping for this tag, as a boolean value. Default is false. |=== - - - - -[[spring.tld.eval]] -== The eval tag - -Evaluates a Spring expression (SpEL) and either prints the result or assigns it to a -variable. - -[[spring.tld.eval.table]] -[cols="1,1,1,3"] -.Attributes -|=== -| Attribute| Required?| Runtime Expression?| Description - -| expression -| true -| true -| The expression to evaluate. - -| 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. - -| 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. - -| 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. -|=== -