При первом входе в developerWorks для Вас будет создан профиль. Выберите информацию отображаемую в Вашем профиле — скрыть или отобразить поля можно в любой момент.

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

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

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

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

My developerWorks:

Сообщения:

Выйти

Выбрать язык:

Введение в JavaScript API из IBM Lotus Forms V3

Гу И, ведущий инженер-программист, IBM

Гу И (Gu Yi) - ведущий инженер-программист из группы IBM Software Services for Lotus (ISSL) Emerging Services Team китайской лаборатории разработки ПО IBM. Гу И занимается проектами IBM Software Services с 2005 г. и принимал участие в нескольких проектах сервисов с применением IBM Lotus Forms. Кроме того, Гу И обладает двухлетним опытом работы с IBM WebSphere Portal и четырёхлетним опытом промышленной J2EE-разработки. Связаться с ним можно по адресу guyi@cn.ibm.com.

И Тин Шань, инженер-программист, IBM

И Тин Шань (Yi Ting Shan) - инженер-программист из лаборатории разработки ПО IBM в Китае (China Development Lab - CDL). Он обладает более чем двухлетним опытом разработки ПО и анализа проектов. В настоящее время он работает в группе IBM Software Services for Lotus (ISSL) Emerging Services Team.

Описание: Новый JavaScript API из IBM Lotus Forms V3.0 позволяет управлять поведением встроенных форм Lotus Forms в браузере при помощи простого HTML и JavaScript. Новый механизм подписчика на события (event listener) позволяет создавать специальные функции для обработки форм и облегчает интеграцию с другими системами.

Пометить это!

Дата: 02.10.2008
Уровень сложности: средний
Активность: 1727 просмотров
Комментарии:

Статья представляет JavaScript API из IBM Lotus Forms, описывает механизм его работы и даёт примеры использования этого API. Вы должны быть знакомы с IBM Lotus Forms.

Что представляет собой JavaScript API?

Для поддержки внешнего доступа к основанным на HTML и другим формам IBM Lotus Forms в семейство Lotus Forms был добавлен новый JavaScript API. Этот API позволяет манипулировать формой, отображаемой в HTML-файле. Выводить формы можно при помощи IBM Lotus Forms Viewer или IBM Lotus Forms Webform Server. Этот JavaScript API облегчает интеграцию Lotus Forms с другими приложениями.

Если сравнивать с базовыми API языков Java и C, JavaScript API имеет аналогичные библиотеки FormNodeP и XFDL, предоставляющие стандартный способ доступа к форме на основе load и set/get. Имена интерфейсов этих библиотек совпадают с именами в базовом API. Кроме библиотеки FormNodeP в JavaScript API добавлена новая библиотека событий. Эта библиотека событий обеспечивает уведомление JavaScript, когда с формой происходят определённые события. Такой механизм подписчика позволяет HTML-страницам тесно взаимодействовать со встроенными формами Lotus Forms. В настоящее время API поддерживает четыре события: onBlur, onChange, onClick и onFocus.

В начало

Механизм работы JavaScript API

Для обеспечения работы подписчиков на события JavaScript в качестве интерфейса передачи информации между кодом JavaScript и встроенным Lotus Forms Viewer используется элемент управления ActiveX, как показано на рисунке 1.

Рисунок 1. Механизм обработки событий

На рисунке 1 показана процедура обработки событий с помощью JavaScript API и Lotus Forms Viewer. При вызове метода добавления события JavaScript API регистрирует событие в списке наблюдения за событиями Lotus Forms Viewer при помощи элемента управления ActiveX. При получения события окна для какого-нибудь элемента Lotus Forms Viewer проверяет, является ли это событие ожидаемым. Если да, то оно помещается в очередь событий, а элементу управления ActiveX посылается уведомление о том, что в этой очереди что-то находится. Элемент управления ActiveX получает это событие и создаёт одиночное событие браузера, которое передаётся внутреннему обработчику событий JavaScript API. Затем внутренний обработчик событий вызывает зарегистрированный метод подписки на события для дальнейшей обработки.

В начало

Установка JavaScript API

Поделиться...


	Разместить на Digg

	Разместить на del.icio.us

	Разместить на Slashdot!

Отдельного установочного пакета JavaScript API не существует. После установки Lotus Forms Viewer V3.0 и Lotus Forms Webform Server V3.0 библиотеку JavaScript API можно найти по следующему адресу:

<<Viewer Installation Folder>>\JavaScript

Viewer Installation Folder - это папка, в которую устанавливается Lotus Forms Viewer, например C:\Program Files\IBM\Lotus Forms\Viewer\3.0.

<<Webform Server Installation Folder>>\redist

Webform Server Installation Folder - это папка, в которую устанавливается Lotus Forms Webform Server, например C:\Program Files\IBM\Lotus Forms\Server\3.0\Webform Server\redist.

В таблице 1 приведены три файла, которые находятся в этих каталогах.

Таблица 1. Библиотечные файлы

Имя файла	Описание
LF_FormNodeP.js	Интерфейс для всех обычных и новых, основанных на событиях, функций FormNodeP
LF_ViewerScript.js	Интерфейс для регистрации / разрегистрации форм
LF_XFDL.js	Предоставляет функцию addViewer() для создания объектных HTML-тегов. Более нет необходимости использовать вложенные объектные теги для Microsoft Internet Explorer и Mozilla Firefox. Удаляет предупреждение “Click to activate this ActiveX control” из Microsoft Internet Explorer.

В начало

Интерфейс JavaScript API

Три вышеперечисленных библиотечных файла определяют интерфейс обработки встроенных форм. Ниже даётся краткая вводная информация по этому интерфейсу.

Массив ibmforms

Массив ibmforms - глобальный ассоциативный массив, определяемый в файле LF_XFDL.js. С помощью XFDL.registerForm() можно зарегистрировать форму в глобальной переменной для получения доступа ко всем зарегистрированным формам посредством ссылки на массив ibmforms.

Класс XFDL

Класс XFDL определяет набор констант и функций, которые используются для обработки самой формы. В классе XFDL определяются функции registerForm() and deregisterForm(). Весь класс можно найти в файле LF_XFDL.js.

Класс FormNodeP

Класс FormNodeP определяет методы, которые можно использовать для управления узлом формы. Этот класс аналогичен методам, определённым в базовых API языков Java и C. Каждый элемент и опция формы представляет собой узел FormNodeP. Интерфейс FormNodeP определяется в файле LF_FormNodeP.js. В нём имеется большинство традиционных методов обработки FormNode, как показано в таблице 2.

Таблица 2. Методы узла формы

Метод	Описание
dereferenceEx()	Задаёт местонахождение конкретного FormNodeP
setLiteralByRefEx()	Находит конкретный FormNodeP, указанный в строке ссылки, и задаёт литерал при обнаружении FormNodeP
getLiteralByRefEx()	Находит конкретный FormNodeP, указанный в строке ссылки, и возвращает литерал FormNodeP при обнаружении FormNodeP

JavaScript API служит посредником между HTML-файлами и встроенными Lotus Forms. Для уведомления HTML-контекста об изменении состояний встроенных форм определяется полный набор событий. Для поддержки системы работы с сообщениями в класс FormNodeP добавляется новая коллекция методов регистрации событий.

В таблице 3 приведены некоторые полезные методы регистрации и разрегистрации событий.

Таблица 3. Методы регистрации и разрегистрации событий

Метод	Описание
addOnBlur () / removeOnBlur ()	Регистрирует/разрегистрирует обработчик событий для события onBlur. Событие onBlur генерируется, когда снимается выделение элемента курсором.
addOnChange () / removeOnChange ()	Регистрирует/разрегистрирует обработчик событий для события onChange. Событие onChange генерируется, когда изменяется значение элемента.
addOnClick () / removeOnClick ()	Регистрирует/разрегистрирует обработчик событий для события onClick. Событие onClick генерируется, когда на элементе щёлкают мышью.
addOnFocus () / removeOnFocus ()	Регистрирует/разрегистрирует обработчик событий для события onFocus. Событие onFocus генерируется, когда на элемент наводится курсор.

В начало

Примеры использования JavaScript API

В этом разделе приводится несколько примеров использования JavaScript API с Lotus Forms Viewer и Lotus Forms Webform Server.

Использование JavaScript API c Lotus Forms Viewer

Для использования JavaScript API с Lotus Forms Viewer необходимо создать HTML-файл со встроенной формой. Ниже приводится подробная информация по созданию примера HTML-файла, конвертирующего денежную сумму на основе обменного курса, заданного в HTML-файле.

Создание HTML-файла.

Сначала создадим HTML-файл с полем ввода и разделом <div>. Раздел <div> зарезервирован для последующей вставки примера формы. Нужно создать текстовое поле <input>, чтобы пользователи могли ввести обменный курс, а также кнопку <input> для его ввода во встроенную форму.

Листинг 1. Создание HTML-файла

                        

<P>
Ratio Today = <INPUT id='field_ratio' style='width:160;height:25' 
type='textbox' value="2.0230"></INPUT>
	<INPUT id="button_ratio" style='width:100;height:25' value='Set The Ratio' 
	type='button' onClick='setRatio();'></INPUT>
</P>
<div id="divID">
</div>
<P id="result"></P>

Встраивание формы в HTML-файл.

Поместите XFDL-форму в HTML-файл в окружении пары тегов <script>. Обратите внимание, что содержимое формы должно оформляться как HTML-комментарий.

Листинг 2. Встраивание формы в HTML-файл

                        


<SCRIPT language="XFDL" id="XFDLData" type="application/vnd.xfdl; wrapped=comment">
<!-- 
<?xml version="1.0" encoding="UTF-8"?>
	//Здесь располагается содержимое XFDL-формы
-->
</SCRIPT>

Включение библиотечных файлов.

Библиотечные файлы обеспечивают базовые функции, необходимые пользователям для управления встроенной формой. Для запуска приложений необходимо импортировать их в HTML-файлы.
<SCRIPT TYPE="text/javascript" SRC="LF_XFDL.js"></SCRIPT> <SCRIPT TYPE="text/javascript" SRC="LF_FormNodeP.js"></SCRIPT> <SCRIPT TYPE="text/javascript" SRC="LF_ViewerScript.js"></SCRIPT>

Добавление формы в раздел <div>.

Чтобы сделать встроенную форму видимой, необходимо создать для неё объектные HTML-теги. В предыдущих версиях Lotus Forms требовалось добавлять эти теги вручную и создавать различные наборы тегов для браузеров Microsoft Internet Explorer и Mozilla Firefox. При использовании JavaScript API работу облегчает специальная функция addViewer().

Листинг 3. Добавление формы в раздел <div>

                        

<P>
Ratio Today = <INPUT id='field_ratio' style='width:160;height:25' 
type='textbox' value="2.0230"></INPUT>
<INPUT id="button_ratio" style='width:100;height:25' 
value='Set The Ratio' type='button' onClick='setRatio();'></INPUT>
</P>
<div id="divID">
<script language="Javascript">
addViewer("divID","sample_form",450,400,"XFDLID","XFDLData", 
"detach_id", "12354678901234567890");
</script>
</div>
<P id="result"></P>

Инициализация формы и регистрация обработчика события при загрузке HTML-файла.

Во всех случаях, когда HTML-файл загружается в браузер, вызывается функция onLoadForm(). Функция onLoadForm() вызывает addEvent() для регистрации функции обратного вызова fieldOnChange() для XFDL-поля во встроенной форме, а функция setRatio() вызывается, когда пользователь нажимает на кнопку Set the Ratio.

Листинг 4. Инициализация формы

                        

var formName = "sample_form";
function onLoadForm()
{
var aForm = new FormNodeP(formName);
//регистрация formName
	XFDL.registerForm(aForm,formName);
	addEvent();
}

//установка события onload
if(window.addEventListener)
	window.addEventListener('load', onLoadForm, false);
else
	window.attachEvent('onload', onLoadForm);

function addEvent()
{
	var fieldNode;
	var s;
	var theForm = ibmForms[formName];
	fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD_USD", 0, 
	FormNodeP.UFL_ITEM_REFERENCE, null);
	//добавление подписчика на события OnChange
	fieldNode.addOnChange(fieldOnChange);
}
	   
function fieldOnChange(xfdlEvent) 
{
	var theForm = ibmForms[formName];
	//получение значения поля для XFDL 
	var gbpValue = theForm.getLiteralByRefEx
	(null, "PAGE1.FIELD_GBP.value", 0, null);
	var usdValue = theForm.getLiteralByRefEx
	(null, "PAGE1.FIELD_USD.value", 0, null);
	var ratioValue = theForm.getLiteralByRefEx
	(null, "global.global.custom:ratio", 0, null);
	document.getElementById("result").innerHTML = gbpValue + 
	" equals to " + usdValue + " at the ratio " + ratioValue + "." ;
}

function setRatio() {
	var theForm = ibmForms[formName];
	var ratio = parseFloat(document.getElementById("field_ratio").value);
	if (isNaN(ratio) || ratio < 0) {
		alert("Please enter a positive number as the ratio.");
}else {
		//установка значения формы
		theForm.setLiteralByRefEx(null, "global.global.custom:ratio", 
		0, null, ratio.toString());
		}
}

Тестирование результатов.

Откройте HTML-файл в браузере. Измените сумму в поле GBP (фунты стерлингов) формы. Соответствующее значение в поле USD (доллары) изменится, как показано на рисунке 2. Так как мы зарегистрировали событие onChange для поля USD, вызывается обработчик событий fieldOnChange(). Он извлекает из встроенной формы сумму и обменный курс и преобразует их в читаемую строку, расположенную внизу HTML-файла.

Рисунок 2. Тестирование результатов, часть 1

Теперь изменим обменный курс. Попробуйте изменить значение в поле Ratio Today (сегодняшний курс) с 2,0230 на 2,1230 и нажать на кнопку Set the Ratio, как показано на рисунке 3. Можно увидеть, как меняется значение поля USD в форме; соответствующим образом меняется и текст в нижней части окна.

Рисунок 3. Тестирование результатов, часть 2

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

Использование JavaScript API с Lotus Forms Webform Server

Помимо использования JavaScript API с Lotus Forms Viewer V3.0, можно использовать его с Lotus Forms Webform Server V3.0 для взаимодействия с созданной формой. Существуют некоторые отличия между применением JavaScript API в Lotus Forms Viewer и в Lotus Forms Webform Server.

Транслятор Lotus Forms Webform Server изначально поддерживает JavaScript API, однако Web-приложениям всё равно требуется выполнять вызовы JavaScript API. Необходимо также импортировать библиотеки JavaScript в JSP. После вызова JavaScript API, Lotus Forms Webform Server передаёт обратный вызов транслятору. Для реализации функции JavaScript добавьте следующий метод, чтобы зарегистрировать форму с правильным ID в сервлете, возвращающем созданную форму:

this.setFormName(response, "myFormID");

setFormName() - это интерфейс в сервлете com.ibm.form.webform.framework.servlet.IBMWorkplaceFormsServer Servlet, который должен расширяться каждым специальным классом сервлета. Для использования JavaScript API в портлете, расширяющем IBMWorkplaceFormsServerServlet, необходимо вызвать этот метод.

В листинге 5 показан фрагмент сервлета.

Листинг 5. Использование JavaScript API в сервлете


//задаём использование HTML 
this.useHTML(response, true);
//задаём тип получаемого в ответ контента
response.setContentType("application/vnd.xfdl");
//задаём имя файла, которое будет именем по умолчанию
//при сохранении сформированных данных в Webform Server
this.setFilename(response, fileName);
//задаём id формы
this.setFormName(response, "myFormID");
OutputStream responseOS = response.getOutputStream();
//записываем файл в выходящий поток ответа

Подробную информацию по использованию IBMWorkplaceFormsServerServlet и работе с его API см. в документации по продукту Lotus Forms (EN).

Одним из способов использования JavaScript API для управления сформированной HTML-формой является применение двух фреймов в HTML-файле. Один фрейм ссылается на специально настроенную страницу приложения, взаимодействующую с Lotus Forms. На ней могут содержаться вызовы JavaScript API. Другой фрейм ссылается на сервлет, конвертирующий XFDL в HTML. Вот пример:

<FRAME SRC="/application/ViewFormServlet" name="bottom_frame">

Этот код ссылается на специальный сервлет, конвертирующий XFDL в HTML. JavaScript-код, управляющий формой, - такой же, как код, используемый для Lotus Forms Viewer. Поведение функций также аналогично.

В начало

Заключение

Lotus Forms JavaScript API - это новый API, интегрирующий Lotus Forms с другими формами, например, формами на основе HTML. В него добавлен механизм подписчика на события, которыми обмениваются Lotus Forms Viewer и JavaScript, что обеспечивает большую гибкость при разработке форм.

В начало

Загрузка