Understanding the config.xml File

When you create an app with ymdt, the source directory includes a file called config.xml. Yahoo! Mail looks at this file while bootstrapping your app, mostly to figure out what kinds of events the app is interested in.

The formal syntax of the config.xml is described in the config schema definition file, but that's useless by itself, even to XML wonks.

Skeletal Config

Here's a minimal app configuration. It doesn't do anything useful, but it will pass XML validation. 
  1. <?xml version="1.0"?>
  2. <openmail_app_config version="0">
  3. </openmail_app_config>
<?xml version="1.0"?>
<openmail_app_config version="0">
</openmail_app_config>

Events

You can configure your app to be called on any of these events:

  • <click> occurs when a user click's on your app's icon, located in the Application's section of the Yahoo! Mail UI for installed apps.
  • <compose> listen for compose.start events. Your javascript can then inject content into the compose window.
  • <message_read> lets you enhance how a message is rendered.
  • <uninstall> take action when a user uninstalls your app, use in conjunction with app.uninstall event.

For example, if a user clicks your app's icon, your app can get notification of the click with an config.xml like this: 

  1. <?xml version="1.0"?>  
  2. <openmail_app_config version="0">  
  3.     <name>Hello World</name>  
  4.     <description>Hello World Sample App</description>  
  5.     <data/>  
  6.     <events>  
  7.         <click>  
  8.         <action>  
  9.             <launch>  
  10.                 <view>main.html</view>  
  11.                 <target_zone>tab</target_zone>  
  12.             </launch>  
  13.         </action>  
  14.         </click>  
  15.     </events>  
  16. </openmail_app_config> 
<?xml version="1.0"?>  
<openmail_app_config version="0">  
    <name>Hello World</name>  
    <description>Hello World Sample App</description>  
    <data/>  
    <events>  
        <click>  
        <action>  
            <launch>  
                <view>main.html</view>  
                <target_zone>tab</target_zone>  
            </launch>  
        </action>  
        </click>  
    </events>  
</openmail_app_config>

The interesting part here is the <events> section. It says to load the app's "views/main.html" file in a tab when a user clicks the app's icon. Currently, the only useful <action> you can configure is a <launch> action, which loads an HTML view. To see how your view can then user our javascript API once it is launched, check out the Hello World Tutorial.

Launch Actions

When your app gets an event, it can load one of its HTML views in a <target_zone>. That view than can execute javascript to invoke Yahoo! Mail APIs. Visible target_zones are dialog, tab, and lightbox. If you only need to react to an event by executing javascript, you can use a hidden target zone for your view. In this case, your view is just an HTML container for javascript.

Besides view and target_zone elements, your launch element may include the following sub-elements:

  • <id> assigns this id to the view's DOM element. If a view is already open with the same id, bring it into focus instead of launching a new one.
  • <title> displayed in your view's titlebar, if it has one.
  • <width> dialog view width in pixels.
  • <height> dialog view height in pixels.
  • <context> string you can access via the getParameters() API.
  • <ttl> integer number of seconds after which to automatically close the view. Only works for target_zone hidden.

When your app is first installed, a dialog shows the user links to your Terms of Service, Privacy Policy, and developer "landing page." Specify these using the <legal> tag in your config.xml. The landing page is also linked to the developer's name in the gallery. Here's an example <legal> section: 

  1. <legal>
  2.     <terms_of_service url="http://developer.yahoo.com/terms/"/>
  3.     <privacy_policy url="http://info.yahoo.com/privacy/us/yahoo/devel/details.html"/>
  4.     <landing_page url="http://developer.yahoo.com/mailapplications/index.html"/>
  5. </legal>
<legal>
    <terms_of_service url="http://developer.yahoo.com/terms/"/>
    <privacy_policy url="http://info.yahoo.com/privacy/us/yahoo/devel/details.html"/>
    <landing_page url="http://developer.yahoo.com/mailapplications/index.html"/>
</legal>

p3p

In order for you app to set cookies against IE, you need an appropriate P3P compact privacy policy for the app. Here is an example of a P3P policy specified in your config.xml: 

  1. <?xml version="1.0"?>
  2. <openmail_app_config version="2">
  3.  . . .
  4.  <p3p>P3P: CP="CAO PSA OUR"</p3p>
  5. </openmail_app_config>
<?xml version="1.0"?>
<openmail_app_config version="2">
 . . .
 <p3p>P3P: CP="CAO PSA OUR"</p3p>
</openmail_app_config>

Support & Community

Ask questions and share insights on our forum.