Repository: struts-site Updated Branches: refs/heads/master b0896ba39 -> bf29f7abc
fix some validators pages Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/bf29f7ab Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/bf29f7ab Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/bf29f7ab Branch: refs/heads/master Commit: bf29f7abc99a4d89556c787a65c45e42c31a171f Parents: b0896ba Author: Aleksandr Mashchenko <amashche...@apache.org> Authored: Mon Sep 11 00:29:55 2017 +0300 Committer: Aleksandr Mashchenko <amashche...@apache.org> Committed: Mon Sep 11 00:29:55 2017 +0300 ---------------------------------------------------------------------- source/core-developers/conversion-validator.md | 134 ++++++++++++------- source/core-developers/date-validator.md | 79 +++++++---- source/core-developers/double-validator.md | 80 +++++++---- source/core-developers/required-validator.md | 51 +++---- .../core-developers/requiredstring-validator.md | 61 +++++---- 5 files changed, 252 insertions(+), 153 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/struts-site/blob/bf29f7ab/source/core-developers/conversion-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/conversion-validator.md b/source/core-developers/conversion-validator.md index a28e6eb..f572fa1 100644 --- a/source/core-developers/conversion-validator.md +++ b/source/core-developers/conversion-validator.md @@ -5,54 +5,86 @@ title: conversion validator # conversion validator -####Description#### - - - -~~~~~~~ -{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.ConversionErrorFieldValidator} -~~~~~~~ - -####Parameters#### - - - -~~~~~~~ -{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.ConversionErrorFieldValidator} -~~~~~~~ - -####Examples#### - - - -~~~~~~~ -{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.ConversionErrorFieldValidator} -~~~~~~~ - -####Repopulating Field upon conversion Error#### - - - -~~~~~~~ -{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RepopulateConversionErrorFieldValidatorSupport} -~~~~~~~ - - -~~~~~~~ -{snippet:id=exampleJspPage|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RepopulateConversionErrorFieldValidatorSupport} -~~~~~~~ - - -~~~~~~~ -{snippet:id=exampleXwork|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RepopulateConversionErrorFieldValidatorSupport} -~~~~~~~ - - -~~~~~~~ -{snippet:id=exampleJava|lang=java|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RepopulateConversionErrorFieldValidatorSupport} -~~~~~~~ - - -~~~~~~~ -{snippet:id=exampleValidation|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RepopulateConversionErrorFieldValidatorSupport} -~~~~~~~ +### Description + +Field Validator that checks if a conversion error occurred for this field. + +### Parameters + +- `fieldName` - The field name this validator is validating. Required if using Plain-Validator Syntax otherwise not required. + +### Examples + +``` +<!-- Plain Validator Syntax --> +<validator type="conversion"> + <param name="fieldName">myField</param> + <message>Conversion Error Occurred</message> +</validator> + +<!-- Field Validator Syntax --> +<field name="myField"> + <field-validator type="conversion"> + <message>Conversion Error Occurred</message> + </field-validator> +</field> +``` + +### Repopulating Field upon conversion Error + + The capability of auto-repopulating the stack with a fake parameter map when a conversion error has occurred can be done with `repopulateField` property set to `true`. + +This is typically useful when one wants to repopulate the field with the original value when a conversion error occurred. Eg. with a textfield that only allows an Integer (the action class have an Integer field declared), upon conversion error, the incorrectly entered integer (maybe a text 'one') will not appear when dispatched back. With `repopulateField` property set to true, it will, meaning the textfield will have 'one' as its value upon conversion error. + +``` +<!-- myJspPage.jsp --> +<s:form action="someAction" method="POST"> + .... + <s:textfield label="My Integer Field" name="myIntegerField" /> + .... + <s:submit /> +</s:form> +``` + +``` +<!-- xwork.xml --> +<xwork> +<include file="xwork-default.xml" /> +.... +<package name="myPackage" extends="xwork-default"> + .... + <action name="someAction" class="example.MyActionSupport.java"> + <result name="input">myJspPage.jsp</result> + <result>success.jsp</result> + </action> + .... +</package> +.... +</xwork> +``` + +``` +<!-- MyActionSupport.java --> +public class MyActionSupport extends ActionSupport { + private Integer myIntegerField; + + public Integer getMyIntegerField() { return this.myIntegerField; } + public void setMyIntegerField(Integer myIntegerField) { + this.myIntegerField = myIntegerField; + } +} +``` + +``` +<!-- MyActionSupport-someAction-validation.xml --> +<validators> + ... + <field name="myIntegerField"> + <field-validator type="conversion"> + <param name="repopulateField">true</param> + <message>Conversion Error (Integer Wanted)</message> + </field-validator> + </field> + ... +</validators> +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/bf29f7ab/source/core-developers/date-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/date-validator.md b/source/core-developers/date-validator.md index c06bed9..f8e0f3c 100644 --- a/source/core-developers/date-validator.md +++ b/source/core-developers/date-validator.md @@ -5,31 +5,54 @@ title: date validator # date validator -####Description#### - - - -~~~~~~~ -{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.DateRangeFieldValidator} -~~~~~~~ - -####Parameters#### - - - -~~~~~~~ -{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.DateRangeFieldValidator} -~~~~~~~ - -**(\!) Warning** - - -> \{snippet:id=parameters\-warning|javadoc=true|url=com\.opensymphony\.xwork2\.validator\.validators\.DateRangeFieldValidator\} - -####Examples#### - - - -~~~~~~~ -{snippet:id=example|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator.validators.DateRangeFieldValidator} -~~~~~~~ +### Description + +Field Validator that checks if the date supplied is within a specific range. + +**NOTE:** If no date converter is specified, `XWorkBasicConverter` will kick in to do the date conversion, which by default using the `Date.SHORT` format using the a problematically specified locale else falling back to the system default locale. + +### Parameters + +- `fieldName - The field name this validator is validating. Required if using Plain-Validator Syntax otherwise not required. +- `min` - the min date range. If not specified will not be checked. +- `max` - the max date range. If not specified will not be checked. +- `parse` - if set to true, minExpression and maxExpression will be evaluated to find min/max. +- `minExpression` - expression to calculate the minimum value (if none is specified, it will not be checked). +- `maxExpression` - expression to calculate the maximum value (if none is specified, it will not be checked). + +You can either use the min / max value or minExpression / maxExpression (when parse is set to true) - using expression can be slightly slower, see the example below. + +> Warning +> Do not use `${minExpression}` and `${maxExpression}` as an expression as this will turn into infinitive loop! + +### Examples + +``` +<validators> + <!-- Plain Validator syntax --> + <validator type="date"> + <param name="fieldName">birthday</param> + <param name="min">01/01/1990</param> + <param name="max">01/01/2000</param> + <message>Birthday must be within ${min} and ${max}</message> + </validator> + + <!-- Field Validator Syntax --> + <field name="birthday"> + <field-validator type="date"> + <param name="min">01/01/1990</param> + <param name="max">01/01/2000</param> + <message>Birthday must be within ${min} and ${max}</message> + </field-validator> + </field> + + <!-- Field Validator Syntax with expression --> + <field name="birthday"> + <field-validator type="date"> + <param name="minExpression">${minValue}</param> <!-- will be evaluated as: Date getMinValue() --> + <param name="maxExpression">${maxValue}</param> <!-- will be evaluated as: Date getMaxValue() --> + <message>Age needs to be between ${min} and ${max}</message> + </field-validator> + </field> +</validators> +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/bf29f7ab/source/core-developers/double-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/double-validator.md b/source/core-developers/double-validator.md index 0c9a3d4..71d96c5 100644 --- a/source/core-developers/double-validator.md +++ b/source/core-developers/double-validator.md @@ -5,31 +5,55 @@ title: double validator # double validator -####Description#### - - - -~~~~~~~ -{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.DoubleRangeFieldValidator} -~~~~~~~ - -####Parameters#### - - - -~~~~~~~ -{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.DoubleRangeFieldValidator} -~~~~~~~ - -**(\!) Warning** - - -> \{snippet:id=parameters\-warning|javadoc=true|url=com\.opensymphony\.xwork2\.validator\.validators\.DoubleRangeFieldValidator\} - -####Examples#### - - - -~~~~~~~ -{snippet:id=example|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator.validators.DoubleRangeFieldValidator} -~~~~~~~ +### Description + +Field Validator that checks if the double specified is within a certain range. + +### Parameters + +- `fieldName` - The field name this validator is validating. Required if using Plain-Validator Syntax otherwise not required. +- `minInclusive` - the minimum inclusive value in FloatValue format specified by Java language (if none is specified, it will not be checked). +- `maxInclusive` - the maximum inclusive value in FloatValue format specified by Java language (if none is specified, it will not be checked). +- `minExclusive` - the minimum exclusive value in FloatValue format specified by Java language (if none is specified, it will not be checked). +- `maxExclusive` - the maximum exclusive value in FloatValue format specified by Java language (if none is specified, it will not be checked). +- `minInclusiveExpression` - the minimum inclusive value specified as a OGNL expression (if none is specified, it will not be checked). +- `maxInclusiveExpression` - the maximum inclusive value specified as a OGNL expression (if none is specified, it will not be checked). +- `minExclusiveExpression` - the minimum exclusive value specified as a OGNL expression (if none is specified, it will not be checked). +- `maxExclusiveExpression` - the maximum exclusive value specified as a OGNL expression (if none is specified, it will not be checked). + +You can specify either `minInclusive`, `maxInclusive`, `minExclusive` and `maxExclusive` or `minInclusiveExpression`, `maxInclusiveExpression`, `minExclusiveExpression` and `maxExclusiveExpression` as a OGNL expression, see example below. You can always try to mix params but be aware that such behaviour was not tested. + +> Warning +> Do not use `${minInclusiveExpression}`, `${maxInclusiveExpression}`, `${minExclusiveExpressionExpression}` and `${maxExclusive}` as an expression as this will turn into infinitive loop! + +### Examples + +``` +<validators> + <!-- Plain Validator Syntax --> + <validator type="double"> + <param name="fieldName">percentage</param> + <param name="minInclusive">20.1</param> + <param name="maxInclusive">50.1</param> + <message>Age needs to be between ${minInclusive} and ${maxInclusive} (inclusive)</message> + </validator> + + <!-- Field Validator Syntax --> + <field name="percentage"> + <field-validator type="double"> + <param name="minExclusive">0.123</param> + <param name="maxExclusive">99.98</param> + <message>Percentage needs to be between ${minExclusive} and ${maxExclusive} (exclusive)</message> + </field-validator> + </field> + + <!-- Field Validator Syntax with expression --> + <field name="percentage"> + <field-validator type="double"> + <param name="minExclusiveExpression">${minExclusiveValue}</param> <!-- will be evaluated as: Double getMinExclusiveValue() --> + <param name="maxExclusiveExpression">${maxExclusiveValue}</param> <!-- will be evaluated as: Double getMaxExclusiveValue() --> + <message>Percentage needs to be between ${minExclusive} and ${maxExclusive} (exclusive)</message> + </field-validator> + </field> +</validators> +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/bf29f7ab/source/core-developers/required-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/required-validator.md b/source/core-developers/required-validator.md index ede31e0..8e6db62 100644 --- a/source/core-developers/required-validator.md +++ b/source/core-developers/required-validator.md @@ -5,26 +5,31 @@ title: required validator # required validator -####Description#### - - - -~~~~~~~ -{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredFieldValidator} -~~~~~~~ - -####Parameters#### - - - -~~~~~~~ -{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredFieldValidator} -~~~~~~~ - -####Examples#### - - - -~~~~~~~ -{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredFieldValidator} -~~~~~~~ +### Description + +RequiredFieldValidator checks if the specified field is not null. + +### Parameters + +- `fieldName` - field name if plain-validator syntax is used, not needed if field-validator syntax is used. + +### Examples + +``` +<validators> + <!-- Plain Validator Syntax --> + <validator type="required"> + <param name="fieldName">username</param> + <message>username must not be null</message> + </validator> + + + <!-- Field Validator Syntax --> + <field name="username"> + <field-validator type="required"> + <message>username must not be null</message> + </field-validator> + </field> + +</validators> +``` http://git-wip-us.apache.org/repos/asf/struts-site/blob/bf29f7ab/source/core-developers/requiredstring-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/requiredstring-validator.md b/source/core-developers/requiredstring-validator.md index bb6c7d8..4268db6 100644 --- a/source/core-developers/requiredstring-validator.md +++ b/source/core-developers/requiredstring-validator.md @@ -5,26 +5,41 @@ title: requiredstring validator # requiredstring validator -####Description#### - - - -~~~~~~~ -{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredStringValidator} -~~~~~~~ - -####Parameters#### - - - -~~~~~~~ -{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredStringValidator} -~~~~~~~ - -####Examples#### - - - -~~~~~~~ -{snippet:id=examples|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredStringValidator} -~~~~~~~ +### Description + +RequiredStringValidator checks that a String field is non-null and has a length > 0. (i.e. it isn't ""). The `trim` parameter determines whether it will `String#trim()` the String before performing the length check. If unspecified, the String will be trimmed. + +### Parameters + +- `fieldName` - The field name this validator is validating. Required if using Plain-Validator Syntax otherwise not required. +- `trim` - (Optional) Boolean, default true. Trims the field name value before validating. +- `trimExpression` - (Optional) String. Specifies the trim param as an OGNL expression. + +### Examples + +``` +<validators> + <!-- Plain-Validator Syntax --> + <validator type="requiredstring"> + <param name="fieldName">username</param> + <param name="trim">true</param> + <message>username is required</message> + </validator> + + <!-- Field-Validator Syntax --> + <field name="username"> + <field-validator type="requiredstring"> + <param name="trim">true</param> + <message>username is required</message> + </field-validator> + </field> + + <!-- Field-Validator Syntax with expression --> + <field name="username"> + <field-validator type="requiredstring"> + <param name="trimExpression">${trimValue}</param> <!-- will be evaluated as: boolean getTrimValue() --> + <message>username is required</message> + </field-validator> + </field> +</validators> +```