Справочное руководство по XML гаджетов

Это справочное руководство об XML спецификации гаджетов (OpenSocial, версия 0.9).

Справочное руководство по JavaScript можно найти здесь.

Тем, кто стремится изучить API гаджетов более основательно, рекомендуем ознакомиться со спецификациями гаджетов.

Содержание

  1. Элементы и атрибуты контейнера ModulePrefs
  2. Пользовательские настройки
  3. Раздел "Содержание"
  4. Справочное руководство по JavaScript
    1. Специализированные библиотеки JavaScript, ориентированные на конкретные функции

Элементы и атрибуты контейнера ModulePrefs

Раздел <ModulePrefs> файла XML описывает такие характеристики гаджета как название, автор, предпочтительные размеры и т.д. Например:

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

Пользователи гаджета не могут изменять эти атрибуты.

<ModulePrefs> выступает в роли контейнера для всех метаданных, функций и правил обработки. Описания вложенных элементов см. ниже в соответствующих разделах. Данный раздел посвящен элементам и атрибутам, входящим в <ModulePrefs>. В последующих разделах уровень вложенности отмечается косой чертой. Например, /ModulePrefs/Locale описывает элемент <Locale>, вложенный в элемент <ModulePrefs>. В спецификациях гаджета это может выглядеть следующим образом:

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

ModulePrefs

В следующей таблице перечислены атрибуты <ModulePrefs>, которые поддерживаются во всех контейнерах. Подробнее об <ModulePrefs> атрибутах конкретного контейнера см. в документации по контейнеру.

Атрибут Описание
title Необязательная строка, содержащая название гаджета. Это название отображается в строке заголовка гаджета на странице iGoogle. Если данная строка содержит переменные для подстановки параметров пользователя, а гаджет планируется отправить в каталог содержания iGoogle, необходимо также предоставить directory_title для отображения каталога.
title_url Необязательная строка, содержащая адрес URL, на который ссылается название гаджета. Например, название можно связать с веб-страницей, относящейся к гаджету.
description Необязательная строка, описывающая гаджет.
author Необязательная строка, представляющая автора гаджета.
author_email Необязательная строка, предоставляющая адрес электронной почты автора гаджета. Допускается использование любой системы электронной почты, но во избежание получения спама не следует использовать личный адрес электронной почты. Одним из возможных подходов является представление адреса электронной почты в спецификациях гаджета в виде helensmith.feedback+coolgadget@gmail.com.

Почтовая система Gmail опускает все содержимое адреса, следующее за знаком (+), поэтому данный адрес электронной почты интерпретируется как адрес helensmith.feedback@gmail.com.

Для создания учетной записи в почтовой системе Gmail воспользуйтесь этой ссылкой.
screenshot Необязательная строка, предоставляющая адрес URL для снимка экрана гаджета. Это изображение должно находиться на общедоступном веб-сайте, а доступ к изображению не должен быть заблокирован с помощью файла robots.txt. Предпочтительным форматом является PNG, но допускаются также изображения в формате GIF и JPG. Снимки экранов гаджетов должны иметь ширину 280 пикселей. Высота снимка экрана должна совпадать с "естественной" высотой гаджета в его рабочем состоянии.
thumbnail Необязательная строка, содержащая адрес URL уменьшенного изображения гаджета. Это изображение должно находиться на общедоступном веб-сайте, а доступ к изображению не должен блокироваться файлом robots.txt. Предпочтительным форматом является PNG, но допускаются также изображения в формате GIF и JPG. Уменьшенные изображения гаджетов должны иметь размер 120x60 пикселей.

Элементы ModulePrefs/Require и ModulePrefs/Optional

В элементах <Require> и <Optional> объявляются функциональные зависимости гаджета.

Атрибуты:

  • "feature" – имя функции. Обязательный

Примеры.

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

Элементы ModulePrefs/Require/Param и ModulePrefs/Optional/Param

Эти элементы предоставляют параметры настройки для функции.

Атрибуты:

  • "name" – имя параметра. Обязательный.

ModulePrefs/Preload

Элемент <Preload> содержит инструкции для контейнера об извлечении данных из удаленного источника в процессе визуализации гаджета. Данный элемент используется совместно с элементом makeRequest(), извлекающим данные с удаленного сервера.

Пусть запрос выглядит следующим образом.

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

Содержание, находящееся по адресу http://www.example.com, можно загрузить, добавив тег <Preload> в раздел <ModulePrefs> гаджета.

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

Когда гаджет выполняет вызов makeRequest(), это содержание возвращается незамедлительно, и повторного обращения к серверу не требуется.

Элемент <Preload> используется с целью сокращения задержки для гаджетов, использующих makeRequest() для извлечения данных с удаленных серверов. Подробнее об этом см. в документе Знакомство с элементом makeRequest.

Атрибуты:

  • "href" – URL, указывающий местонахождение данных, для которых требуется упреждающее извлечение. Обязательный.
  • "authz" – тип аутентификации, который следует использовать для формирования данного запроса. Допустимыми являются значения "none" (по умолчанию), "signed" и "oauth". Необязательный.

Эти атрибуты соответствуют параметрам авторизации в строке запроса makeRequest().

Атрибут Описание
oauth_service_name Псевдоним, используемый гаджетом для ссылки на элемент OAuth <Service> из спецификации XML гаджета. Если не указан, по умолчанию используется значение "". Соответствует gadgets.io.RequestParameters.OAUTH_SERVICE_NAME.
oauth_token_name Псевдоним, используемый гаджетом для ссылки на маркер OAuth, предоставляющий доступ к конкретным ресурсам. Если не указан, по умолчанию используется значение "". Если гаджеты имеют доступ к нескольким ресурсам одного и того же поставщика услуг, они могут использовать несколько имен маркеров. Например, гаджет с доступом к списку контактов и календарю мог бы использовать имя маркера "contacts" для маркера списка контактов и список контактов "calendar" для маркера календаря. Соответствует gadgets.io.RequestParameters.OAUTH_TOKEN_NAME.
oauth_request_token Поставщик услуг может автоматически предоставлять гаджету маркер запроса, по которому доступ к ресурсу разрешен заранее. Гаджет может использовать этот маркер с параметром OAUTH_REQUEST_TOKEN. Этот параметр является необязательным. Соответствует gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN.
oauth_request_token_secret Код secret, соответствующий заранее разрешенному маркеру запроса. Этот параметр является необязательным. Соответствует gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET.
sign_owner Логическое значение, указывающее, требуется ли аутентификация владельца. Если не указано, по умолчанию используется значение "true". Соответствует gadgets.io.RequestParameters.SIGN_OWNER.
sign_viewer Логическое значение, указывающее, требуется ли аутентификация читателя. Если не указано, по умолчанию используется значение "true". Соответствует gadgets.io.RequestParameters.SIGN_VIEWER.
views Разделенный запятыми список имен просмотров, запускающих указанную предварительную загрузку.

Отметим, что все атрибуты <Preload> применяются также к содержанию, передаваемому посредством прокси.

ModulePrefs/Icon

Элемент <Icon> описывает изображение размером 16 x 16 пикселей, которое контейнеры могут сопоставлять конкретному гаджету (например, контейнер может отображать значок рядом с именем гаджета в левой строке навигации).

В тег <Icon> может входить один из следующих вариантов содержания.

  • Адрес URL в формате HTTP, указывающий на файл изображения в Интернете
  • Встроенные данные изображения в кодировке base64.

Атрибуты:

  • "mode" – кодировка, используемая для значка при встраивании изображения. В настоящее время поддерживается только кодировка base64. Необязательный.
  • "type" – MIME текста встроенного значка. Необязательный.

Примеры.

<ModulePrefs title="My gadget">
  <Icon>http://remote/favicon.ico</Icon>
</ModulePrefs>

<ModulePrefs title="My gadget">
  <Icon mode="base64" type="image/png">base64 encoded data</Icon>
</ModulePrefs>

ModulePrefs/Locale

Элемент <Locale> описывает региональные настройки, поддерживаемые гаджетом. Его можно использовать также для описания пакетов сообщений, как указано в документе Подготовка гаджетов к локализации.

Атрибуты:

  • "lang" – язык, соответствующий региональным настройкам. Необязательный.
  • "country" – страна, соответствующая региональным настройкам. Необязательный.
  • "messages" – адрес URL, указывающий на пакет сообщений. Пакеты сообщений представляют собой файлы XML, в которых находятся переведенные для заданных региональных настроек строки. Подробнее см. в документе Подготовка гаджетов к локализации. Необязательный.
  • "language_direction" – направление гаджета. Необязательный. Его значением может быть либо "rtl" (справа налево), либо "ltr" (слева направо). По умолчанию установлено значение "ltr". Данный атрибут позволяет создавать гаджеты, поддерживающие языки с направлением письма как слева направо, так и справа налево. Более подробно данная тема обсуждается в разделе Создание двунаправленных гаджетов. Совместно с атрибутом language_direction можно использовать следующие переменные подстановки.
    • __BIDI_START_EDGE__: содержит значение "left", если гаджет работает в режиме LTR, и значение "right", если гаджет работает в режиме RTL.
    • __BIDI_END_EDGE__: содержит значение "right", если гаджет работает в режиме LTR, и значение "left", если гаджет работает в режиме RTL.
    • __BIDI_DIR__: эта переменная содержит значение "ltr", если гаджет работает в режиме LTR, и значение "rtl", если гаджет работает в режиме RTL.
    • __BIDI_REVERSE_DIR__: эта переменная содержит значение "rtl", если гаджет работает в режиме LTR, и значение "ltr", если гаджет работает в режиме RTL.

Например, в следующем фрагменте описаны две различные региональные настройки.

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

Оба атрибута "lang" (язык) и "country" (страна) являются необязательными, но по крайней мере один из них необходим для каждого элемента <Locale>. Если опущены оба атрибута, значение эквивалентно "*" и "ALL". Если указана страна, но не указан язык, считается, что гаджет поддерживает все языки, соответствующие данной стране. Подобным же образом, если указан язык, но не указана страна, считается, что гаджет поддерживает все страны, соответствующие данному языку.

Для параметра языка допустимыми значениями являются состоящие из двух цифр коды языков по стандарту ISO639-1, а для страны — коды ISO 3166-1 alpha-2.

Существует несколько исключений.

  • Китайский (упрощенный): lang="zh-cn" (обычно для country="cn").
  • Китайский (традиционный): lang="zh-tw" (обычно для country="tw" или "hk", Тайвань или Гонконг, соответственно).

ModulePrefs/Link

Ссылка конкретного контейнера. Этот тег можно использовать, например, для поддержки новых типов ссылок, таких как gadgetsHelp и gadgetsSupport.

Атрибуты:

  • "rel" – значение, запускающее событие жизненного цикла. Обязательный.
  • "href" – URL. Обязательный.
  • "method" – метод (POST или GET) отправки запроса. По умолчанию используется метод GET. Необязательный.

Дополнительно контейнер может поддерживать отправку событий жизненного цикла на сайт разработчика приложения, отправляя для этого в конечную точку URL соответствующие параметры запроса. Для приема этих событий можно использовать тег <Link>. У каждого тега <Link> имеется атрибут rel и href. Атрибут href обозначает конечную точку, в которую передаются запросы ping событий. Если атрибут rel имеет значение "opensocialevent", тогда все события передаются в данную конечную точку. Если атрибут rel имеет значение "opensocialevent.TYPE",, тогда в данную конечную точку передаются все события TYPE. Чтобы указать способ передачи запроса, для необязательного атрибута метода можно установить значение POST или GET. По умолчанию установлен метод GET. Ниже приведено несколько примеров.

<link rel="event" href="http://www.example.com/pingme" method="POST/>
<link rel="event.addapp" href="http://www.example.com/add" />
<link rel="event.removeapp" href="http://www.example.com/remove" />

В большинстве событий имеется информация об одном или нескольких значениях OpenSocial ID. Эти значения ID передаются в виде одного или нескольких атрибутов ID. Отметим, что указывая несколько значений ID, можно в один пакет ping включить несколько событий.

Определяются следующие типы событий.

  • addapp – пользователи, установившие приложение (ID). Необязательный параметр "from" описывает способ, которым пользователь добавил данное приложение. Возможны значения "invite", "gallery" и "external".
  • removeapp – идентификаторы пользователей, удаливших приложение
  • appaction={enabled|disabled|approved} reason={policy|quota|maintenance}
  • inviteid приглашенные лица, from_id – идентификтор, отправивший приглашение.

ModulePrefs/OAuth

Элемент <OAuth> определяет использование гаджетом прокси OAuth. Подробнее о реализации OAuth в гаджетах см. в разделе Создание гаджетов OAuth.

ModulePrefs/OAuth/Service

Этот элемент определяет единственную настройку службы OAuth.

Атрибуты:

  • "name" – имя службы (например, "google"), используемое в процессе выполнения для ссылки на службы OAuth. Данный параметр является необязательным, и если он не указан, по умолчанию используется пустое значение "". Разработчики гаджетов указывают, какую службу OAuth требуется использовать, передавая имя службы в качестве параметра функции makeRequest().

Элементы ModulePrefs/OAuth/Service/Request и ModulePrefs/OAuth/Service/Access

Представляет маркер запроса OAuth и адреса URL маркеров доступа. Подробнее см. Спецификация OAuth и Создание гаджетов OAuth.

Атрибуты:

  • "url" – URL конечной точки.
  • "method" – команда HTTP, используемая для создания запроса. Этот параметр является необязательным. Если не указан, по умолчанию используется POST.
  • "param_location" – одно из трех возможных местоположений в запросе к службе, куда могут передаваться параметры OAuth. Это значение можно использовать для указания местоположения параметров, относящихся к OAuth. Возможны следующие значения.
    • "uri-query" – параметры OAuth передаются в строке запроса.
    • "auth-header" – параметры OAuth передаются в заголовке авторизации.
    • "post-body" – параметры OAuth передаются в теле запроса POST.

Эти значения соответствуют вариантам, описанным в документе Спецификация OAuth. По умолчанию используется значение "auth-header".

ModulePrefs/OAuth/Service/Authorization

Адрес URL авторизации OAuth.

Настройки пользователя

Некоторые гаджеты должны обеспечивать ввод информации, относящейся к конкретному пользователю. Например, гаджету погоды может потребоваться, чтобы пользователи предоставляли свои почтовые коды. В разделе настроек пользователя (<UserPref>) файла XML описываются поля для ввода информации пользователем, которые во время выполнения гаджета превращаются в элементы управления пользовательского интерфейса.

В следующей таблице перечислены атрибуты <UserPref>.

Атрибут Описание
name Обязательное "символьное" имя настройки пользователя; отображается пользователю при редактировании, если не определено display_name. Оно должно состоять только из букв, цифр и подчеркиваний, то есть быть регулярным выражением ^[a-zA-Z0-9_]+$. Имя должно быть уникальным.
display_name Необязательная строка для отображения в окне редактирования рядом с настройками пользователей. Имя должно быть уникальным.
urlparam Необязательная строка, передаваемая как название параметра содержания type="url".
datatype Необязательная строка, указывающая тип данных этого атрибута. Может принимать значения string, bool, enum, hidden (неотображаемая, которую пользователь не может изменять) или list (динамический массив, генерируемый на основе введенных пользователем данных). По умолчанию используется значение string.
required Необязательный логический аргумент (true или false), указывающий, является ли данная пользовательская настройка обязательной. По умолчанию используется значение false.
default_value Необязательная строка, указывающая значение по умолчанию для настройки пользователя.

Из гаджета доступ к пользовательским настройкам можно получать с помощью пользовательских настроек JavaScript API, например:

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

Типы данных Enum

Одним из значений, которые можно указать для атрибута <UserPref> datatype, является enum. Тип данных enum представлен в пользовательском интерфейсе в виде меню с вариантами для выбора. Содержание меню указывается с помощью <EnumValue>.

Например, элемент <UserPref> позволяет пользователям настраивать уровень сложности в игре. Каждое значение, отображаемое в меню (Легкий, Средний, Сложный), определяется с помощью тега <EnumValue>.

<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>

В следующей таблице перечислены атрибуты <EnumValue>.

Атрибут Описание
value Обязательная строка, предоставляющая уникальное значение. Это значение отображается в меню в поле редактирования настроек пользователя, если нет display_value.
display_value Необязательная строка, отображаемая в меню в поле редактирования настроек пользователя. Если не указано display_value, в пользовательском интерфейсе отображается value.

Раздел "Содержание"

Раздел <Content> определяет тип содержания и содержит либо само содержание, либо ссылку на внешнее содержание. Именно в разделе <Content> атрибуты гаджета и пользовательские настройки объединяются с программной логикой и информацией о форматировании, что необходимо для выполнения гаджета. Подробнее о типах содержания см. в документе Выбор типа содержания.

В следующей таблице перечислены атрибуты <Content>.

Атрибут Описание
type Необязательная строка, предоставляющая тип содержания. Возможны значения html и url. По умолчанию используется значение html.
href Строка с URL назначения. Этот атрибут можно применять либо к гаджету type="url", либо к содержанию, передаваемому через прокси.
view Необязательная строка. Только для гаджетов OpenSocial. Указывает, при каком типе просмотра контейнера OpenSocial должно отображаться содержание. В гаджете OpenSocial можно определить несколько разделов содержания, каждый из которых может применяться к разным вариантам отображения.
preferred_height Исходная высота гаджета в пикселях.
preferred_width Исходная ширина гаджета в пикселях.

ModulePrefs/Content@href (содержание, передаваемое через прокси)

Содержание, передаваемое через прокси, является функцией, которая применяется к гаджетам OpenSocial. Эта функция позволяет с помощью URL указать содержание в формате HTML для конкретного типа просмотра. Подробнее о просмотрах см. в документе Несколько разделов содержания.

Целевой адрес URL, который указывается для этой функции, должен быть допустимым выражением в формате HTML 4.01, XHTML 1.1 и т.д. Не следует указывать URL изображения или Flash, хотя можно заключить их в HTML и затем сформировать ссылку на этот HTML. В целевое содержание HTML должны входить теги <html>, <head> и <body>.

Например, следующий гаджет использует содержание, передаваемое через прокси, для просмотра canvas, и встроенное содержание для просмотра home.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs title="Proxied Content Example">
</ModulePrefs>
  <Content view="canvas" 
    href="http://gadget-doc-examples.googlecode.com/svn/trunk/opensocial-09/mycontent.html">
  </Content>
  <Content view="home">
    <![CDATA[
      Hello, home view!
    ]]>
  </Content>
</Module>

В содержании, передаваемом посредством прокси, используются те же атрибуты, которые применяются к элементу <Preload>. Подробнее см. в разделе ModulePrefs/Preload.

Справочное руководство по JavaScript

Справочное руководство по JavaScript см. здесь.

Включение специализированных библиотек JavaScript для конкретных функций

Для создания гаджета, использующего конкретную функцию, например, вкладки или флэш-фильм, в спецификацию гаджета необходимо включить библиотеку функций с помощью тега <Require> (внутри <ModulePrefs>). Например:

<ModulePrefs 
  title="My Tabbed Gadget">
  <Require feature="tabs"/>
</ModulePrefs> 

API для gadgets.* предоставляет следующие библиотеки функций.

Библиотека функций Описание Синтаксис
setprefs Программным образом устанавливает значение настройки пользователя. Подробнее см. в документе Сохранение состояния. <Require feature="setprefs"/>
dynamic-height Предоставляет гаджету возможность самостоятельно изменять свои размеры. Подробнее см. в документе Определение высоты гаджета. <Require feature="dynamic-height"/>
settitle Программно устанавливает название гаджета. Подробнее см. в документе Создание названия гаджета. <Require feature="settitle"/>
tabs В гаджет добавляется интерфейс, использующий вкладки. Подробнее см. в документе Вкладки. <Require feature="tabs"/>
minimessage Отображает в гаджете временное сообщение, которое должен закрыть пользователь. Подробнее см. в документе MiniMessages. <Require feature="minimessage"/>
flash Встраивает в гаджет флэш-фильм (а именно файл .swf). Подробнее см. в документе Flash. <Require feature="flash"/>
locked-domain Библиотека locked-domain изолирует гаджет от других гаджетов, работающих на этой же странице. Эту функцию можно использовать только с гаджетами, имеющими тип type="html". Рекомендуется добавлять в гаджет требование на эту функцию, если гаджет сохраняет важные личные данные пользователей. Данная функция поддерживается только на страницах iGoogle и Календарь Google. Другие контейнеры гаджетов могут не поддерживать эту функцию и будут отклонять ваш гаджет. <Require feature="locked-domain"/>

Для просмотра всех методов, поддерживаемых конкретной функцией, ознакомьтесь с разделом Справочное руководство по JavaScript.

 

К началу