My Yahoo! Theme API

With the My Yahoo! Theme API, you can create a page theme with your own colors and background images and share it with My Yahoo! users.

Overview of the My Yahoo! Theme API

The My Yahoo! Theme API allows you to create an XML file that specifies the colors and images that are used to style a My Yahoo!. You can then place an "Add to My Yahoo!" button for your theme anywhere on the web. Users who click this button will have your theme added to their pages.

Theme XML file format

My Yahoo! themes are represented as XML files with the following format:

<?xml version="1.0" encoding="UTF-8"?>
<Theme version="1.0">
    <Element name="element name">element value</Element>
    <Element name="element name">element value</Element>
    ...
</Theme>

Example: spring.xml

The following section documents the names, purposes, and allowed values of theme elements.

Theme element reference

The values of elements are either colors, image URLs, or strings. Some things to note:

  • Colors should be expressed using 6 hex characters, e.g., "DFD03B". Upper or lower case is fine, but do not place a "#" in front.
  • Image URLs should point to images on publicly-accessible web servers.
  • Image servers should have sufficient capacity as images are not cached by Yahoo! (normal browser caching applies).

The example "Spring" theme provides a useful reference for the purposes of these elements.

Element NameTypePurpose
gallery.name stringname used for your theme in the My Yahoo! UI (10 characters or less)
global.controls_sprite URL image sprite containing control icons used throughout page; see details below
header.backgrounds_sprite URL background of page header area; tiled horizontally; see details below
header.background_color color page header; not visible unless header.backgrounds_sprite includes transparency
header.top.pipe.right_color color right side of "pipe" dividers between links in top line of page header
header.top.pipe.left_color color left side of "pipe" dividers between links in top line of page header
header.top.text_color color non-link text in top line of page header
header.top.link_color color link text in top line of page header
header.logo string, allowed values are "standard" (default) and "reverse"use "reverse" to get an all-white logo for themes with a dark header background color
header.searchbox.background_image URL optional; frames the search box; note: must be 697x86 pixels in PNG format
header.searchbox.pipe.right_color color right side of "pipe" dividers between links above the search box
header.searchbox.pipe.left_color color left side of "pipe" dividers between links above the search box
header.searchbox.text_color color non-link text around the search box
header.searchbox.link_color color link text around the search box
header.bottom.pipe.right_color color right side of "pipe" dividers between links in bottom line of page header
header.bottom.pipe.left_color color left side of "pipe" dividers between links in bottom line of page header
header.bottom.text_color color non-link text in bottom line of page header
header.bottom.link_color color link text in bottom line of page header
tabs.selected.background_color color background of tab the user is currently viewing and horizontal bar containing personalization controls
tabs.selected.text_color color label of tab the user is currently viewing
tabs.selected.border_color color outline of tab the user is currently viewing and horizontal bar containing personalization controls
tabs.unselected.background_color color background of tabs other than the one the user is currently viewing
tabs.unselected.text_color color labels of tabs other than the one the user is currently viewing
personalization.button_text_color color labels of personalization controls
personalization.button.hover_color color background of personalization controls when mouse is hovering
personalization.button.depressed_color color background of personalization controls after click
quicklinks.background_color color background of "Quicklinks" pop-down navigation menu
quicklinks.link_color color links in "Quicklinks" pop-down navigation menu
body.divider_color color horizontal rule separating page header from page body
body.background_image URL optional; background image for page body, tiled both horiztonally and vertically
body.background_color color background of page; not visible if body.background_image set (unless image includes transparency)
app.border_style string, allowed values are "none", "solid", "shadow" (default)determines whether individual apps have no border, a thin rule, or a thin rule plus a shadow on the right and bottom edges
app.border_color color outer and inner borders of apps (if app.border_style = none, only applies to inner borders)
app.shadow_color color shadow of apps (only applies if app.border_style = shadow)
app.head.background_color color background color for app headers
app.head.text_color color text in app headers
app.body.background_color color background color for apps bodies; not visible if app.body.background_image is set (unless image includes transparency)
app.body.background_image URL optional; background image for app bodies, tiled both horizontally and vertically
app.body.text_color color non-link text in app bodies
app.body.link_color color links in app bodies
app.body.vlink_color color visited links in app bodies
app.body.subhead.background_color color background of sub-headers in app bodies (e.g., portfolio headers in the Stock Portfolios app)
app.body.subhead.text_color color text in sub-headers in app bodies (e.g., portfolio headers in the Stock Portfolios app)
app.body.secondary.text_color color optional; non-primary text in app bodies (e.g., RSS feed timestamps)
app.body.secondary.background_color color optional; alternate background color (e.g., every other quote in the Stock Portfolios app)

Details: global.controls_sprite

The controls sprite is an image containing about 30 icons used throughout the page. Rather than creating a controls sprite from scratch, you'll want to grab the controls sprite from one of the themes in the My Yahoo! theme gallery and either use it as-is or colorize it to match your theme.

Example: the controls sprite from the "Spring" them. A couple of things to note:

  • The sprite uses different colors for the header and app icons.
  • Some of the icons are present with two subtly different colors--these are used for rollover effects.

Details: header.backgrounds_sprite

The header background image is tiled horizontally across the top of the My Yahoo! page. Your image should be 200px high, and only as wide as necessary to capture your repeating pattern (we suggest a minimum width of 2px just to be on the safe side).

Note that if your image is taller than 200px, the image may "bleed through" to other parts of the header area. This is because the "built-in" My Yahoo! themes use this image as a sprite with multiple components. Due to ongoing optimizations, you should not build a theme that assumes the current layout of this sprite will remain valid.

Testing your theme

To test your theme, the XML file and any image assets must be on a publicly-accessible web server.

You can test your theme by constructing a URL of the form http://my.yahoo.com/set/theme?url=XMLURL where XMLURL is the URL of your theme XML file. Tip: the URL of your XML file should be URL encoded, especially if it includes a query string.

To view changes to your theme, update the XML file and hit the above URL again to refresh the settings.

Distributing themes to My Yahoo! users

You can distribute your themes by posting "Add to My Yahoo!" buttons anywhere on the web. Here's how to create an "Add to My Yahoo!" button for a theme:

  • Put your theme XML file on a public web server.
  • Create a URL of this form: http://my.yahoo.com/set/theme?url=XMLURL where XMLURL is the URL of your theme XML file. Tip: the URL of your XML file should be URL encoded, especially if it includes a query string.
  • Use this URL in an anchor tag with this image:
  • Example button (try it!):

Notes:

  • When users adopt your theme, it is added to their personal "Custom" category in the My Yahoo! user interface, located under "Change Appearance > Choose Theme".
  • Your theme is cached indefinitely for a given user, with the theme URL used as the GUID.
  • If your theme file changes, the theme on a user's page will not automatically change. However, if the user subsequently clicks the "Add to My Yahoo!" button for that theme, the version used for their page (and stored in their personal "Custom" category) will be updated.