Add documentation for Composite

3 files changed, 31 insertions, 18 deletions

diff --git a/documentation/application/application-architecture.asciidoc b/documentation/application/application-architecture.asciidoc
index c2dec0443e..5e87ea8531 100644
--- a/documentation/application/application-architecture.asciidoc
+++ b/documentation/application/application-architecture.asciidoc
@@ -117,8 +117,8 @@ While extending layouts is an easy way to make component composition, it is a
 good practice to encapsulate implementation details, such as the exact layout
 component used. Otherwise, the users of such a composite could begin to rely on
 such implementation details, which would make changes harder. For this purpose,
-Vaadin has a special [classname]#CustomComponent# wrapper, which hides the
-content representation.
+Vaadin has the special wrappers [classname]#Composite# and
+[classname]#CustomComponent#, which hide the content representation.
 
 
 [source, java]
@@ -144,9 +144,9 @@ class MyView extends CustomComponent {
 MyView myview = new MyView();
 ----
 
-For a more detailed description of the [classname]#CustomComponent#, see
+For a more detailed description of [classname]#Composite# and [classname]#CustomComponent#, see
 <<dummy/../../../framework/components/components-customcomponent#components.customcomponent,"Composition
-with CustomComponent">>.
+with Composite and CustomComponent">>.
 
 
 [[application.architecture.navigation]]
diff --git a/documentation/application/application-overview.asciidoc b/documentation/application/application-overview.asciidoc
index d6012f7ffa..0e653da9bd 100644
--- a/documentation/application/application-overview.asciidoc
+++ b/documentation/application/application-overview.asciidoc
@@ -107,7 +107,7 @@ Interface Components">>, for layout components, see
 <<dummy/../../../framework/layout/layout-overview.asciidoc#layout.overview,"Managing
 Layout">>, and for compositing components, see
 <<dummy/../../../framework/components/components-customcomponent#components.customcomponent,"Composition
-with CustomComponent">>.
+with Composite and CustomComponent">>.
 
 Events and Listeners:: Vaadin Framework follows an event-driven programming paradigm, in which events, and
 listeners that handle the events, are the basis of handling user interaction in
diff --git a/documentation/components/components-customcomponent.asciidoc b/documentation/components/components-customcomponent.asciidoc
index 5529bf21be..01679a3f9b 100644
--- a/documentation/components/components-customcomponent.asciidoc
+++ b/documentation/components/components-customcomponent.asciidoc
@@ -1,11 +1,11 @@
 ---
-title: Composition with CustomComponent
+title: Composition with Composite and CustomComponent
 order: 32
 layout: page
 ---
 
 [[components.customcomponent]]
-= Composition with CustomComponent
+= Composition with Composite and CustomComponent
 
 The ease of making new user interface components is one of the core features of
 Vaadin. Typically, you simply combine existing built-in components to produce
@@ -15,15 +15,26 @@ the majority of the user interface.
 As described earlier in
 <<dummy/../../../framework/application/application-architecture#application.architecture.composition,"Compositing
 Components">>, you have two basic ways to create a composite - either by
-extending a layout component or the [classname]#CustomComponent#, which
-typically wraps around a layout component. The benefit of wrapping a layout
-composite in [classname]#CustomComponent# is mainly encapsulation - hiding the
+extending a layout component or by using a composition component (a
+[classname]#Composite# or a [classname]#CustomComponent#), which typically
+wraps around a layout component.
+The benefit of wrapping a layout composite is mainly encapsulation - hiding the
 implementation details of the composition. Otherwise, a user of the composite
 could rely on implementation details, which would create an unwanted dependency.
 
-To create a composite, you need to inherit the [classname]#CustomComponent# and
-set the __composition root__ component in the constructor. The composition root
-is typically a layout component that contains other components.
+IMPORTANT: The [classname]#Composite# component is currently being developed and only available in the Framework 8.1 prerelease versions, starting from 8.1.0.alpha6.
+
+To create a composite, you need to inherit [classname]#Composite# or
+[classname]#CustomComponent# and set the __composition root__ component in the
+constructor. The composition root is typically a layout component that contains
+other components.
+
+The difference between the two composition classes is that a
+[classname]#CustomComponent# introduces another layer in the DOM on the
+browser, which can be used e.g. for styling but does require its own size
+setting etc. On the other hand, a [classname]#Composite# is a more light-weight
+version that has no visual representation in the browser, and is effectively
+replaced by its contents.
 
 For example:
 
@@ -41,21 +52,23 @@ class MyComposite extends CustomComponent {
         panelContent.addComponent(label);
         panelContent.addComponent(new Button("Ok"));
 
+        // The composition root MUST be set
+        setCompositionRoot(panel);
+
         // Set the size as undefined at all levels
         panelContent.setSizeUndefined();
         panel.setSizeUndefined();
+        // this is not needed for a Composite
         setSizeUndefined();
-
-        // The composition root MUST be set
-        setCompositionRoot(panel);
     }
 }
 ----
 
 Take note of the sizing when trying to make a customcomponent that shrinks to
 fit the contained components. You have to set the size as undefined at all
-levels; the sizing of the composite component and the composition root are
-separate.
+levels. In the case of [classname]#CustomComponent#, the sizing of the composite
+component and the composition root are separate, whereas [classname]#Composite#
+delegates its size management to its composition root.
 
 You can use the component as follows: