Skip to end of metadata
Go to start of metadata

{use-layout} macro

(info) Requires Theme Builder 3 or above

This macro allows you to automatically change the layout used for a specific page, optionally latching that layout for the rest of the user's session.

(warning) page under construction - see wiki notation guide (when editing a page using wiki markup mode) for more info








The ID of the layout to use




Whether to latch the layout for subsequent page views throughout the site:

  • false – only change the layout for this page
  • true – change the layout for all pages


Hints and Tips

You can use this macro to create URLs for mobile phone users, etc., that will automatically select an appropriate layout when accessed.

 Show me how...

Create a page in a public space and give it a short title, for example: "Mobiles".

If you want a short URL for the page, ideal for sending in a SMS message, use the Tiny URL shown on the page information view or alternatively put the page-info macro on the page to display it:


Latch the desired layout (eg. a layout with id "mobile" that's designed for small screen mobile phones) with the following:


You can display a welcome message on that page or alternatively redirect to another page using the redirect macro:

  • No labels


  1. Unknown User (davidchapmanattpt)

    I'm looking at implementing a light weight layout for PDA devices. The problem I'm running into is our default layout is pretty heavy and even 3G phones tremble trying to load it. Is there a way to detect the user agent and redirect accordingly?

    I know this isn't entirely related.

    1. Unknown User (amoran)

      {builder-show:agent=String to be present in user agent} ... {builder-show}

      builder-show macro

  2. Unknown User (simonwheatley)

    Is it possible to trigger the use-layout behaviour with a URL GET parameter, as below?

    1. Unknown User (gfraser)

      builder-show/hide macros have URL-based switching in recent versions.

      EDIT: I think? Check the notation guide for the macros (the docu in this space might not be up to date)

      1. Unknown User (simonwheatley)

        Ah. So (after you explained it to me on IM (smile) ) I think I understand:


        It doesn't look like there's the ability in builder-show to inspect GET params on the URL. Would this be possible/difficult to add?

        1. Unknown User (amoran)

          the use-layout functionality is a by-product of the url GET functionality ... ie: the url GET functionality came first!!!!

          the parameters you are looking for are layout=XXXX&latch=true (wink)

          1. Unknown User (simonwheatley)

            That's excellent. Thanks Alain!

          2. Unknown User (

            Is there a way to use use-layout and latch to the default confluence theme? Or make certain action pages use the default confluence theme instead of theme builder themes?

            1. Unknown User (amoran)

              Not exactly - the confluence theming architecture doesn't allow anything remotely resembling use-layout or the layout= url parameter, once a theme has been chosen for a space then you are stuck with that theme.

              However there is a workaround ... you can install the CONFLUENCE210 layout and set that as your default builder layout & switch about between builder layouts as needed.

              I would recommend using Builder 4.0.2 or later for this since in 4.0.2 we have resolved many of the issues that the builder menu code was having with the confluence jQuery driven links - there are still some outstanding problems with the favourite & watch links, however these are close to being resolved

  3. Unknown User (davef)

    Rant retracted. Functionality found under View, other pages menu.

    1. Unknown User (amoran)

      If you wish to reproduce the standard atlassian look & feel then install the confluence 2.10 layout & base your layout on that.

      The default builder layout is kept as basic as possible to avoid interfering with any customisations that you wish to build on top of it.

      As to the lack of pre-built layouts - yes we know this is an issue, however the layouts we build for clients belong to those clients, as such we are not at liberty to give them away.

      If however you build a layout & would like to contribute to the layout library then feel free to create an issue on and I'll do my best to check through it for anything untoward & then post it up to the library crediting you for it's creation.

  4. Unknown User (

    Can latching be used so that it only applies to a given layout. If I create a link that changes and latches a layout, the latch would only apply to pages that use a specific layout. Can I check for a latch?