Layout

Object Layout

The org.apache.causeway.applib.layout.grid and org.apache.causeway.applib.layout.component packages together define a number of classes that allow the layout of domain objects (entities and view models) to be customized. These classes fall into two main categories:

grid classes, that define a grid structure of rows, columns, tab groups and tabs, and;
common component classes, that capture the layout metadata for an object’s properties, collections and actions. These are bound (or associated) to the regions of the grid

The framework provides an implementation of the grid classes modelled closely on Bootstrap, along with Web UI (Wicket viewer) components capable of rendering that grid system. In principle it is also possible to extend the layout architecture for other grid systems. The component classes, though, are intended to be reusable across all grid systems.

The component classes, meanwhile, are broadly equivalent to the "layout" annotations (@PropertyLayout, @CollectionLayout, @ActionLayout and @DomainObjectLayout

All of the classes in this package are JAXB-annotated, meaning that they can be serialized to/from XML (the component classes in the https://causeway.apache.org/applib/layout/component XSD namespace, the bootstrap 3 grid classes in the https://causeway.apache.org/applib/layout/grid/bootstrap3 XSD namespace). This ability to serialize to/from XML is used by the GridLoaderService, the default implementation of which reads the grid layout for a domain class from a .layout.xml file on the classpath. It also allows the grid to be exposed through the REST API provided by the REST API (Restful Objects viewer), as either XML or JSON.

The various components (properties, collections, actions and domain object) also allow a link to be associated with each. These links are populated by the framework automatically when exposing the object layout grid through the REST API, pointing back to the standard Restful Objects resources. This design greatly assists in the implementation of generic REST clients.

Component

The component classes reside in the org.apache.causeway.applib.layout.component package, and consist of:

FieldSet

A fieldset (sometimes also called a property group or member group) of a number of the domain object’s properties (along with any associated actions of those properties).
layout data classes, which correspond to the similarly named annotations:
- PropertyLayoutData, corresponding to the @PropertyLayout annotation;
- CollectionLayoutData, corresponding to the @CollectionLayout annotation;
- ActionLayoutData, corresponding to the @ActionLayout annotation;
- DomainObjectLayoutData, corresponding to the @DomainObjectLayout annotation.

In addition, the component package includes Grid, representing the top level container for a custom layout for a domain object. Grid itself is merely an interface, but it also defines the visitor pattern to make it easy for validate and normalize the grid layouts. The GridAbstract convenience superclass provides a partial implementation of this visitor pattern.

The XSD for these classes is available at https://causeway.apache.org/applib/layout/component/component.xsd.

Bootstrap Grid

The bootstrap grid classes are modelled closely on Bootstrap. Bootstrap’s grid system divides the page width equally into 12 columns, and so each column spans 1 or more of these widths. Thus, a column with a span of 12 is the full width, one with a span of 6 is half the width, one with a span of 4 is a third of the width, and so on.

When specifying the span of a column, Bootstrap also allows a size to be specified (XS, SM, MD, LG). The size determines the rules for responsive design. Apache Causeway defaults to MD but this can be overridden. It is also possible to specify multiple size/spans for a given column.

The grid classes provided by Apache Causeway reside in the org.apache.causeway.applib.layout.grid.bootstrap3 package, and consist of:

BSGrid

Consists of a number of BSRows.

This class is the concrete implementation of Grid interface, discussed previously. As such, it extends the Grid.Visitor to iterate over all of the Rows of the grid.
BSRow

A container of BSCols. This element is rendered as <div class="row">.
BSCol

A container of almost everything else. A column most commonly contains properties (grouped into FieldSets, described above) or collections (specified by CollectionLayoutData, also above). However, a Col might instead contain a BSTabGroup (described below) in order that the object members is arranged into tabs.

It is also possible for a Col to contain the object’s title/icon (using DomainObjectLayoutData) or indeed arbitrary actions (using `ActionLayoutData).

Finally, a BSCol can also contain other BSRows, allowing arbitrarily deep hierarchies of containers as required.

This element is rendered as, for example, <div class="col-md-4"> (for a size MD, span of 4).
BSTabGroup

A container of BSTabs.
BSTab

A container of BSRows, which will in turn contain BSCols and thence ultimately the object’s members.

There are also two close cousins of Col, namely ClearFixVisible and ClearFixHidden. These map to Bootstrap’s responsive utility classes, and provide greater control for responsive designs.

As you can probably guess, the BSGrid is the top-level object (that is, it is JAXB @XmlRootElement); this is the object that is serialized to/from XML.

All of these classes also allow custom CSS to be specified; these are added to the CSS classes for the corresponding <div> in the rendered page. The application.css file can then be used for application-specific CSS, allowing arbitrary fine-tuning of the layout of the page.

The XSD for these classes is available at https://causeway.apache.org/applib/layout/menubars/bootstrap3/menubars.xsd.

Link

The link classes reside in the org.apache.causeway.applib.layout.links package, and consist of just the Link class:

import lombok.Getter;

public class Link  {
    @Getter
    private String rel;         (1)
    @Getter
    private String method;      (2)
    @Getter
    private String href;        (3)
    @Getter
    private String type;        (4)
    ...
}

1	a "rel" (as defined by section 2.7.1.2 of the RO spec v1.0), identifying the nature of the link.
2	the HTTP method to access the link. This is always "GET".
3	The (absolute) URL to access the Restful Objects resource.
4	The media type (`Accept` header) that will be returned by the URL.

The XSD for these classes is available at https://causeway.apache.org/applib/layout/links/links.xsd.

MenuBars Layout

The org.apache.causeway.applib.layout.menubars package and subpackages define a number of interfaces classes that allow the layout of domain service actions to be organised across menu bars, menus and menu sections.

The classes define a hierarchical structure of menu bars, menus and menu sections. Similar to the object layout classes, the concrete menu classes support bootstrap3; support for other layout systems is possible.

The component class ServiceActionLayoutData defines action metadata, being broadly equivalent to the "layout" annotations for actions, ie @ActionLayout. This is similar to the ActionLayoutData component class used for object layouts, but also captures the identity of the "owning" domain service. Service actions are grouped into menu sections.

All of the classes in this package are JAXB-annotated, meaning that they can be serialized to/from XML (in the https://causeway.apache.org/applib/layout/menubars/bootstrap3 XSD namespace). This ability to serialize to/from XML is used by the MenuBarsLoaderService, the default implementation of which reads the grid layout for a domain class from a .layout.xml file on the classpath. It also allows the menu bars to be exposed through the REST API provided by the REST API (Restful Objects viewer), as either XML or JSON.

The service action component also allows a link to be associated with it. Each such link is populated by the framework automatically when exposing the menu bars layout through the REST API, pointing back to the standard Restful Objects resources. This design greatly assists in the implementation of generic REST clients.

Menus

The menu classes reside in the org.apache.causeway.applib.layout.menubars.bootstrap3 package, consisting of:

BSMenuBars

The top-level structure that define three fields: a primary BSMenuBar, secondary BSMenuBar and tertiary BSMenuBar. The Web UI (Wicket viewer) places the primary bar to the left, the secondary bar aligned right, and the tertiary bar (expected to consist of just one BSMenu) under the user names.
BSMenuBar

consisting of one or many BSMenus.
BSMenu

consisting of one or many BSMenuSections. The Web UI (Wicket viewer) renders a separator between each section.
BSMenuSection

consisting of one or many actions (ServiceActionLayoutDatas)

Components

The service action class reside in the org.apache.causeway.applib.layout.component package, consisting of just:

ServiceActionLayoutData class

which correspond to the @ActionLayout annotation.

This is similar to ActionLayoutData (of the object layout classes), however it also identifies the domain service to which it belongs. (This isn’t required for the object layouts because the owner in that case is implicit).

Link

The link classes reside in the org.apache.causeway.applib.layout.links package, and consist of just the Link class.

The XSD for these classes is available at https://causeway.apache.org/applib/layout/links/links.xsd.