Theme Builder Plugin

[All Adaptavist Apps]

Page tree

  • Created by Unknown User (amoran), last modified on Dec 18, 2008

If you have need of switching layouts dependant on the context of the page being viewed, then you can achieve this through the {builder-show} and {builder-hide} macros, when used alongside the {use-layout} macro.

If for example you had a layout with no sidebars, but wanted to display the quick-help guide in the right-sidebar when in edit mode without needing to include the right-sidebar for general pages.

To do this, you would create a child layout to your main layout, lets call it EDITLAYOUT. In this child layout you then switch the right sidebar on and ensure it contains a copy of the {builder-infopanel} macro, and save your changes.

Then move back to the original (parent) layout and edit one of the panels, ideally the first one down the screen, so if you have the header panel switched on then use that, followed by the menu panel, navigation panel etc...

You will then need to enter code similar to this:

{builder-show:mode=edit}{use-layout:EDITLAYOUT}{builder-show}

This concept can be extended using the functionality of the builder-show/hide macros to select the layout based on any number of things, ranging from the user-agent (aka browser/platform) of the person viewing the page, to the kind of page being viewed, the user's permissions on that page, groups, labels, page title, parent page title, orphaned pages, for example:

Display blackberry layout based on browser

{builder-show:user-agent:BlackBerry}{use-layout:BLACKBERRY}{builder-show}

Display layout based on content age

{builder-show:olderthan=3m}{use-layout:OLDNEWS}{builder-show}

Display layout based on parent page title

{builder-show:title=forum|recurse=true}{use-layout:FORUM}{builder-show}

etc...

If you are unsure of the parameters you need for your use-case, please create an issue through tracker

  • No labels

19 Comments

  1. Unknown User (vmanuja)

    I wanted my Space's Home page to have a different layout (say LAYOUT02) than the rest of the site (say LAYOUT01). I put the following line in my Header Panel that already has code pertaining to LAYOUT01

    {builder-show:title=Home}{use-layout:LAYOUT02}{builder-show}
... <code for LAYOUT01>...

    both layouts use custom CSS.

    I found my Home page, had mixed elements from LAYOUT01 and LAYOUT02. Also, it seem to still execute <code for LAYOUT01>

    Both layouts utilize Custom CSS for page presentation.

    1. Does the 2nd layout has to be child of the main layout?
    2. If since both layouts have Custom CSS, does it matter if some of the styles/ classes share the same name? For instance, I had DIV.title for Home page (LAYOUT02) defined with H3, while DIV.title for the rest of the site (LAYOUT01) had it with H2

    1. Unknown User (gfraser)

      Earlier versions of Builder suffered with that problem - it should be fixed in more recent releases. Also I'd advise just putting the use-layout macro directly in to the home page because the home page might not always be called "Home" (you can edit it and change it's title, or choose a different home page in space admin, etc). I think there's an @home setting in builder-show/hide macros that can get around that issue though?

      1. Unknown User (amoran)

        There is no way currently to specify @home, although I can see that it would be a useful feature to add ... so I've added it to 3.4.0!

        I've also adjusted the naming of the parameters (the old ones will still be accepted, but may be deprecated in a distant future release), so from 3.4.0-M2 you will be able to use

        {builder-show:hastitle=@home}....{builder-show}

        Your other points:

        1. The second layout does not need to be a child of the main layout, you may use ANY layout you like (so long as it exists)
        2. The two layouts can be as different or as similar as you like, I'm not sure I understand what your concern is about.

        1. Unknown User (vmanuja)

          1. Maybe not, but the documentation seem to imply that the new layout has to be a child layout (... To do this, you would create a child layout to your main layout, lets call it EDITLAYOUT...; I figure it's illustrative only)
          2. I started off my Space (SPACE01) with LAYOUT01 that had most of the layout defined using Panel options (eg Header BG image, width, height, etc)
            1. LAYOUT01 utilized Custom CSS to mostly style text, left & right navs etc
          3. I decided to change my Home Page and started fresh on a new Space (SPACE02) and created Home page using LAYOUT02
            1. LAYOUT02 utilized Custom CSS to define most of the page elements (header, navigation, left nav, etc). However, I reused many Style names from LAYOUT01 CSS.

          When I tried to implement the changes from SPACE02 to SPACE01, as stated above, the resulting Home Page seem to have, for instance, images that were defined in LAYOUT01 and not in LAYOUT02... It seem, apropos to the code segment I indicated in the post above, <code for LAYOUT01> also got executed.

          I can send screenshots (to a personal email ID) if you need illustration. To be able to simply utilize different layouts for different sections of the Space was out main reason to not meddle with the default Confluence Velocity templates. So please advise.

          Using TB: 3.3.2 on conf 2.10.1

          1. Unknown User (gfraser)

            By default layouts inherit settings from their parents - including panel content, CSS, etc. If you're still having problems, please create a ticket on https://tracker.adaptavist.com and attach a backup (from Theme Administration) of your layout settings.

            1. Unknown User (vmanuja)

              that's what I thought and planned not to use child layout. LAYOUT01 and LAYOUT02 are at the same level.

              1. Unknown User (gfraser)

                Hrm, could be a bug in Builder. Could you try this:

                1. Remove the use-layout macro from the layout
                2. Add use-layout macro to the actual home page (ie. edit the wiki page, paste in the macro you removed from the theme layout)

                It's possible that having the layout switching taking place within the layout is carrying over some of the settings prior to the switch occuring. When you use the use-layout macro in a wiki page, it takes effect before the theme renders.

                If the above works, then it would indicate a problem with using use-layout macro within the theme layout itself.

                1. Unknown User (amoran)

                  There are no known issues WRT use-layout or the layout= parameters in builder 3.3.3

              2. Unknown User (amoran)

                Builder doesn't care where the layout is, or what it contains - it just applies it to the page as you tell it to, for instance the following links allow you to display this page with a variety of different layouts none of which are children of each other

                Unknown macro: {compound-menuitem}
                Unknown macro: {compound-menuitem}
                Unknown macro: {compound-menuitem}
                Unknown macro: {compound-menuitem}
                Unknown macro: {compound-menuitem}

                The above links use the layout= parameter from menulink to specify the layout to be used, this is implemented through the same mechanism as the use-layout macro.

                Perhaps if you open an issue and upload backups of your layouts then it will be simpler for you to explain your situation and allow us to offer a solution.

                1. Unknown User (gfraser)

                  From the initial description vmanuja gave, it sounds like the use-layout macro is being used within a theme panel, ie. it gets rendered during theme rendering stage, not the initial page rendering stage. As such, the existing layout is already being rendered when the use-layout takes affect and switches to a different layout - surely that will cause the layout settings to get mixed up a bit?

                  1. Unknown User (amoran)

                    It's complicated to fully explain, if ever you want a complete description of what goes on when you call use-layout button-hole me next time I'm passing.

                    In laymans terms, when you call use-layout as well as pre-setting the layout it flushes certain caches. This means that any processing done before with the old layout id will be ditched and the panels re-rendered as needed - hence the reason why we encourage you to insert the use-layout macros as high up your layout as possible: its position wont affect the operation of the macro/theme, but placing it low down in the layout (eg footnotes) will cause several panels to be rendered more than once which will slow down your response times.

                    1. Unknown User (vmanuja)

                      I figured. The issue resided in the fact that even though I had the use-layout instruction in the Header Panel of LAYOUT01, the rest of the code in that Panel still got executed (... <code for LAYOUT01>... in my example above, which had styles that were not meant for the Home Page).

                      Interestingly, my Header Panel code in LAYOUT02 was bypassed! I got around it by copying the entire code into the Menu Panel of LAYOUT02 instead.

                      I got it to work. But it seem "all" panels are not re-rendered. The panel that calls use-layout in the CALLING Layout, seem to render fully and the tantamount Panel in the CALLED layout gets skipped.

                      I don't suspect it is a desired behavior.

                      1. Unknown User (amoran)

                        I'm going to need a copy of your layout data before I can help you any further.

  2. Unknown User (support@bulletin.net)

    @ Alain: I really like the Blast from the Past layout. Is that the layout that the Theme v4 tutorial is about?

  3. Unknown User (mhammout)

    Hi all,

    Is there a way to act not on the layout but on css classes ?

    Here is one example : I have a tab "edit" on each page an I wish the background of the tab "edit" to change when I edit a page.

    Another one : if I have a logo "watch this page", I wish to display another logo (unwatch this page) when the page is currently watched...

    Thank you in advance for any help.
    BR, Malik

    1. Unknown User (gfraser)

      We add loads of classes to the <body> tag which you can use to apply CSS for various actions, layouts and many other things.

      1. Unknown User (mhammout)

        Thank you for your answer, but I am not sure to understand... my problem is not to add classes or such things, my problem is to create a "if then else".

        Here is an example of what I'm trying to do:

        IF MODE = EDIT PAGE :
        {li:class=menuli}{li}

        ENDIF

        IF MODE = VIEW PAGE :
        {li:class=menuli2}{li} <- here is a different css class
        ENDIF

        Another example :

        IF WATCHSTATE= WATCHPAGE :
        {li:class=menuli }{li}
        ENDIF

        IF WATCHSTATE= UNWATCHPAGE :
        {li:class=menuli2}{li} <- here is a different css class

        ENDIF

        I read the documentation here, but I found nothing...

        Thank aou for your help,
        Malik

        1. Unknown User (amoran)

          you can use flag-logic in conjunction with the builder-show/hide macros to add classes to the body tag, however there is no switch in builder-show/hide that will allow you to check the watch/favourite status of a page/space, this could be added however it would require funding.

  4. Unknown User (ville.valtasaari@thl.fi)

    It seems I'm not getting this.

    I'm experimenting with a local installation of Confluence 3.0.1 with Builder 3.3.5-conf2.10. I'm trying to make a theme that would have a left sidebar when viewing pages inside spaces and an additional right sidebar when viewing the space home page. No sidebars outside the view context (eg. edit, news, labels, attachments, admin, etc).

    My layout hierarchy:

    • CONFLUENCE27 - had the builder-show statements in the header
      • CF27EXTRA - has the left sidebar
        • CF27EXTRAHOME - has both sidebars

    One of the builder-show statements I tried:

    {builder-show:mode=view|context=page}{use-layout:CF27EXTRA}{builder-show}
{builder-show:mode=view|context=page|hastitle=@home}{use-layout:CF27EXTRAHOME}{builder-show}

    Context=page has the expected effect of keeping sidebars out of the global context but the sidebar appears in a all modes within the space. I haven't managed to check for the home page so the right sidebar never seems to appear.

    I don't want to use the page name for identifying the home page.

    Is it even possible to use multiple, mutually exclusive, builder-show -statements in the header? Should I for some kind of velocity if-else approach?

    Any tips on how I should proceed?

    r. Ville