Установка гаджетов Google на главной странице Lotus Connections

Эта статья знакомит читателей с разработанной IBM спецификацией iWidget, которая используется в различных продуктах IBM, таких как IBM Lotus Connections 2.0. В статье объясняются различные аспекты спецификации на практическом примере, который показывает, как реализовать iWidget, выступающий в качестве оболочки для гаджетов Google.

Винсент Буркхардт, инженер-программист, IBM

Винсент Буркхардт (Vincent Burckhardt) работает инженером-программистом в лаборатории программного обеспечения IBM в Дублине. С 2007 года он входит в состав группы разработчиков IBM Lotus Connections. С ним можно связаться по адресу: vincent.burckhardt@ie.ibm.com.



12.01.2011

Примечание. В настоящей статье рассматривается версия Lotus Connections 2.0. Вы можете обратиться к другой статье developerWorks, Настройка Lotus Connections 2.5 с помощью Lotus Widget Factory и гаджетов Google, в которой приводятся краткие сведения о способах реализации гаджетов Google в Lotus Connections 2.5. Отметим, что сведения по программированию, изложенные в настоящей статье, также служат хорошей отправной точкой для разработчиков, желающих больше узнать о деталях спецификаций iWidget.

Lotus Connections 2.0 содержит новую настраиваемую и наращиваемую главную страницу, которая предоставляет пользователям объединенную информацию из разнообразных источников. Главная страница основана виджетах и позволяет легко расширять платформу социального программного обеспечения Lotus Connections.

Она позволяет также создавать и добавлять свои собственные виджеты. iWidget – это новое определение IBM для виджетов. Структуру такого виджета определяет Спецификация iWidget. Стандарт iWidget не является специфическим для Lotus Connections и используется в других продуктах, таких как компонент Lotus Mashups в IBM Mashup Center, что позволяет, однажды написав виджет, использовать его в различных продуктах.

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

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

Процесс создания и установки простого виджета относительно несложен. В данной статье подразумевается, что вы знакомы с наиболее распространенными технологиями Web-разработки, такими как JavaScript, Java Platform, Enterprise Edition и XML. Достаточно знаний промежуточного уровня, а дополнительная информация по более узким вопросам, таким как использование JavaScript Dojo Toolkit, приводится в статье по мере необходимости.

Обзор виджетов главной страницы и спецификации iWidget

В этом разделе дается краткий обзор спецификации IBM iWidget и минимальные теоретические знания, необходимые для понимания практической части, которая за ним последует. В этой статье не мы не будем слишком углубляться в детали каких-либо функций, описанных в спецификации.

Структура виджета главной страницы

Прежде чем обсуждать технические детали, давайте рассмотрим структуру виджета главной страницы. Виджет главной страницы можно разделить на две части:

  • Заголовок. Содержит название виджета и несколько кнопок (перемещения виджета, редактирования, обновления, справки и закрытия).
  • Тело. Тело, ограниченное на рисунке 1 красным прямоугольником, – это место, где может отображаться любой iWidget.
Рисунок 1. Структура виджета главной страницы
Структура виджета главной страницы

У разработчика виджета есть практически полный контроль над содержанием тела виджета главной страницы. Виджет может показывать все, что может присутствовать на стандартной Web-странице. Единственное ограничение заключается в необходимости следовать компонентной модели, определенной в спецификациях iWidget.

Программа исполнения главной страницы автоматически генерирует строку заголовка. Уровень настройки строки заголовка ограничен. Программист может определить, какие действия поддерживает iWidget. Главная страница автоматически скрывает значки действий, не поддерживаемых встраиваемым iWidget. Название виджета определяет администратор на этапе установки.

Дескриптор iWidget

Дескриптор – основная часть любого виджета iWidget. Это место, где объявляются различные возможности, поддерживаемые виджетом. Дескриптор iWidget можно написать с использованием двух различных стилей: микроформат или синтаксис XML. Поскольку главная страница Lotus Connections поддерживает только определений стиль XML, синтаксис микроформата в данной статье не рассматривается. В листинге 1 приведен пример XML-дескриптора виджета Hello World.

Листинг 1. XML-дескриптор виджета Hello World
<iw:iwidget name="helloWorld" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" 
iScope="HelloWorldWidgetClass">
   <iw:resource uri="helloworld.js" />			
   <iw:content mode="view">
      <![CDATA[
         <div id="root">
            Hello World! <br/>
               <button id="click" 
               onclick="iContext.iScope().onClickButton()">Click me!</button>
         </div>
      ]]> 
   </iw:content>     
</iw:iwidget>

Этот виджет отображает строку "Hello World" и кнопку, как показано на рисунке 2.

Рисунок 2. Виджет Hello World
Виджет Hello World

Важные части XML-дескриптора в этом примере:

  • Атрибут iScope. Этот атрибут определяет имя класса, в котором содержится логика iWidget. Как правило, это класс JavaScript, определенный в одном из ресурсов, объявленных в XML-дескрипторе (см. следующий пункт в этом списке). Среда iWidget создает экземпляр объекта iScope для каждого экземпляра iWidget.
  • Теги iw:resource. Эти теги указывают на различные ресурсы, необходимые для выполнения iWidget. Главная страница поддерживает ресурсы JavaScript и каскадные таблицы стилей (CSS). Каждый ресурс, объявленный в XML-дескрипторе, извлекается и оценивается. Атрибут с именем uri (Uniform Resource Identifier – универсальный идентификатор ресурса) относится к расположению XML-дескриптора. В этом примере мы объявляем только один ресурс, файл JavaScript с именем helloworld.js, расположенный в том же каталоге, что и теги XML-дескриптора file.iw:content. Эти теги определяют разметку заданного режима. Фрагмент разметки – это HTML-код, подготовленный главной страницей для iWidget, когда она отображается в заданном режиме. В этом примере виджет имеет только один режим, просмотра (view), который является режимом по умолчанию.

В листинге 2 показан код из файла helloworld.js, который определяет класс iScope HelloWorldWidgetClass. Тот, в свою очередь, определяет единственный метод onClickButton – обработчик, связанный с событием нажатия кнопки onclick, как определено в листинге 1. Когда пользователь нажимает кнопку, в окне выводится строка Button clicked (Кнопка нажата).

Синтаксис Dojo

JavaScript – это язык, основанный на прототипах. Чтобы облегчить жизнь разработчикам, привыкшим к объектно-ориентированным языкам программирования, Dojo Toolkit предоставляет несколько помощников объектно-ориентированных классов. В этом примере используется метод dojo.declare для объявления расширения безродительского класса (null) HelloWorldWidgetClass при наличии единственного метода (onClickButton).

Листинг 2. Содержание helloworld.js
dojo.provide("HelloWorldWidgetClass");

dojo.declare(
 /* имя класса */      
 "HelloWorldWidgetClass", 
 /* родительский класс */ 
 null,
 /* методы и переменные */ 
 {	
 onClickButton: function(){
  alert("Button clicked");
 }
 }
}

Использование сервисов, предоставляемых средой iWidget

Объект iContext – это центральный пункт, который используется для взаимодействия с сервисами, предоставляемыми средой iWidget. Среда iWidget автоматически вводит объект с именем iContext в качестве члена класса iScope виджета (this.iContext). Возможности среды iWidget используются с помощью объекта iContext.

Объект iContext можно использовать также в HTML-разметке виджета для вызова метода связанного с ним экземпляра класса iScope в инкапсулированном виде. Например, в листинге 1 этот прием используется для вызова метода onClickButton.

Инкапсуляция и iContext

Инкапсуляция – важная часть спецификаций iWidget. Каждый iWidget должен быть инкапсулирован, чтобы избежать конфликтов между ресурсами, объявленными несколькими виджетами, одновременно открытыми на одной и той же странице. Среда iWidget помогает инкапсулировать виджеты, но и вам необходимо проделать определенную работу. В частности, как разработчик iWidget, вы должны:

  • правильно объявить границы класса iWidget (iScope), как описано в разделе "Дескриптор iWidget" настоящей статьи. Любые методы или переменные, используемые виджетом, должны быть объявлены внутри iScope;
  • избегать использования глобальных функций и переменных JavaScript в ресурсах своего виджета iWidget, потому что нельзя гарантировать, что другие виджеты на странице не объявили объекты с тем же именем, что приведет к конфликтам;
  • взаимодействовать со средой iWidget посредством объекта iContext, чтобы получить соответствующий объект scope. В примере Hello World это сделано с помощью оператора iContext.iScope().

Множества ItemSet

ItemSet – это множество пар имя-значение, управляемое средой iWidget. Как правило, они используются для хранения свойств iWidget. Множествами ItemSet управляет код класса iScope с помощью таких методов, как getItemValue и getAllNames. (Подробнее см. в спецификации iWidget.) Множества ItemSet можно объявлять в дескрипторе XML, как показано в листинге 3.

Листинг 3. Объявление ItemSet
<iw:itemSet id="itemSetId">
 <iw:item id="item1" value="value1" />
 <iw:item id="item2" value="value2" />
</iw:itemSet>

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

Использование других сервисов, предоставляемых средой iWidget

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

  • Система событий. Эта система позволяет iWidget инициировать и регистрировать события. На главной странице этот механизм используется для инициализации событий iWidget, когда пользователь выбирает одно из действий в строке заголовка (например, "изменить" или "обновить").
  • Модуль ввода/вывода. Согласно той же политике безопасности, которая принята в JavaScript (подробнее см. в http://www.mozilla.org/projects/security/components/same-origin.html), по умолчанию нельзя адресовать запросы Ajax в домен, отличный от домена Home page. Чтобы обеспечить возможность направлять запросы в другие домены, у главной страницы имеется Ajax-заместитель. Указанный модуль ввода/вывода можно использовать для изменения любого URL таким образом, чтобы запросы Ajax переадресовывались через встроенный Ajax-заместитель главной страницы. Его можно использовать также для поиска ресурса относительно местонахождения XML-дескриптора.
  • Система коммуникаций. Пользователи могут настроить два или более виджета на обмен данными с использованием системы событий, описанной в первом пункте этого списка. Заметим, что эта функция не работает на главной странице Lotus Connections, но включена в Lotus Mashups.

Обзор гаджета Google

Гаджеты Google – это компактные, легкие приложения, состоящие из XML, HTML и JavaScript. Гаджеты Google можно добавлять в контейнеры Gadget, такие как iGoogle (настраиваемая главная страница Google), Orkut, Google Maps или Google Desktop. Разработка гаджетов общедоступна. Google предоставляет открытый каталог, в котором можно публиковать свои гаджеты.

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

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

Установка гаджетов Google на любой Web-сайт

Google предоставляет возможность устанавливать гаджеты на любой Web-странице – это называется синдикацией. Ее можно использовать для создания оболочки, позволяющей отображать гаджеты Google на главной странице Lotus Connections.

  • Чтобы можно было выполнить гаджет вне контейнера, Google предоставляет Web-сервис, который возвращает отформатированные выходные данные, состоящие из HTML и JavaScript, отвечающие за инициирование зависимостей гаджета и его отображение. Этот сервис принимает несколько атрибутов запроса, в частности: URL файла XML-определения гаджета Google.
  • Пользовательские настройки, определенные в XML-дескрипторе гаджета, которым можно присваивать значения, передавая имя параметра с приставкой _up, как для параметра запроса к сервису. Переданные значения параметров настройки переопределяют значения по умолчанию, указанные в XML-определении гаджета Google.
  • Отображение настроек, таких как название, ширина (w), высота (h) и тип границы.

Базовый URL сервиса Google: http://www.gmodule.com/ig/ifr. Вот пример полного URL, включая атрибуты запроса к сервису Google, возвращающего код JavaScript гаджета Google Date Time (Дата и время):

http://www.gmodules.com/ig/ifr?url=http://www.google.com/ig/modules/
datetime.xml&up_color=blue&up_firstDay=0&
w=320&h=136&output=js

Обратите внимание на следующие параметры:

  • URL XML-дескриптора гаджета Date Time: строка http://www.google.com/ig/modules/datetime.xml.
  • Параметры настройки Color и firstDay (специфические для данного гаджета) устанавливают синий цвет и 0 (воскресенье).
  • Параметры ширины (w) и высоты (h) установлены равными соответственно 320 и 136 пикселей.

URL Web-сервиса можно составить вручную, но лучше для включения того или иного параметра запроса использовать предоставляемый Google инструмент Page Creator. Этот инструмент легко строит URL посредством графического интерфейса. Он позволяет указать значения параметров настройки гаджета и генерирует URL сервиса, включая правильные параметры запроса для определения различных предпочтений в соответствии с XML-определением гаджета. Чтобы воспользоваться инструментом Page Creator, выполните следующие действия:

  1. Войдите в библиотеку гаджетов Google.
  2. Выберите гаджет и нажмите кнопку "Добавьте на свою страницу". Настройте гаджет и выберите значения параметров. Страница отобразит гаджет с новыми значениями.
  3. По окончании настройки нажмите кнопку "Получить код".
  4. На странице отобразится включаемый код. URL Web-сервиса – это строка в атрибуте src тега script.

ПРИМЕЧАНИЕ. Как вы, наверное, уже заметили, в URL, возвращаемом Page Creator, заменены некоторые специальные символы. Например, знак амперсанд (&) заменен на &amp;. Поскольку URL предназначен для вставки в HTML- или XML-документ, чтобы этот документ работал, необходимо заменить специальные символы.


Упаковка гаджета Google в дескриптор iWidget

Теперь можно написать оболочку для гаджета Google Date Time. На рисунке 3 показан результат после установки гаджета на главную страницу.

Рисунок 3. Гаджет Google Date Time, установленный на главную страницу
Гаджет Google Date Time, установленный на главную страницу.

Метод, приведенный в этом разделе, подходит для любого другого гаджета Google, причем изменяется только одна строка кода, указывающая на соответствующий гаджет.

Как и при первом подходе, оболочка остается простой: ее единственная цель – отобразить гаджет на главной странице. В заключительном разделе этой статьи речь пойдет о добавлении к этой оболочке таких возможностей, как редактирование, когда пользователи могут изменять значения параметров настройки гаджета.

Способ отображения гаджета и XML-дескриптор

Чтобы отобразить гаджет Google на главной странице, вызовем Web-сервис Google, описанный в разделе "Установка гаджетов Google на любой Web-сайт", с соответствующими параметрами запроса. Ответ, состоящий из кода HTML и JavaScript, вставляется в элемент Script. Элемент Script находится в HTML-документе, загруженном в раздел IFRAME виджета iWidget.

IFRAME

IFRAME – это встроенный фрейм, который содержит другой документ. Это стандартный элемент HTML, никак не связанный со спецификациями iWidget. Атрибут IFRAME src указывает на URL загружаемого документа.

В листинге 4 приведена структура кода XML-дескриптора iWidget. Листинг 5 содержит фрагмент JSP-документа (gadgetWrapper.jsp) с элементом script, указывающим на сервис Google.

Листинг 4. Определение оболочки iWidget для гаджета Google
<iw:iwidget name="googleDateTime" 
xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget">
 <iw:content mode=”view”>
 <![CDATA[
 <iframe scrolling="auto" width="100%" height="300px" frameborder="0" 
 src="/gadgetWrapper/gadgetWrapper.jsp?url=<google gadget xml url>">
 </iframe>
 ]]> 
 </iw:content> 
</iw:iwidget>
Листинг 5. gadgetWrapper.jsp
<%
 StringBuffer url = new StringBuffer();
 url.append("http://www.gmodules.com/ig/ifr?");
 url.append(request.getQueryString());	
 %>

<script src="<%= url.toString() %>"></script>

iWidget визуализирует HTML-элемент IFRAME, указывающий на JSP-страницу gadgetWrapper. JSP-страница решает следующие задачи:

  • Извлечь части URL со строкой запроса. Это подстрока после символа ? в URL. В данном случае строкой запроса /gadgetWrapper/gadgetWrapper.jsp?url=<google gadget xml url> является url=<google gadget xml url>.
  • Составить URL сервиса Google путем добавления строки запроса к контекстному корню сервиса на gmodule.com.
  • Установить атрибут src элемента script, чтобы он указывал на сервис Google с соответствующими параметрами настройки гаджета из строки запроса.

Если вы не используете Java, то можете адаптировать поведение, описанное для JSP-страницы, к любому другому языку со стороны сервера (например, PHP или .NET). Важно только установить элемент script с URL сервиса Google.

Отметим три следующих аспекта:

  • Мы могли бы включить элемент script непосредственно в XML-определение кода iWidget. Однако некоторые конфликты между кодом JavaScript, возвращаемым сервисом Google, и средой iWidget вынуждают выбирать решение с изоляцией тега SCRIPT в элементе IFRAME.
  • Сервис Google принимает html-значение параметра выходного запроса (вместо js). Это приводит к генерации HTML-кода, который можно вставлять непосредственно в IFRAME, как показано в листинге 4, без использования страницы JSP. Однако это решение не включает кнопки "gadget powered by Google" и "+Google", расположенные под гаджетом Google, что нарушает Условия обслуживания гаджетов Google.
  • В этом iWidget отсутствует логика поддержки. Поэтому XML-определение не содержит никаких ссылок на ресурсы iScope или JavaScript. Некоторая логика добавляется к iWidget в последнем разделе этой статьи.

Гаджет Google Date Time

В листинге 6 показан код XML-дескриптора iWidget, который упаковывает гаджет Google Date Time, показанный на рисунке 3. Атрибут SRC элемента IFRAME указывает на URL XML-дескриптора этого гаджета: http://www.google.com/ig/modules/datetime.xml. В нем устанавливаются также параметры настройки, характерные для этого гаджета, такие как цвет фона (оранжевый) и первый день недели (0= воскресенье). Как описано выше, чтобы узнать, какие параметры настройки доступны для данного гаджета, можно либо просмотреть XML-определение, либо воспользоваться инструментом Google Page Creator.

Листинг 6. Определение оболочки iWidget для гаджета Google Date Time
<iw:iwidget name="googleDateTime" 
xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget">
 <iw:content mode="view">
 <![CDATA[
 <iframe scrolling="auto" width="100%" frameborder="0"
	 src="/gadgetWrapper/gadgetWrapper.jsp?url=
http://www.google.com/ig/modules/datetime.xml&amp;up_color=
orange&amp;up_firstDay=0&amp;title=&amp;border=
&amp;output=js"></iframe>
 ]]> 
 </iw:content>
</iw:iwidget>

Чтобы получить URL выбранного гаджета Google для включения в атрибут IFRAME SRC (source), выполните действия, описанные в разделе "Установка гаджетов Google на любой Web-сайт". На данный момент мы жестко запрограммировали параметры настройки в строке запроса URL. В последнем разделе этой статьи мы изменим код, чтобы пользователи могли изменять эти параметры.

ПРИМЕЧАНИЕ. В листинге 6 обратите внимание на то, что мы установили также два параметра отображения (title и border), присвоив им пустые значения. Это позволяет отображать гаджет Google без названия и без всякой рамки.


Установка гаджета Google на главной странице

iWidget устанавливается на главной странице за два основных этапа:

  1. Установка XML-дескриптора и всех ресурсов iWidget на Web-сервере.
  2. Регистрация виджета в каталоге главной страницы путем указания на URL XML-дескриптора установленного iWidget.

Установка iWidget

Установка iWidget на Web-сервере осуществляется гибко, потому что вы не привязаны ни к какой конкретной серверной технологии. Например, iWidget может быть PHP-проектом и устанавливаться на сервере PHP. Его можно реализовать и как проект Java Platform, Enterprise Edition, установив в контейнер servlet/Java Platform, Enterprise Edition, такой как WebSphere Application Server или Tomcat. Выбор за вами. Заметим, что если контейнер Java Platform, Enterprise Edition не используется, необходимо адаптировать JSP-страницу, описанную в разделе "Способ отображения гаджета и XML-дескриптор".

В следующих пунктах подробно рассматривается процесс создания проекта iWidget в среде Eclipse в качестве Web-проекта и экспортирования его в файл EAR. Затем файл EAR можно установить в контейнер Java Platform, Enterprise Edition.

ПРИМЕЧАНИЕ. Для создания Web-проекта в Eclipse нужно установить плагин Web tools. Его можно загрузить отсюда: http://download.eclipse.org/webtools/downloads/. Этот плагин входит в версию Eclipse Java Platform, Enterprise Edition.

Давайте создадим проект и файл EAR, готовый к установке. Сначала создадим проект в Eclipse:

  1. Выберите File – New – Project.
  2. В открывшемся окне выберите Web – Dynamic Web Project и нажмите кнопку Next.
  3. Введите имя проекта по своему выбору, например, gadgetWrapper. Если вы хотите установить проект непосредственно из Eclipse, можете выбрать целевую среду исполнения; в противном случае выберите None.
  4. Выберите Add Project с опцией EAR, чтобы среда Eclipse создала и связала с этим Web-проектом проект EAR.
  5. Нажмите Next, чтобы открыть последнее окно. Не меняйте никакие настройки по умолчанию. Нажмите кнопку Finish, чтобы создать Web-проект.

Теперь вы готовы к работе над проектом.

Добавим к проекту XML дескриптор iWidget:

  1. В разделе WebContent создайте новый файл XML, щелкнув правой кнопкой мыши на имени папки и выбрав New – File. Введите имя файла gadgetWrapper.xml.
  2. Откройте файл в Eclipse, дважды щелкнув на нем, а затем вставьте код, показанный в листинге 6. Если не удается изменить файл, убедитесь, что выбрана вкладка source (см. рисунок 4).
  3. Сохраните файл.
Рисунок 4. Редактирование gadgetWrapper.xml в Eclipse
Редактирование gadgetWrapper.xml в Eclipse

Повторите те же действия, что и при добавлении XML-дескриптора, чтобы добавить к проекту код JSP, определенный в листинге 5. Полная версия этого файла содержится в gadgetWrapper.ear из раздела "Загрузка" настоящей статьи.

Теперь создайте файл EAR для установки в контейнер Java Platform, Enterprise Edition, такой как WebSphere Application Server:

  1. Выберите проект EAR, связанный с уже созданным Web-проектом.
  2. Щелкните правой кнопкой мыши и выберите Export – EAR file.
  3. Выберите пункт назначения на жестком диске.

Вот и все! Файл EAR, содержащий ресурсы iWidget и XML-файл, готов к установке в любой контейнер Java Platform, Enterprise Edition.

Теперь файл EAR можно установить в контейнер Java Platform, Enterprise Edition, как любой другой файл EAR.

ПРИМЕЧАНИЕ. IFRAME, показанный в листинге 6, ссылается на страницу JSP (показанную в листинге 5) с корневым контекстом /gadgetWrapper. Возможно, вам придется адаптировать этот параметр в зависимости от реального корневого контекста, в котором устанавливается файл EAR. В заключительной части этой статьи мы покажем, как избавиться от этого ограничения с помощью модуля ввода/вывода iWidget.

Регистрация виджета в каталоге главной страницы

Главная страница содержит интерфейс администрирования для добавления новых виджетов в базу данных каталога. Заметим, что только пользователи с правами администратора могут добавлять в каталог главной страницы новые виджеты.

Выполните следующие шаги, чтобы добавить наш iWidget с помощью Web-интерфейса администрирования главной страницы:

  1. Войдите в учетную запись администратора на главной странице.
  2. Перейдите на вкладку Administration главной страницы, как показано на рисунке 5.
    Рисунок 5. Вкладка Administration
    Вкладка Administration
  3. Выберите вариант Add another widget (Добавить другой виджет) в нижней правой части страницы.
  4. Отображается вид, показанный на рисунке 6. Введите имя и местоположение XML-дескриптора iWidget.
    Рисунок 6. Страница администрирования
    Страница администрирования
  5. Введите название виджета. Название отображается в строке заголовка виджета; например, это может быть Google Date Time.
  6. Введите адрес XML-дескриптора. Это поле зависит от того, где был установлен виджет (см. раздел "Установка iWidget" выше).
  7. Другие текстовые поля заполнять не обязательно. Они позволяют, например, указать значок. Значок отображается на боковой панели, когда виджет закрыт.
  8. Оставьте все рамки пустыми. Они нужны только для виджетов, взаимодействующих с другими функциями Lotus Connections.
  9. Нажмите кнопку Save.

Более подробную информацию по опциям управления виджетами можно найти в Информационном центре Lotus Connections v2.


Дальнейшие усовершенствования оболочки гаджета

В этом разделе мы рассмотрим, как добавить дополнительные возможности к основному виджету iWidget. В частности, можно добавить возможность изменения некоторых настроек, указанных в определении гаджета Google. Обратите внимание, что настройками управляет сам гаджет Google, так как они объявлены в качестве элементов <UserPrefs> в XML-определении гаджета Google. Цель в том, чтобы пользователи могли выбрать значения этих настроек и передать их сервису Google.

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

  1. Создать форму редактирования iWidget, в которой пользователи могут настраивать параметры, объявленные в определении гаджета Google.
  2. Передать введенные значения в сервис Google (см. раздел "Установка гаджета Google на любой Web-сайт" выше). Это делается путем передачи новых значений сервису Google в виде части URL.

С помощью этих шагов можно также увидеть практический пример использования нескольких понятий, введенных в этой статье, таких как множества ItemSets, механизмы инкапсуляции, предусмотренные средой iWidget, и система обработки событий.

Параметры настройки гаджета Date Time

В этом разделе мы модифицируем имеющийся iWidget для того, чтобы пользователи могли менять настройки гаджета Google Date Time. Обратите внимание, что эти шаги – одни и те же для любых гаджетов Google; так что предложенные здесь идеи несложно адаптировать для настройки любого гаджета на главной странице.

Обычно имеются два способа получения списка параметров настройки гаджета Google:

  • можно просмотреть XML-дескриптор гаджета и найти элементы <UserPrefs>;
  • иначе, можно воспользоваться инструментом Page Creator. Параметры настройки перечислены в разделе Gadget settings.

Просматривая XML-определение гаджета Date Time, вы найдете две пользовательские настройки:

  • цвет фона;
  • первый день недели в календаре.

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

Листинг 7. Фрагмент XML-определения гаджета Date Time со списком значений цвета фона
<UserPref name="color" datatype="enum" default_value="blue" 
display_name="__MSG_color__">
 <EnumValue value="blue" display_value="__MSG_blue__"/>
 <EnumValue value="green" display_value="__MSG_green__"/>
 <EnumValue value="orange" display_value="__MSG_orange__"/>
 <EnumValue value="pink" display_value="__MSG_pink__"/>
 <EnumValue value="purple" display_value="__MSG_purple__"/>
 <EnumValue value="red" display_value="__MSG_red__"/>
 <EnumValue value="yellow" display_value="__MSG_yellow__"/>
</UserPref>

Добавление логики в iWidget

Рассматриваемый здесь iWidget – это простейший виджет, который содержит лишь некоторую разметку, но не включает никакой логики JavaScript. В этом случае URL сервиса Google жестко программируется в разделе разметки (iw:content) iWidget. Теперь мы хотим составлять URL динамически в зависимости от значений, выбранных пользователем. Для этого нужно написать некоторый код поддержки, который реализует логику составления строки URL. Первая задача – перенести URL сервиса Google из разметки HTML iWidget в код поддержки, выполнив следующие действия.

  1. Удалить URL из разметки, исключив атрибут src из элемента IFRAME в XML-определении iWidget. Теперь эта часть кода должна выглядеть, как показано в листинге 8.

    Листинг 8. Разметка представления оболочки iWidget
    <iw:content mode="view">
     <![CDATA[
     <iframe id="frame" scrolling="auto" width="100%" 
     frameborder="0"></iframe>
     ]]> 
    </iw:content>
  2. Создать файл JavaScript, содержащий логику поддержки. Как говорилось выше, вся логика реализована в классе JavaScript, называемом iScope. В Eclipse процесс создания и добавления файла JavaScript производится так же, как процесс добавления XML-определения файла в проект, описанный в разделе "Установка iWidget". Назовем файл JavaScript именем googleGadgetWrapper.js. Код для добавления этого файла приведен в листинге 9.

    Листинг 9. Первая версия googleGadgetWrapper.js
    dojo.provide("GoogleGadgetWrapper");
    
    dojo.declare("GoogleGadgetWrapper", null, {	
    
     onLoad: function(){
     },
    	
     onview: function(){
     // получение объекта фрейма DOM, объявленного в разметке виджета
     var frame = this.iContext.getElementById("frame");	
    
     // получение указателя URL страницы JSP без необходимости
     // указывать в коде корневого контекста. Например, если корневой
     // контекст после установки /gadgetWrapper/, то jspLocation 
     // устанавливается в /gadgetWrapper/gadgetWrapper.jsp
     var jspLocation = this.iContext.io.rewriteURI("gadgetWrapper.jsp");
    	
     // установка атрибута src iframe		
     frame.src = jspLocation + "?url=http://www.google.com/ig/modules/datetime.xml&
     title=&border=&output=js&w=400";
     }
    }

Давайте разберем код из листинга 9:

  1. Среда iWidget направляет в виджет событие iEvent с именем Load. Не вдаваясь в детали механизма обработки событий, заметим только, что это приводит к вызову метода с именем on+<имя события> в iScope нашего iWidget. В данном случае этот механизм вызывает метод OnLoad.
  2. Среда iWidget загружает режим виджета по умолчанию (view). Режим загружается в два этапа:
    • пользователю предоставляется разметка (элемент content в XML-дескрипторе) в соответствии с данным режимом. Напомним, что мы объявили разметку виджета для этого режима в листинге 7 (атрибут mode="view");
    • iEvent с именем режима передается в виджет. В нашем случае это приводит к применению метода onview.

Результатом является то, что методы OnLoad и onview активизируются средой автоматически, когда виджет помещается на страницу.

Кроме того, обратите внимание, что мы используем метод rewriteURI из модуля ввода/вывода, предоставляемый средой iWidget (через объект iContext). Такой подход позволяет получить реальное местоположение JSP-файла, не включая в код корневой контекст проекта. Во время разработки корневой контекст установки iWidget точно не известен, потому что его значение может быть изменено администратором.

Внутренняя логика должна устанавливать связь с XML-определением iWidget. Это делается в два этапа:

  1. Добавить тег элемента resource, указывающий на файл JavaScript, который вы только что добавили к проекту:
    <iw:resource uri="googleGadgetWrapper.js" />
  2. Установить атрибут iScope в теге элемента iw:widget XML-дескриптора iWidget, чтобы он указывал на класс JavaScript, определенный в googleGadgetWrapper.js. Так как имя класса JavaScript – GoogleGadgetWrapper, тег iw:widget должен выглядеть следующим образом:
    <iw:iwidget name="googleDateTime"
    xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget" iScope="GoogleGadgetWrapper">

Вот и все! Теперь атрибут IFRAME src устанавливается динамически при инициализации виджета. Пользователи не видят никакой разницы в поведении виджетов. Теперь все готово, чтобы сгенерировать часть запроса URL сервиса Google.

Сохранение параметров и создание URL сервиса Google

Вы познакомились с простым способом создания и изменения URL сервиса Google перед включением URL в IFRAME. В этом разделе мы изменим этот URL, добавив значения параметров настройки, в три этапа:

  1. Сохранить значения параметров настройки гаджета Google в ItemSet соответствующего iWidget. ItemSet используется для хранения предпочтений по следующим причинам:
    • это удобное место хранения данных, которое можно использовать в разных частях кода для записи и чтения значений, выбранных пользователем;
    • оно позволяет сохранять параметры настройки между пользовательскими сеансами на сервере главной страницы. Этот момент реализован в разделе "Сохранение параметров настройки" ниже.

    Сначала изменим XML-определение iWidget, объявив ItemSet. Назовем ItemSet именем UserPrefs. В листинге 10 показан фрагмент кода для двух параметров настройки, которые позднее нужно будет извлечь в представление edit.

    Листинг 10. ItemSet с параметрами настройки для гаджета Date Time
    <iw:itemSet id="userPrefs">
     <iw:item id="color" value="green" />
     <iw:item id="firstDay" value="0" />
    </iw:itemSet>

    Обратите внимание, что мы указали также значение по умолчанию для каждого параметра настройки (зеленый цвет и 0=воскресенье).

  2. Нужно реализовать механизм для динамического создания URL сервиса Google из значений, хранящихся в ItemSet. Для этого добавим дополнительный метод getQueryString к классу iScope среды iWidget. Код этого метода приведен в листинге 11.
    Листинг 11. Метод, возвращающий строку параметров из ItemSet
    getQueryString: function(){
     // получение объекта ItemSet
     var userPrefs = this.iContext.getItemSet("userPrefs");
    
     // получение имен ("id") элементов в виде массива		
     var prefNames = userPrefs.getAllNames();
    
     // инициализация пустого объекта JavaScript, используемого для отображения
     var params = {};
    
     // заполнение отображения params параметрами пользователя
     dojo.forEach(prefNames, function(name) { 
     // перед именем нужно вставить "up_", чтобы передать его в Google Service 
     as discussed in “Google gadget overview” part
     var upName = "up_" + name;
    	params[upName] = userPrefs.getItemValue(name);		
     });
    
     // генерация строки из отображения params
     return dojo.objectToQuery(params);		
    }

    Этот метод возвращает строку, содержащую значения параметров настройки. Например, для гаджета Date Time он возвращает строку up_color=green&up_firstDay=0. Эта строка может непосредственно использоваться для составления URL сервиса Google, который возвращает соответствующую разметку гаджета Google.

  3. Нужно изменить метод onview, представленный в листинге 8, вызывая getQueryString для составления URL сервисаGoogle, прежде чем установить его в атрибут IFRAME src. Новая версия onview показана в листинге 12.
    Листинг 12. Новая версия onview с динамической генерацией строки URL, включая значения параметров настройки
    onview: function(){ 
     var frame = this.iContext.getElementById("frame");	
    	
     var query = this.getQueryString();
    
     var jspLocation = this.iContext.io.rewriteURI("gadgetWrapper.jsp");
    
     frame.src = jspLocation + "?url=http://www.google.com/ig/modules/datetime.xml&
     title=&border=&output=js&w=400&" + query;
    }

Реализация представления edit

Итак, мы реализовали механизм для хранения параметров настройки и сгенерировали URL сервиса Google с параметрами настройки. В этом разделе мы заполним ItemSet значениями, выбранными пользователем. Это задача в три действия:

  1. Реализовать графический интерфейс, который позволяет пользователю выбирать значения параметров настройки. Для этого нужно выполнить разметку режима редактирования (edit). Это реализация представления, с помощью которого пользователь выбирает параметры настройки, когда включен режим редактирования. В случае гаджета Google Date Time пользователь должен выбрать цвет фона и первый день недели. Так что достаточно реализовать представление edit с двумя раскрывающимися списками, содержащими допустимые значения для двух параметров настройки.

    На рисунке 7 показано представление edit нашей оболочки iWidget для гаджета Date Time.

    Рисунок 7. Представление edit оболочки iWidget
    Представление edit оболочки iWidget

    В листинге 13 показан фрагмент кода разметки XML-дескриптора iWidget.

    Листинг 13. Код представления edit виджета < iw: content mode="edit">
     <![CDATA[
     <table>
     <tr>
     <td>Color: </td>
    	<td>
     <select id="color">
    	 <option value="blue">Blue</option>
    	 <option value="green">Green</option>
    	 <!—other options here 
    	</select>
    	</td>
     </tr>
     <tr>
     —-- same principle as for the color drop-down list here -->
     </tr>
     </table>
     <br/>
     <input id="saveButton" type="button" value="Save" 
     onclick="iContext.iScope().onSave()" />
     <input id="cancelButton" type="button" value="Cancel" 
     onclick="iContext.iScope().onCancel()" />
     ]]> 
    </iw:content>

    Обратите внимание на следующие моменты:

    • разметка находится в элементе iw:content с атрибутом режима edit;
    • для гарантии правильной инкапсуляции используется метод iContext.iScope();
    • разметка – это просто таблица HTML с двумя раскрывающимися списками и двумя кнопками ("Сохранить" и "Отменить").
  2. Добавить методы поддержки логики iWidget для записи вводимых пользователем параметров в itemSet. Для этого нужно реализовать внутреннюю логику работы кнопок – методы onSave () и onCancel(). Листинг 14 иллюстрирует код метода onSave(), который вызывается при нажатии пользователем кнопки "Сохранить".
    Листинг 14. Код метода onSave()
    onSave: function(){
     // получение объекта ItemSet
     var userPrefs = this.iContext.getItemSet("userPrefs"); 
    
     // присвоение элементу значений, выбранных из раскрывающегося списка
     userPrefs.setItemValue("color", 
     this.iContext.getElementById("color").value);
     userPrefs.setItemValue("firstDay", 
     this.iContext.getElementById("firstDay").value);
    
     // возврат в режим просмотра (обычное представление виджета как гаджета)		
     this.iContext.iEvents.fireEvent("onModeChanged", 
     null, "{newMode: 'view'}");		
    }

    Метод onSave()устанавливает новые значения для двух параметров настройки ItemSet в соответствии с выбором пользователя. Последняя строка метода save используется для возвращения в режим просмотра виджета. Для этого нужно вызвать событие onModeChanged по отношению к виджету. Это событие интерпретируется средой как запрос на изменение текущего режима отображения виджета с edit на view. После этого активизируется механизм управления режимом, описанный в разделе "Добавление логики к iWidget".

    Назначение кнопки "Отменить" состоит в том, чтобы вернуться в режим просмотра без сохранения параметров в ItemSet. Таким образом, onCancel() – это просто последняя строка onSave(), которая вызывает событие onModeChanged.

  3. Зарегистрировать режим редактирования в XML-дескрипторе iWidget. Для этого необходимо добавить атрибут supportedMode в элемент iw:iwidget XML-дескриптора:
    <iw:iwidget name="googleDateTime"
    xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
    iScope="GoogleGadgetWrapper" supportedModes="edit view">

    После внесения этих изменений и переустановки виджета пользователи увидят значок редактирования в строке заголовка виджета на главной странице, как показано на рисунке 8.

Рисунок 8. Кнопка редактирования в строке заголовка iWidget
Кнопка редактирования в строке заголовка iWidget

Когда пользователь нажимает кнопку редактирования, среда исполнения главной страницы запускает событие onModeChanged в отношении встроенного iWidget. Это событие вызывает отображение окна редактирования и активизирует метод onedit в iScope виджета iWidget. Наконец, в листинге 15 показано, как добавить в метод onedit логику, чтобы создать на представлении редактирования два раскрывающихся списка со значениями, сохраняемыми в ItemSet.

Листинг 15. Метод onedit создает в окне редактирования раскрывающиеся списки с сохраняемыми значениями
onedit: function(){
 var userPrefs = this.iContext.getItemSet("userPrefs"); 
 this.iContext.getElementById("color").value = userPrefs.getItemValue("color");
 this.iContext.getElementById("firstDay").value = userPrefs.getItemValue("firstDay");
}

Сохранение параметров настройки

Обновление: Lotus Connections 2.5 теперь поддерживает сохранение параметров настройки в соответствии со спецификацией iWidget. Хотя содержащаяся в этом разделе информация остается в силе, так как Lotus Connections 2.5 обеспечивает обратную совместимость, рекомендуется использовать стандартный способ iWidget. См. раздел "iWidget specification v1.0 in Lotus Connections 2.5" статьи Customizing Lotus Connections 2.5 with Lotus Widget Factory and Google Gadgets.

Последним усовершенствованием нашей оболочки iWidget будет сохранение параметров настройки в ItemSet. После этого настройки, выбранные пользователем, не потеряются. Среда выполнения главной страницы предоставляет два метода (_save и _load) сохранения ItemSet на стороне сервера.

ПРИМЕЧАНИЕ. Эта реализация является специальным расширением среды iWidget для главной страницы; она не будет работать в других контейнерах iWidget, таких как Lotus Mashups.

Методы _save и _load принимают URI в качестве параметра, который указывает место хранения ItemSet. Преобразование в последовательную форму, используемое этими методами для кодирования и декодирования ItemSet, выходит за рамки данной статьи. Вы должны знать только то, что главная страница предоставляет сервис (Servlet), который принимает и возвращает преобразованную строку по адресу: handleUP?Act=XXX&FId=XXX, причем Act принимает SaveCustomization и LoadCustomization в качестве значений, а FID – это идентификатор iWidget.

ПРИМЕЧАНИЕ. На главной странице идентификатор виджета можно получить из iContext (iContext.widgetId). Эта переменная специфична для главной страницы и не входит в спецификацию iWidget.

В листинге 16 показан код метода OnLoad (вызывается только после того, как виджет помещается на страницу), который отвечает за заполнение UserPrefs ItemSet значениями из уровня хранения. Обратите внимание, что если сохраненное значение отсутствует (что означает, что пользователь не отредактировал и не сохранил параметры настройки для этого виджета), устанавливаются значения по умолчанию, определенные в XML-дескрипторе iWidget (см. листинг 9).

Листинг 16. Загрузка параметров настройки из уровня хранения главной страницы
onLoad: function(){
 var userPrefs = this.iContext.getItemSet("userPrefs");
 userPrefs._load("handleUP?Act=LoadCustomization&FId=" + this.iContext.widgetId);
}

Наконец, необходимо сохранить значения ItemSet. Это делается, когда пользователь нажимает кнопку Save в окне редактирования. Таким образом, нужно вызвать метод _save объекта UserPrefs в методе onSave непосредственно перед запуском события onModeChanged. Исходный код можно посмотреть в файле EAR в разделе "Загрузка" данной статьи.


Заключение

В этой статье рассмотрены шаги по созданию и установке простой оболочки iWidget для гаджета Google на главной странице Lotus Connections. Кроме реализации самой оболочки, вы на конкретных примерах познакомились с некоторыми функциями, предоставляемыми средой iWidget. После прочтения этой статьи вы должны достаточно хорошо разбираться в таких понятиях, как XML-дескриптор, множества ItemSet, режимы и события, чтобы уметь создавать простые виджеты для домашней страницы. Более того, вы можете продолжать совершенствование оболочки Google, например, предоставив пользователям возможность вводить дескриптор местонахождения гаджета в окне редактирования iWidget.


Загрузка

ОписаниеИмяРазмер
Образец кодаgadgetWrapper.ear4 KБ

Ресурсы

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Lotus
ArticleID=607529
ArticleTitle=Установка гаджетов Google на главной странице Lotus Connections
publish-date=01122011