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
- Theme XML file format
- Theme element reference
- Distributing themes to 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 Name | Type | Purpose |
|---|---|---|
| gallery.name | string | name 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.