Layout Defaulting

There seems to be some confusion about how to select the layout that is shown by default, this document hopes to make the situation clearer.

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=true

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

Space Layout Selection

When you use the choose-layout screen for a space, this defines the layout that has been selected for that space, if no layout has been specificly 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 id that should be used when a space does not have a specific layout selected, if there is no default layout selected then the global layout will be used

Global Layout Selection

This screen serves the same function as the space-layout selection in that it defines which layout should be used for global pages (eg dashboard), if no layout has been selected for global spaces then the inbuilt builder DEFAULT layout will be used