1.1 Installing WhiteJazz

You should place all themes in the sites/all/themes folder of your Drupal installation. If you have not installed additional themes yet, this folder may not exist. If this is the case, simply create a subfolder in the sites/all folder called themes.

Download the WhiteJazz theme distribution and extract the files. The WhiteJazz theme is distributed in a pkzip or a compressed tar file. Download the appropriate distribution for your platform and extract the contents using a tool such as pkZip, 7-Zip, or Stuffit. Linux users can extract the file using the tar command.

Locate the themes folder of the WhiteJazz distribution. Within this folder is a subfolder named whitejazz. This is the folder that you will copy to your Drupal themes folder.

FTP/Copy/SCP the whitejazz folder to the sites/all/themes folder of your Drupal installation.

Enable the theme by logging into the administrator account of your Drupal installation, pointing your browser to /yoursite/admin/build/themes, and checking the 'Enabled' checkbox next to the WhiteJazz theme. If you want to use WhiteJazz as the default theme for your site, select the Default button next to the WhiteJazz theme. Click the Save Configuration button to save the changes.

For detailed instructions on installing and configuring Drupal themes, check out the Drupal.org handbook page on theme installation.

1.2. Installing the Theme Settings API Module

The ThemeSettingsAPI module is only required for Drupal version 5. The features of this module are built into Drupal version 6. If you're using Drupal version 6, you can skip forward to the next section.

You should place all modules in the sites/all/modules folder of your Drupal installation. If you have not installed additional modules yet, this folder may not exist. If this is the case, simply create a subfolder in the sites/all folder called modules.

Download the WhiteJazz theme distribution and extract the files. The WhiteJazz theme is distributed in a pkzip or a compressed tar file. Download the appropriate distribution for your platform and extract the contents using a tool such as pkZip, 7-Zip, or Stuffit. Linux users can extract the file using the tar command.

Locate the modules folder of the WhiteJazz distribution. Within this folder is a subfolder named themesettingsapi. This is the folder that you will copy to your Drupal modules folder.

FTP/Copy/SCP the themesettingsapi folder to the sites/all/modules folder of your Drupal installation.

Enable the module by logging into the administrator account of your Drupal installation, pointing your browser to /yoursite/admin/build/modules, and checking the 'Enabled' checkbox next to the Theme Settings API module. Click the Save Configuration button to save the changes.

For detailed instructions on installing and configuring Drupal modules, check out the Drupal.org handbook page on module installation.

1.3. Configuring WhiteJazz

If you have successfully installed and enabled the Theme Settings API module (or if you're running Drupal version 6), you can easily configure many aspects of the WhiteJazz theme from the Drupal administration menus.

Drupal 5 Users: You can use the WhiteJazz theme without installing the Theme Settings API module. However, you will not be able to control the theme features as described below without this module installed and enabled.

Point your browser to /yoursite/admin/build/themes/settings/whitejazz. At the bottom of this form is a series of options specific to the WhiteJazz theme. Each of the available options is described below. Modify the options to your liking and click the Save Configuration button at the bottom of the page. Your changes will take effect immediately.

Use Fixed Width: If this option is enabled, the WhiteJazz content window will have a fixed width. The width is specified in the Fixed Width Size input. If this option is disabled, the WhiteJazz content window will be fluid, meaning it will grow to fill the width of the browser window.

Fixed Width Size: This option allows you to specify the width of the WhiteJazz content window when using the fixed-width option. The default value is 850, which represents a page that is 850 pixels wide.

Show Breadcrumbs: If this option is enabled, Drupal will display breadcrumbs in the upper-left corner of each page.

Use IE PNG Fix: When this feature is enabled, WhiteJazz will load a javascript program that allows IE6 to display transparent PNG images.

Font Family: This option allows you to select the default font family for your site. You can select one of the provided options, or you can select Custom and specify your own font selector below.

Custom Font-Family Setting: If you selected Custom from the Font Family drop-down menu, you can specify a custom font-family string here. The string should be valid in the context of a CSS definition. Font family names that includes spaces should be enclosed in quotes, and multiple font names should be separated by commas.

Include Local Content File: If this option is enabled, Drupal will load a CSS file with the name specified beolow during the page-load sequence. This allows you to create a custom CSS file with site-specific CSS customizations. Isolating theme modifications and site-specific CSS in this manner prevents future theme updates from overwriting your changes.

Local Content File Name: If the Include Local Content File option is enabled, this option is used to specify the file name of the local content file. Note that the path is relative to the tapestry theme root folder.

Left Sidebar Width: This option is used to specify the width, in pixels, of the left sidebar.

Right Sidebar Width: This option is used to specify the width, in pixels, of the right sidebar.

Use Suckerfish Menus: Internet Explorer 6 has a bug related to the CSS hover attribute that prevents pure CSS suckerfish menus from working correctly. WhiteJazz provides a javascript file that will work around this problem and allow suckerfish menus to work correctly in IE. If you want to use this feature, you must enable this checkbox. If you do not enable this option, suckerfish menus will not work in IE6.

Specify Custom Logo Size: This option allows you to specify the dimensions of the logo image. This will not be necessary in all circumstances. However, if you are using a PNG image and you have enabled the IE PNG fix, you might need to enable this option and specify the logo image size.

Logo Width: The width, specified in pixels, of the logo image.

Logo Height: The height, specified in pixels, of the logo image.

2.1. Using WhiteJazz Regions

WhiteJazz provides 12 regions that you can publish blocks to (along with a region for the Suckerfish menu.) The WhiteJazz Regions Page shows each of the available regions. Looking at this page will give you a feel for where the regions are in relation to the one another.

The Basics

First, let's get the terminology down. A Drupal page typically includes a Content area and, optionally, one or more Blocks, which are published to Regions.

The Content area is the main part of the page, and is made up of Nodes. A node can be a story, a blog post, a forum post, or a custom node type. For the most part, Drupal manages the Content area, and you direct it using the Drupal administion menus.

A Region is essentially a physical place on the page. For example, a left sidebar region might be provided to display something to the left of the Content area. Regions are provided by the theme, and different themes will provide a different selection of regions.

A Block is a piece of content. Blocks can have a title and body text. In order to display a Block on your site, you publish it to a Region. In selecting a Region for a particular Block, you are determining where on the page that Block will be displayed.

Collapsible Regions

WhiteJazz Regions are grouped into collapsible sections. The User1, User2, and User3 regions are the blocks below the masthead. We collectively call these three regions Section1. Similarly, User4, User5, and User6 make up Section2.

In order to display a Section, simply publish a block to one of the User Regions in that Section. If you publish to only one User Region in a Section, that Region will fill the width of the page. Publish to two or to all three User Regions in a Section, and the Regions will split the horizontal space accordingly.

Similarly, if you publish content to the Outside, Left or Right Sidebars, they will appear. Publish nothing to one of the sidebars and it collapses out of sight. And the same applies to the Banner Region below the Masthead.

If you publish nothing to one of the sidebars, the main Content area will grow to fill the horizontal space normally taken by the sidebar. Publish to none of the sidebars and the main Content area will fill the width of the page.

A region will stretch vertically as much as necessary to display the content you publish to it. You can publish as many blocks to an individual region as you want. When you publish more than one block to a region, the blocks are stacked vertically atop one another. You can determine the order that blocks appear within a region by configuring the Weight of each block.

2.2. Using The Primary Links Menu

WhiteJazz displays a primary navigation menu below the mastehead. This menu can either be a two-level static menu or a suckerfish drop-down menu. This section describes how to configure the two-level static menus. Suckerfish drop-down menus are described in the next section.

WhiteJazz displays the Primary Links menu at the top right of the content portion of the page, just below the masthead.

You can designate any Drupal menu(s) as your primary and secondary links menus. A standard Drupal installation will come with a menu named Primary links, but you can select another menu to act as your sites Primary Links.

You can crate a new menu by clicking on the Add menu tab of the admin/build/menu page, or you can add and delete items from an existing menu to get the structure you want.

Once you've got your menu and menu items created, you need to tell Drupal that this will be the Primary Links menu. By pointing your browser to /yoursite/admin/build/menu/settings, you will have an opportunity to designate your Primary Links menu. Select your menu from the Menu containing primary links dropdown, and then click the Save configuration button.

Your new menu should appear immediately. You don't need to publish your new Prinary Links menu to a region. As long as you've designated a menu to provide the Prinary Links for your site, WhiteJazz will display it.

The WhiteJazz Primary and Secondary Links menus are designed to present a single horizontal row of top-level menu items. If you publish a menu that has too many top-level items to fit in one row, you're not likely to get the behavior you expect.

2.3. Using Suckerfish Menus

WhiteJazz has son-of-suckerfish menus integrated into the theme. Using this feature, you can create a standard Drupal menu and present it as a dynamic drop-down menu that is compatible with most browsers.

WhiteJazz provides a region called suckerfish menu. If you publish a standard Drupal menu in this region, it will be displayed as a suckerfish drop-down menu. However, there are a few things you need to do in order for everything to work correctly.

To start with, you'll need a menu. You can create a new menu in Drupal by pointing your browser to /yoursite/admin/build/menu and clicking on the Add Menu tab. After creating a menu, you'll want to add your menu items one at a time by clicking on the Add Item link and entering the item information. Use the Parent Item selection box to organize your menu items into the desired structure.

It is very important that all Parent Menu Items in a suckerfish menu have the Expanded checkbox enabled. This option instructs Drupal to generate HTML code for the entire menu structure. If you do not enable this feature for a particular parent menu item, you will not see its child menu items.

Once you've create a menu and enabled the Expanded option for all parent menu items, you can publish the menu to the suckerfish region. Point your browser to /yoursite/admin/build/block and select the suckerfish menu region from the selection box next to your menu block name. Then click the Save Blocks button.

The WhiteJazz suckerfish menu is designed to present a single horizontal row of top-level menu items. If you publish a menu that has too many top-level items to fit in one row, you're not likely to get the behavior you expect.

Important! Internet Explorer 6 has a bug related to the CSS hover attribute that prevents pure CSS suckerfish menus from working correctly. WhiteJazz provides a javascript file that will work around this problem and allow suckerfish menus to work correctly in IE. If you want to use this feature, you must enable the 'Enable Suckerfish Javascript for IE6' checkbox on the theme settings page. If you do not enable this option, suckerfish menus will not work in IE6.

2.4. Using WhiteJazz Custom Typography

WhiteJazz provides several custom styles that you can use in your node or block content. You can see examples of these styles on the Typography Sample page.

You can use the custom typography styles on your site by inserting a small amount of HTML code into your node or block content. Each of the examples on the Typography Sample page specify the HTML code necessary to use that style.

For example, the alert style example on the Typography Sample page specifies that you'll need to wrap your content in a set of <span class="alert">...</span> tags.

Within your block or node body, you could enter the following code:

<span class="alert">This is really important!</span>

You will need to change the Input format of your node or block to Full HTML, or else Drupal will filter out your HTML code.

If you've done everything correctly, WhiteJazz will display this as:

This is really important!

Similarly, if you create a block or node with the following code:

<blockquote>This is a really famous quote from a really famous person that 
was taken from a really famous story out of a really famous book.</blockquote>

WhiteJazz will display it as:

This is a really famous quote from a really famous person that was taken from a really famous story out of a really famous book.

2.5 Using The IE PNG Fix

Internet Explorer versions 5.5 and 6.0 do not display transparent PNG files correctly. Instead of applying the image transparency, the browser displays transparent images in an ugly gray box. WhiteJazz includes a javascript-based fix for this bug. To enable the use of the IE PNG fix, simply select the IE PNG Fix checkbox from the theme configuration page.

The WhiteJazz IE PNG fix is implemented using Drupal's built-in jquery framework, so it should not interfere with any additionally installed modules. However if you do experience a problem (or if you just don't use PNG files on your site), try disabling the IE PNG fix.

2.6. Using Images in WhiteJazz Regions

Drupal provides a myriad of options for displaying images, and numerous modules provide some variation of this capability.

However, you can create a banner block like the one above with a standard Drupal installation by simply inserting HTML code into the block body. You can place images in any WhiteJazz region. We'll use the Header region as an example, but the things covered here apply to all regions.

WhiteJazz provides a Header region below the Site Title. It is visible on this page as the fabric image. If you want to duplicate the style of banner used on this page, you'll need to start with the image. We placed our image in the /files/images folder of our Drupal site. If you choose to place your images in a different folder, you will want to ensure that Drupal can access this folder and that the file is is readable by Drupal.

Next, point your browser to /yoursite/admin/build/block, click on the the Add Block tab and enter a block description (we called ours 'Banner Block'). For the block body, you'll want to enter the HTML code necessary to display the image. The block body for the banner image on this page looks like this:

<img src="/files/images/banner.jpg" />

Finally, and this is important, change the Input Format of your block to Full HTML. If you do not change the input format to Full HTML, Drupal will not display your image. Then click the Save Block button.

Now that you have a banner block, you can publish it to the banner region. Point your browser to /yoursite/admin/build/block, select the banner region from the drop-down list next to your new banner block, and click the Save Blocks button.

3.1. Setup and Configuration Issues

Here's a list of some of the more common questions we get about the installation and configuration of WhiteJazz.

Why can't I see WhiteJazz in my list of available Drupal themes?

Most likely, you have not copied the whitejazz folder into the appropriate place on your host. You should copy the whitejazz theme folder into the sites/all/themes folder. You should also ensure that the whitejazz folder has appropriate perrmissions.

Why can't I see the WhiteJazz configuration options on the theme settings page?

Most likely, you have not installed (or not enabled) the ThemeSettingsAPI module. If you downloaded WhiteJazz from our website, the ThemeSettingsAPI module is included in the download. However, you'll still need to install the module. If you download the theme from somewhere else, you may also need to download the module from drupal.org. After installing the module, you must enable it.

Why don't my suckerfish menus drop down?

Possibly you have not configured the menu options properly. A common mistake is to forget to check the Expanded checkbox for one or more parent items.

3.2. Layout Issues

There's a lot of things going on when Drupal generates a page of XHTML code for visitors to your site. Some of this code is generated by WhiteJazz, some by the modules you have installed and enabled, some by Drupal itself, and some by your unique site content. If one component of this process is broken, the entire page can fail to render properly.

Broken layouts are the result of invalid or incomplete markup somewhere in the page. The most common problems occur whenever there are one or more unclosed HTML elements in the page. A single <div> without a matching </div> can cause the entire page to 'fall apart'.

There are many possible sources of such incomplete markup. But there are three sources of layout problems that we encounter so frequently that they warrant special attention.

Broken Layouts caused by teaser breaks

The default home page for a standard Drupal site is a list of node teasers. A teaser is simply the beginning portion of a node. Drupal doesn't really store a separate teaser. It simply marks a point in the node content called the teaser break. Whenever Drupal displays a node teaser, it displays the content of the node up to the teaser break.

You can configure the point in a node where Drupal will insert teaser breaks to some degree. The Post Settings page (admin/content/node-settings) allows you to set the default teaser break location to occur after a fixed number of characters (i.e. insert teaser break after 200 characters.) You can also set this value to Unlimited, which will disable node teasers. By default, a standard Drupal install will insert teaser breaks after 600 characters.

Be aware that changing this value will not change the teaser break location for existing nodes. It will only change the default value imposed on newly created or edited nodes.

Teaser breaks aren't really a problem if your nodes contain nothing but plain text. But what if your nodes contain HTML code? And what if this HTML code includes tables or divs that span across multiple lines. And what if Drupal decides to insert a teaser break right in the middle of that HTML code? Things could turn ugly.

If your nodes contain anything other than plain text, then the Drupal default mechanism of arbitrarily inserting a teaser break after a fixed number of characters probably won't work for you. There are essentially three effective alternatives.

If you don't want or need teasers, then change the Length of trimmed posts value to Unlimited. Drupal will not insert teaser breaks, and thus an improperly trimmed post will never break your layout.

Another option is to manually insert teaser breaks by including the string <!--break--> at an appropriate point in your node content. The presence of this manual teaser break in a node will override the default Drupal teaser behavior. See this drupal.org handbook page for further information.

A third option is to install a module that automatically corrects invalid HTML code, like the HTML corrector. This module is so useful that it's been made part of the Drupal 6.0 core.

Broken Layouts caused by WYSIWYG editors

Many Drupal users install a WYSIWYG editor so that they can format their site content without having to manually create the HTML code. Editors such as TinyMCE and FCKeditor are basically mini-HTML editors for Drupal node content.

The code generated by these editors contains HTML markup... sometimes, a LOT of it. As such, nodes created with such editors are particularly susceptible to the teaser break issues described above. If you are using one of these editors, then you should absolutely also be running the HTML corrector module.

Broken Layouts caused by over-sized content

This one is simple to understand. If you publish a block that contains a 600-pixel-wide image to a sidebar that is configured to be 300 pixels wide, something has to give.

There are things that we could have done to WhiteJazz in an attempt to 'contain the damage' caused by such situations (like applying the overflow:hidden attribute to blocks.) However, such attempts would inhibit the ability to use the theme in creative ways (like using negative margins to make an image 'break out' of a block's boundaries.) So we've chosen to make you, the content provider, responsible here. Ensure that your content is compatible with your layout.