Migrate ChooseInputFieldComponentsWisely

8 files changed, 93 insertions, 0 deletions

diff --git a/documentation/articles/ChooseInputFieldComponentsWisely.asciidoc b/documentation/articles/ChooseInputFieldComponentsWisely.asciidoc
new file mode 100644
index 0000000000..d6e542f9e0
--- /dev/null
+++ b/documentation/articles/ChooseInputFieldComponentsWisely.asciidoc
@@ -0,0 +1,92 @@
+[[choosing-input-field-components-wisely]]
+Choosing input field components wisely
+--------------------------------------
+
+The core Vaadin framework has more than ten different input field
+components. Choosing the right one can improve your application’s
+usability significantly. Which component is the best fit in a certain
+situation depends on so many factors that it’s pretty much impossible to
+set down any specific rules. Nevertheless, here are some helpful
+pointers that might guide you in the right direction.
+
+[[textfield-or-selection-component]]
+Textfield or selection component?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**TextField**s are of course the most obvious choice in most cases.
+However, their inherent lack of restrictions requires that the user
+understands what kind of values are acceptable. They don't present any
+options to choose from, and, although you can restrict them to certain
+kinds of values e.g. by using **Converter**s, these restrictions are not
+immediately obvious to the user. Furthermore, if the UI in question is
+mostly mouse-operated, a *TextField* forces the user to move her hands
+to the keyboard to enter a value. Thus, a selection component can in
+many cases be more convenient for your users.
+
+[[optiongroup-and-checkbox]]
+OptionGroup and Checkbox
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+**OptionGroup**s are handy for very small sets of options (typically
+2-4). You can toggle between single-select (radiobuttons) and
+multi-select (checkboxes) with the *setMultiSelect(boolean)* method.
+Using an OptionGroups to present purely numerical options might be
+somewhat strange, though.
+
+image:img/optiongroup.png[OptionGroup]
+
+For binary either/or, yes/no options, a *CheckBox* is a natural choice.
+However, if the meaning of the "no" option (i.e. unchecked) is not
+completely obvious, or the "yes" (i.e. checked) option could be
+confusing by itself, a two-item single-select *OptionGroup* might be
+better, since it clearly states what both options represent.
+
+image:img/checkbox-vs-og.png[Checkbox vs OptionGroup]
+
+[[nativeselect]]
+NativeSelect
+^^^^^^^^^^^^
+
+The often-overlooked *NativeSelect* component is also convenient for
+small sets of options (up to 10 or so), and works great both for named
+items and small sets of numbers.
+
+image:img/nativeslect.png[NativeSelect]
+
+[[combobox]]
+ComboBox
+^^^^^^^^
+
+If the set of options is larger than about 10 items, a *ComboBox* might
+be a better choice, since it allows the user to search for a specific
+value to typing part of it, and supports lazy loading.
+
+image:img/combo.png[ComboBox]
+
+[[slider]]
+Slider
+^^^^^^
+
+The *Slider* is great for _quickly_ selecting a value from a wide range
+of values, _if precision is not that important_, such as audio volume,
+brightness, or any approximate value. (If precision is important it's
+much better to allow the user to manually enter the value, such as with
+a *TextField*.)
+
+image:img/slider.png[Slider]
+
+[[datefields]]
+DateFields
+^^^^^^^^^^
+
+The *PopupDateField* component, which opens a calendar popup for date
+selection, is great for entering dates and times. Remember to set the
+datefield's _resolution_ to something appropriate: seconds are hardly
+relevant in most cases, and sometimes all you need is the date.
+
+image:img/datefield.png[DateField]
+
+There’s also the *InlineDateField*, which is really just the
+*PopupDateField*’s datepicker without a textfield. It’s probably a bit
+too big to use in most forms, but if picking dates is one of the few
+tasks in a form, give it a try if you have the space.
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 462e6df4fc..2c71cb4d68 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -37,3 +37,4 @@ are great, too.
 - link:GeneratingDynamicResourcesBasedOnURIOrParameters.asciidoc[Generating dynamic resources based on URI or parameters]
 - link:OptimizingTheWidgetSet.asciidoc[Optimizing the widget set]
 - link:UsingServerInitiatedEvents.asciidoc[Using server-initiated events]
+- link:ChooseInputFieldComponentsWisely.asciidoc[Choose input field components wisely]
diff --git a/documentation/articles/img/checkbox-vs-og.png b/documentation/articles/img/checkbox-vs-og.png
new file mode 100644
index 0000000000..23b6fdc70f
--- /dev/null
+++ b/documentation/articles/img/checkbox-vs-og.png
diff --git a/documentation/articles/img/combo.png b/documentation/articles/img/combo.png
new file mode 100644
index 0000000000..fa3cbe8995
--- /dev/null
+++ b/documentation/articles/img/combo.png
diff --git a/documentation/articles/img/datefield.png b/documentation/articles/img/datefield.png
new file mode 100644
index 0000000000..8788130758
--- /dev/null
+++ b/documentation/articles/img/datefield.png
diff --git a/documentation/articles/img/nativeslect.png b/documentation/articles/img/nativeslect.png
new file mode 100644
index 0000000000..80843f404d
--- /dev/null
+++ b/documentation/articles/img/nativeslect.png
diff --git a/documentation/articles/img/optiongroup.png b/documentation/articles/img/optiongroup.png
new file mode 100644
index 0000000000..a22b6dcf10
--- /dev/null
+++ b/documentation/articles/img/optiongroup.png
diff --git a/documentation/articles/img/slider.png b/documentation/articles/img/slider.png
new file mode 100644
index 0000000000..01835f7686
--- /dev/null
+++ b/documentation/articles/img/slider.png