Application XML Specification

Requirements

Application XML must conform to the gadget XSD. This will quickly create or update your application. It can be edited further after it is created or updated.

Recognized Elements and Attributes

ModulePrefs

Only one ModulePrefs is recognized. If multiple ModulePrefs elements are provided, the first one is used and the rest are ignored.

title 

The short name associated with the application.

• This attribute is required to create / update an application.
• Minimum length: 1 character.
• Maximum length: 64 characters.
• Must use only the following characters: a-z, A-Z, 0-9, ', &, !, ., -, _, ?, [space], and all characters in the hexadecimal range C0-FFFF.
• Must start with a letter.

description 

A short description of the application, used for display in the App Gallery.

• This attribute is required to create / update an application.
• Minimum length: 1 character.
• Maximum length: 256 characters.
• Must use only the following characters: a-z, A-Z, 0-9, ', &, !, ., -, _, ?, [space], and all characters in the hexadecimal range C0-FFFF.

thumbnail 

The URL of the thumbnail image associated with the gadget.

• Displayed in the App Gallery, and the App Profile page.
• Must point to a valid GIF, PNG, or JPG file.
• Image dimensions must be 64x64 pixels.
• File size must be less than 300k.
• Image will be imported and hosted by MySpace.

height 

Indicates the preferred height, in pixels, to render content.

• Optional.
• Default is to use the default rendering height for the view surface.
• Minimum value: 20.
• Maximum value: 1000.

category 

Primary category of the application.

• Must match an existing category from the list on the Edit App Information page.

category2 

Secondary category of the application.

• Must match an existing category from the list on the Edit App Information page.

Icon

A 16x16 small icon displayed next to the application.

mode

The method used to provide the icon.

• Optional.
• Valid value is "base64".
• When "base64" is specified then the data in the Icon element has to be in the format of "data:[mime type];[base64 encoded data]".
• If no mode is provided, the data in the Icon element has to be a valid URI pointing to a valid ICO, GIF, PNG, or JPG file.

Locale

Strings that are used to localize applications.

Lang (optional)

Two character language code.

• Defaults to application's default culture and is used for all users who have a not specified a culture.

country (optional)

Two character country code.

• Defaults to a country corresponding to the language specified if a language is provided.

messages 

A URI pointing to a message bundle XML file.

• Must conform to the Message Bundle XSD.
• Optional if no "msg" elements are provided inline.

msg 

The content of the element - the localized string.
Example: "My Title"

• name - Unique identifier for string.
  Example: "title"
• Can be used in description, title, thumbnail, UserPref display_name, and UserPref EnumValue display_value.
• Localization of content is not yet supported.
• The format must be "__MSG_[name]__" in the attribute that uses localization.
  Example: <ModulePrefs title="the title of this app is __MSG_title__">

Link

href 

The callback URL.

i.e. www.example.com/installed

rel 

Must be either:

• "event.addapp" for installs, or
• "event.removeapp" for uninstalls.

These correspond to the "Install Callback URL" and "Uninstall Callback URL" on the application information page. The URLs are called each time a user installs or uninstalls the application.

Content

type 

Indicates whether the content is inline html, or located at an external URL.

• Optional.
• Default is "inline html".
• Valid values are: "html" and "url".
• When "url" is specified then the surface will be an external iFrame.

href 

The external URL that points to the content.

• Required if "type" attribute is "url".
• If type attribute is "html" then the content is retrieved and treated as though it were inline.
• URL has to be accessible and a valid absolute URL. HTML and SWF files are allowed.

view

Indicates which surface the content should render.

• Optional.
• If missing, "canvas" is used as the default.
• Allowed values: "canvas", "profile", "profile.left", "profile.right", "home", and "all".
• When using "profile" the position will be defaulted to right.
• When using "all" then the content is used for canvas, profile, and home surfaces.
• If a surface is provided more than once and the type is "html" then the content will be concatenated.

preferred_height (formerly preferredHeight) 

Specifies the initial height desired for the surface.

• If not provided, then "height" attribute from "ModulePrefs" element is used.
• Minimum value: 20.
• Maximum value: 1000.
• If the preferred_height is specified multiple times for the same view / surface then the last one takes precedence.

Require

feature 

Highly Recommended Features

• Valid values are "opensocial-0.7", "views" and "dynamic-height". Use "require" for features that your application depend on.

Optional

feature 

Highly Recommended Features

• Supported values are "opensocial-0.7", "views" and "dynamic-height". Use "Optional" for features that your application uses if the feature is available, but will not break the application if it is not implemented on MySpace.

UserPref

Although UserPrefs are supported in XML (you can import them), UserPref hasn’t been released as a feature yet.

name (required) 

The name or "key" of this UserPref.

datatype (required) 

The datatype.

• Valid values: "string", "number", "bool", "enum", "list", "hidden".

display_name (required) 

The name that will be preseted to the user.

• This field can be localized with "Locale" elements.

required 

whether or not to require the user to enter a value for this preference.

• Optional.
• Default is "false".

default_value 

The default value presented to the user.

• Optional
• localization for this field is not supported.

urlparam 

Name of the URL query string parameter that will be passed to the IFrame of the application.

• Optional

UserPref child element:

EnumValue (required if datatype is enum, illegal otherwise) 

The list of legal enum values and their displays.

• Enums will be displayed as a multiple-choice selection to the user, in a drop-down menu.
• EnumValue attributes:
  • value
    The value for this selection within the enum, such as "beginner" or "intermediate", or "advanced"
  • display_value
    The display_value presented to the user in the drop-down.
    • This value can be localized based on "Locale" elements

Unrecognized Elements and Attributes

ModulePrefs

This element is recognized, with the exception of the following attributes:

• title_url
• author
• author_email
• screenshot
• directory_title
• author_affiliation
• author_location
• author_photo
• author_aboutme
• author_quote
• author_link
• show_stats
• show_in_directory
• string
• width
  The width is set based on the surface selected.
• singleton
  Applications can only appear once per surface.
• render_inline
• scaling
• scrolling

Icon

This element is recognized, with the exception of one attribute:

• type

Locale

This element is recognized, with the exception of one attribute:

• language_direction

Preload