From: Erik Lumme Date: Wed, 13 Sep 2017 11:59:17 +0000 (+0300) Subject: Migrate ConfigureInputFieldsToGuideDataEntry X-Git-Tag: 8.2.0.alpha2~64^2~3 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=refs%2Freviewable%2Fpr9959%2Fr50;p=vaadin-framework.git Migrate ConfigureInputFieldsToGuideDataEntry --- 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 Binary files /dev/null and b/documentation/articles/img/form1.png differ diff --git a/documentation/articles/img/form2.png b/documentation/articles/img/form2.png new file mode 100644 index 0000000000..25f6374fdd Binary files /dev/null and b/documentation/articles/img/form2.png differ diff --git a/documentation/articles/img/form3.png b/documentation/articles/img/form3.png new file mode 100644 index 0000000000..dde67b305f Binary files /dev/null and b/documentation/articles/img/form3.png differ diff --git a/documentation/articles/img/locationfield.png b/documentation/articles/img/locationfield.png new file mode 100644 index 0000000000..e654776002 Binary files /dev/null and b/documentation/articles/img/locationfield.png differ diff --git a/documentation/articles/img/searchfield.png b/documentation/articles/img/searchfield.png new file mode 100644 index 0000000000..3690b92eaf Binary files /dev/null and b/documentation/articles/img/searchfield.png differ