Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Myfaces Wiki" for change notification.
The "Extensions/Validator/I18N" page has been changed by RudyDeBusscher.
http://wiki.apache.org/myfaces/Extensions/Validator/I18N?action=diff&rev1=2&rev2=3
--------------------------------------------------
- ## page was copied from Extensions/Validator/Versions
- = Version overview and Upgrade-Guides =
+ = Internationalization =
+ == Introduction ==
+ The messages that are shown when a validation fails can be customized in different ways. Due to the fact that there are different types of validations possible (like JSF based validators, BeanValidation based, ExtVal powered, and so on) it can be sometimes a bit confusing what needs to be done to change a certain text. This page gives an easy way to customize the messages.
+ == Message bundle keys ==
+ Just like most web applications, the messages are identified by keys of resource bundles. The following table gives an overview of the keys:
- == ExtVal x.x.3 ==
- MyFaces ExtVal r3 is a major version of ExtVal.<<BR>>
- [[/Versions/UpgradeGuide|Here]] you can find information about possible steps you have to perform.
+ ==== ExtVal annotations ====
+ ||<:>'''annotation''' ||<:>'''resource bundle key''' ||
+ ||@Required ||field_required ||
+ ||@Length ||javax.faces.validator.LengthValidator.MINIMUM <<BR>>javax.faces.validator.LengthValidator.MAXIMUM ||
+ ||@Pattern ||no_match ||
+ ||@LongRange ||javax.faces.validator.LongRangeValidator.NOT_IN_RANGE <<BR>>javax.faces.validator.LongRangeValidator.MAXIMUM <<BR>>javax.faces.validator.LongRangeValidator.MINIMUM <<BR>>javax.faces.validator.LongRangeValidator.TYPE ||
+ ||@DoubleRange ||javax.faces.validator.DoubleRangeValidator.NOT_IN_RANGE <<BR>>javax.faces.validator.DoubleRangeValidator.MAXIMUM <<BR>>javax.faces.validator.DoubleRangeValidator.MINIMUM <<BR>>javax.faces.validator.DoubleRangeValidator.TYPE ||
+
+
+ ==== JPA annotations ====
+ ||<:>'''annotation''' ||<:>'''resource bundle key''' ||
+ ||@Column <<BR>> @Basic<<BR>> @Id <<BR>> @OneToOne <<BR>> @ManyToOne ||field_required <<BR>> field_too_long ||
+
+
+ ==== ExtVal Crossvalidation annotations ====
+ ||<:>'''annotation''' ||<:>'''resource bundle key''' ||
+ ||@Equals ||duplicated_content_required ||
+ ||@NotEquals ||duplicated_content_denied ||
+ ||@DateIs ||wrong_date_not_before<<BR>> wrong_date_not_after <<BR>> wrong_date_not_equal ||
+ ||@RequiredIf ||empty_field ||
+ ||@EmptyIf ||field_not_empty ||
+
+
+ ==== BeanValidation annotations ====
+ The key which is used, can be constructed using the annotation name. The pattern is ''javax.validation.constraints.'xxx'.message'' where xxx is the annotation name.
+
+ So the resource bundle key for the @Null annotation is javax.validation.constraints.Null.message
+
+ For completeness, this is the list of known annotations : @AssertFalse, @AssertTrue, @DecimalMax, @DecimalMin, @Digits, @Future, @Max, @Min, @NotNull, @Null, @Past, @Pattern, @Size
+
+ == Define Resource Bundle ==
+ In the above list you can see that there are 4 groups of annotations that can be used by ExtVal to do validations. The validation strategies (the code that is responsible for making the actuals checks) for the ExtVal annotations can be split up into 2 groups. The ones that uses the JSF Validators (like @Length) and those that are implmented by ExtVal itself (like @Pattern and @Required). So we have actually 5 groups that have small differences in 'resolving' their message. You can find the details in the next paragrapgh, but if you need a quick solution that works for any group, do the following:
+
+ 1. Make a new resource bundle, according to the standards of Java (a properties files with the correct postfixes for the languages and countries). An example could be com/mycompany/myprog/messages.properties, com/mycompany/myprog/messages_NL.properties, etc ..
+ 1.
+ Define this resource bundle as message bundle in your faces-config file<<BR>> '''<application>''''''<<BR>>'''''' <message-bundle>com.mycompany.myprog.messages</message-bundle>''''''<<BR>>'''''' </application>'''
+
+ 1.
+ Define the following web application parameters in your web.xml file.<<BR>> '''<context-param>''''''<<BR>>'''''' <param-name>org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE</param-name>''''''<<BR>>'''''' <param-value>com.mycompany.myprog.messages</param-value>''''''<<BR>>'''''' </context-param>''''''<<BR>>'''''' <context-param>''''''<<BR>>'''''' <param-name>org.apache.myfaces.extensions.validator.JPA_VALIDATION_ERROR_MESSAGES</param-name>''''''<<BR>>'''''' <param-value>com.mycompany.myprog.messages</param-value>''''''<<BR>>'''''' </context-param>'''<<BR>>
+
+
+ You now can use the keys listed in first section of this page to redefine the message you like to see when the validation fails. It is best that you also add the key with the postfix _detail to this custom resource bundle, because otherwise it is possible that the message isn't taken (although the detail message isn't used from JSF 1.2 anymore)
+
+ If you like to use other keys then the ones on this page, you can specify them with the property validationErrorMsgKey (non BeanValidation annotations) or messages (BeanValidation annotations) except for the JPA annotations and the annotations that uses a JSF validator (@Length, @LongRange and @DoubleRange)
+
+ == Detailed customization steps ==
+ In this paragrapgh, the different steps which are followed to resolve the message are written out for each of the 5 groups. This can be used if you want to customize the Internationalization aspect of ExtVal further more.
+
+ See also on the advanced Internationalization page (TODO) for some examples that uses some of these aspects.
+
+ ==== MessageResolver ====
+ MessageResolver is the interface that needs to be implemented when ExtVal is responsible for looking up the message of the validation message. (See ... TODO)
+
+ ==== ExtVal annotation that isn't using a JSF Validator ====
+ These are the steps that are followed when a validation error occurs linked to the @Required and @Pattern annotation.
+
+ The text or the key of the resource bundle specified in the property ''validationErrorMsgKey ''of the annotation will be used to lookup the message. If the user didn't specify one, the default one is used and can be found in the table on top of the page. The value of it will be referenced as ''msgOrKey ''in the rest of the paragraph.
+
+ 1.
+ When the ''msgOrKey ''value contain a space, it is the '''literal text''' that is used as message.
+
+ 1.
+ The value of ''msgOrKey ''is used as the key of the resource bundle which is injected into the messageResolver properties '''messageBundleBaseName '''or '''messageBundleVarName'''. If found, this message is used.
+
+ 1.
+ if ''msgOrKey ''found in resource bundle '''org.apache.myfaces.extensions.validator.custom.validation_messages''' use this on.
+
+ 1.
+ if msgOrKey found in resource bundle specified as parameter '''org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE''' in web.xml use this one.
+
+ 1.
+ if msgOrKey found in resource bundle '''org.apache.myfaces.extensions.validator.baseval.message.bundle.validation_messages''' use this one (bundle provided in the module jar, so if default key value not overriden in annotation, message is now resolved)
+
+ 1.
+ Use the default message (key '''javax.faces.component.UIInput.REQUIRED''') from the resource bundle specified in the faces-config in case of a @Required annotation validation.
+
+
+ ==== ExtVal annotation that is using a JSF Validator ====
+ The message is resolved througgh the standard functionality of JSF. This means that the JSF keys (javax.faces.validator.xxxx) are looked up first in the message bundle defined in the faces-config file. If it can't find it there, it looks in the default bundle of the system where they are always present.
+
+ So ExtVal isn't responsible for resolving the message.
+
+ ==== JPA annotations ====
+ The keys used (as value for msgOrKey) is field_reqiured or field_too_long.
+
+ 1.
+ When the ''msgOrKey ''value contain a space, it is the '''literal text''' that is used as message. This can only be achieved by using some add-on that uses the Virtual metadata add-on to change the value.
+
+ 1.
+ The value of ''msgOrKey ''is used as the key of the resource bundle which is injected into the messageResolver properties '''messageBundleBaseName '''or '''messageBundleVarName'''. If found, this message is used.
+
+ 1.
+ if ''msgOrKey ''found in resource bundle '''org.apache.myfaces.extensions.validator.custom.validation_messages''' use this on.
+
+ 1.
+ if msgOrKey found in resource bundle specified as parameter '''org.apache.myfaces.extensions.validator.JPA_VALIDATION_ERROR_MESSAGES''' in web.xml use this one.
+
+ 1.
+ When a resourcebundle is specified in the global property '''JPA_VALIDATION_ERROR_MESSAGES''' and the key is found there, use that one.
+
+ 1.
+ if msgOrKey found in resource bundle '''org.apache.myfaces.extensions.validator.baseval.message.bundle.validation_messages''' use this one (bundle provided in the module jar, so if default key value not overriden in annotation, message is now resolved)
+
+ 1.
+ Use the default message (key '''javax.faces.component.UIInput.REQUIRED''' or '''javax.faces.validator.LengthValidator.MAXIMUM''', depending on the violation found)) from the resource bundle specified in the faces-config.
+
+
+ ==== Cross validation annotations ====
+ The text or the key of the resource bundle specified in the property ''validationErrorMsgKey ''of the annotation will be used to lookup the message. If the user didn't specify one, the default one is used and can be found in the table on top of the page. The value of it will be referenced as ''msgOrKey ''in the rest of the paragraph.
+
+ 1.
+ When the ''msgOrKey ''value contain a space, it is the '''literal text''' that is used as message.
+
+ 1.
+ The value of ''msgOrKey ''is used as the key of the resource bundle which is injected into the messageResolver properties '''messageBundleBaseName '''or '''messageBundleVarName'''. If found, this message is used.
+
+ 1.
+ if ''msgOrKey ''found in resource bundle '''org.apache.myfaces.extensions.validator.custom.validation_messages''' use this on.
+
+ 1.
+ if msgOrKey found in resource bundle specified as parameter '''org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE''' in web.xml use this one.
+
+ 1.
+ if msgOrKey found in resource bundle '''org.apache.myfaces.extensions.validator.crossval.message.bundle.validation_messages''' use this one (bundle provided in the module jar, so if default key value not overriden in annotation, message is now resolved)
+
+
+ ==== Bean validation ====
+ The validations performed by the Bean Validation Framework are based on a completely different system then the ones by JSF itself. No exception with a message is thrown but a list of problems is returned. However, they have forseen a pluggable mechanism for the messages, the MessageInterpolator. ExtVal suplies a bridge to the MessageResolver system of ExtVal which results in a almost identical list of posibilities.
+
+ The message for the validation message is based on the text/resource key of the property message. An important remark is that all keys (and messages) should be enclosed by curly brackets ({ and }) to go through the ExtValAdapter that allows the usage of the MessageResolver.
+
+ 1.
+ When the ''msgOrKey ''value contain a space, it is the '''literal text''' that is used as message.
+
+ 1.
+ The value of ''msgOrKey ''is used as the key of the resource bundle which is injected into the messageResolver properties '''messageBundleBaseName '''or '''messageBundleVarName'''. If found, this message is used.
+
+ 1.
+ if ''msgOrKey ''found in resource bundle '''org.apache.myfaces.extensions.validator.custom.validation_messages''' use this on.
+
+ 1.
+ if msgOrKey found in resource bundle specified as parameter '''org.apache.myfaces.extensions.validator.CUSTOM_MESSAGE_BUNDLE''' in web.xml use this one.
+
+ 1.
+ if msgOrKey found in resource bundle '''org.apache.myfaces.extensions.validator.core.message.bundle.validation_messages''' use this one. But this resource bundle isn't avalaible by default. It can be specified by the user.
+
+
+ When no curly braces are specified, the adapter is not used and you have only the default functionality of BV. If the resource key doesn't exist in the resource bundle ValidationMessages or default implemntation resource bundle like org.hibernate.validator.ValidationMessages, you get the value itself (and it is supposed to be the error message)
+