diff options
Diffstat (limited to 'documentation/components/components-customcomponent.asciidoc')
| -rw-r--r-- | documentation/components/components-customcomponent.asciidoc | 39 |
1 files changed, 26 insertions, 13 deletions
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: |