Создание собственных гаджетов

Начало работы – введение в гаджеты. Следующий шаг – создание собственных гаджетов. Этот документ расскажет, как.

Содержание

  1. Основные шаги
  2. Структура гаджета
    1. Определение содержания
    2. Определение пользовательских настроек
    3. Определение настроек гаджетов
  3. Не забывайте: гаджеты общедоступны
  4. Дальнейшие действия

Основные шаги

Здесь описано несколько основных шагов при создании и размещении гаджетов.

  1. Составьте спецификацию гаджета в текстовом редакторе, а затем сохраните ее на общедоступном веб-сервере.
  2. Добавьте гаджет в контейнер, например iGoogle или Orkut. Контейнер – это приложение или сайт, которые могут выполнять гаджеты.

Структура гаджета

Разобравшись в способах изменения и публикации гаджетов, можно начинать включать в спецификации гаджетов более "продвинутые" функции. XML-cпецификация гаджета состоит из 3 основных частей.

  • Раздел содержания. Раздел <Content> – то место, где происходит настоящая работа вашего гаджета. Здесь следует указывать тип гаджета, логику программирования, а также зачастую элементы HTML, определяющие его внешний облик.
  • Пользовательские настройки. В разделе <UserPrefs> определены функции, которые дают пользователям возможность выбирать настройки гаджета. Например, в гаджете персонального приветствия может находиться текстовое поле, в котором пользователям следует указывать, как их зовут.
  • Настройки гаджета. В разделе <ModulePrefs> XML-файла указаны характеристики гаджета (например, название, автор, предпочитаемый размер и т.д.).

Примечание. В атрибутах XML спецификации гаджета необходимо правильно закодировать некоторые символы, т.е. символы "перевода", чтобы обеспечить их правильную интерпретацию. Подробнее см. в разделе Перевод специальных символов.

Создавая гаджет, следует начинать с раздела <Content>.

Определение содержания

Раздел <Content> представляет собой "мозг" гаджета. Раздел <Content> определяет тип содержания и содержит само содержание или ссылается на внешнее содержание. Раздел <Content> – это место, где атрибуты гаджета и пользовательские настройки объединяются с логикой программирования и сведениями о форматировании в работающий гаджет.

Простейший способ создать гаджет – просто поместить HTML (а возможно и JavaScript или Flash) в раздел <Content>. Опытные веб-разработчики могут почитать Выбор типа содержания, где описаны другие варианты контроля доступа, удаленного хостинга, использование других языков создания сценариев и многое другое. Вот простой пример гаджета. В этом гаджете имеется фотография, которую нужно нажать, чтобы открыть фотоальбом на новой странице HTML:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Go to Photo Album" height="250" scaling="false" />
  <Content type="html">
  <![CDATA[ 
    <div style="text-align:center"><a
      id="Riggs" title="My Photo Album" target="_blank" 
      href="http://picasaweb.google.com/doc.examples/ShelfBoy">
<img border="0" alt="Photo" src="http://doc.examples.googlepages.com/Riggsie-OP.jpg"
title="Click Here."></a>
</div> ]]> </Content> </Module>

Определение пользовательских настроек

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

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

  • Имя, используемое в приветствии. Это имя пишется также в строке заголовка.
  • Цвет фона.
  • Нужно ли показывать фотографию.

Вот как выглядит гаджет, когда пользователь нажимает изменить для изменения пользовательских настроек:

Элементы управления пользовательскими настройками

В спецификации формата XML определены элементы управления в интерфейсе включенного гаджета, которые отвечают за пользовательские настройки.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="250" />
<UserPref name="myname" display_name="Name" required="true" />
<UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
<UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
<UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" > <EnumValue value="Red" /> <EnumValue value="Aqua" /> <EnumValue value="Lime" /> <EnumValue value="Yellow" /> <EnumValue value="Pink" /> <EnumValue value="Orange" /> <EnumValue value="White" /> </UserPref>

Необходимо учесть следующее.

  • Строка 3 файла содержит текст title="Preferences for __UP_myname__". При выполнении гаджета значение, предоставленное для пользовательских настроек myname динамически подставляется вместо __UP_myname__.
  • Пользовательская настройка myname отмечена как "обязательная".Если пользователь пытается выполнить гаджет, не предоставив значение этого поля, окошко изменения пользовательских настроек остается открытым до тех, пока оно не будет предоставлено.
  • Пользовательская настройка mychoice имеет тип данных bool. В интерфейсе пользователя ей соответствует флажок.
  • Пользовательская настройка mycolor имеет тип данных enum. Список EnumValues указывает варианты, которые появятся в раскрывающемся меню в окне изменения пользовательских настроек.

Вот весь гаджет, вместе с кодом JavaScript, который отображает текст приветствия для этого гаджета.

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Preferences for __UP_myname__" height="400"/> 
  <UserPref name="myname" display_name="Name" default_value="Rowan"/>
  <UserPref name="myphoto" display_name="Photo" default_value="http://doc.examples.googlepages.com/rowan-headshot.jpg"/>
  <UserPref name="mychoice" display_name="Show Photo?" datatype="bool" default_value="true"/>
  <UserPref name="mycolor" display_name="Color" default_value="Yellow" datatype="enum" >
    <EnumValue value="Red" />
     <EnumValue value="Aqua" />
     <EnumValue value="Lime" />
     <EnumValue value="Yellow" />
     <EnumValue value="Pink" />
     <EnumValue value="Orange" />
     <EnumValue value="White" />
   </UserPref>
   <Content type="html"><![CDATA[
   <div id="content_div"></div>
   <script type="text/javascript">
   // Get userprefs
   var prefs = new gadgets.Prefs();

   function displayGreeting () {
     // Get current time
     var today = new Date();
     var time = today.getTime();
     var html = "";
  
     // Based on the time of day, display an appropriate greeting
     var hour = today.getHours();
     var salutation = "Afternoon";
     if (hour < 12) {
       salutation = "Morning";
     } else if (hour > 17) {
       salutation = "Evening";
     }

     // Set the background color according to the mycolor userpref
     var element = document.getElementById('content_div');  
     element.style.height=250;
     // Set the background color according to the mycolor userpref   
     element.style.backgroundColor=prefs.getString("mycolor"); 

     // Display a greeting based on the myname userpref
     html += "<br><FONT SIZE=6>Good " + salutation + ", " +
           prefs.getString("myname") + "!!!<br><br></FONT>";

     // If the "Show Photo?" checkbox is checked, display photo.
     if (prefs.getBool("mychoice") == true) {
       html += '<img src="' + prefs.getString("myphoto") + '">';
     }
     element.innerHTML = html;
   }
   // Pass the userprefs for this module instance to the function
   // (allows users to include multiple module instances on their page)
   gadgets.util.registerOnLoadHandler(displayGreeting); 
  
   </script> 
   ]]>  
  </Content>
</Module>

Список атрибутов <UserPref> см. в Справочном руководстве.

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

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

Список всех функций JavaScript см. в Справочном руководстве JavaScript.

Подстановка переменных для пользовательских настроек

Вы можете использовать подстановку переменных формата __UP_userpref__ в разделах <ModulePrefs> или <UserPref>, где userpref соответствует названию атрибута пользовательской настройки. После запуска гаджета строковое значение соответствующей пользовательской настройки подставляется вместо переменной, без перевода. Например, в этом фрагменте значение, представляемое пользователем во время выполнения для пользовательской настройки projects подставляется вместо __UP_projects__ в строке title_url:

<Module>
  <ModulePrefs title="Build Monitor"
             title_url="http://www.example.com/build/status.php?__UP_projects__"/>
  <UserPref name="projects" display_name="project(s)"/>
  <Content ... />
</Module>

Еще это можно посмотреть в примере пользовательских настроек.

Ниже приводится общее руководство по применению подстановки переменных для пользовательских настроек.

  • Для атрибута <ModulePrefs> title используйте __UP_name__ . Это переведено в HTML.
  • Для атрибута <ModulePrefs> title_url используйте __UP_name__ . Это переведено в HTML.
  • В HTML в разделе <Content> используйте __UP_name__. Это переведено в HTML.
  • В коде JavaScript в разделе <Content> используйте функцию gadgets.Prefs().

Совместный доступ к настройкам пользователей

С помощью функции shareable-prefs можно предоставить нескольким пользователям возможность изменять настройки гаджета. Таким образом, пользователи могут совместно пользоваться гаджетом и видеть, кто что изменил. Например, члены семьи могут иметь общий гаджет со списком покупок и каждый человек может добавлять свои любимые продукты. Данные настроек пользователей – часть состояния гаджета, хранящаяся на iGoogle. Дополнительные сведения о пользовательских настройках можно найти в Руководстве разработчика API гаджетов.

Для того чтобы пользовательские настройки гаджета совместно использовались несколькими пользователями, гаджет должен содержать строку <optional feature="shareable-prefs"/> в разделе <ModulePrefs>. Например, этот гаджет использует пользовательскую настройку стипом данных list для заполнения списка покупок:

Совместный доступ к гаджету

Вот код гаджета:

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs 
    title="Our Grocery List" 
    scrolling="true"> 
    <optional feature="shareable-prefs"/> 
   </ModulePrefs>
  <UserPref name="mylist" 
    display_name="Add items" 
    datatype="list" />
  <Content type="html">
  <![CDATA[ 
    <div id="content_div" style='color: #CC0099; font-family: serif; font-size: 120%;'></div>

  <script type="text/javascript"> 
    // Get userprefs
    var prefs = new gadgets.Prefs();
    // Get the list
    var items = prefs.getArray("mylist");  
    var html = "";
    // If there are no items in the list yet, display message.
    if (items.length == 0)
    {
      html += "Edit the userprefs to add items to the list.";
    }
    else {
      for (var i = 0; i < items.length ; i++) {
        var term = (items[i]);
        html += term + "<br />";
      }
    }
    document.getElementById("content_div").innerHTML = html; 
  </script>
  ]]> 
  </Content>
</Module>

Добавив на iGoogle гаджет, поддерживающий настройки совместного доступа, его можно сделать доступным для совместного использования следующим образом.

Шаг 1: Нажмите треугольник на том гаджете, к которому нужно предоставить совместный доступ, и выберите Открыть доступ к этому гаджету.

Совместный доступ к гаджету

Шаг 2: Если вы используете Gmail, выберите друзей, которым вы хотите открыть доступ к гаджету или введите их адреса электронной почты.

Совместный доступ к гаджету

Шаг 3: Решите, смогут ли друзья редактировать содержание гаджета или только просматривать его на своих страницах iGoogle.

  • При выборе Просматривать и редактировать содержание друзья смогут редактировать пользовательские настройки гаджета. Их изменения будут отражаться в вашей версии гаджета и во всех остальных совместно используемых версиях этого гаджета.
  • При выборе Просматривать содержание друзья не смогут изменять как сам гаджет, так и его копии на собственных страницах. Только вы сможете изменять гаджет, а ваши изменения будут применены ко всем совместно используемым версиям гаджета.

Нажмите Отправить приглашения. Друзья получат от вас письмо с приглашением добавить гаджет на свои страницы iGoogle.

Приглашение к совместному использованию

Друзья, которым вы разрешили изменять гаджет, могут редактировать пользовательские настройки и публиковать изменения во всех совместно используемых версиях гаджета.

Определение настроек гаджетов

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

<Module>
<ModulePrefs title="Today's Network Traffic" title_url="http://www/~rowan/gadgets/stats/"
height="200" author="Jane Smith" author_email="xxx@google.com"/>
<Content ...>
... content ...
</Content>
</Module>

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

Список атрибутов <ModulePrefs> см. в Справочном руководстве.

Не забывайте: гаджеты общедоступны

Помните, что частных гаджетов не бывает. После того как вы опубликуете свой гаджет на общедоступном веб-сайте, люди смогут найти и просмотреть его. Ни в коем случае не включайте в него личную информацию, например свой номер телефона или адрес электронной почты.

Как ограничить доступ к своему гаджету? Google призывает авторов гаджетов делиться спецификациями. Однако если требуется свести к минимуму доступ к гаджету до момента готовности к выпуску, обратите внимание на несколько советов ниже.

  • Не подавайте гаджет в каталог содержания и не размещайте его в таких каталогах, как googlemodules.com или hotmodules.com.
  • Если ваш гаджет нельзя будет найти, вряд ли кто-то сможет угадать его URL. Вот несколько тонких моментов, которые необходимо учесть, чтобы избежать сканирования поисковыми системами.
    • Убедитесь, что на веб-сервере отсутствует список файлов, включающий ваш файл (это также поможет скрыть его от пользователей).
    • Удостоверьтесь в том, что к гаджету не ведут гиперссылки

Дальнейшие действия

Если вы готовы писать более сложные гаджеты, зайдите в Основные принципы разработки или обратно на главную страницу документации, где есть обзор разделов и тем.

В начало