About DecoratorsConfluence is built on top of the Open Source SiteMesh library, a web-page layout system that provides a consistent look and feel across a site. SiteMesh works through "decorators" that define a page's layout and structure, and into which the specific content of the page is placed. If you are interested, you can read more on the SiteMesh website. What this means for Confluence is that you can customise the look and feel of almost all of your Confluence site through editing three decorators:
You can view and edit these decorators from within Confluence: they are available from the "Layouts" option on the site's Administration menu. Changes to the decorators will affect all spaces hosted on that Confluence installation. The decorator that is used to draw Confluence's administrative pages can not be edited from within Confluence. This means that if you make some editing mistake that renders the rest of the site unuseable, the administrative pages should still be available for you to fix the template. |
|
icon on each page)
The information on this page Browsing the Default Decorators
At any time, you can browse the default decorators that come packaged with Confluence by following the "View Default" links on the "Site Layouts" page. The template browser also allows you to view the "#parsed" templates that are included within the template when it is compiled. While you can't edit these included templates, you will probably have to copy some or all of them into your custom template as you do your customisation.
Editing Custom Decorators: Add a Logo
To edit Confluence decorators, you should have a good knowledge of HTML, and some understanding of the Velocity templating language.
The first thing you will see when you choose to create a custom "Main" decorator is... there's not much to edit. By default, most of the content of this decorator is included from other files:
We can add our logo, changing the "logocell" table cell:
When you insert this into the right section of the template and hit save, visitors to the site will see the logo at the top of each page. Note, the administrative pages will be unaffected: you will have to go to the dashboard or to a space to see the changes you have made.
Macros
Some parts of the page are drawn using Velocity macros, including the navigation bar. The macros you should know about when editing decorators are described in Working With Decorator Macros.
If Something Goes Terribly Wrong
From the "Site Layouts" page in Confluence's administrative menu, you can delete your custom templates. When you do this, the default template will be restored, fixing anything that may have been broken.
Alternatively, the custom templates are stored in the DECORATOR table in the database. If you have somehow managed to render Confluence completely unuseable through editing your templates, delete the relevant entries from the DECORATOR table.
For Advanced Users
The velocity directory is at the front of Confluence's velocity template search path. As such, you can override any of Confluence's velocity templates by placing an identically named file in the right place.
While we don't recommend you do this unless you know exactly what you're doing, it does give you complete control over the look of every aspect of Confluence. It also means that you can edit your templates in a text-editor if you wish, rather than through the web interface.
There are, however, two important caveats:
- Velocity is configured to cache templates in memory. When you edit a page from within Confluence, it knows to reload that page from disk. If you are editing the pages on disk, you will either have to turn off velocity's caching temporarily in
WEB-INF/classes/velocity.properties, or restart the server to make your changes visible. - Because we only officially support the modification of the three global decorator files, other changes may interact unpredictably with future versions of Confluence. When upgrading, you should always test your custom modifications thoroughly before deploying them on a live site.
22 Comments
Hide/Show CommentsJan 30, 2004
Anonymous
I'd like to add some links to pages in the spaces to the main,
is there a macro (#pagelink(space:page) to do this without pasting in the full link (http:.../confluence/.../)?
Feb 05, 2004
David Valentine
## custom link into space decorator #parse ("/decorators/includes/header.vmd") <div id="Content"> <table border="0" cellpadding="0" cellspacing="0" width="100%"> <tr> <!-- adl navbar --> <td colspan="2"> <table align="right" border=0 cellspacing=1 cellpadding=2 bgcolor="ffffff"> <tr> ##macro(navitem $title $url $selected $tooltip $accessKey) #navitem ("<u>A</u>DL WORK" "$req.contextPath/display/Brainstorm/Home" "/display/Brainstorm/Home" "Go to the ADL Workspace" "a") #navitem ("<u>P</u>eople" "$req.contextPath/display/Brainstorm/People" "/display/Brainstorm/People" "Go to the ADL People" "a") #navitem ("Pro<u>j</u>ects" "$req.contextPath/display/Brainstorm/ADL%2BProjects" "/display/Brainstorm/ADL%2BProjects" "Go to the ADL Projects" "j") #navitem ("<u>M</u>eetings" "$req.contextPath/display/Meetings/Home" "/display/Meetings/Home" "Go to the ADL Meetings" "m") #navitem ("<u>D</u>ocuments" "$req.contextPath/display/Brainstorm/Documentation%2BEfforts" "/display/Brainstorm/Documentation%2BEfforts" "Go to the ADL Dcouments" "d") #navitem ("UCSB <u>L</u>ibrary Work" "$req.contextPath/display/LibraryWebsiteAdmin/Home" "/display/LibraryWebsiteAdmin/Home" "Go to the Library Web Admin" "l") #navitem ("ADL Project" "http://www.alexandria.ucsb.edu/" "Home" "Go to the ADL Project" "r") #navitem ("UCSB Library" "http://www.library.ucsb.edu/" "Home" "Go to the Library Web" "u") </tr> </table> </td> </tr> <tr> <td width="60%" rowspan=2 class="logocell">#pagetitle("spacenametitle")</td> <td width="40%" align="right" valign="top"> #globalnavbar("table") </td> </tr> #if ($setup.isSetupComplete()) <tr> <td align=right valign="bottom"> #usernavbar() #printableicon() #helpicon() </td> </tr> #end </table> <div width="100%" class="breadcrumbs"> <table width=100% cellspacing=0 cellpadding=0 border=0><tr> <td> #breadcrumbs() </td> #searchbox() </tr></table> </div> <table border="0" cellpadding="5" cellspacing="0" width="100%"><tr><td> <table border="0" cellpadding="0" cellspacing="0" width="100%"><tr> ## end adl custom <td valign="top" class="pagebody"> #if ($page.getProperty("page.operations-icons")) <table align="right" class="toolbar"><tr><td> $page.getProperty("page.operations-icons") </td></tr></table> #end #if ($page.getProperty("page.surtitle")) <div class="surtitle"> $page.getProperty("page.surtitle") </div> #end <div class="pageheader"> <span class="pagetitle">$title</span> </div> $body </td> #parse ("/decorators/includes/complete_footer.vmd")Oct 27, 2004
Angelo Schneider
This page, I mean this URL: "http://confluence.atlassian.com/display/DOC/Custom+Decorator+Templates" is buggy.
For some reason it asks for my screen resolution and renders teh HTML in a super wide screen. (Page references and Hot REfferers are outside of my screen, 1024x1280)
The other pages on Confluence here worked fine.
Angelo
Mar 25, 2005
Anonymous
The page is wide is because someone posed a extra wide comment with a code example.
May 03, 2005
PJ Mudd
Is there a way to replace the confluence_logo.gif and the logo2.gif that you see at the top left of the pages with our companies logo? I understand how to add our logo, but that only adds it to the middle of the pages, next to the Confluence one. Thanks.
May 16, 2005
Michael Coxon
I want to add a space-wide footer feature.
As far as I can see, in order to have it close to the other page content (i.e., user-submitted content), it has to be within the $body aggregation. That is, if you place anything anywhere else, it appears either well above the content, or well below it (after the comments widget etc.).
Is there a satisfactory way of editing how the $body content is rendered?
Sep 09, 2005
Anonymous
We are looking at possibly buying Confluence with an unlimited user license and source code access. From poking around here, I understand you can customize the look and feel of confluence using SItemesh and Velocity and Velocity is a scripting language that access the methods of Java objects.
What I am wondering about is the ability to integrate with an outside system and customize behavoir not just appearance from within Confluence. Say if I had an article about something on one of my data driven web pages and I wanted to give the user the ability to create a wikie type article or post comments using confluence about that article. I would want the use to hit a button or link on my page, and provide them with a customized empty Confluence page with possibly a cutom title and header to write\upload their content. Will I be able customize or create Java objects within Confluence to handle this?
I know there will be issues regarding upgrading and service packs etc...
Sep 12, 2005
Jens Schumacher
Hi,
I'm not to 100% certain what you are trying to achieve, but it sounds like that the Remote API would do what you are looking for. The remote API will allow you to keep the interface to enter the data on your page and then create a page in Confluence on submission.
You could also modify the templates and link to Confluence directly. Writing themes you will be able to write your own java objects to handle certain tasks, but from what I understand, that would not be necessary.
If you have further questions please send us an email to:
confluence-support@atlassian.com
Cheers,
Jens
Oct 25, 2005
Barthélémy von Haller
Hi,
I just want to change the color of the text of the usernavbar but I dont find how to do that. I tried to modify the main decorator by adding
<span style="color: red">
#usernavbar()
</span>
But that doesn't work...
How can I do that ?
Thanks
Barth
Oct 25, 2005
Daniel Ostermeier
The best way to change usernavbar colour is via the "Administration Console | Look and Feel | Colour Schemes". This allows you to configure the user nav bar among other things.
Alternatively, you would need to update the Confluence CSS file that is used to control the colours.
Regards,
-Daniel
Jul 06, 2007
Brett Lewinski
How can I remove the logout link?
Thanks-
Brett
Jul 09, 2007
Tony Cheah Tong Nyee
Hi Brett,
To my understanding, you would like to exclude the "Log Out" link available in the top right of the Confluence site whenever a user is logged in? This is possible by editing the file
macros.vmlocated in confluence\template\includes directory.An example to remove the link would be as follow:
macros.vmfile:<a href="$req.contextPath/logout.action" id="logout">$action.getText('logout.name')</a> Please ensure that you have a make copy of the
macros.vmfile before performing the suggestion above. Also note that such modification would actually disable everyone from seeing the logout link including administrator. However the user can still logout from Confluence by appending the logout link to the browser such as:For further questions regarding customizing Confluence, you can always share them in our forums, as there will be users/developers who have experience in similar configuration might share their idea with you.
Cheers,
Tony
Jul 09, 2007
Brett Lewinski
Tony -
Thanks for the help, it did the trick. I appreciate it.
Sorry about posting in the wrong place
Thanks Again!
Brett
Nov 29, 2007
rusty
I'm having problems with white space and word wrapping when I try to upload some mail archives. I've tried customizing the <pre> tag with some external CSS, but I believe my fix isn't going to work until I edit the table a bit that surrounds it. I've done very little decorator editing so far for our install, but the edits I have made up to this point seem to work fine.
My problem is this:
When I try to edit mail.vmd, none of the changes are rendered when I view my space's mail. My edits are saved as a custom decorator, but when I view the page it seems to simply be pulling the default .vmd. Any suggestions?
My <pre>, which fixes the problem in Firefox but not in IE6, which is the browser I'm forced to care about:
Dec 13, 2007
Ming Giet Chong
Hi Rusty,
Thanks for putting the comment. However, to further investigate the issue, I would suggest you to raise a support request at the issue tracker at:
Regards,
MG
Jul 10, 2008
jackie
Hi there.. I have tried to edit the Quote style in Confluence. I want to delete the bar in the left hand side when i quote.
I go to \confluence\includes\css\master.css and edit the blockquote style as:
blockquote {
font-style: bold;
font-size: 10pt;
border-left-width: 1px;
padding: 0 20px;
margin: 10px 20px;
}
but the Confluence still has an italic and left-hand-side bar (boarder). What can I do?
Thank you in advance!
Jul 11, 2008
Tony Cheah Tong Nyee
Hi Jackie,
Please take a look at my reply here. Hope it helps.
Cheers,
Tony
Jul 30, 2008
Anonymous
Since upgrading to version 2.8.1 all of the body text has become italicized. I hate that because it is difficult to read. I've tried setting the style in master.css to include a line:
in the body text definition, but that didn't help at all. How can I get rid of italics?
Aug 01, 2008
Tony Cheah Tong Nyee
Hi there,
I presumed you would like to customized the CSS of the "Default Theme". If that is the case, you might also want to give a try to look into the
default-theme.cssfile (located in the same location as themaster.cssfile) to see if the changes takes effect. If you are using other themes, then you may need to look into the themes source and make modification from there.Cheers,
Tony
Apr 17, 2009
Matus
What #parse, #onload() and any other #whatever are doing? Where can I find documentation for that?
Apr 20, 2009
Arie Murdianto
Those are macros. You can refer to the code for what are they doing. You can refer to macros.vm. There, you should find some of macros being defined there. While, #parse macro is from velocity which is used to include velocity code to the current velocity.
Jun 25, 2009
Giles Gaskell [Atlassian Technical Writer]
Hi Matus,
You can find some documentation on the Velocity template language and syntax in the Apache Velocity User Guide. The relevant link in the documentation above has also been updated to point to this user guide.
I hope this information helps.
Best regards,
Giles Gaskell
Technical Writer
ggaskell@atlassian.com
ATLASSIAN - http://www.atlassian.com
Add Comment