Developer's Guide

The Themes API lets you create custom designs for iGoogle, giving tens of millions of users tools to further personalize their homepage. Themes are dynamic designs--they can change throughout the day to reveal a visual storyline, message, or anything else.

This document has been modified to reflect changes from additional features to iGoogle. Sections are marked as being ^New! or ^Updated! to help you identify content that has changed since the last version.

This document covers two different versions of the iGoogle user interface (UI): the original UI, and the new UI, which you can see in the iGoogle sandbox. Over time, the new UI will be replacing the old UI. Most of the settings described in this document apply to both versions of the UI, but some only apply to one or the other.

Contents

1. What is a theme?
2. Creating and testing themes
3. Basic steps
4. Creating the visual designs
   1. Designing the header
   2. Choosing colors
   3. Choosing an iGoogle logo
   4. Designing the tabs
   5. Designing the left navigation
   6. Designing chat
   7. Designing the content area
   8. Changing the colors of button icons
   9. Designing the footer
5. Creating a dynamic theme
6. Localizing a theme
7. Submitting a theme
8. Updating a theme

What is a theme?

A theme is custom design for the iGoogle page. You define a theme in a basic 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 specifies a look and feel for the attributes you want to include in your theme, creating a single design for the iGoogle page. A theme with multiple skins is a dynamic theme, changing the iGoogle page's design depending on the time of day.

Each skin is represented in the theme XML file 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 needs at least two <ConfigMap> sections: one for the metadata, and one for 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> 
    <Meta name="author_email">Rowan@gmail.com</Meta>
    <Meta name="thumbnail">http://gmodules.com/ig/images/skins/ig_thumb_beach.jpg</Meta>
  </ConfigMap> 
  <ConfigMap type="Skin"> 
    <Attribute name="header.background_color">teal</Attribute>
    <Attribute name="header.logo">white</Attribute> 
    <Attribute name="header.link_color">blue</Attribute> 
    <Attribute name="header.text_color">black</Attribute> 
    <Attribute name="gadget_area.gadget.header.background_color">teal</Attribute>
  </ConfigMap> 
</ConfigMaps>

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

^Updated 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 on an international version of iGoogle as follows:

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

Note: if you are a new user, you have to click "See your page" in the setup box to test a theme.

To test the theme with the latest iGoogle features, first sign up for the sandbox at http://www.google.com/ig/sandbox. Then test the theme again by adding ?skin=<theme-url> at the end of the iGoogle URL. For example, you can test the simple example in sandbox by signing up and then visiting:

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

In order to properly test your theme design, make sure you are logged in to your Google account. Review all areas of the page, including the new features like chat.

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. Here are the steps for creating a theme:

1. Creating the visual designs
2. Filling out the theme template
3. Testing your theme and submitting it 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.
• Google reserves the right to decide what themes are approved for users and added to the directory.

Creating the visual designs

The iGoogle page consists of these sections: the header, left navigation, 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.

^Updated Designing the header

The header is the graphical area at the top of iGoogle. It includes the iGoogle logo, the search box, text, links, and so on. It may also include tabs (depending on the user's version of iGoogle). For example, here is the header for the iGoogle tea house theme:

The header is constructed out of the following layers:

• Background color
• Repeating tiles
• A center image
• The logo, search box, and links

Before you design your header and create your tiles, it's helpful to understand how the layers of the header are constructed. You don't have to use each layer -- more on that later. The elements of the header are laid down in the following order:

1. 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>
2. 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 uses repeated tile images to expand and contract. 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>
3. Center image. The next element to be added to the header is the center image. This image 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 and edges line up with the underlying tiles. For example:
   <Attribute name="header.center_image.url">http://www.example.com/center_img.jpg</Attribute>
4. 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 -- the tiles and center image must be that tall.  The center image 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).

Since the header is a fixed size image, you need to construct it in a way that makes it seamlessly adjust to different screen resolutions and to users resizing the browser window. To achieve this flexibility, you can construct the header using one of the following techniques:

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

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. Using a transparent center image, you can then place objects on top of the background, leaving other areas transparent so that the background shows through. For example:

Create a solid header image and tile to each side

This is similar to the second technique, except the tiles in the middle are covered by a solid center image. To make the transition from the center image to the tile seamless, the left edge of the center image and right edge of the tile must match, as well as the right edge of the center image and the left edge of the tile. To ensure the tile and center image align on the iGoogle page, the tile image needs to fit evenly behind the center image. If the center 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 center image align to create a seamless image.

For example:

Choosing colors

The Themes API lets you specify colors for text and links in the header, footer, 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. You can also set colors using hex values, as done for the content area link color:

<Attribute name="header.link_color">white</Attribute>
<Attribute name="header.text_color">white</Attribute>
<Attribute name="gadget_area.gadget.header.background_color">#00B366</Attribute>

Links

All links are the same color and must be visible on the page. Links include:

• Advanced Search
• Preferences
• Language Tools
• Personalize this page

Some versions of iGoogle may also include the following links:

• Select theme
• Add Stuff >>
• Add a tab

Plain text

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

• Options for what pages to search (for example, pages from the UK)
  

Some versions of iGoogle may also include the following text:

• 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>

^Updated Designing the tabs

Note that the tabs are being moved to the left navigation. While we deploy new features to iGoogle users, some users will have tabs and some will have the left navigation. We suggest specifying both values for the time being.

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

^New! Designing the left navigation

Note: This is replacing horizontal tabs.

The Themes API lets you modify the following characteristics of the left navigation:

• Background color for the navbar. This color is the navbar's base color, shown for all unselected tabs, links, and empty space.
• Border color for the navbar. The outline color that goes around the navbar and content area.
• Color for icons in the navbar. The color for icons like expand and collapse.
• Color for selected links. When a tab is selected, it is shown on a white background. This is the color for links that appear on top of the white background.
• Color for unselected links. The color for unselected links, which are shown on top of the background color for the navbar.
• Color for the lines between tabs in the navbar.

For example:

<Attribute name="navbar.background_color">#FFF9BF</Attribute>
<Attribute name="navbar.border_color">blue</Attribute>
<Attribute name="navbar.icons.icon_color">aqua</Attribute>
<Attribute name="navbar.tab.selected.link_color">teal</Attribute>
<Attribute name="navbar.tab.unselected.link_color">teal</Attribute>
<Attribute name="navbar.tab.unselected.border_color">teal</Attribute>

^New! Designing chat

The Themes API lets you modify the following characteristics of the chat feature. The chat list appears at the bottom of the left navigation.

• Contacts color. Text color for chat contacts.
• Status color. Text color for contact status messages.
• Hover background color for contacts.
• Hover card border color. Hover cards appear when your mouse moves over contacts.
• Hover card header color.
• Invite border color. Invites appear when other people invite you to chat with them.
• Invite background color.
• Invite text color.
• Invite link color.
• Header background color for chat conversations.
• Highlighted header background color, flashes when new chats arrive.

For example:

<Attribute name="navbar.contacts.contact_color">#FF8080</Attribute>
<Attribute name="navbar.contacts.status_color">#FF8080</Attribute>
<Attribute name="navbar.contacts.hover_background_color">#FF0000</Attribute>
<Attribute name="navbar.contacts.card.border_color">#B30000</Attribute>
<Attribute name="gadget_area.chat.header.background_color">#FFBFBF</Attribute>
<Attribute name="gadget_area.chat.header.highlight.background_color">#FF8080</Attribute>

^Updated 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 on the page have the same background color.
• Frame color for the gadgets. This is a thin border around the gadgets.
  
• Frame color for the gadgets on mouse hover.
• 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:

^New! Changing the colors of button icons

Note: This replaces the option to specify custom images for button icons.

The Themes API lets you modify the buttons that appear in the headers for gadgets. You can specify the color of the buttons you want using one of the values listed in the API reference.

For example:

<Attribute name="gadget_area.icons.icon_color">#ffaa00</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's center image and right edge of the tile must match, as well as the right edge of the footer's center image 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. 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>
....

Valid time ranges are from 12am - 12am. If the end time is before the start time, it will cause a submit-time error. For example, suppose that you want to specify a time span from 11pm-5am. This time span would be invalid. To make it work, you would have to split it up into two Traits, one with TimeOfDay from 11pm-12am, and another with TimeOfDay from 12am-5am.

^New! Localizing a theme

You can help users around the world to find your theme by including localized metadata fields for particular languages and countries. You can localize the following fields:

• title. Title displayed in the Themes directory.
• description. Description of the theme and what it does.
• thumbnail. Thumbnail that appears in the Themes directory to give users a preview of a theme.
• screenshot. Screenshot that appears in the Themes directory on the page about your theme.
  

To localize these fields, include an additional <ConfigMap> in your theme XML file for each language and country you want to support. If a language or country is not included in the theme, the theme's directory defaults to the first <ConfigMap> that does not have a language or country specified. For example:

<ConfigMaps>
  <!-- These values are the defaults for all countries -->
  <ConfigMap type="Skin">
    <Meta name="title">Simple Theme</Meta>
    <Meta name="description">Simple theme example.</Meta>
    <Meta name="author">Rowan</Meta>
    <Meta name="author_email">Rowan@gmail.com</Meta>
    <Meta name="thumbnail">http://mysite.com/images/ig_thumb_beach.jpg</Meta>
    <Meta name="screenshot">http://mysite.com/images/ig_screenshot_beach.jpg</Meta>
  </ConfigMap>
  <!-- Localized fields, which will replace the defaults for language ja, and country jp -->
  <ConfigMap type="Skin">
    <Trait name="Language">ja</Trait>
    <Trait name="Country">jp</Trait>
    <Meta name="title">単純なテーマ</Meta>
    <Meta name="description">単純なテーマの例</Meta>
    <Meta name="thumbnail">http://mysite.com/images/thumb_beach_jp.jpg</Meta>
    <Meta name="screenshot">http://mysite.com/images/screenshot_beach_jp.jpg</Meta>
  </ConfigMap>

You are not required to specify both a language and a country. You can just specify one or the other. For example, you could create a <ConfigMap> for all French speakers, or you could create a <ConfigMap> that only applies to French speakers in Canada. It depends on how specifically you want to target a particular audience.

The valid values for Language are ISO639-1 two-digit language codes, and for Country they are ISO 3166-1 alpha-2 codes. For a list of the languages and countries supported by iGoogle, see iGoogle Supported Languages and Countries.

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 themes. 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 and ensure that all images used in the theme are publicly accessible.

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, so you don't need to worry about traffic to your host.

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 XML file. If you have any questions or feedback, please visit the Themes API group.

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.

Back to top