From 70fe0cee8d4fbfbfe55d01d8adb530ed356756cd Mon Sep 17 00:00:00 2001 From: ymeine Date: Fri, 20 Mar 2015 19:00:31 +0100 Subject: [PATCH] feat ariatemplates/ariatemplates#1427 Customization of widget's error messages Documentation for feature described there: ariatemplates/ariatemplates#1427 Not all details have been documented (widgets' resources are kind of fully private now). Specific documentation for each widget has been added. Below is the original description of the feature. ---- It is now possible for a user to customize the error messages used by the widgets. There are 3 levels of error messages specifications, the two firsts being user configuration while the last is the hardcoded default. This is resolved in this order of precedence: - local: widget's configuration - global: application's environment - hardcoded: widget's resources --- resources/articles/navigationbar/next.jade | 2 + src/next/index.md | 1 + .../widgets/aria_widgets_lib/autocomplete.md | 19 +++++- .../widgets/aria_widgets_lib/datefield.md | 28 +++++++- .../widgets/aria_widgets_lib/numberfield.md | 17 +++++ .../widgets/aria_widgets_lib/timefield.md | 17 +++++ .../error_messages_customization.md | 64 +++++++++++++++++++ 7 files changed, 146 insertions(+), 2 deletions(-) create mode 100644 src/next/widgets/around_widgets/error_messages_customization.md diff --git a/resources/articles/navigationbar/next.jade b/resources/articles/navigationbar/next.jade index ecbbb66..f280f03 100644 --- a/resources/articles/navigationbar/next.jade +++ b/resources/articles/navigationbar/next.jade @@ -135,6 +135,8 @@ div.menu-container a(href="prefill_feature", rel="nofollow") Prefill Feature li.son a(href="autoselect_feature", rel="nofollow") Autoselect Feature + li.son + a(href="error_messages_customization", rel="nofollow") Error messages customization li.dad a(href="the_html_widgets_library", rel="nofollow") The HTML Widgets Library li.dad diff --git a/src/next/index.md b/src/next/index.md index b2593c2..bcef605 100644 --- a/src/next/index.md +++ b/src/next/index.md @@ -78,6 +78,7 @@ CssClass: maintoc - [Validators](validators) - [Prefill Feature](prefill_feature) - [Autoselect Feature](autoselect_feature) + - [Error messages customization](error_messages_customization) - ### [The HTML Widgets Library](the_html_widgets_library) - [HTML TextArea](html_textarea) - ### [Creating A Custom Widgets Library](creating_a_custom_widgets_library) diff --git a/src/next/widgets/aria_widgets_lib/autocomplete.md b/src/next/widgets/aria_widgets_lib/autocomplete.md index 620c528..37fc5e6 100644 --- a/src/next/widgets/aria_widgets_lib/autocomplete.md +++ b/src/next/widgets/aria_widgets_lib/autocomplete.md @@ -82,4 +82,21 @@ It is possible to add listeners to some of the events raised by the widget DOM u In this sample the **onchange** callback shows a small notification above the AutoComplete. If you type something in the field and highlight its options the callback is not called, but if you select one option clicking on it, pressing _Enter_ or _Tab_, the notification appears. The callback is called also if you type an invalid text. - \ No newline at end of file + + +## Error messages customization + +Please refer to the main article concerning default [error messages customization](error_messages_customization). + +Here is the list of error messages that can be customized, with for each: + +- the key to be used in the configuration map +- its description +- its hard-coded default value + +Messages: + +- validation + - key: `validation` + - description: for cases where the input's value can't match any option + - default hard-coded: `"There is no suggestion available for the given entry."` diff --git a/src/next/widgets/aria_widgets_lib/datefield.md b/src/next/widgets/aria_widgets_lib/datefield.md index d08addb..aadb166 100644 --- a/src/next/widgets/aria_widgets_lib/datefield.md +++ b/src/next/widgets/aria_widgets_lib/datefield.md @@ -8,6 +8,7 @@ The whole list of configuration parameters is available in [DateFieldCfg bean](h ## Binding + The "value" property in the dateField is bind-able and can be bound to a property in the data model. @@ -58,4 +59,29 @@ The "value" property in the dateField is bind-able and can be bound to a propert * 15DEC10/-3 (equivalent to: 12DEC10) * 15DEC2010/+10 (equivalent to: 25DEC2010) * 15DEC2010/-3 (equivalent to: 12DEC2010) -* When the user leaves the field (on blur), the content is reformatted according to the pattern configured in the DateField properties. \ No newline at end of file +* When the user leaves the field (on blur), the content is reformatted according to the pattern configured in the DateField properties. + +## Error messages customization + +Please refer to the main article concerning default [error messages customization](error_messages_customization). + +Here is the list of error messages that can be customized, with for each: + +- the key to be used in the configuration map +- its description +- its hard-coded default value + +Messages: + +- validation + - key: `validation` + - description: for wrong input's value format, resulting in the impossibility to interpret it for the widget's value + - default hard-coded: `"Please enter a valid date format, for example: 10/12 or 01MAR or +4"` +- minimum value + - key: `minValue` + - description: for cases where the entered date is below the minimum date set in the widget's configuration + - default hard-coded: `"Date is before the minimum date."` +- maximum value + - key: `maxValue` + - description: for cases where the entered date is beyond the maximum date set in the widget's configuration + - default hard-coded: `"Date is after the maximum date."` diff --git a/src/next/widgets/aria_widgets_lib/numberfield.md b/src/next/widgets/aria_widgets_lib/numberfield.md index dc98c2f..c847dab 100644 --- a/src/next/widgets/aria_widgets_lib/numberfield.md +++ b/src/next/widgets/aria_widgets_lib/numberfield.md @@ -51,6 +51,23 @@ You can use formatting patterns to specify how a number should be conventionally The supported patterns are a subset of the [java.text.DecimalFormat](http://download.oracle.com/javase/1.4.2/docs/api/java/text/DecimalFormat.html) specs. More information are available at [localization_and_resources](localization_and_resources). +## Error messages customization + +Please refer to the main article concerning default [error messages customization](error_messages_customization). + +Here is the list of error messages that can be customized, with for each: + +- the key to be used in the configuration map +- its description +- its hard-coded default value + +Messages: + +- validation + - key: `validation` + - description: for wrong input's value format, resulting in the impossibility to interpret it for the widget's value + - default hard-coded: `"Number field must be a numerical value."` + ## Sample usage The following sample shows how to create and use a NumberField widget, with a mandatory attribute for error checking and number format patterns. diff --git a/src/next/widgets/aria_widgets_lib/timefield.md b/src/next/widgets/aria_widgets_lib/timefield.md index 2e10156..ced327d 100644 --- a/src/next/widgets/aria_widgets_lib/timefield.md +++ b/src/next/widgets/aria_widgets_lib/timefield.md @@ -32,6 +32,23 @@ Indeed, default time patterns at the application level can be overridden and/or Please keep in mind that "setEnvironment" will override all settings, use "updateEnvironment" to update one property. +## Error messages customization + +Please refer to the main article concerning default [error messages customization](error_messages_customization). + +Here is the list of error messages that can be customized, with for each: + +- the key to be used in the configuration map +- its description +- its hard-coded default value + +Messages: + +- validation + - key: `validation` + - description: for wrong input's value format, resulting in the impossibility to interpret it for the widget's value + - default hard-coded: `"Please enter a valid time format, for example: 1000 or 10:00"` + ## Sample usage The following sample shows how to create and use a TextField widget, packed with number format patterns. diff --git a/src/next/widgets/around_widgets/error_messages_customization.md b/src/next/widgets/around_widgets/error_messages_customization.md new file mode 100644 index 0000000..f791d20 --- /dev/null +++ b/src/next/widgets/around_widgets/error_messages_customization.md @@ -0,0 +1,64 @@ +Title: Error messages customization + + + +It is possible to customize the error messages that are displayed upon validation of a widget's input field's content. + +There are two levels of customization, from the most specific (highest priority) to the least specific (lowest priority): + +- per instance of the widget +- globally + +If you don't customize the messages, an hard-coded default value will be used. + +To wrap-up this gives the following resolution order: + +1. widget's configuration +2. global configuration +3. widget's hard-coded value + +Now, let's see how you can customize the messages in practice. + +## Locally (per widget instance) + +Each widget for which its default error messages can be customized will accept a specific property in its configuration object: `defaultErrorMessages`. + +This property holds an object used as a map of messages. Each message has been given a key which can be specified in this map. The actual set of messages and their names is specific to each widget. + +This property can be set statically: + + + +or it can be bound: + + + +considering there is a data model set as: + + + +## Globally + +### Where? + +The global configuration is held in the __application environment__. + +The application environment is managed by the specific class [`aria.core.AppEnvironment`](http://ariatemplates.com/aria/guide/apps/apidocs/#aria.core.AppEnvironment) which provides generic methods to alter the configuration. + +In practice there is one important method, with one important parameter: [`setEnvironment`](http://ariatemplates.com/aria/guide/apps/apidocs/#aria.core.AppEnvironment:setEnvironment:method), whose third parameter tells whether the configuration provided as argument should override the whole configuration or not. Please see the API documentation page for reference. + +### How? + +What you need to know then is the sequence of keys you need to specify for this configuration store. + +First, since this is related to widgets' settings, the root key in this store is `widgetSettings`. Then, as you want to customize the default error messages, the sub-key is `defaultErrorMessages`, as for the property in widgets' local configuration. + +This key holds an object used as a map between widgets and default error messages. Therefore the first level of keys will correspond to the names of the widgets for which error message can be customized. For instance: `DateField`. + +Finally, the value associated to each widget will correspond exactly to what the specific widget's configuration can accept for its default error messages customization. + +Here's an example to make it clearer: + + + +Note the last argument set to `true`, which indicates to do a recursive update of the objects instead of replacing the whole `widgetSettings` property's value with the provided argument (thus erasing all other related configurations).