デコレーターについて

Confluence 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:

  • The "Main" decorator defines the look and feel of most pages on the site
  • The "Popup" decorator defines the look and feel of the popup windows such as the "Insert Link" and "History" pages.
  • The "Printable" decorator defines the look and feel of the printable versions of pages (available through the icon on each page)

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.

 

デフォルト デコレーターを参照する

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:

<html>
<head>
     <title>$title - Confluence</title>

     #standardHeader()
</head>
<body onload="placeFocus()">

<div id="Content">
     <table border="0" cellpadding="0" cellspacing="0" width="100%">
         <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>

     #breadcrumbsAndSearch()

     <table border="0" cellpadding="5" cellspacing="0" width="100%"><tr><td>
<table border="0" cellpadding="0" cellspacing="0" width="100%"><tr>

     <td valign="top" class="pagebody">
## The "toolbar-style" page operations
## #if ($page.getProperty("page.operations"))
## <table align="right" class="toolbar"><tr><td>
## $page.getProperty("page.operations")
## </td></tr></table>
## #end

         #if ($page.getProperty("page.surtitle"))
             $page.getProperty("page.surtitle")
         #end

         #if (!$page.getProperty("page.no-page-header"))
             <div class="pageheader">
                 <span class="pagetitle">$title</span>
             </div>
         #end

         $body
     </td>

#parse ("/decorators/includes/complete_footer.vmd")

We can add our logo, changing the "logocell" table cell:

<td width="60%" rowspan=2 class="logocell">
<img align="right" 
src=http://www.atlassian.com/images/atlassian_logo.gif 
width="203" height="60">#pagetitle("spacenametitle")</td>

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.

マクロ

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.

別の方法として、カスタムテンプレートはデータベースの DECORATOR に保存されます。テンプレートの編集を介して何らかの方法で Confluence が完全に利用できなくなった場合、DECORATOR テーブルから関連するエンティティを削除します。

高度なユーザーの場合

velocity ディレクトリは Confluence の Velocity テンプレートの検索パスの手前にあります。そのため、同じ名前のファイルを適切な場所に配置することで、Confluence の任意の Velocity テンプレートを上書きできます。

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.

ただし、重要な注意点が2つあります。

  1. Velocity はテンプレートをメモリにキャッシュするように設定されています。Confluence 内からページを編集する場合、そのページをディスクからリロードします。ディスク上のページを編集する場合、WEB-INF/classes/velocity.properties で Velocity のキャッシングを一時的にオフにするか、変更を可視化するためにサーバを再起動する必要があります。
  2. 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.