Themes

Themes API
More Themes resource links

Developer's Guide

The Themes API lets you create custom designs for iGoogle. Themes are visual designs that personalize iGoogle pages for millions of users. Themes are not just static designs--they can change throughout the day to reveal a visual storyline, message, or anything else.

What is a theme?

A theme is custom design for the iGoogle page. You define a theme in an XML file that contains key-value pairs for iGoogle page attributes, such as background and text color. A theme can be as simple as a color setting for the header background and iGoogle logo, or it can include multiple images and dynamic behavior.

A theme has one or more skins. A skin is a particular design for the iGoogle page. For example, you could have a theme that displays different skins depending on the time of day.

Each skin is represented in a themes specification by a different ConfigMap (configuration map). A theme is essentially a collection of configuration maps.

Here is a simple example that illustrates the basic syntax of the theme XML file. Note that skins are defined within <ConfigMap> tags. A theme can define multiple skins, and each skin is defined within a <ConfigMap> section. A theme minimally needs two <ConfigMap> sections: one to wrap the metadata, and one to wrap the design attributes for at least one skin. For example:

<?xml version="1.0" encoding="UTF-8" ?> 
<ConfigMaps> 
  <ConfigMap type="Skin"> 
    <Meta name="title">Simple Theme</Meta> 
    <Meta name="description">Simple theme example.</Meta> 
    <Meta name="author">Rowan</Meta> 
  </ConfigMap> 
  <ConfigMap type="Skin"> 
    <Attribute name="header.background_color">teal</Attribute> 
    <Attribute name="header.logo">white</Attribute> 
    <Attribute name="header.link_color">#ffffff</Attribute> 
    <Attribute name="header.text_color">#ffffff</Attribute> 
    <Attribute name="gadget_area.gadget.body.link_color">#8B4513</Attribute> 
    <Attribute name="gadget_area.tab.unselected.text_color">gray</Attribute> 
  </ConfigMap> 
</ConfigMaps>

See the reference for a complete list of the attributes and metadata fields.

Creating and testing themes

You can write a theme XML file using any text editor, such as Wordpad.

To test a theme, you must host the XML file and theme images on a public server. For example, you could host your theme XML and image files through the Google Gadgets Editor, or through Google Code, as described here. Once your theme resources are hosted, you can test the theme by adding ?skin=<theme-url> at the end of the iGoogle URL. For example, you can test the simple example shown above as follows:

http://www.google.com/ig?skin=http://gadget-doc-examples.googlecode.com/svn/trunk/themes/theme_simple.xml

Basic steps

An iGoogle Theme consists of a header and footer image, and styles that you define in an XML template for different parts of the page. There are three steps to creating a theme:

Creating the visual designs
Filling out the theme template
Submitting your theme to the iGoogle directory

These steps are described in more detail below.

Before you begin creating a theme, please review our program policy. These guidelines include:

No trademarks, logos, or signatures outside of the designated attribution area.
All iGoogle logos, links, and text on the page must remain visible and fully usable.
You cannot change, remove, or disparage the iGoogle logo.
We reserve the right for what themes are approved for users and added to the directory.

Creating the visual designs

The iGoogle page consists of three sections: the header, content area, and footer.

Remember, the theme can change throughout the day, so don’t stop once you have created one design – create a dynamic theme.

Designing the header

The header is the graphical area at the top of iGoogle. It includes the iGoogle logo, the search box, tabs, text, links, and so on. For example, here is the header for the iGoogle tea house theme:

Tea house header

The header is constructed of multiple layers constructed out of tiles. The patterns on these tiles are aligned to make them appear to be a single image. The tiled approach makes it possible for the header display to adjust as the browser window expands and contracts.

Before you design your header and create your tiles, it's helpful to understand how the layers of the page are constructed. The elements of the page are laid down in the following order:

Background color. The first layer of the page to be laid down is your background color. For example:
<Attribute name="header.background_color">teal</Attribute>
Tiled image. Next, your header tiles are put in place. The header appears to the user as a single image at the top of the page, but in fact it is constructed of tiles. When the page is constructed, the first tile is put in the center of the header area. Then identical tiles are put on either side of it, continuing out to the edge of the browser window. Note that this set of tiles must be identical, and you must line up the patterns on the tiles to create the impression of a seamless background. For example:
<Attribute name="header.tile_image.url">http://www.example.com/tile_img.jpg</Attribute>
Themed image. The next element to be added to the page is the themed image. This tile is placed in the center of the header area, and it can either be transparent or opaque. If it is opaque, it must be designed so that its pattern lines up with the underlying visual tiles. For example:
<Attribute name="header.center_image.url">http://www.example.com/center_img.jpg</Attribute>
Logo and search box. Finally, the Google logo, search box, and other elements (such as links) are added to the header.

The header image is 175 px in height and must be at least 640 px wide. You can make the image as wide as you like, as long as the file size stays under 40 kb (Hint: smaller images load faster, and tend to be more popular). The header image is centered on the page and fixed in place behind the iGoogle logo, search box, links, and tabs.

Since the header is a fixed size image, you need to construct it in a way that makes it seamlessly adjust to users resizing the browser window. There are different ways to handle horizontal resizing of the page:

Fill the background with a single color
Use a large tile as a background and add the header on top
Create a solid header image and tile to each side

These techniques are described in more detail below.

Fill the background with a single color

You can use a single color to fill-in the background behind your header image. As the page gets wider, this color will appear to the sides of your header image. To make the transition between the header and background color seamless, your header image should blend into the same color on the left and right sides. You can then use that color as the background. For example:

Background Color

This example was created by John Maeda.

Use a tiled background and add a transparent center image

You can create a tile that repeats and serves as the background for the entire image header. The edges of the tile should meet, such that the image can be repeated without any visible borders or breaks. Your header image can then place objects on top of the background, leaving other areas transparent so that the background shows through. The header image should be the same width as the background tile. For example:

Bus stop background

Bus stop people

Combined

Bus stop combined

Create a solid header image and tile to each side

This is similar to option 2, except the tile is covered by a solid image in the middle. To make the transition from the image to the tile seamless, the left edge of the header and right edge of the tile must match, as well as the right edge of the header and the left edge of the tile. To ensure the tile and header image align, the tile image needs to fit evenly behind the background image. If the header image is 900 px wide, the tile must be 900 px (1 tile fits behind), 300 px wide (3 tiles), etc. This ensures that when the page is resized, the tiles and the header align to create a seamless image. For example:

Tea House background

Tea house background

Tea House tile

Tea house tile

Choosing colors

The Themes API lets you specify colors for text and links in the header, footer, tabs, and content area (referred to in the API as the "gadget area"). For example, this snippet sets the link and text color in the header to white, and the content area link color to red:

<Attribute name="header.link_color">white</Attribute>
<Attribute name="header.text_color">white</Attribute>
<Attribute name="gadget_area.gadget.body.link_color">red</Attribute>

Plain text

Choose the color for plain text. All unlinked text is the same color and must be visible on the page. Text includes:

Select theme (after clicked)

Choosing an iGoogle logo

Every theme must include an iGoogle logo, and the logo must be clearly visible on the page. To specify an iGoogle logo for your theme, use the header.logo attribute. This attribute takes a value that can be one of the following:

original -- the original multi-colored iGoogle logo, but with a transparent background. If you don't specify a logo, your theme displays the original logo with a white background, which isn't the desired effect in most cases.
beveled_original -- the original multi-colored iGoogle logo, beveled.
color -- one of the supported logo colors; see the reference for the complete list.
beveled_color -- one of the supported logo colors with a beveled edge.

Here are some examples.

White logo, flat:

<Attribute name="header.logo">white</Attribute>

Yellow logo, beveled:

<Attribute name="header.logo">beveled_yellow</Attribute>

Original logo, beveled:

<Attribute name="header.logo">beveled_original</Attribute>

Designing the tabs

The Themes API lets you modify the following characteristics of the iGoogle tabs:

Text color for the selected tab.
Background color for selected tab.
Text color for unselected tabs. All unselected tabs have the same text color.
Background color for unselected tabs. All unselected tabs have the same background color.
Outline color for both selected and unselected tabs. All tabs have the same outline color.

For example, this snippet:

<Attribute name="gadget_area.tab.selected.background_color">white</Attribute>
<Attribute name="gadget_area.tab.selected.text_color">blue</Attribute>
<Attribute name="gadget_area.tab.unselected.background_color">gray</Attribute>
<Attribute name="gadget_area.tab.unselected.text_color">black</Attribute>    
<Attribute name="gadget_area.tab.border_color">navy</Attribute>

creates this tab design (shown against a teal header background):

Tabs

Designing the content area

The Themes API lets you modify the following characteristics of the content area. The content area is the part of the page that displays the gadgets:

Text color for gadget titles. All the titles for each gadget have the same text color.
Background color for the titlebar. All titlebars have the same background color.
Frame color for the gadgets. This is a thin border around the gadgets.
Color for links inside gadgets. Some links inside gadgets and feeds can be adjusted as well.

For example, this snippet:

<Attribute name="gadget_area.gadget.body.link_color">#00B366</Attribute>
<Attribute name="gadget_area.border_color">#007D48</Attribute>
<Attribute name="gadget_area.gadget.border_color">#007D48</Attribute>
<Attribute name="gadget_area.gadget.header.background_color">#BFFFE4</Attribute>
<Attribute name="gadget_area.gadget.header.text_color">#00B366</Attribute>

creates this color scheme in the content area (only one gadget is shown here; the content area typically contains multiple gadgets):

Content Area

Using custom button icons

You can provide custom 12x12px images in place of the default gadget icons. You can design your own icons, or choose one from the button directory.

The Themes API lets you provide custom images for the following gadget icons and states:

Menu icon (also applies to the active tab)
Menu icon on mouse hover (also applies to the active tab)
Collapse icon
Collapse icon on hover
Expand icon
Expand icon on hover
Close icon
Close icon on hover

You specify an icon by URL. For example:

<Attribute name="gadget_area.menu_icon.image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_menu.gif</Attribute>
<Attribute name="gadget_area.menu_icon.hover_image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_menu_hover.gif</Attribute>
<Attribute name="gadget_area.delete_icon.image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_delete.gif</Attribute>
<Attribute name="gadget_area.delete_icon.hover_image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_delete_hover.gif</Attribute>
<Attribute name="gadget_area.collapse_icon.image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_collapse.gif</Attribute>
<Attribute name="gadget_area.collapse_icon.hover_image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_collapse_hover.gif</Attribute>
<Attribute name="gadget_area.expand_icon.image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_expand.gif</Attribute>
<Attribute name="gadget_area.expand_icon.hover_image.url">http://igoogle-themes.googlecode.com/svn/trunk/ffaa00_expand_hover.gif</Attribute>

Designing the footer

Designing a footer is optional and is similar to designing the header. The links and text and change colors, there are restrictions on the height and width, and the footer can tile in the same manner.

You have three options for designing the footer:

Use white or a plain background color
This ensures that your theme loads fast, and keeps the design simple. For example, this snippet sets the footer color to gray:
<Attribute name="footer.background_color">gray</Attribute>
Use a background tile
This is a single tile that goes across the entire footer. It’s a simple design that’s still loads quickly. Specify the tile image in the footer, and ensure the left and right sides of the tile properly align. It should be 140 px in height. You use the footer.tile_image.url attribute to specify a footer background tile, for example:
<Attribute name="footer.tile_image.url">http://www.example.com/footer_img.jpg</Attribute>
Use a themed image and tile/background color, similar to the header
The footer image is 140 px in height and must be at least 640 px wide. You can make the image as wide as you like, as long as the file size stays under 20 kb (Hint: smaller images load faster, and tend to be more popular). The image is centered on the page and fixed in place behind the links and text in the footer.
Remember, to make the transition from the image to the tile seamless, the left edge of the footer and right edge of the tile must match, as well as the right edge of the footer and the left edge of the tile. To ensure the tile and footer image align, the tile image needs to fit evenly behind the background image. If the footer image is 900 px wide, the tile must be 900 px (1 tile fits behind), 300 px wide (3 tiles), etc. This ensures that when the page is resized, the tiles and the footer align to create a seamless image. For example:
<Attribute name="footer.center_image.url">http://www.example.com/footer_center_img.jpg</Attribute>

You can also modify the the color for links and text in the footer. For example, this snippet sets the footer link color to white, and the footer text color to black:

<Attribute name="footer.link_color">white</Attribute>
<Attribute name="footer.text_color">black</Attribute>

The footer is also where you can put an attribution, such as your name, signature, or logo. The attribution area is 50 pixels by 100 pixels in the top right corner of the footer. For details, see the program policy. You use the attribution.image.url attribute to add an attribution image. For example:

<Attribute name="attribution.image.url">http://www.example.com/my_attribution_image.jpg</Attribute>

Creating a dynamic theme

Remember, the header image, logo, text colors, and more can all change throughout the day based on time of day or weather. Feel free to create as many designs as you like (note that changes during hours at night are not seen often, and having too many images may cause users to miss a few if they don’t visit often).

When you have a dynamic theme, you create different skins for different time periods. Every skin must be fully qualified--that is, you must define all attributes for every skin. You use the <Trait> tag to specify the period of time that applies to that particular skin. For example:

<ConfigMap type="Skin">
  <Trait name="TimeOfDay">12am-1am</Trait>
    ...attributes...
</ConfigMap>
<ConfigMap type="Skin">
  <Trait name="TimeOfDay">1am-2am</Trait> 
    ...attributes...
</ConfigMap>
....

Submitting a theme

You can use the Themes API to create simple designs for yourself and your friends. However, unless a theme is in the iGoogle Themes directory, you can only apply it in "test mode" through the URL, as described in Creating and testing a theme. To share your theme with a wider audience and make it possible for users to persistently apply your theme to iGoogle, you must submit it to the iGoogle Themes directory. For a theme to be included in the iGoogle Themes directory, it must be a compelling, polished, tested design that conforms to the guidelines given in the program policy. You must also include all of the metadata fields.

Once your theme is ready, you can submit it here. When Google accepts your theme and includes it in the Themes directory, your images are copied over and hosted by Google.

If you have problems submitting your theme, make sure that all of the syntax is correct and that there are no blank lines in your themes spec.

Updating a theme

If you want to make changes to a theme you've already submitted, just submit the theme again using the same url and it will be updated in about 1-2 weeks.