CSS Tab

The CSS tab allows you to define custom CSS for a layout and optionally disable the inclusion of various CSS resources to gain more control over the overall CSS used in the layout.

Editing the CSS

The primary purpose of this tab is to allow you to add CSS that will be included on all pages viewed using the layout.

Clicking either the "Edit Custom CSS" or "Edit IE CSS" buttons will display the CSS editor window:

You can quickly switch between the two CSS resources by clicking the tabs shown at the top of the editor window.

Once you have finished making changes, click the "OK" button. If you want to discard changes, click the "Cancel" button.

Each of the CSS resources also has a "Use Default..." link at the top which will clear the selected CSS resource and instruct the layout to use the settings from the parent layout.

Custom CSS

The Custom CSS, if specified, is included on all pages viewed using the layout, for all web browsers.

IE CSS

Internet Explorer still isn't fully standards compliant, even in the latest version. As such you will sometimes need to add CSS that only applies to Internet Explorer and that's what this option is for.

The IE CSS gets loaded after all the other CSS allowing you to override styles already defined by the Custom CSS, etc., where necessary.

Note: The IE CSS is only included for Internet Explorer version 5.5 and above.

Important Notes

In older versions of Theme Builder, the only way to define a "global" or "central" style sheet was to create a CSS file and then use the @import directive to include it in to a layout. While this works it will have performance impacts on page loading due to various caching issues.

In Theme Builder 2.1 and above, use Layout Hierarchy instead as that has the advantage of intelligently caching the CSS with "Cache Expire" and also managing things like CSS merging, etc.

Options

There are several options which allow you to further customise which CSS resources are used by the layout. These options are intended for "power users" who need extreme levels of control in their quest for perfection. If you don't understand these options, leave them ticked

Each option has a "Use Default..." option which will clear the layout-specific setting and use whatever setting is found in the parent layout.

Merge this layout's CSS with it's parent's

By default, the Custom CSS and IE CSS defined in a layout will be merged with the CSS from the parent layout (and so on, depending on the settings of the parent layout and it's parents).

This means that the CSS resources will include the CSS used by the parent layout, followed by the CSS used in the current layout.

If you want to start with a "blank sheet" you can disable this feature to ensure that only the CSS defined in the current layout is output.

For more information on how layouts inherit from their parent layouts, please see Layout Hierarchy.

Use panel CSS for this layout

The panel CSS is defined using the Panel Editor in the Layout Tab. It's a quick and easy way to set the majority of styles such as backgrounds, borders, text settings, etc.

If you want more control, we'd recommend simply enhancing the Panel CSS using the Custom CSS and IE CSS options because that allows you to still make the more macroscopic changes using the Panel Editor.

However, if you want ultimate control you can disable the Panel CSS resource. In this scenario, people can still use the Panel Editor and save their changes but their settings won't affect the layout.

TIP: You can turn off this option and then restrict CSS editing privileges to prevent people from customising the CSS in your layout.

Use inbuilt CSS for this layout

Theme Builder has an inbuilt, hard-coded CSS resource that ensures all styles commonly required by Confluence and a wide selection of macros are present so that everything "just works".

However, sometimes the inbuilt CSS can get in the way of your own custom CSS if you're doing something really complex. If you want extreme control over the CSS that's used in your layout you can turn off the inbuilt CSS but be warned that you'll then have to manually create lots of custom CSS for all the various features in Confluence.

Our recommendation: Always include the inbuilt CSS unless you're willing to do a lot of extra work on your own Custom CSS.

FAQ's

Can I add CSS resources for specific versions of specific browsers?

Currently the only browser-specific CSS you can add is for Internet Explorer 5.5 and above using the IE CSS resource.

At present, there's no way to add CSS for specific versions of Internet Explorer or other browsers. It's on our to-do list and will hopefully appear in a future version of the plugin.

How do I centrally define some CSS to use in multiple layouts?

Define your main CSS in a parent layout and then create child layouts based on that parent layout - by default the CSS defined in the parent layout will be included in all the child layouts. Changing the CSS in the parent layout will instantly update all the child layouts.

You can add additional CSS in the child layouts using the Custom CSS and IE CSS resources. If you add styles to the child layout that are already defined in the parent layout, they will override the styles defined in the parent layout because they are output after the parent layout styles. (hope that makes sense!)

The Merge this layout's CSS with it's parent's setting allows you to define whether a child layout also includes the CSS from the parent layout.

How do I define CSS for a specific panel?

Simply include the appropriate panel class in your style definition. For example, if you wanted to make the Heading 1 text in the left sidebar red, you would define:

.atb-leftSidebar h1 {
 color: #ff0000;
}

For a list of the available panel classes, please see Panel Classes and IDs.

I'm trying to override an inbuilt style but it's not working...

The easiest way to solve this problem is to make your style definition more "specific" than that of the inbuilt CSS.

To make styles more specific, simply include more of the "path" to the element you want to style. For example, you could create a specific style for the text used in list items in the content panel as follows:

.atb-page .atb-content li {
 color: #008800;
}

I'm trying to define styles for elements with compound classes but it's not working in Internet Explorer - why?

Internet Explorer has a really nasty bug. It only looks at the last class!

For example, let's say you have CSS like this:

.foo {
 color: green;
}
.bar.foo {
 color: red;
}

And then somewhere on a wiki page the following notation:

{div:class=foo}This should be green{div}
{div:class=foo bar}This should be red{div}

In all other browsers, the text colours will be correct. However in Internet Explorer all of the text would be red! This is because Internet Explorer sees .bar.foo as just .foo (it only looks at the last part) and because the style for .bar.foo comes after the style for .foo it overrides the style for .foo making that text red instead of green.

To work around this problem, you need to make slight tweaks, for example:

.foo {
 color: green;
}
.foo.bar {
 color: red;
}

So Internet Explorer sees .foo.bar as .bar. Obviously, you're still going to get problems, but that's just something we have to live with until Microsoft manage to make a standards compliant browser (which is extremely unlikely).

Some of my CSS styles aren't taking effect - any other ideas?

Some browsers (Internet Explorer) and some web pages (generally XHTML pages) result in case-sensitive CSS.

For example, if you had this on a wiki page:

{span:class=FooBar}Wibble!{span}

Your style definition would need to be:

.FooBar {
 color: blue;
}

Page tree