Gadgets: Начало работы с гаджетами таблиц

http://docs.google.com/support/bin/answer.py?hl=ru&answer=96978

Печать

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

Гаджет таблицы - это небольшая программа, работающая с содержимым таблицы. Ее визуальный экземпляр создается либо в самой таблице, либо на другой веб-странице, поддерживающей гаджеты Google (например, iGoogle).

С помощью гаджетов таблиц можно сделать следующее:

• добавить в таблицу специальные функции;
• объединить данные таблицы с содержимым из Интернета;
• визуализировать данные таблицы оригинальным образом;
• вывести данные таблицы на других веб-страницах.

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

Для того чтобы увидеть, как обратиться к гаджету таблицы из Документов Google, зайдите в свой аккаунт Документов Google и сделайте следующее:

• Создайте новую таблицу.
• Нажмите на значок диаграммы или откройте меню "Вставить".
• Выберите "Гаджет...", чтобы открыть список доступных всем гаджетов.

Ваш первый гаджет таблицы:

для того чтобы создать новый гаджет таблицы, воспользуйтесь следующим кодом и поэкспериментируйте с изменениями в его логике. Этот пример получает и выводит в виде одного столбца содержимое диапазона ячеек. Все ячейки, содержащие слово "world", выделяются красным цветом. Пример состоит из трех основных частей: задания заголовка гаджета Google, получения данных из таблицы с помощью визуализаций Google и программного фрагмента, создающего HTML-код. Для этого необходимы два API-интерфейса: API гаджетов Google и API визуализаций Google. По мере возникновения более сложных технических вопросов обращайтесь к подробной информации, описывающей эти API-интерфейсы.

Для начала создадим заголовок гаджета Google:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs
title="Simple Table Gadget"
description="Учебный гаджет таблицы"
author="Google Engineering"
 author_affiliation="Google Inc."
author_email="visualization.api+spreadsheet@gmail.com"
screenshot="/ig/modules/spreadsheet.png"
 thumbnail="/ig/modules/spreadsheet-thm.png" > 
<Require feature="idi"/>
<Require feature="locked-domain" />
</ModulePrefs>
<UserPref name="_table_query_url" display_name="Data source url" required="true"/>
 <UserPref name="_table_query_refresh_interval" display_name="Data refresh interval (minutes)" 
default_value="0" datatype="enum" required="false">
<EnumValue value="0" display_value="Do not refresh"/>
 <EnumValue value="60" display_value="1"/>
<EnumValue value="300" display_value="5"/>
<EnumValue value="1800" display_value="30"/>
</UserPref>
 <Content type="html"><![CDATA[ 

Для получения данных из таблицы воспользуйтесь API-интерфейсом визуализаций. Сначала загрузите стандартный загрузчик Google, предоставляющий API-интерфейс визуализаций для чтения содержимого таблицы:

<script src="http://www.google.com/jsapi" type="text/javascript"></script>

Задайте область HTML (в данном случае это будет тэг DIV), в которую будут выводиться результаты:

<div id="tablediv" style="overflow: auto;"><img src="http://www.google.com/ig/images/spinner.gif" /></div>
 

Загрузите все API-интерфейсы по порядку и задайте название для функции ("sendQuery"), которая будет выполняться при загрузке API-интерфейса:

<script>

var gadgetHelper = null;
_IG_RegisterOnloadHandler(loadVisualizationAPI);
function loadVisualizationAPI() { 
  google.load("visualization", "1");
   google.setOnLoadCallback(sendQuery);
}

Создайте запрос на базе настроек пользователя гаджетов Google, который будет обращаться к источнику данных таблицы. Кроме того, задайте имя функции ("handleQueryResponse"), которая будет выполняться при получении данных таблицы:

function sendQuery() {
  var prefs = new _IG_Prefs(); // настройки пользователя 
  gadgetHelper = new google.visualization.GadgetHelper(); 
  var query = gadgetHelper.createQueryFromPrefs(prefs);
   query.send(handleQueryResponse);
} 

Основная логика. Обработайте данные таблицы так, как вам необходимо. В данном примере мы создаем HTML-код, который будет снова показан пользователю. Для пошагового описания того, что делается, воспользуемся внутритекстовыми комментариями.

function handleQueryResponse(response) {

  /**
   * Использование класса визуализации GadgetHelper для обработки ошибок 
   */
  if (!gadgetHelper.validateResponse(response)) {
    return;     // Default error handling was done, just leave. 
   }

  /**
   * ПОЛУЧЕНИЕ ДАННЫХ ИЗ ТАБЛИЦЫ - простите за крик прописными буквами, но это ключевой момент
   */
  var data = response.getDataTable();

  var html = [];   // начало строки выводимого HTML-кода
   html.push('Looking for the secret word\n');

  /**
   * Обработка всех строк в выбранном диапазоне
   */
  for (var row = 0; row < data.getNumberOfRows(); row++) {

    /**
     * Обработка столбцов в каждой строке
      */
    for (var col = 0; col < data.getNumberOfColumns(); col++) {

      /**
       * ПОЛУЧЕНИЕ ЭЛЕМЕНТА ДАННЫХ ИЗ ДИАПАЗОНА - еще раз простите за крик, но это еще один ключевой момент 
       */
       var formattedValue = data.getFormattedValue(row, col);
      formattedValue = escapeHtml(formattedValue);

      /**
       * Поиск слова 'world'... добавлять его в HTML-код можно как угодно, но его форматирование при этом должно отличаться
        */
      if (formattedValue == 'world') {
        html.push('<span style="color:red; font-size:24pt; font-weight:bold;">');
        html.push(formattedValue);
        html.push('</span>');
       } else {
        html.push(formattedValue);
      }
      html.push('\n');
    }
  } 

  /**
   * Размещение сгенерированного HTML-кода в контейнере DIV.
   */
  var tableDiv = _gel('tablediv');
   tableDiv.innerHTML = html.join('');
  tableDiv.style.width = document.body.clientWidth + 'px';
  tableDiv.style.height = document.body.clientHeight + 'px';
}

Добавление какого-нибудь дополнительного кода (например, вот такой полезной функции, которая экранирует в выводимом HTML-коде специальные символы):

function escapeHtml(text) {
  if (text == null) {
    return '';
  }
  return _hesc(text);
} 
</script>

Наконец, в довершение работы над гаджетом - XML-тэги:

]]>
</Content>
</Module>

Вот и все. Код находится в редакторе гаджетов Google. Если хотите, поэкспериментируйте с его логикой (Примечание: в браузере Safari это может отображаться как пустая область)
Для того чтобы полностью создать и развернуть гаджет таблицы, нужно всего лишь:

1. написать код;
2. загрузить его на сервер;
3. обратиться к нему из редактора таблиц Документов Google.

Вот несколько моментов, на которые стоит обратить внимание при выполнении всех этих действий:

1. Написание кода.

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

• Редактор гаджетов Google Gadget Editor (GGE) позволяет редактировать, просматривать, сохранять, загружать и публиковать код гаджетов. Он используется и на этой странице для работы с учебным кодом. Редактор GGE - это тоже гаджет (meta!).
• Хостинг проектов Google Home Project Hosting позволяет разместить свой код в Интернете.
• Можно использовать и любой другой редактор или хостинг, который вам понравится.

Использование редактора гаджетов Google

• Чтобы настроить редактор гаджетов Google (GGE) для создания гаджетов, сделайте следующее.
1. Добавьте его на свою страницу iGoogle.
2. Разместите редактор CGE на отдельной вкладке.
3. Для того чтобы отредактировать параметры вкладки, нажмите на маленькую стрелку рядом с названием вкладки и выберите "Редактировать эту вкладку". Для того чтобы сделать поле редактора CGE шире, переключитесь в режим отображения одной или двух колонок.
• Редактор GGE позволяет сохранять код на сервере Google и загружать его оттуда. Для того чтобы получить URL-адрес кода, нажмите на гиперссылку в правом верхнем углу CGE.

2. Загрузка кода на сервер.

Если вы используете редактор гаджетов Google, код уже находится на сервере Google. Для того чтобы получить URL-адрес конкретного гаджета, нужно открыть его в редакторе гаджетов Google, нажать правую кнопку на имени (ссылке) гаджета в верхней правой части окна (на компьютере Mac - нажать кнопку, удерживая нажатой клавишу Ctrl) и выбрать "Копировать ссылку". Теперь можно перейти к следующему шагу - "Обращение к коду гаджета". Если используется другой способ хранения гаджета, понадобится просто полный URL-адрес этого гаджета.

3. Обращение к коду гаджета из редактора таблиц:

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

1. Теперь, когда гаджет загружен на какой-либо сервер, скопируйте URL-адрес этого гаджета. Он должен заканчиваться на ".xml".
2. В таблице нажмите "Вставить" > "Гаджет...", затем в левой части окна выбора гаджета нажмите на ссылку "Пользовательский...".
3. Вставьте в поле скопированный URL-адрес. ВАЖНОЕ ПРИМЕЧАНИЕ: при тестировании гаджета необходимо добавить в конец его URL-адреса параметр "?nocache", что позволит коду гаджета обновляться по мере внесения вами в него каких-либо изменений.
4. Нажмите "Добавить". Ваш гаджет появится в плавающем окне поверх таблицы. Теперь можно задать параметры пользователя и приступить к работе с гаджетом. При желании можно также опубликовать свой гаджет на iGoogle; для этого нужно выбрать гаджет, нажать на треугольник справа от заголовка и выбрать "Добавить гаджет в iGoogle...".
5. Если гаджет работает не так, как нужно, воспользуйтесь советами по отладке.

Совместное использование гаджета с другими людьми

• Если вы хотите поделиться своим гаджетом с другими людьми, можно либо дать им доступ к таблице, на которой используется этот гаджет, либо (если нужно совместно использовать не таблицу, а только гаджет) сообщить им URL-адрес своего гаджета и предложить добавить его на свои таблицы в качестве пользовательского. Мы пытаемся упростить этот процесс.

Публикация своего гаджета для общего пользования

• Когда код уже готов к использованию, можно опубликовать его в галерее API визуализаций Google. Лучшие гаджеты будут доступны всем пользователям таблиц Документов Google!