Gadgets XML

From VZ Developer Wiki
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth


ModulePrefs Elements and Attributes

The <ModulePrefs> section in the XML file specifies characteristics of the gadget, such as title, author, thumbnail, and so on. For example:

 <Module>
  <ModulePrefs title="Developer Forum" 
     title_url="http://groups.google.com/group/Google-Gadgets-API"
     author="Jane Smith" 
     author_email="xxx@google.com"/>
  <Content ...>
     ... content ...
  </Content>
 </Module>

The users of your gadget cannot change these attributes. On the platform this data is used to describe and identify your gadget.

<ModulePrefs> serves as a container element for all metadata, features, and processing rules. For nested element descriptions, see their individual sections below. This section summarizes the elements and attributes in <ModulePrefs>. In the sections below, the level of nesting is indicated by slashes. For example, /ModulePrefs/Locale describes the <Locale> element that is nested inside the <ModulePrefs> element. This might appear in a gadget specification as follows:


 <ModulePrefs>
   <Locale lang="en" country="us" />
   <Locale lang="ja" country="jp" />
 </ModulePrefs>

ModulePrefs

The following table lists the <ModulePrefs> attributes that are supported:

Attribute Description
title

necessary String that provides the title of the gadget. This title is displayed in the gadget title bar, gallery and every Dialog which contains the name of the gadget (e.g. install, uninstall). max. 64 characters

description necessary string that describes the gadget. used in the gadget install dialog. max. 255 characters
preview necessary string with a short preview description of the gadget. used in the gadget gallery. max. 255 characters
author necessary string that lists the author of the gadget. max. 255 characters.
author_email

necessary string that provides the gadget author's email address. You can use any email system, but you should not use a personal email address because of spam. max. 80 characters.

thumbnail necessary string that gives the URL of a gadget thumbnail. This must be an image on our cdn (use relative path from gadget package root). PNG is the preferred format, though GIF and JPG are also acceptable. Gadget thumbnails should be 150x100 pixels. Since Thursday, the 26th of May 2011 it must have a maximum file-size of 30kb in all new app-revisions.
icon necessary string that gives the URL of a gadget icon. This must be an image on our cdn (use relative path from gadget package root). PNG is the preferred format, though GIF and JPG are also acceptable. Gadget icons should be 85x85 pixels. Since Thursday, the 26th of May 2011 it must have a maximum file-size of 30kb in all new app-revisions.
platform optional filter to allow a gagdget to be installed only on given platforms. Possible values are 'meinvz+studivz' and 'schuelervz'. Multiple platforms can be concatenated with a ',' (e.g. 'studivz+meinvz,schuelervz'). Note that you can not allow access for meinVZ or studiVZ seperately. The standard is to allow installation on all platforms.
age_restriction optional age restriction for a gagdet. You can enter any integer between 1 and 99. E.g. 18 means that a user should be at least 18 to bea able to access your gadget. Standard is no age restriction.
private optional value to indicate the gadget privacy settings for the gadget. Possible values are nobleprofile (gadget is only installable by noble profiles and from the gadget administration backend), toolbox (gadget is only installable by noble profiles with special rights and from the gadget administration backend), hidden (gadget is only installable from the gadget administration backend), false (default, gadget is installable by everyone)
multiple_installations optional boolean value to indicate that multiple installations of one gadget for one user are allowed. Possible values are "true" or "false". Standard value is 'false'.
host_location necessary string value describing the location/country where the gadget backend stores additional data about the user (e.g. "Germany", "United States", ...)
feed_promotion_text optional string value that will be published in the activity feed next to the icon, when an installation event is shown. Max. 140 characters.
default_privacy optional string value that indicates the privacy settings that are chosen by default when the user installs the app. Possible values are "all" (default), "friends" and "none".


Help.png

This tutorial will give you more examples or information on these features:
Lesson 02: Meta data and how it's used

ModulePrefs/Require and ModulePrefs/Optional

The <Require> and <Optional> elements declare feature dependencies of the gadget.

Attributes:

  • "feature" -- The name of the feature. Required

Examples:

 <Require feature="dynamic-height"/>
 <Optional feature="shareable-prefs"/>

For a list of features see Gadgets_Features

ModulePrefs/Require/Param and ModulePrefs/Optional/Param

These elements provide configuration parameters for a feature.

Attributes:

  • "name" -- The name of the parameter. Required.

ModulePrefs/Require/Fields (OpenSocial only)

Please see the OpenSocial_RequiredFields section to learn how you can require specific OpenSocial vCard fields.

ModulePrefs/Preload

The <Preload> element instructs the container to fetch data from a remote source during the gadget rendering process. This element is used in conjunction with makeRequest(), which fetches data from a remote server.

For example, suppose you have a request that looks like this:


 gadgets.io.makeRequest("http://www.example.com", response, params);

You can preload the content at http://www.example.com by adding a <Preload> tag to your gadget's <ModulePrefs> section:

<ModulePrefs title="Demo Preloads" description="Demo Preloads">
<Require feature="opensocial-0.9" /> <Preload href="http://www.example.com" /> </ModulePrefs>

When your gadget executes the makeRequest() call, this content is returned instantly, without needing to hit your server again.

You use <Preload> to reduce latency for gadgets that use makeRequest() to fetch data from remote servers. For more discussion of this topic, see makeRequest()

Help.png

This tutorial will give you more examples or information on these features:
Lesson_10:_Interact_with_your_own_Backend

Attributes:

  • "href" -- A URL specifiying the location of the data to prefetch. Required.
  • "authz" -- The authentication type to use for making this request. Valid values are "none" (default) and "signed". Optional.

These attributes map to the authorization parameters in the makeRequest() query string:

Attribute Description
oauth_service_name The nickname the gadget uses to refer to the OAuth <Service> element from its XML spec. If unspecified, defaults to "". Maps to gadgets.io.RequestParameters.OAUTH_SERVICE_NAME.
oauth_token_name The nickname the gadget uses to refer to an OAuth token granting access to a particular resources. If unspecified, defaults to "". Gadgets can use multiple token names if they have access to multiple resources from the same service provider. For example, a gadget with access to a contact list and a calendar might use a token name of "contacts" to use the contact list token, and a contact list of "calendar" to use the calendar token. Maps to gadgets.io.RequestParameters.OAUTH_TOKEN_NAME.
oauth_request_token A service provider may be able to automatically provision a gadget with a request token that is preapproved for access to a resource. The gadget can use that token with the OAUTH_REQUEST_TOKEN parameter. This parameter is optional. Maps to gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN.
oauth_request_token_secret The secret corresponding to a preapproved request token. This parameter is optional. Maps to gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET.
sign_owner Boolean that indicates whether the owner must be authenticated. If unspecified, defaults to "true". Maps to gadgets.io.RequestParameters.SIGN_OWNER.
sign_viewer Boolean that indicates whether the viewer must be authenticated. If unspecified, defaults to "true". Maps to gadgets.io.RequestParameters.SIGN_VIEWER.
views A comma-separated list of the view names that trigger the specified preload.

Note that all of the <Preload> attributes also apply to [#proxied_content proxied content].

ModulePrefs/Locale

The <Locale> element specifies the locales supported by your gadget. You can also use it to specify message bundles, as described in Gadgets and Internationalization.

Attributes:

  • "lang" -- The language associated with the locale. Optional.
  • "country" -- The country associated with the locale. Optional.
  • "messages" -- A URL that points to a message bundle. Message bundles are XML files that contain the translated strings for a given locale. For more information, see Gadgets and Internationalization. Optional.
  • "language_direction" -- The direction of the gadget. Optional. Its value can either be "rtl" (right-to-left) or "ltr" (left-to-right). The default is "ltr". This attribute lets you create gadgets that support both left-to-right and right-to-left languages. For more discussion of this topic, see Gadgets Localization. You can use the following substitution variables in conjunction with language_direction:
    • __BIDI_START_EDGE__: The value is "left" when the gadget is in LTR-mode and "right" when the gadget is in RTL-mode.
    • __BIDI_END_EDGE__: The value is "right" when the gadget is in LTR-mode and "left" when the gadget is in RTL-mode.
    • __BIDI_DIR__: The value of this variable is "ltr" when the gadget is in LTR-mode and "rtl" when the gadget is in RTL-mode.
    • __BIDI_REVERSE_DIR__: The value of this variable is "rtl" when the gadget is in LTR-mode and "ltr" when the gadget is in RTL-mode.

For example, this snippet specifies two different locales:


 <ModulePrefs>
   <Locale lang="en" country="us" />
   <Locale lang="ja" country="jp" />
 </ModulePrefs>

The "lang" (language) and "country" attributes are both optional, but you must have at least one of them for each <Locale>. If you omit either attribute, the value is equivalent to "*" and "ALL". If you specify a country and no language, it is assumed that your gadget supports all languages associated with the country. Likewise, if you specify a language and no country, it is assumed that your gadget supports all countries associated with the language.

The valid values for language are ISO639-1 two-digit language codes, and for country they are ISO 3166-1 alpha-2 codes.

There are a few exceptions to the usual language rules:

  • Simplified Chinese: lang="zh-cn" (typically for country="cn").
  • Traditional Chinese: lang="zh-tw" (typically for country="tw" or "hk", Taiwan or Hong Kong, respectively).


Help.png

This tutorial will give you more examples or information on these features:
Lesson 07: Gadget Localization

ModulePrefs/Link

We support sending lifecycle events to an application developer's site by sending relevant query-params to a URL endpoint. To receive these events you can use the <Link> tag.. Each <Link> tag has a rel and an href attribute. The href attribute denotes the endpont where event pings are sent. If the rel attribute matches "event.TYPE", then events of TYPE are sent to that endpoint. An optional method attribute can be set to POST or GET to specify how the request should be sent. The default is GET. Here are some examples:

 <ModulePrefs>
  <link rel="event.addapp" href="http://www.example.com/myuniquegadgetendpoint/add" />
  <link rel="event.removeapp" href="http://www.example.com/myuniquegadgetendpoint/remove" />
 </ModulePrefs>

The following event types are defined:

  • addapp -- called when an user installs the app.
    • Additional parameters
      • id id of user that has installed the app (ID).
      • sourceView<code> designates how the user added this app.
        Possible values are:
        • 'invite'
        • 'profile'
        • 'start'
        • 'group'
        • 'canvas'
        • 'home'
        • 'popup'
        • 'integration'
        • 'groupinstallation'
        • 'groupcanvas'
        • 'groupcanvasinstallation'
        • 'nobleprofile'
        • 'nobleprofilecanvas'
        • 'popupinstallation'
        • 'integrationinstallation'
        • 'embed'
        • 'embedprovider'
        • 'gallery'
        • 'mobilcanvas'
    • Example GET call
  • removeapp -- called when an user uninstalls the app.
  • invite -- called when a user has invited other users to install the gadget
    • POST only
    • Example POST body
* The POST body contains a JSON object which looks like this:
{ 
  'from_id' : senderOsUserId, 
  'token' : optToken, 
  'users' : [ 
    { 'id': receiverOsUserId, 'has_installed' : boolean}, 
    ... 
  ]
}

If you set that you want to receive the install or uninstall events as a POST request, the call will also contain any preference parameters from the installation which is being uninstalled or the copied preferences of the source installation from which the app is being installed.

Signature: Each request is automatically signed with the gadget's consumer secret according to the OAuth 1.0A standard. The signature method which is used is HMAC_SHA1.

Additionally to the event specific parameters we return:

  • oauth_signature_method
  • oauth_nonce
  • oauth_timestamp
  • oauth_consumer_key
  • oauth_signature
  • env (name of container context in which this event has been called (sandbox, avz, pvz, svz))

Sample code for validation:


 $request = OAuthRequest::from_request();
 $server = new OAuthSignatureMethod_HMAC_SHA1();
 $consumer = new OAuthConsumer('CONSUMER KEY', 'CONSUMER SECRET');
 $return = $server->check_signature($request, $consumer, null, $_GET['oauth_signature']);
 
 if (! $return) {
  die('invalid signature');
 }

We highly recommend to provide an endpoint for the 'event.removeapp' especially in conjunction with OpenSocial Gadgets, so that you can delete all data you stored for an user, if this user uninstalls the gadget

ModulePrefs/AllowedDomain

The <AllowedDomain> element declares domains from which external endpoints the gadget can request data through the makeRequest() method. Currently there is a maximum of six elements of this kind allowed.

Attributes:

  • "name" -- The domain name or IP address which shall be allowed for makeRequest(). Be sure to specifiy only the domain (no protocol like 'http' or ports). Required.

Sample XML snippet:

 <ModulePrefs>
   <AllowedDomain name="yourbackend.com" />
   <AllowedDomain name="your.second-backend.com" />
   <AllowedDomain name="123.123.123.123" />
 </ModulePrefs>

ModulePrefs/OAuth

The <OAuth> element defines a gadget's use of the OAuth proxy. For more information about implement OAuth in gadgets, see Lesson 23: Connecting to an external API with OAuth authorization.

ModulePrefs/OAuth/Service

This element identifies a single OAuth service configuration.

Attributes:

  • "name" -- The name of the service (for example, "google"), used for referencing OAuth services at runtime. Gadget developers specify which OAuth service they wish to use by passing the service name as a parameter to makeRequest().

ModulePrefs/OAuth/Service/Request and ModulePrefs/OAuth/Service/Access

Represents the OAuth request token and access token URLs. See the OAuth spec and Lesson 23: Connecting to an external API with OAuth authorization for details.

Attributes:

  • "url" -- The URL for the endpoint.
  • "method" -- The HTTP verb to use for making the request. This parameter is optional. If unspecified, it defaults to POST.
  • "param_location" -- One of 3 possible locations in the request to the service where the OAuth parameters may be passed. You can use this value to specify the location of OAuth-related parameters. The possible values are:
    • "uri-query" -- OAuth parameters are passed in the query string.
    • "auth-header" -- OAuth parameters are passed in the Authorization header.
    • "post-body" -- OAuth parameters are passed in the body of the POST request.

These values correspond to the options described in the OAuth spec. The default value is "auth-header".

ModulePrefs/OAuth/Service/Authorization

The OAuth authorization URL.


User Preferences

Some gadgets need to give users a way of supplying user-specific information. For example, a weather gadget might require users to provide their postal codes. The user preferences (<UserPref>) section in the XML file describes the user input fields that are turned into user interface controls when the gadget runs.

If a user start the install flow of a gadget from another installation instance (e.g. a group, another profile or a noble profile) the preferences set in this installation will be copied to the new installation. So if you have e.g. a RSS reader gadget, which sets the RSS URL in the preferences, the new installation will have the same URL set in its preferences as the source installation.

The following table lists the <UserPref> attributes:

Attribute Description
name Required "symbolic" name of the user preference; displayed to the user during editing if no display_name is defined. Must contain only letters, number and underscores, i.e. the regular expression ^[[]a-zA-Z0-9_]+$. Must be unique.
display_name Optional string to display alongside the user preferences in the edit window. Must be unique.
urlparam Optional string to pass as the parameter name for content type="url".
datatype Optional string that indicates the data type of this attribute. Can be string, bool, [#Enums enum], hidden (a string that is not visible or user editable), or [fundamentals.html#list list] (dynamic array generated from user input). The default is string.
required Optional boolean argument (true or false) indicating whether this user preference is required. The default is false.
default_value Optional string that indicates a user preference's default value.

User preferences can be accessed from your gadget using the user preferences Gadgets.Prefs_(v0.8), for example:

<script type="text/javascript">
   var prefs = new gadgets.Prefs();
   var someStringPref = prefs.getString("StringPrefName");
   var someIntPref = prefs.getInt("IntPrefName");
   var someBoolPref = prefs.getBool("BoolPrefName");
</script>

Enum Data Types

One of the values you can specify for the <UserPref> datatype attribute is enum. The enum data type is presented in the user interface as a menu of choices. You specify the contents of the menu using <EnumValue>.

For example, this <UserPref> lets users set the level of difficulty for a game. Each value that will appear in the menu (Easy, Medium, and Hard) is defined using an <EnumValue> tag.

<UserPref name="difficulty" 
     display_name="Difficulty"
     datatype="enum"
     default_value="4">
  <EnumValue value="3" display_value="Easy"/>
  <EnumValue value="4" display_value="Medium"/>
  <EnumValue value="5" display_value="Hard"/>
</UserPref>

The following table lists the <EnumValue> attributes:

Attribute Description
value Required string that provides a unique value. This value is displayed in the menu in the user preferences edit box unless a display_value is provided.
display_value Optional string that is displayed in the menu in the user preferences edit box. If you do not specify a display_value, the value is displayed in the user interface.


Help.png

This tutorial will give you more examples or information on these features:
Lesson 04: Preferences

Content Section

The <Content> section defines the type of content, and either holds the content itself or has a reference to external content. The <Content> section is where the gadget attributes and user preferences are combined with programming logic and formatting information to become a running gadget.

A Content block has the following attributes:

@type
REQUIRED. The type of content included in the body of this element. Valid values are "html" and "url".
  • When /Content/@type is "html", a variable substitution is done on the final assembled content section.
  • When /Content/@type is "url", The gadget server redirects to the url in /Content/@href and appends the following query string parameters to the URL:
up_<name>
A query parameter for each User Preference as a name/value pair.
lang
The language of the User viewing the gadget (valid values are the same as for /ModulePrefs/Locale/@lang
country
The country of the User viewing the gadget. (valid values are the same as for /ModulePrefs/Locale/@country
libs
A relative URL that points to any JavaScript files necessary to satisfy the features specified in /ModulePrefs/Require and /ModulePrefs/Optional elements in the Gadget.
@href
A URL pointing to an external file containing the body of this element.
  • If @type is "url", this value is REQUIRED. If @type is "url", this value represents an external document that will be presented directly to Users without filtering, by redirecting to it in the gadget IFRAME.
  • If @type is "html", the Container makes an HTTP GET request to the URL specified by @href, and interprets the response body as though it were /Content/text(). (See also Proxied Content)
@view
A comma delimited list of Views in which to include the content in this section. Example: <Content view="Profile,Canvas,Group"/> contains Content for three named views: Profile, Canvas, Group. See Gadgets_Views_Tech for a technical overview of the different views available.
To assemble a View, all Content sections where @view contains the required view name are concatenated. Concatenation does not happen when the @href is set on a <Content> block. In this case, the set of view names on <Content> blocks with @href set to a non-null, non-empty string MUST be unique within the Gadget XML.
text()
Contains data in an appropriate format to satisfy the requirements for @type. When @type is "html", if no @href is specified, this value MUST be a block of html. The text within this element SHOULD be wrapped in CDATA to avoid having to escape HTML tags and to prevent them from being interpreted by the XML parser. Important: if your gadget is installable by users, a profile and a preview view is required.

Example

 <?xml version="1.0" encoding="UTF-8"?>
 <Module>
   <ModulePrefs title="Proxied Content Example">
   </ModulePrefs>
   <Content view="profile,group">
     <![CDATA[
       Hello, profile or group view!
     ]]>
   </Content&gt;
   <Content view="canvas">
     <![CDATA[
       Hello, canvas view!
     ]]>
   </Content>
 </Module>

Substitutions and variables

The Gadget Server automatically substitutes some variables in the Gadget XML content section and in the metadata section. The following substitutions are available:

  • __MODULE_ID__: current module id
  • __MSG_*__: string from current message bundle
  • __ENV_CONTAINER__: name of current container (sandbox, svz, pvz, avz)
  • __VAR_*__: value of set variable

You can set variables in the ModulePrefs section of the Gadget XML with a Variable tag. The following attributes are available:

  • name: name of the variable
  • value: value of the variable
  • env: container in which this variable should be replaced (sandbox, svz, pvz, avz). if you do not specify this attribute the variable will be inserted in all container contexts.
<Variable name="TEST1" value="abc" />
<Variable name="TEST2" />
<Variable name="TEST3" env="sandbox" value="def" />
<Variable name="TEST3" env="svz" value="ghi" />