Themes Developer's Guide

---

Themes API lets you create custom designs for iGTab, giving 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.

Contents

---

• What is a theme?
• Creating and testing themes
• Creating a dynamic theme
• Themes API Reference
• Submitting a theme
• Updating a theme
• Examples

What is a theme?

---

A theme is a custom design for the iGTab page. You define a theme in a basic XML file that contains key-value pairs for iGTab page attributes, such as background images. A theme can be as simple as a simple background image, 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 iGTab page. A theme with multiple skins is a dynamic theme, changing the iGTab 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 theme metadata (containing <Meta> tags); another for the design attributes (containing <Attribute> tags) for at least one skin.

Here is a simple example that illustrates the basic syntax of a theme XML file.

    <?xml version="1.0" encoding="UTF-8"?>
        <ConfigMaps>
            <ConfigMap type="Skin">
            <Meta name="title">Android</Meta>
            <Meta name="description">Android</Meta>
            <Meta name="author">iGoogle</Meta>
            <Meta name="author_email">igooglehdthemes+android@example.com</Meta>
            <Meta name="full_page_thumbnail.url">
                https://igtab.com/docs/images/android_1920x1200_thumb.png
            </Meta>
        </ConfigMap>
        <ConfigMap type="Skin">
            <Attribute name="full_page.background_image.url">
                https://igtab.com/docs/images/android_1920x1200_fullpage.png
            </Attribute>
        </ConfigMap>
    </ConfigMaps>
                

Creating and testing themes

---

You can write a theme XML file using any text editor.

To test a theme, you must host the XML file and theme images on a public server. There are few options available:

• You can use github.com to host XML source and images of your theme and it's free.
• Other option available from Google which work for theme hosting is Google App Engine

Please make sure you use correct mime type for text files & images

    text/css
    text/javascript
    image/png
    image/jpeg
    image/gif
                

Once your theme resources are hosted, you can verify images and xml url entering it into browser.

    https://igtab.com/docs/xml/themeSimple.xml
    https://igtab.com/docs/images/android_1920x1200_thumb.png
    https://igtab.com/docs/images/android_1920x1200_fullpage.png
                

Creating a dynamic theme

---

Remember, the background image can all change throughout the day based on time of day or day of week. 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 or day-of-week. Every skin must be fully qualified--that is, you must define all attributes for every skin. You use the tag to specify the period of time that applies to that particular skin.

A Time-of-day 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. You can also refer to the Ocean Theme as an example.

A Day-Of-Week Example

    <ConfigMap type="Skin">
        <Trait name="DayOfWeek">sun</Trait>
        ...attributes...
    </ConfigMap>
        <Trait name="DayOfWeek">mon</Trait>
        ...attributes...
    </ConfigMap>
    ...
                

Valid DayOfWeek values are: sun, mon, tue, wed, thu, fri, sat You can also refer to the Planets Theme as an example.

Themes API Reference

---

This is the reference for the Themes API. Themes are implemented in XML files that contain key-value pairs for metadata and design elements.

Metadata Attributes

---

The top section of a themes specification lists the metadata attributes for the theme, such as the title and author:

    <?xml version="1.0" encoding="UTF-8"?>
    <ConfigMaps>
        <ConfigMap type="Skin">
            <Meta name="title">Android</Meta>
            <Meta name="description">Android</Meta>
            <Meta name="author">iGoogle</Meta>
            <Meta name="author_email">igooglehdthemes+android@example.com</Meta>
            <Meta name="full_page_thumbnail.url">
                https://igtab.com/docs/images/android_1920x1200_thumb.png
            </Meta>
        </ConfigMap>
        <ConfigMap type="Skin">
            <Attribute name="full_page.background_image.url">
                https://igtab.com/docs/images/android_1920x1200_fullpage.png
            </Attribute>
        </ConfigMap>
    </ConfigMaps>
                

A ConfigMap represents one fully-qualified skin. That is, it represents a skin with all attributes that apply to a single visual state. But the concept is actually more general than that. Each ConfigMap really just describes all Skin attributes that apply to an arbitrary set of Attributes. The "actual" skin is computed from all applicable ConfigMaps. A theme specification must minimally have two <ConfigMap> sections: one to wrap the metadata, and one to wrap the design attributes for at least one skin.

This table lists the attributes that can be included in the metadata section. You must include all metadata attributes in your theme to submit it to the iGTab Themes directory, though you can test the theme without them. If you plan to submit a theme to the iGTab Themes directory, it must be a polished, complete design that conforms to the guidelines in the program policy.

Design Attributes

---

The following table lists the attributes used to define the design details for a particular skin. Strictly speaking, none of these elements is required--there is no run-time checking, in other words. However, if you plan to submit a theme to the iGTab Themes directory, it must be a polished, complete design that conforms to the guidelines in the program policy.

Within the attributes section, you can use the <Trait name="TimeOfDay">xx-xx</Trait> element to specify the time of day that a particular skin is displayed. For details, see creating a dynamic theme.

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 iGTab themes directory, no one can apply it. To share your theme with a wider audience and make it possible for users to persistently apply your theme to iGTab, you must submit it to the iGTab themes directory. For a theme to be included in the iGTab 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 iGTab accepts your theme then includes it in the Themes directory.

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 contact us.

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.

Examples

---

• Sea of Fog
• Ocean
• Planets
• Beach