feat ariatemplates/ariatemplates#1427 Customization of widget's error messages

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

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)

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.
 
-<iframe class='samples' src='%SNIPPETS_SERVER_URL%/samples/github.com/ariatemplates/documentation-code/samples/widgets/autocomplete/onchange/' ></iframe>
+<iframe class='samples' src='%SNIPPETS_SERVER_URL%/samples/github.com/ariatemplates/documentation-code/samples/widgets/autocomplete/onchange/' ></iframe>
+
+## 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."`

src/next/widgets/aria_widgets_lib/datefield.md

@@ -8,6 +8,7 @@ The whole list of configuration parameters is available in [DateFieldCfg bean](h
 <iframe class='samples' src='%SNIPPETS_SERVER_URL%/samples/github.com/ariatemplates/documentation-code/samples/widgets/datefield/' ></iframe>
 
 ## Binding
+
 The "value" property in the dateField is bind-able and can be bound to a property in the data model.
 <iframe class='samples' src='%SNIPPETS_SERVER_URL%/samples/github.com/ariatemplates/documentation-code/samples/widgets/datefield/binding/' ></iframe>
 
@@ -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.
+* 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."`

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.

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.

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:
+
+<script src='%SNIPPETS_SERVER_URL%/snippets/github.com/ariatemplates/documentation-code/snippets/widgets/DefaultErrorMessages.tpl?tag=static&lang=at&outdent=true'></script>
+
+or it can be bound: 
+
+<script src='%SNIPPETS_SERVER_URL%/snippets/github.com/ariatemplates/documentation-code/snippets/widgets/DefaultErrorMessages.tpl?tag=bound&lang=at&outdent=true'></script>
+
+considering there is a data model set as: 
+
+<script src='%SNIPPETS_SERVER_URL%/snippets/github.com/ariatemplates/documentation-code/snippets/widgets/DefaultErrorMessagesScript.js?tag=datamodel&lang=at&outdent=true'></script>
+
+## 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: 
+
+<script src='%SNIPPETS_SERVER_URL%/snippets/github.com/ariatemplates/documentation-code/snippets/widgets/DefaultErrorMessagesScript.js?tag=global&lang=at&outdent=true'></script>
+
+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).