Update general Component documentation

Part of vaadin/framework8-issues#538

1 files changed, 51 insertions, 6 deletions

diff --git a/documentation/components/components-combobox.asciidoc b/documentation/components/components-combobox.asciidoc
index b5eb92de7e..ccd75a3dc5 100644
--- a/documentation/components/components-combobox.asciidoc
+++ b/documentation/components/components-combobox.asciidoc
@@ -24,12 +24,6 @@ Components">>.
 .The [classname]#ComboBox# Component
 image::img/combobox-basic.png[width=35%, scaledwidth=50%]
 
-[classname]#ComboBox# supports adding new items when the user presses
-kbd:[Enter].
-ifdef::web[]
-See <<dummy/../../../framework/components/components-selection#components.selection.newitems,"Allowing Adding New Items">>.
-endif::web[]
-
 [[components.combobox.filtering]]
 == Filtered Selection
 
@@ -73,6 +67,57 @@ containing the input string. As shown in <<figure.components.combobox.filter>>
 below, when we type some text in the input area, the drop-down list will show
 all the matching items.
 
+[[components.combobox.newitems]]
+== Allowing Adding New Items
+
+[classname]#ComboBox# allows the user to add new items, when the user types
+in a value and presses kbd:[Enter]. You need to enable this with
+[methodname]#setNewItemHandler()#.
+
+Adding new items is not possible if the selection component is read-only. An
+attempt to do so may result in an exception.
+
+
+=== Handling New Items
+
+Adding new items is handled by a [interfacename]#NewItemHandler#, which gets the
+item caption string as parameter for the [methodname]#accept(String)# method.
+
+
+[source, java]
+----
+// List of planets
+List<Planet> planets = new ArrayList<>();
+planets.add(new Planet(1, "Mercury"));
+planets.add(new Planet(2, "Venus"));
+planets.add(new Planet(3, "Earth"));
+planets.add(new Planet(4, "Mars"));
+
+ComboBox<Planet> select =
+    new ComboBox<>("Select or Add a Planet");
+select.setItems(planets);
+
+// Use the name property for item captions
+select.setItemCaptionGenerator(Planet::getName);
+
+// Allow adding new items and add
+// handling for new items
+select.setNewItemHandler(inputString -> {
+
+    // Create a new bean - can't set all properties
+    Planet newPlanet = new Planet(planets.size(), inputString);
+    planets.add(newPlanet);
+
+    // Update combobox content
+    select.setItems(planets);
+
+    // Remember to set the selection to the new item
+    select.select(newPlanet);
+
+    Notification.show("Added new planet called " +
+                      inputString);
+});
+----
 
 [[components.combobox.css]]
 == CSS Style Rules