-
Notifications
You must be signed in to change notification settings - Fork 17
WContainer
WContainer is a particularly remarkable WComponent and one which is rarely considered: but ought be. WContainer is remarkable because it has absolutely no UI artifact or impact. It does not exist in the XML output by the WComponents Java and does not, therefore have a transform or any client side code.
WContainer is used to group other WComponents. These can then be manipulated as if they were a single component. So, for example, a group of WComponents may be placed in a single layout cell by placing them into a WContainer. For UI purposes WContainer may be used to group components into a single unit for layout purposes.
One may expect that WContainer will be used by developers for grouping without UI artifacts. WContainer, however, looks remarkably like a WPanel with no type when looking at a UI wireframe, since they both have no direct "appearance" in the UI. WPanel will always output at least two HMTL elements which will add weight to your UI and therefore reduce performance. WContainer does not do this. Once a WPanel has a Layout applied then many more UI artefacts may be created with at least one extra wrapper for each component added to the layout (see WComponents without UI artefacts for a detailed discussion of the side effects of this).
/* add a WCheckBox `cb` to a WFieldLayout `layout` with WLabel `label`,
and the WCheckBox is a trigger for a WAjaxControl `control` which
affects a WComponent `target` elsewhere in the UI. To ensure the
WCheckBox and the WAjaxControl are added to the UI correctly one
can use a WContainer as the component to add: */
WContainer cbAndControllerContainer = new WContainer();
cbAndControllerContainer.add(cb);
cbAndControllerContainer.add(control);
layout.addField(label, cbAndControllerContainer);If an application does not need to address a group of components as a group (for WAjaxControl or WSubordinateControl targetting for example) then one should explicitly specify WContainer to remove any possible ambiguity.
When constructing a container WComponent which accepts a content element in the constructor (such as WCollapsible or WTab it is almost always best to construct the container using a WContainer as the content element. The only real exception to this is if the outer container component's content will consist of exactly one other layout component which requires some layout specification (such as a WPanel with a Layout, a WTable, a WFieldLayout or a WFieldSet).
WContainer content = new WContainer();
WTab tab = new WTab(content, TAB_TITLE, WTabSet.TabMode.LAZY);
// then add stuff to `content`.WContainer may be used to create a naming context rather than using a separate WNamingContext.
WContainer should not be specified if the grouped components are already grouped in some other way, for example in a FlowLayout, WFieldLayout or WFieldSet. If the group of components has a semantic meaning then WContainer is probably inappropriate and WFieldSet, WCollapsible or a WPanel of a particular type may be more appropriate.
WContainer has no UI artifact and therefore cannot be used as a target for WAjaxControl or WSubordinateControl, therefore one ought use a WPanel with no type for a group which needs to be the target of one of these (unless the target is otherwise grouped, such as in a WFieldSet).
If grouping a set of radio buttons or check boxes one should consider WRadioButtonSelect or WCheckBoxSelect. If grouping a set of individual WRadioButtons or WCheckBoxes as "answers" to a single "question" (where the equivalent pre-grouped component is unsuitable) then one should use WFieldSet and WFieldLayout.
For general layout one should consider a WPanel with a layout but groups within a "cell" of a layout may be suitable candidates for WContainer.
WContainer has a single default constructor.
WContainer container = new WContainer();That is all there is (then let's keep dancing).