Описание базовых элементов интерфейса
Поскольку методы выполняются управляющим объектом plugin-программы, очевидно, что параметры в них готовятся приложением Oktell, а возвращаемые значения - самой plugin-программой. Поэтому при описании в текущем разделе возвращаемых значений методов везде пишется «возвращает...», а понимается «должно возвращаться...». Подробно формат и состав параметров приводится в дальнеших разделах. В текущем же разделе присутствует общее описание назначения методов.
Общие модульные методы
Методы этого раздела служат для доступа к общей информации о plugin-программе, ее назначении и составе.
- Guid GetId ( ). Возвращает уникальный Guid-идентификатор plugin-программы. Используется при различении программ и при обновлениях. По идентификатору приложение загружает plugin в память процесса и не допускает копий.
- int GetInterfaceVersion ( int lastknownversion ). Возвращает версию интерфейса, на котором базируется plugin-программа.
В качестве параметра из Oktell передается максимально поздняя поддерживаемая версия. Изначально базовая версия 81022. Если plugin-программа при вызове метода возвращает номер версии, неизвестный для текущей версии Oktell, зарегистрировать ее не удастся.
- string GetModuleVersion ( ). Возвращает версию plugin-программы в строковом виде. Например «A1.0.1».
- string GetModuleName ( ). Возвращает собственное название plugin-программы. При использовании в комплексе в качестве имени будет использоваться другое, назначенное администратором при регистрации имя. Однако собственное может нести какую-либо дополнительную информацию.
- string GetDBUpdate ( ). Возвращает строку с запросом в формате Transact-SQL, представляющую собой пакет обновлений для БД при регистрации plugin-программы. Возможно присутствие нескольких батчей, разделенных строчками «GO» согласно tSQL. Запрос выполняется в БД в момент первого сохранения plugin-программы на сервере. Однако возможно и повторное исполнение в случае, если предварительно удалить регистрацию и создать новую с теми же параметрами. Это необходимо иметь в виду при создании запроса-обновления и формировать проверочные условия и/или удаляющие команды. Обновление для БД может отсутствовать. Однако для plugin-программ, реализующих доступ к уникальным сведениям в БД необходимо гарантировать существование в БД соответствующих таблиц, функций и хранимых процедур.
При формировании проверочных условий необходимо оценивать, как должен себя вести модуль при обновлениях: просто проверять наличие таблиц, функций и процедур и создавать их в случае отсутствия и корректировать в случае несовпадений типов, или удалять и пересоздавать.
Пример возвращаемого значения:
<?xml version="1.0" encoding="utf-16"?>
<oktellxmlmapper version="80710">
<property_set>
<property_cdata key="sqltext"><![CDATA[if exists ( Select * FROM sysobjects where id = object_id ( 'dbo.T_PluginTest' ) )
Drop Table dbo.T_PluginTest]]></property_cdata>
<property_cdata key="sqltext"><![CDATA[Create table dbo.T_PluginTest (id int identity ( 1, 1 ) Primary Key, name nvarchar ( 50 ), st bit )]]></property_cdata>
<property_cdata key="sqltext"><![CDATA[Insert into T_PluginTest ( Name, St ) Values ( 'A', 1 )]]></property_cdata>
</property_set>
</oktellxmlmapper>
Текстовая информация из полей CDATA в каждом элементе property_cdata содержится отдельный batch-блок с запросом в формате tSQL. Все перечисленные запросы выполнятся поочередно в порядке присутствия в теле XML строки. Каждый запрос будет выполнен в отдельном batch-блоке. Если необходимо разделить текст запроса, представленного внутри одного property_cdata, необходимо стандарным способом в необходимом месте разделения вставить строку «GO».
Пример 2 возвращаемого значения.
Можно также возвращать строку, сразу содержащую тело запроса, в котором блоками GO разделяются batch-блоки.
if exists ( Select * FROM sysobjects where id = object_id ( 'dbo.T_PluginTest' ) )
Drop Table dbo.T_PluginTest
GO
Create table dbo.T_PluginTest (id int identity ( 1, 1 ) Primary Key, name nvarchar ( 50 ), st bit ) GO
Insert into T_PluginTest ( Name, St ) Values ( 'A', 1 ) GO
- string GetForms ( ). Возвращает перечень заявленных стартовых plugin-форм (и компонентов) в виде строки с XML-содержимым установленной структуры. Для описания каждой plugin-формы используются параметры id, caption (name), description, controltype (control/form/none), module (dialog/crm/scriptcomponent), helplink. Именно этот метод определяет формат работы с plugin-программой. Настройка всех вариантов ее применения в комплексе зависит от состава стартовых plugin-форм и их направленности.
Каждая форма имеет уникальный Guid-идентификатор (id). Используется очевидным образом: Для настройки ссылок, а также для различения параметров (их принадлежности к конкретной форме при обмене информацией между plugin-программой и приложением Oktell). Название (caption) и описание (description) используются для отображения в приложении Oktell в модулях настройки на работу с plugin-программой.
Тип контрола (controltype) определяет в каком виде форма создана в теле plugin-программы, то есть экземпляром какого класса она является (в .NET это System.Windows.Forms.Control или System.Windows.Forms.Form, а в Win32 - имеет ли собственную рамку или встраивается в другие окна). В зависимости от этого клиентское приложение Oktell по-разному организует их отображение в диалоговом режиме. Оконные формы отображаются в собственной рамке, а контрольные размещаются в стандартном операторском диалоговом окне Oktell. Серверные компоненты не имеют визуального содержимого. Этот параметр для них можно не указывать, или указывать равным «2» или «none».
Первый рисунок - пример формы на базе Control, отображенной в режиме операторского диалога в стандартном для этого окне приложения Oktell.
Второй рисунок - формы на базе Form. Понятно, что она может принимать любой вид.
Вариант использования (module) указывает приложению Oktell, где описываемую форму можно применять в настройках. Очевидно, одна и та же визуальная форма может в принципе быть использована в обоих режимах (операторские диалоговые окна и доступные через меню модули интерфейса). Но в описываемом интерфейсе взаимодействия производится их четкое разделение. Поэтому в случае подобной задачи на уровне объекта управления необходимо приложению Oktell указывать о наличии двух разных форм с разными идентификаторами, а при создании возвращать экземпляры одного класса. Возвращать же одни и те же экземпляры по запросам разных форм не рекомендуется, и делать необходимо крайне осмотрительно, так как при допущении ошибок в проекте итоговые окна могут исчезать и появляться в используемых местах непрогнозируемым образом.
Адрес справки (helplink) используется для режима модулей интерфейса и определяет веб-страницу (или раздел в файле справки), которая будет отображена при щелчке мышью на пиктограмму с вопросительным знаком в поле пункта меню главного окна клиентского приложения, соответствующего описываемой plugin-форме. Если адрес не задан, пиктограмма для пункта меню не отображается. Ссылка может быть адресом веб-страницей или веб-сервиса, а также ссылкой на раздел в некотором файле справки. Поиск файла будет осуществляться в основном каталоге клиентского приложения (его обновление производится стандартным способом через каталог LiveUpdate с обновлениями), и в каталоге с plugin-программой (для использования этого способа при регистрации plugin-программы через архив или вручную файл должен быть размещен в основной каталог plugin-программы). Примеры задания ссылки на автономно доступный файл справки: «plugin1_manual.chm», «manual.chm::/topic.htm#anchor», «form1.htm».
На сервере могут исполняться только компоненты, имеющие невизуальное представление (формы с controltype=2 или controltype=none), и обозначенные для использования в составе сценариев (module=2 или module=scriptcomponent). При работе с такими компонентами сервером используются также интерфейсные методы GetInputParams, GetOutputParams и PrepareShow (описание ниже).
Пример возвращаемого значения.
В представленном примере из демонстрационной plugin-программы объявлены и реализованы пять стартовых plugin-форм: две для использования в диалоговом режиме и три для использования в режиме отображения внешних модулей.
<?xml version="1.0" encoding="utf-16"?>
<oktellxmlmapper version="80710">
<property_set> <property_simple key="id" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" /> <property_cdata key="name"><![CDATA[Операторская форма 1]]></property_cdata> <property_cdata key="description"><![CDATA[Демонстрационная форма для диалогового режима на базе Form]]></property_cdata> <property_simple key="controltype" value="0" name="form" /> <property_simple key="module" value="0" name="dialog" /> </property_set> <property_set> <property_simple key="id" value="87b3e68e-8e27-4e1b-b3fa-d512f5c0148f" /> <property_cdata key="name"><![CDATA[Операторская форма 2]]></property_cdata> <property_cdata key="description"><![CDATA[Демонстрационная форма для диалогового режима на базе Control]]></property_cdata> <property_simple key="controltype" value="1" name="control" /> <property_simple key="module" value="0" name="dialog" /> </property_set> <property_set> <property_simple key="id" value="817d77a7-5d0e-4783-9304-e310c2ac3443" /> <property_cdata key="name"><![CDATA[Модуль 1]]></property_cdata> <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 1 на базе Control]]></property_cdata> <property_simple key="controltype" value="1" name="control" /> <property_simple key="module" value="1" name="crm" /> <property_cdata key="helplink"><![CDATA[manual.chm::/topic_pluginABC.htm#form1]]></property_cdata> </property_set> <property_set> <property_simple key="id" value="38a86f47-073f-4ad7-a942-6919a048ab8a" /> <property_cdata key="name"><![CDATA[Модуль 2]]></property_cdata> <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 2 на базе Control]]></property_cdata> <property_simple key="controltype" value="1" name="control" /> <property_simple key="module" value="1" name="crm" /> <property_cdata key="helplink"><![CDATA[manual.chm::/topic_pluginABC.htm#form2]]></property_cdata> </property_set> <property_set> <property_simple key="id" value="03e57976-b970-45ff-aec2-fa95ef274bd7" /> <property_cdata key="name"><![CDATA[Модуль 3]]></property_cdata> <property_cdata key="description"><![CDATA[Демонстрационный встраиваемый модуль образца 3 на базе Form]]></property_cdata> <property_simple key="controltype" value="0" name="form" /> <property_simple key="module" value="1" name="crm" /> <property_cdata key="helplink"><![CDATA[1]]></property_cdata> </property_set>
</oktellxmlmapper>
Режим диалога (операторские формы)
Перечисленные в этом разделе методы вызываются только для plugin-форм, заявленных как формы для диалоговых сценариев. Даже если plugin-программа вовсе не имеет форм для диалоговых сценариев, все методы должны присутствовать в классе управляющего объекта для соответствия интерфейсу.
- string GetInputParams ( string xml ). Возвращает перечень входных параметров для указанной формы (компонента).
Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы.
Возвращаемое значение представляет собой строку в XML формате, содержащую структуру, которая описывает все необходимые форме параметры, их названия, идентификаторы, типы, возможно значения по умолчанию.
Используется при настройке компонента plugin-форма в момент создания сценария диалога. Администратор, создающий сценарий, задает описанные входные значения на основе свойств, указанных в возвращаемой структуре. Возможные типы: аргументы (строковые, числовые, дата-время, общие), запросы к БД, возвращающие значения или наборы, а также перечислимые типы с возможными вариантами, описанными в структуре. В момент выполнения сценария при передаче управления компоненту Plugin-форма, выполняются вычисления всех установленных параметров, готовится XML структура, которая затем передается в плагин на отображение модуля.
Пример передаваемого параметра:
<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710">
<property_set name="forminput"> <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" /> <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" /> </property_set>
</oktellxmlmapper>
Возвращаемое значение.
Каждый параметр представляет собой отдельный набор property_set в основной коллекции. Задаваемые свойства:
- paramkey - уникальное имя параметра, по которому необходимо будет производиться сопоставление, когда параметры в рабочем процессе будут переданы в форму.
- paramtype - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 7 вариантов (1-string, 2-int, 3-datetime, 4-argument, 5-table, 6-tablequery, 7-fixedlist).
- 1, 2, 3, 4 - задаются из формы аргумента, позволяющей выбрать константное значение, значение переменной, выражения или встроенной в диалоговый сценарий функции, различия лишь в ограничении на формат выходного значения (строка, число, строка с дата/время содержимым, произвольный аргумент).
- 5 - возвращает некоторый набор данных из БД, задается в формате SQL создателем сценария.
- 6 - аналогично возвращает из БД набор данных, однако задает «запрос по умолчанию». Указанный текст будет отображаться в поле ввода запроса у разработчика сценария в начале и каждый раз, когда он будет очищать это поле. Для указания текста запроса у соответствующего параметру элемента property_set задается коллекция, содержащая один подэлемент с именем «query». В нем должно присутствовать свойство property_cdata с ключом sqltext. Также допускаются свойства connectiontype, connectionstring, определяющие в случае указания соответственно направление подключения (Собственная БД, ADO, OLE, Oracle, ODBC) и строку подключения к БД. Этот тип параметра может быть использован в случае, если разработчики plugin-программы закладывают жесткую структуру взаимодействия с БД, и их квалификация существенно выше, чем у возможного разработчика сценария.
- 7 - фиксированный список. Предлагает разработчику выбрать один из описанных в теле параметра вариантов. Для этого в соответствующем элементе property_set задается коллекция из других элементов, описывающих возможные варианты значений. Каждый описательный набор property_set имеет атрибуты name="category" и id, установленный в соответствии с идентификатором варианта. В теле описательного набора присутствуют свойства с ключами id и name. id - определяет код, который будет передан как выбранный вариант при формировании значений для передачу в форму, name - название, которое увидит разработчик сценария в списке.
- paramname - название параметра, которое увидит разработчик сценанрия.
- paramdescription - описание параметра для разработчика сценария (подробная инструкция для получения ожидаемого значения).
- paramextra - значение параметра, которое будет без изменений передано на вход в режиме выполнения. Может не быть задано.
Пример возвращаемого значения:
<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710">
<property_set>
<property_simple key="paramkey" value="operator" />
<property_simple key="paramtype" value="1" name="string" />
<property_cdata key="paramname"><![CDATA[Оператор]]></property_cdata>
<property_cdata key="paramdescription"><![CDATA[Имя текущего оператора]]></property_cdata>
</property_set>
<property_set>
<property_simple key="paramkey" value="clientid" />
<property_simple key="paramtype" value="2" name="int" />
<property_cdata key="paramname"><![CDATA[Клиент]]></property_cdata>
<property_cdata key="paramdescription"><![CDATA[Код обрабатываемого клиента]]></property_cdata>
<property_simple key="paramextra" value="500" />
</property_set>
<property_set>
<property_simple key="paramkey" value="queuetime" />
<property_simple key="paramtype" value="4" name="argument" />
<property_cdata key="paramname"><![CDATA[Время в очереди]]></property_cdata>
<property_cdata key="paramdescription"><![CDATA[Будет отображено на форме без анализа]]></property_cdata>
</property_set>
<property_set>
<property_simple key="paramkey" value="products" />
<property_simple key="paramtype" value="5" name="table" />
<property_cdata key="paramname"><![CDATA[Текущие товары]]></property_cdata>
<property_cdata key="paramdescription"><![CDATA[Набор товаров запросом из БД (Id, Name, Set)]]></property_cdata>
</property_set>
<property_set>
<property_simple key="paramkey" value="users" />
<property_simple key="paramtype" value="6" name="tablequery" />
<property_cdata key="paramname"><![CDATA[Пользователи]]></property_cdata>
<property_cdata key="paramdescription"><![CDATA[Пользователи (Id, Name)]]></property_cdata>
<property_collection name="query" count="1">
<property_set name="query">
<property_simple key="connectiontype" value="1" name="sql" />
<property_simple key="connectionstring" value="" />
<property_cdata key="sqltext"><![CDATA[Select Id, Name From A_Users]]></property_cdata>
</property_set>
</property_collection>
</property_set>
<property_set>
<property_simple key="paramkey" value="categories" />
<property_simple key="paramtype" value="7" name="fixedlist" />
<property_cdata key="paramname"><![CDATA[Категории]]></property_cdata>
<property_cdata key="paramdescription"><![CDATA[Направление работы]]></property_cdata>
<property_collection name="categories" count="2">
<property_set name="category" id="0">
<property_simple key="id" value="0" />
<property_cdata key="name"><![CDATA[Товары]]></property_cdata>
</property_set>
<property_set name="category" id="1">
<property_simple key="id" value="1" />
<property_cdata key="name"><![CDATA[Услуги]]></property_cdata>
</property_set>
</property_collection>
</property_set>
</oktellxmlmapper>
string GetOutputParams ( string xml ). Возвращает перечень выходных параметров для указанной формы (компонента).
Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы.
Возвращаемое значение представляет собой строку в XML формате, содержащую структуру, которая описывает все получаемые на выходе из формы параметры, их названия, идентификаторы, типы.
Используется при настройке компонента plugin-форма в момент создания сценария диалога. Администратор, создающий сценарий, указывает в какие переменные будут при выполнении сохранены значения описанных выходные параметров. В момент выполнения сценария после завершения выполнения компонента Plugin-форма, в указанные переменные попадут соответствующие значения выходных параметров.
Пример передаваемого параметра:
<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710">
<property_set name="formoutput"> <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" /> <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" /> </property_set>
</oktellxmlmapper>
Возвращаемое значение.
Каждый параметр представляет собой отдельный набор property_set в основной коллекции. Обязательными являются свойства:
- paramkey - уникальное имя параметра, по которому необходимо будет производиться сопоставление, когда параметры в рабочем процессе будут переданы в форму.
- paramtype - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 4 варианта (1-string, 2-int, 3-datetime, 4-variable). Влияют на формат выбора переменной для сохранения значения. Соответственно для выбора предоставляется список только строковых переменных, только числовых, только переменных дата/время или список всех переменных.
- paramname - название параметра, которое увидит разработчик сценанрия.
- paramdescription - описание параметра для разработчика сценария (подробная инструкция для получения ожидаемого значения).
Пример возвращаемого значения:
<?xml version="1.0" encoding="utf-16"?> <oktellxmlmapper version="80710">
<property_set> <property_simple key="paramkey" value="selectedproduct" /> <property_simple key="paramtype" value="2" name="int" /> <property_cdata key="paramname"><![CDATA[Выбранный товар]]></property_cdata> <property_cdata key="paramdescription"><![CDATA[Код (id) выбранного товара]]></property_cdata> </property_set> <property_set> <property_simple key="paramkey" value="info" /> <property_simple key="paramtype" value="4" name="variable" /> <property_cdata key="paramname"><![CDATA[Текст уведомления]]></property_cdata> <property_cdata key="paramdescription"><![CDATA[Для отображения следующим компонентом в сценарии после завершения работы с формой]]></property_cdata> </property_set> <property_set> <property_simple key="paramkey" value="dt" /> <property_simple key="paramtype" value="3" name="datetime" /> <property_cdata key="datetimeformat"><![CDATA[dd.MM.yyyy HH:mm:ss]]></property_cdata> <property_cdata key="paramname"><![CDATA[Время]]></property_cdata> <property_cdata key="paramdescription"><![CDATA[Время, установленное для следующей связи]]></property_cdata> </property_set>
</oktellxmlmapper>
string ShowDesign ( string xml )
