Layout Defaulting

In builder it is possible to affect the layout used to present content in many ways, the simplest of these is likely to be the default layout functionality in theme administration or through setting the global layout.

Space layout defaulting

When a space is displayed the following sequence is observed when working out which layout should be used

1. URL parameters
2. latched layout
3. use-layout
4. space layout selection
5. space default selection
6. global layout selection
7. builder default layout

Global layout defaulting

When a 'global' page is displayed the sequence changes to become

1. URL parameters
2. latched layout
3. use-layout
4. global layout selection
5. builder default layout

URL parameters

It is possible to override the layout used on any page through the use of the &layoutId=LAYOUTID url parameter, this override will take precedence over all layout selections and is most useful when combined with the &latch=true parameter when you wish to provide a URL for use on an device with special display needs, such as a blackberry or smart-phone,eg:

http://www.adaptavist.com/display/builder/Layout+Defaulting?layoutId=DEFAULT&latch=true

to clear the latch, do not specify a layout:

http://www.adaptavist.com/display/builder/Layout+Defaulting?latch=false

Latched layouts

You can specify a layout to be latched either through the URL as shown above, or through the {use-layout:LAYOUTID|latch=true} macro ... this will force the rest of the user's session to be displayed through the latched layout unless the user comes across another url/macro that latches them to a different layout, or unlatches the layout selection.

{use-layout} macro

The use-layout macro can be used to override the default layout selection on a page-by-page basis, it may also be used to define/undefine a latch, it is often used in combination with the builder-show macro to change the layout based on the content being viewed or even the platform viewing the content (eg: blackberry).

Space Layout Selection

The space layout chooser defines the layout that has been selected for that space, if no layout has been specifically chosen for that space the default layout for that type of space (global/personal) will be used.

Default layout selection

The default layout selection defines the layout that should be used when a space does not have its own layout selected, if there is no default layout selected then the global layout will be used.

Global Layout Selection

This selection is similar to as the space-layout in that it uses the layout chooser to define which layout should be used for global pages (eg dashboard), if no global layout has been chosen then the inbuilt builder DEFAULT layout will be used.

The DEFAULT layout

The DEFAULT layout is a read-only base of internal default data that all layouts can inherit from, it allows new features to be added while providing sensible default values for those features. It is very basic so as to interfere as little as possible with your custom layouts built on top of it, however this means that it's more than a little ugly!