Migrate ConfigureInputFieldsToGuideDataEntry

7 files changed, 120 insertions, 0 deletions

diff --git a/documentation/articles/ConfigureInputFieldsToGuideDataEntry.asciidoc b/documentation/articles/ConfigureInputFieldsToGuideDataEntry.asciidoc
new file mode 100644
index 0000000000..628af4ec1c
--- /dev/null
+++ b/documentation/articles/ConfigureInputFieldsToGuideDataEntry.asciidoc
@@ -0,0 +1,119 @@
+[[configure-input-fields-to-guide-data-entry]]
+Configure input fields to guide data entry
+------------------------------------------
+
+[[field-size]]
+Field size
+^^^^^^^^^^
+
+There are a number of tricks we can use to help users understand what
+kind of values we expect them to enter into a field, without resorting
+to tooltips, footnotes or excessively long captions. Consider the form
+below:
+
+image:img/form1.png[Basic form]
+
+The shape, size and layout of these fields don’t really correspond to
+the kinds of values expected to be entered in them, or to the relations
+between different fields. For instance, while the homepage url is
+probably between 25 and 55 characters long, european postal codes are
+only about 6 digits long, and age maxes out at three digits. By setting
+the widths of these fields to be approximately proportional to the
+lengths of expected values, the fields become easier to identify, and
+the entire form feels more friendly and less monotonous:
+
+image:img/form2.png[Form with different input widths]
+
+Please note that there is no point in trying to _match_ the _exact_
+lengths of expected values – the positive effect here relies more on the
+sizes of fields _relative to each other_ than on specific widths. Also
+note that it’s important not to make the shortest fields too short just
+to distinguish them from longer ones. An address field that can only
+display 10 characters at a time would be really annoying.
+
+An easy way to set field widths to approximately a certain number of
+characters is to set the component’s widths using
+http://en.wikipedia.org/wiki/Em_(typography)[Em units], found in
+Vaadin’s *Sizeable.Unit* enum. One *Em* is approximately the width of
+(actually usually slightly wider than) an uppercase M.
+
+[source,java]
+....
+TextField tfPostalCode = new TextField("Postal code");
+tfPostalCode.setWidth(6, Unit.EM);
+....
+
+This was all about the _width_ of input fields, since most input fields
+are single-line. Fields for which you expect more than a few words of
+text should of course be multi-line *TextAreas*. While the height of a
+*TextArea* might not be as important as the width of a *TextField*
+(since it has scrollbars), it’s still a good idea to set both the width
+and the height of a *TextArea* to roughly match the amount of text you
+expect people to enter. A bigger *TextArea* encourages the user to enter
+more text into it, while a smaller area suggests that perhaps a few
+carefully chosen words is enough, thank you very much.
+
+[[component-grouping]]
+Component grouping
+^^^^^^^^^^^^^^^^^^
+
+Some of the fields in the above example clearly “belong together”. First
+and last name. Street address, postal code, city and country. By
+changing the layout slightly, moving the most closely related fields to
+the same line and adding a little spacing between groups of related
+fields the fields become even easier to identify, and the form easier to
+understand in a single glance:
+
+image:img/form3.png[Form with grouped inputs]
+
+(See layout component sections in Tutorial and Book of Vaadin to see how
+this is done in Vaadin.)
+
+[[input-prompts]]
+Input prompts
+^^^^^^^^^^^^^
+
+An input prompt is a placeholder text inside an input field that
+disappears as soon as a value is entered into the field. Many input
+components in Vaadin have a *setInputPrompt()* method for this:
+
+[source,java]
+....
+TextField tfSearch = new TextField();
+tfSearch.setInputPrompt(“Search by keywords”);
+....
+
+One use for input prompts is as an alternative to a separate *caption*.
+This can be useful especially if there is very little space for the
+field, or if you wish to reduce the visual clutter of your UI. A common
+example is a search or text-filter field with an input prompt like
+_“Search by keywords”_ or _“Filter by name”_ :
+
+image:img/searchfield.png[Search field with prompt]
+
+The decision to use input prompts as captions should not be taken
+lightly, however. Keep in mind that the input prompt disappears as soon
+as any text is entered into the field, so the user will have to remember
+what the field was for, or be able to deduce its identity from its
+current value. In the example above, with just a single search field, or
+even in a login form with username and password fields, this is
+acceptable. In a significantly longer form, however, especially one that
+the user might wish to read through before submitting to check that
+everything has been correctly entered, this approach quickly turns into
+a problem.
+
+Another way to use input prompts is for displaying *additional
+information* about the field, such as the expected *format*, or the
+*types of values that are accepted*. This is quite similar to
+*tooltips*, with the difference that the input prompt must be kept short
+enough to fit into the field itself, and that it is immediately visible,
+without hovering over the field with the mouse pointer. For this reason,
+input prompts are useful on touch screens, as opposed to tooltips.
+
+A good example of indicating the types of values a fields accepts is a
+_Location_ field where you can enter a street address, a postal code or
+just the name of the city. These details are probably too long to fit in
+the field’s caption, and might not be discoverable enough in a tooltip.
+An input prompt briefly explaining the options is an excellent solution:
+
+image:img/locationfield.png[Input field with prompt]
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index b0987aee5b..18c1bf8f60 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -89,3 +89,4 @@ are great, too.
 - link:ViewChangeConfirmations.asciidoc[View change confirmations]
 - link:CreatingABookmarkableApplicationWithBackButtonSupport.asciidoc[Creating a bookmarkable application with back button support]
 - link:BroadcastingMessagesToOtherUsers.asciidoc[Broadcasting messages to other users]
+- link:ConfigureInputFieldsToGuideDataEntry.asciidoc[Configure input fields to guide data entry]
diff --git a/documentation/articles/img/form1.png b/documentation/articles/img/form1.png
new file mode 100644
index 0000000000..52ab03bb28
--- /dev/null
+++ b/documentation/articles/img/form1.png
diff --git a/documentation/articles/img/form2.png b/documentation/articles/img/form2.png
new file mode 100644
index 0000000000..25f6374fdd
--- /dev/null
+++ b/documentation/articles/img/form2.png
diff --git a/documentation/articles/img/form3.png b/documentation/articles/img/form3.png
new file mode 100644
index 0000000000..dde67b305f
--- /dev/null
+++ b/documentation/articles/img/form3.png
diff --git a/documentation/articles/img/locationfield.png b/documentation/articles/img/locationfield.png
new file mode 100644
index 0000000000..e654776002
--- /dev/null
+++ b/documentation/articles/img/locationfield.png
diff --git a/documentation/articles/img/searchfield.png b/documentation/articles/img/searchfield.png
new file mode 100644
index 0000000000..3690b92eaf
--- /dev/null
+++ b/documentation/articles/img/searchfield.png