Просмотр исходного текста страницы Описание базовых элементов интерфейса

{|cellpadding="10" cellspacing="0" border="0"
| [[Встраиваемые_plugin-модули|Наверх]]
| [[Формат параметров и выходных значений|Формат параметров и выходных значений<<<]]
| [[Описание базовых элементов интерфейса]]
| [[Сервисное взаимодействие|>>>Сервисное взаимодействие]]
|-
|}

__TOC__

Поскольку методы выполняются управляющим объектом plugin-программы, очевидно, что параметры в них готовятся приложением Oktell, а возвращаемые значения - самой plugin-программой. Поэтому при описании в текущем разделе возвращаемых значений методов везде пишется «возвращает...», а понимается «должно возвращаться...». Подробно формат и состав параметров приводится в дальнеших разделах. В текущем же разделе присутствует общее описание назначения методов.


==Общие модульные методы==

Методы этого раздела служат для доступа к общей информации о plugin-программе, ее назначении и составе.

*'''<span style="color:blue">Guid</span> GetId ( )'''. Возвращает уникальный Guid-идентификатор plugin-программы. Используется при различении программ и при обновлениях. По идентификатору приложение загружает plugin в память процесса и не допускает копий.

*'''<span style="color:blue">int</span> GetInterfaceVersion ( <span style="color:blue">int</span> lastknownversion )'''. Возвращает версию интерфейса, на котором базируется plugin-программа. 

В качестве параметра из Oktell передается максимально поздняя поддерживаемая версия. Изначально базовая версия 81022. Если plugin-программа при вызове метода возвращает номер версии, неизвестный для текущей версии Oktell, зарегистрировать ее не удастся.

*'''<span style="color:blue">string</span> GetModuleVersion ( )'''. Возвращает версию plugin-программы в строковом виде. Например «A1.0.1».

*<span style="color:blue">string</span> GetModuleName ( ). Возвращает собственное название plugin-программы. При использовании в комплексе в качестве имени будет использоваться другое, назначенное администратором при регистрации имя. Однако собственное может нести какую-либо дополнительную информацию.

*'''<span style="color:blue">string</span> GetDBUpdate ( )'''. Возвращает строку с запросом в формате Transact-SQL, представляющую собой пакет обновлений для БД при регистрации plugin-программы. Возможно присутствие нескольких батчей, разделенных строчками «GO» согласно tSQL. Запрос выполняется в БД в момент первого сохранения plugin-программы на сервере. Однако возможно и повторное исполнение в случае, если предварительно удалить регистрацию и создать новую с теми же параметрами. Это необходимо иметь в виду при создании запроса-обновления и формировать проверочные условия и/или удаляющие команды. Обновление для БД может отсутствовать. Однако для plugin-программ, реализующих доступ к уникальным сведениям в БД необходимо гарантировать существование в БД соответствующих таблиц, функций и хранимых процедур.

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


<u>Пример возвращаемого значения:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="dbupdate" count="1">
   <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>
 </data>
 </oktellxmlmapper></nowiki>


Текстовая информация из полей CDATA в каждом элементе <span style="color:green">property_cdata</span> содержится отдельный batch-блок с запросом в формате tSQL. Все перечисленные запросы выполнятся поочередно в порядке присутствия в теле XML строки. Каждый запрос будет выполнен в отдельном batch-блоке. Если необходимо разделить текст запроса, представленного внутри одного <span style="color:green">property_cdata</span>, необходимо стандарным способом в необходимом месте разделения вставить строку «GO».


<u>Пример 2 возвращаемого значения. </u>

Можно также возвращать строку, сразу содержащую тело запроса, в котором блоками 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


*'''<span style="color:blue">string</span> GetForms ( )'''. Возвращает перечень заявленных стартовых plugin-форм (и компонентов) в виде строки с XML-содержимым установленной структуры. Для описания каждой plugin-формы используются параметры <span style="color:green">id, caption (name), description, controltype (control/form/none), module (dialog/crm/scriptcomponent), helplink</span>. Именно этот метод определяет формат работы с plugin-программой. Настройка всех вариантов ее применения в комплексе зависит от состава стартовых plugin-форм и их направленности. 

Каждая форма имеет уникальный Guid-идентификатор (<span style="color:green">id</span>). Используется очевидным образом: Для настройки ссылок, а также для различения параметров (их принадлежности к конкретной форме при обмене информацией между plugin-программой и приложением Oktell). Название (<span style="color:green">caption</span>) и описание (<span style="color:green">description</span>) используются для отображения в приложении Oktell в модулях настройки на  работу с plugin-программой. 

Тип контрола (<span style="color:green">controltype</span>) определяет в каком виде форма создана в теле plugin-программы, то есть экземпляром какого класса она является (в .NET это '''System.Windows.Forms.Control''' или '''System.Windows.Forms.Form''', а в Win32 - имеет ли собственную рамку или встраивается в другие окна). В зависимости от этого клиентское приложение Oktell по-разному организует их отображение в диалоговом режиме. Оконные формы отображаются в собственной рамке, а контрольные размещаются в стандартном операторском диалоговом окне Oktell. Серверные компоненты не имеют визуального содержимого. Этот параметр для них можно не указывать, или указывать равным «'''2'''» или «'''none'''».

Первый рисунок - пример формы на базе Control, отображенной в режиме операторского диалога в стандартном для этого окне приложения Oktell. 


[[Файл:Описание интерфейса 001.png|center]]


Второй рисунок - формы на базе Form. Понятно, что она может принимать любой вид.


[[Файл:Описание интерфейса 002.png|center]]


Вариант использования (<span style="color:green">module</span>) указывает приложению Oktell, где описываемую форму можно применять в настройках. Очевидно, одна и та же визуальная форма может в принципе быть использована в обоих режимах (операторские диалоговые окна и доступные через меню модули интерфейса). Но в описываемом интерфейсе взаимодействия производится их четкое разделение. Поэтому в случае подобной задачи на уровне объекта управления необходимо приложению Oktell указывать о наличии двух разных форм с разными идентификаторами, а при создании возвращать экземпляры одного класса. Возвращать же одни и те же экземпляры по запросам разных форм не рекомендуется, и делать необходимо крайне осмотрительно, так как при допущении ошибок в проекте итоговые окна могут исчезать и появляться в используемых местах непрогнозируемым образом.

Адрес справки (<span style="color:green">helplink</span>) используется для режима модулей интерфейса и определяет веб-страницу (или раздел в файле справки), которая будет отображена при щелчке мышью на  пиктограмму с вопросительным знаком в поле пункта меню главного окна клиентского приложения, соответствующего описываемой plugin-форме. Если адрес не задан, пиктограмма для пункта меню не отображается. Ссылка может быть адресом веб-страницей или веб-сервиса, а также ссылкой на раздел в некотором файле справки. Поиск файла будет осуществляться в основном каталоге клиентского приложения (его обновление производится стандартным способом через каталог LiveUpdate с обновлениями), и в каталоге с plugin-программой (для использования этого способа при регистрации plugin-программы через архив или вручную файл должен быть размещен в основной каталог plugin-программы). Примеры задания ссылки на автономно доступный файл справки: «plugin1_manual.chm», «manual.chm::/topic.htm#anchor», «form1.htm». 

На сервере могут исполняться только компоненты, имеющие невизуальное представление (формы с controltype=2 или controltype=none), и обозначенные для использования в составе сценариев (module=2 или module=scriptcomponent). При работе с такими компонентами сервером используются также интерфейсные методы [[Описание_базовых_элементов_интерфейса#GetInputParams|GetInputParams]], [[Описание_базовых_элементов_интерфейса#GetOutputParams|GetOutputParams]] и [[Описание_базовых_элементов_интерфейса#PrepareShow|PrepareShow]].


<u>Пример возвращаемого значения.</u>

В представленном примере из демонстрационной plugin-программы объявлены и реализованы пять стартовых plugin-форм: две для использования в диалоговом режиме и три для использования в режиме отображения внешних модулей.

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="availableforms" count="5">
   <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"><nowiki><![CDATA[http://www.telsystems.ru/help/plugins/demoform3.htm]]></nowiki></property_cdata>
   </property_set>
  </data>
  </oktellxmlmapper></nowiki>


==Режим диалога (операторские формы)==

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


<div id="GetInputParams"></div>
*'''<span style="color:blue">string</span> GetInputParams ( <span style="color:blue">string</span> xml )'''. Возвращает перечень входных параметров для указанной формы (компонента). 

Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы. 

Возвращаемое значение представляет собой строку в XML формате, содержащую структуру, которая описывает все необходимые форме параметры, их названия, идентификаторы, типы, возможно значения по умолчанию. 

Используется при настройке компонента plugin-форма в момент создания сценария диалога. Администратор, создающий сценарий, задает описанные входные значения на основе свойств, указанных в возвращаемой структуре. Возможные типы: аргументы (строковые, числовые, дата-время, общие), запросы к БД, возвращающие значения или наборы, а также перечислимые типы с возможными вариантами, описанными в структуре. В момент выполнения сценария при передаче управления компоненту Plugin-форма, выполняются вычисления всех установленных параметров, готовится XML структура, которая затем передается в плагин на отображение модуля.


<u>Пример передаваемого параметра:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="inputparams" count="1">
   <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>   
 </data>
 </oktellxmlmapper></nowiki>


<u>Возвращаемое значение.</u> 

Каждый параметр представляет собой отдельный набор <span style="color:green">property_set</span> в основной коллекции. Задаваемые свойства:

*<span style="color:green">paramkey</span> - уникальное имя параметра, по которому необходимо будет производиться сопоставление, когда параметры в рабочем процессе будут переданы в форму.

*<span style="color:green">paramtype</span> - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 7 вариантов (1-string, 2-int, 3-datetime, 4-argument, 5-table, 6-tablequery, 7-fixedlist). 

**1, 2, 3, 4 - задаются из формы аргумента, позволяющей выбрать константное значение, значение переменной, выражения или встроенной в диалоговый сценарий функции, различия лишь в ограничении на формат выходного значения (строка, число, строка с дата/время содержимым, произвольный аргумент).  

**5 - возвращает некоторый набор данных из БД, задается в формате SQL создателем сценария.  

**6 - аналогично возвращает из БД набор данных, однако задает «запрос по умолчанию». Указанный текст будет отображаться в поле ввода запроса у разработчика сценария в начале и каждый раз, когда он будет очищать это поле. Для указания текста запроса у соответствующего параметру элемента <span style="color:green">property_set</span> задается коллекция, содержащая один подэлемент с именем «'''query'''». В нем должно присутствовать свойство <span style="color:green">property_cdata</span> с ключом '''sqltext'''. Также допускаются свойства '''connectiontype''', '''connectionstring''', определяющие в случае указания соответственно направление подключения (Собственная БД, ADO, OLE, Oracle, ODBC) и строку подключения к БД. Этот тип параметра может быть использован в случае, если разработчики plugin-программы закладывают жесткую структуру взаимодействия с БД, и их квалификация существенно выше, чем у возможного разработчика сценария. 

**7 - фиксированный список. Предлагает разработчику выбрать один из описанных в теле параметра вариантов. Для этого в соответствующем элементе property_set задается коллекция из других элементов, описывающих возможные варианты значений. Каждый описательный набор <span style="color:green">property_set</span> имеет атрибуты <span style="color:green">name</span>="category" и <span style="color:green">id</span>, установленный в соответствии с идентификатором варианта. В теле описательного набора присутствуют свойства с ключами '''id''' и '''name'''. id - определяет код, который будет передан как выбранный вариант при формировании значений для передачу в форму, name - название, которое увидит разработчик сценария в списке. 

*<span style="color:green">paramname</span> - название параметра, которое увидит разработчик сценанрия.

*<span style="color:green">paramdescription</span> - описание параметра для разработчика сценария (подробная инструкция для получения ожидаемого значения).

*<span style="color:green">paramextra</span> - значение параметра, которое будет без изменений передано на вход в режиме выполнения. Может не быть задано.


<u>Пример возвращаемого значения:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="input" count="6">
   <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>
 </data>
 </oktellxmlmapper></nowiki>


<div id="GetOutputParams"></div>
*'''<span style="color:blue">string</span> GetOutputParams ( <span style="color:blue">string</span> xml )'''. Возвращает перечень выходных параметров для указанной формы (компонента). 

Параметр представляет собой строку в XML формате, в которой присутствует Guid идентификатор plugin-формы. 

Возвращаемое значение представляет собой строку в XML формате, содержащую структуру, которая описывает все получаемые на выходе из формы параметры, их названия, идентификаторы, типы. 

Используется при настройке компонента plugin-форма в момент создания сценария диалога. Администратор, создающий сценарий, указывает в какие переменные будут при выполнении сохранены значения описанных выходные параметров. В момент выполнения сценария после завершения выполнения компонента Plugin-форма, в указанные переменные попадут соответствующие значения выходных параметров.

<u>Пример передаваемого параметра:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="outputparams" count="1">
   <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>   
 </data>
 </oktellxmlmapper></nowiki>


<u>Возвращаемое значение.</u>

Каждый параметр представляет собой отдельный набор <span style="color:green">property_set</span> в основной коллекции. Обязательными являются свойства:

*<span style="color:green">paramkey</span> - уникальное имя параметра, по которому необходимо будет производиться сопоставление, когда параметры в рабочем процессе будут переданы в форму.

*<span style="color:green">paramtype</span> - тип параметра. Определяет способ получения значения параметра при настройке в сценарии и тип значения. Допускается 4 варианта (1-string, 2-int, 3-datetime, 4-variable). Влияют на формат выбора переменной для сохранения значения. Соответственно для выбора предоставляется список только строковых переменных, только числовых, только переменных дата/время или список всех переменных.

*<span style="color:green">paramname</span> - название параметра, которое увидит разработчик сценанрия.

*<span style="color:green">paramdescription</span> - описание параметра для разработчика сценария (подробная инструкция для получения ожидаемого значения).


<u>Пример возвращаемого значения:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="output" count="3">
   <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>
 </data>
 </oktellxmlmapper></nowiki>


*'''<span style="color:blue">string</span> ShowDesign ( <span style="color:blue">string</span> xml )'''. Вызывается для отображения диалоговой plugin-формы в «демонстрационном» режиме без передачи установленных для нее входных параметров. 

В строковом параметре находится XML структура с указанием Guid идентификатора интересующей формы. Если в параметре передан верный идентификатор - метод должен отобразить окно с формой в диалоговом режиме (с возвратом управления только после ее закрытия). Если указан неверный параметр - должен сразу вернуть управление.

Возвращается структура с описанием кода возврата.

Может быть вызвана только в момент создания сценария. Реализация метода plugin-программы для отображения диалоговых plugin-форм c CONTROLTYPE = FORM (оконные) может совпадать с реализацией метода '''PrepareShow'''. Для отображения же plugin-форм с CONTROLTYPE = CONTROL (встраиваемые контролы) реализация должна предусматривать создание и размещение такой формы на внутреннем окне и вывод его на экран командой '''ShowDialog()'''.

Пример передаваемого параметра:

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="design" count="1">
   <property_set name="showformdesign">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
   </property_set>   
 </data>
 </oktellxmlmapper></nowiki>

В качестве возвращаемого значения после закрытия формы должно вернуться описание результата. В случае если результат (свойство <span style="color:green">property_simple</span> с ключом '''resultcode''') не возвращает {"0", "success"}, текст результата из свойства <span style="color:green">property_cdata</span> c ключом '''resultdescription''' будет отображен во всплывающем уведомлении.


<div id="PrepareShow"></div>
*'''<span style="color:blue">string</span> PrepareShow ( <span style="color:blue">string</span> xml )'''. Вызывается для отображения операторской диалоговой plugin-формы в рабочем режиме. 

Метод осуществляет создание, подготовку и отображение окна с формой в диалоговом режиме (с возвратом управления только после ее закрытия). Вызывается только в режиме операторских диалогов (module = "dialog") для оконных форм (controltype = "form").


<u>Передаваемый параметр.</u>

В качестве параметра - строка с XML содержимым. В нем в нескольких разделах перечислены 

*Блок <span style="color:green">common</span>. Общие данные по задаче, сценарию, абоненту, оператору, текущему комментарию, Guid идентификаторы plugin-программы и plugin-формы. Имеет жесткую структуру содержимого. Свойство <span style="color:green">idshow</span> задает уникальный код экземпляра отображения - по нему будет запрашиваться закрытие и возврат значений. 

*Блок <span style="color:green">input</span>. Значения для входных параметров в установленном формате. Структура содержимого состоит из наборов, описывающих входные параметры. Их количество и формат определяются на основе данных,  

*Блок <span style="color:green">fillinfo</span>. Информация о наполнении (этапе). При переводе формы от одного оператора к другому у первого окно с формой закрывается, возвращая строку (любого формата) с неким содержимым. Это содержимое будет передано в управляющий объект plugin-программы в клиентском приложении второго оператора как часть структуры в параметре данного метода <span style="color:darkred">PrepareShow</span>. См. также описание метода <span style="color:darkred">GetCurrentFillInfo</span>. Блок может отсутствовать. 

В приведенном примере передаваемого параметра отмеченные зеленым цветом комментарии разделяют описанные зоны. 

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="prepareparams" count="3"></nowiki>
 
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
 <span style="color:green"><nowiki><!--        Раздел COMMON с общими параметрами              --></nowiki></span>
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
   <nowiki><property_set name="сommon">
     <property_cdata key="idplugin"><![CDATA[b3daa197-f539-22f1-bc5a-8442fa9334ec]]></property_cdata>
     <property_cdata key="idform"><![CDATA[a69f5237-77ef-47fd-97d7-64e0da1c0457]]></property_cdata>
     <property_cdata key="iduser"><![CDATA[da803f01-ea77-40fa-bc9d-e2efb36fd5a8]]></property_cdata>
     <property_simple key="allowstop" value="1" />
     <property_simple key="showontop" value="1" />
     <property_cdata key="comment"><![CDATA[Тело комментария]]></property_cdata>
     <property_cdata key="taskname"><![CDATA[Обработка входящих]]></property_cdata>
     <property_simple key="idshow" value="8bc38a2a-5faa-4c75-864e-2f4e6723f1fd" />
     <property_collection count="2">
       <property_set name="clientinfo">
         <property_collection name="fields" count="3">
           <property_set id="0" name="field">
             <property_cdata key="fieldname"><![CDATA[Название]]></property_cdata>
             <property_cdata key="fieldvalue"><![CDATA[ООО "Гульчатай"]]></property_cdata>
           </property_set>
           <property_set id="1" name="field">
             <property_cdata key="fieldname"><![CDATA[Телефон]]></property_cdata>
             <property_simple key="fieldvalue" value="3214567" />
           </property_set>
           <property_set id="3" name="field">
             <property_cdata key="fieldname"><![CDATA[Контактное лицо]]></property_cdata>
             <property_cdata key="fieldvalue"><![CDATA[Веселовский Пал Виталич]]></property_cdata>
           </property_set>
         </property_collection>
       </property_set>
     </property_collection>
   </property_set></nowiki>
  
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
 <span style="color:green"><nowiki><!--        Раздел INPUT с заказанными параметрами          --></nowiki></span>
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
   <nowiki><property_set name="input">
     <property_collection count="6">
       <property_set name="parameter" id="clientid">
         <property_simple key="paramkey" value="clientid" />
         <property_simple key="paramtype" value="1" />
         <property_simple key="paramextra" value="500" />
         <property_simple key="paramvalue" value="822" />
       </property_set>
       <property_set name="parameter" id="operator">
         <property_simple key="paramkey" value="operator" />
         <property_simple key="paramtype" value="1" />
         <property_simple key="paramextra" value="" />
         <property_cdata key="paramvalue"><![CDATA[Иванов Анатолий]]></property_cdata>
       </property_set>
       <property_set name="parameter" id="categories">
         <property_simple key="paramkey" value="categories" />
         <property_simple key="paramtype" value="7" />
         <property_simple key="paramextra" value="" />
         <property_simple key="paramvalue" value="0" />
       </property_set>
       <property_set name="parameter" id="queuetime">
         <property_simple key="paramkey" value="queuetime" />
         <property_simple key="paramtype" value="4" />
         <property_simple key="paramextra" value="" />
         <property_simple key="paramvalue" value="1,4142135623731" />
       </property_set></nowiki>
  
 <span style="color:green">.....................................................................................</span>
 <span style="color:green">Табличный параметр. </span>
 <span style="color:green">Имеет большой достаточно объем описательного текста даже при небольшом объеме данных</span>
 <span style="color:green">Его формат будет описан отдельно в пункте OnQuery</span>
 <span style="color:green">.....................................................................................</span>
  
       <nowiki><property_set name="parameter" id="products">
         <property_simple key="paramkey" value="products" />
         <property_simple key="paramtype" value="5" />
         <property_simple key="paramextra" value="" />
         <property_collection name="table" count="2">
           <property_set name="tableheader">
             <property_collection name="columns" count="3">
               <property_set name="columninfo" id="0">
                 <property_simple key="index" value="0" />
                 <property_simple key="name" value="id" />
                 <property_simple key="typename" value="Int32" />
                 <property_cdata key="typefullname"><![CDATA[System.Int32]]></property_cdata>
               </property_set>
               <property_set name="columninfo" id="1">
                 <property_simple key="index" value="1" />
                 <property_simple key="name" value="name" />
                 <property_simple key="typename" value="String" />
                 <property_cdata key="typefullname"><![CDATA[System.String]]></property_cdata>
               </property_set>
               <property_set name="columninfo" id="2">
                 <property_simple key="index" value="2" />
                 <property_simple key="name" value="st" />
                 <property_simple key="typename" value="Boolean" />
                 <property_cdata key="typefullname"><![CDATA[System.Boolean]]></property_cdata>
               </property_set>
             </property_collection>
           </property_set>
           <property_set name="tabledata">
             <property_collection name="rows" count="2">
               <property_set name="row" id="0">
                 <property_collection name="cells" count="3">
                   <property_set name="cell" id="0">
                     <property_simple key="cellvalue" value="1" />
                   </property_set>
                   <property_set name="cell" id="1">
                     <property_simple key="cellvalue" value="qwer" />
                   </property_set>
                   <property_set name="cell" id="2">
                     <property_simple key="cellvalue" value="1" />
                   </property_set>
                 </property_collection>
               </property_set>
               <property_set name="row" id="1">
                 <property_collection name="cells" count="3">
                   <property_set name="cell" id="0">
                     <property_simple key="cellvalue" value="2" />
                   </property_set>
                   <property_set name="cell" id="1">
                     <property_simple key="cellvalue" value="wert" />
                   </property_set>
                   <property_set name="cell" id="2">
                     <property_simple key="cellvalue" value="1" />
                   </property_set>
                 </property_collection>
               </property_set>
             </property_collection>
           </property_set>
         </property_collection>
       </property_set></nowiki>
  
 <span style="color:green">.....................................................................................</span>
  
     </property_collection>
   </property_set>
  
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
 <span style="color:green"><nowiki><!--   Раздел FILLINFO с информацией об этапе/заполнении    --></nowiki></span>
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
   <property_set name="fillinfo">
     <property_cdata key="fillinfo"><![CDATA[произвольная строка в любом формате от XML до B64]]></property_cdata>
   </property_set>
 </data>
 </oktellxmlmapper>


<u>Возвращаемое значение.</u>

В возвращаемой строке с XML содержимым должна присутствовать структура со значениями в двух разделах:

*Блок <span style="color:green">common</span>. Новое значение комментария (передаваемого из формы в форму и от оператора к оператору), а также значение результата выполнения. По аналогии со стандартом операторского диалогового окна допускается два вида результатов: переход по кнопке '''Далее''' к следующему компоненту сценария с сохранением выходных значений в переменных сценария, а также остановка сценария кнопкой '''Стоп''' без сохранения выходных значений формы в переменных. 

*Блок <span style="color:green">output</span>. Набор, описывающий значения выходных параметров. Они будут применены в обработчике сценариев на сервере для сохранения в соответствующих переменных, указанных при настройке компонента «Plugin-форма».  


В приведенном примере возвращаемого значения отмеченные зеленым цветом комментарии разделяют описанные зоны. 

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="result" count="2"></nowiki>
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
 <span style="color:green"><nowiki><!--   Раздел COMMON с общеий информацией о результате      --></nowiki></span>
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
   <property_set name="common">
     <property_cdata key="comment"><![CDATA[теперь вот такой комментарий]]></property_cdata>
     <property_simple key="result" value="next" />
   </property_set>
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
 <span style="color:green"><nowiki><!--   Раздел OUTPUT со значениями выходных параметров      --></nowiki></span>
 <span style="color:green"><nowiki><!-- ###################################################### --></nowiki></span>
   <property_set name="output">
     <property_collection count="3">
       <property_set name="parameter" id="selectedproduct">
         <property_simple key="paramkey" value="selectedproduct" />
         <property_simple key="paramtype" value="2" name="int" />
         <property_simple key="paramvalue" value="12345555" />
       </property_set>
       <property_set name="parameter" id="info">
         <property_simple key="paramkey" value="info" />
         <property_simple key="paramtype" value="4" name="variable" />
         <property_cdata key="paramvalue"><![CDATA[выходное значение!!!]]></property_cdata>
       </property_set>
       <property_set name="parameter" id="dt">
         <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="paramvalue"><![CDATA[01.12.2008 7:43:10]]></property_cdata>
       </property_set>
     </property_collection>
   </property_set>
 </data>
 </oktellxmlmapper>


*'''<span style="color:blue">string</span> GetCurrentFillInfo ( <span style="color:blue">string</span> xml )'''. Вызывается для определения текущего наполнения формы (этапа) и последующего перевода формы на другого оператора в том виде, в котором она находится у текущего оператора. 

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращаемое значение может иметь любой формат и будет без разбора передано как часть структуры входного параметра (блок <span style="color:green">fillinfo</span>) в метод <span style="color:darkred">PrepareShow</span> или <span style="color:darkred">CreateControl</span> на компьютере оператора, принимающего переведенный вызов.

<u>Пример передаваемого параметра:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="close" count="1">
   <property_set name="forminfo">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
     <property_simple key="idshow" value="e161da32-c52a-5515-e692-34bb1236a62d" />     
   </property_set>   
 </data>
 </oktellxmlmapper></nowiki>


<u>Пример возвращаемого значения:</u>

<span style="color:darkviolet">произвольная строка в любом формате от XML до B64</span>


*'''<span style="color:blue">string</span> StopShow ( <span style="color:blue">string</span> xml )'''. Вызывается для принудительного закрытия диалоговой формы с CONTROLTYPE = FORM (оконные). Это может происходить в случае перевода звонка и соответствено формы на другого оператора (предварительно вызывается <span style="color:darkred">GetCurrentFillInfo</span>) или в случае принудительного завершения диалогового сценария (по настройкам системы).

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращается структура, содержащая значение комментария.


<u>Пример передаваемого параметра:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="close" count="1">
   <property_set name="forminfo">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />     
     <property_simple key="idshow" value="e161da32-c52a-5515-e692-34bb1236a62d" />     
   </property_set>   
 </data>
 </oktellxmlmapper></nowiki>


<u>Пример возвращаемого значения:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="result" count="1">
   <property_set name="common">
     <property_cdata key="comment"><![CDATA[Новое значение комментария]]></property_cdata>
   </property_set>   
 </data>
 </oktellxmlmapper></nowiki>


*'''<span style="color:blue">string</span> GetControlResult ( <span style="color:blue">string</span> xml )'''. Вызывается для получения XML структуры со значениями выходных переменных для форм с CONTROLTYPE = CONTROL (контрольные). Поскольку отображение таких форм производится приложением Oktell (в отличие от оконных форм plugin-программы, для которых вызывается метод <span style="color:darkred">PrepareShow</span>, осуществляющий подготовку, отображение и возврат управления вместе с описываемой структурой значений выходных параметров в контексте самой plugin-программы).

Строковый параметр в XML структуре определяет код интересующей формы (хотя диалоговый режим поддерживает отображение только одной операторской диалоговой формы единовременно).

Возвращаемое значение - XML структура установленного образца с содержимым, соответствующим значениям выходных параметров plugin-формы, структура и состав полностью аналогичны соответствующему возвращаемому значению метода [[Описание_базовых_элементов_интерфейса#PrepareShow|PrepareShow]].


<u>Пример передаваемого параметра:</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="controlresult" count="1">
   <property_set name="getresult">
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="a69f5237-77ef-47fd-97d7-64e0da1c0457" />
     <property_simple key="idshow" value="a26a4540-6bee-4986-8098-adf340d3faa1" />
   </property_set>   
 </data>
 </oktellxmlmapper></nowiki>


==Общие методы для визуальных режимов использования==

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

*'''System.Windows.Forms.Control CreateControl ( <span style="color:blue">string</span> xml )'''. Используется и в режиме диалога, и в режиме подключения внешних модулей (CRM).

В режиме диалога вызывается для создания и подготовки формы с CONTROLTYPE = CONTROL (контрольные). 

Входной параметр представляет собой строку с комплексным XML параметром, который в зависимости от режима использования имеет тот или иной формат. В режиме диалога содержимое параметра аналогично содержимому одноименного параметра метода <span style="color:darkred">PrepareShow</span>, содержит однотипные разделы и служит для настройки требуемого отображения. 

Возвращает созданный экземпляр контрола, который затем размещается в стандартном операторском диалоговом окне Oktell.

В режиме модулей CRM параметр имеет один и тот же вид: в содержимом XML структуры передаются идентификаторы plugin-программы, plugin-формы, экземпляра plugin-формы, а также информация о пользователе, рабочем месте, и т.д. Какие из переданных параметров использовать - дело управляющего объекта.

Возвращает созданный экземпляр окна (оконной формы), которое затем размещается среди других внешних модулей. 

<span style="color:red">ВНИМАНИЕ: Окно представляет собой .NET форму (System.Windows.Forms.Form), которая в классовой структуре FrameWork является потомком System.Windows.Forms.Control.</span>

Значение передаваемого параметра при использовании в режиме диалога полностью совпадает с параметром функции [[Описание_базовых_элементов_интерфейса#PrepareShow|PrepareShow]].

<u>Пример параметра при создании для подключения среди внешних модулей (CRM):</u>

 <nowiki><?xml version="1.0" encoding="utf-16"?>
 <oktellxmlmapper version="80710">
 <data name="info" count="3">
   <property_set name="user">
     <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />
     <property_cdata key="name"><![CDATA[Иванов Анатолий]]></property_cdata>
     <property_simple key="login" value="Ivanov" />
     <property_simple key="password" value="si4255" />
     <property_simple key="isoperator" value="1" />
     <property_simple key="issupervisor" value="1" />
     <property_simple key="isadmin" value="0" />
     <property_simple key="departmentid" value="c4e3b424-3048-4cce-a2e4-033c532a7d99" />
     <property_cdata key="departmentname"><![CDATA[Маркетинг]]></property_cdata>
   </property_set>
   <property_set name="workplace">
     <property_simple key="id" value="de609bc7-6d3b-4daf-a418-a1d0648d7784" />
     <property_cdata key="name"><![CDATA[Marketing1]]></property_cdata>
     <property_simple key="hasphone" value="1" />
   </property_set>
   <property_set name="link">
     <property_simple key="idshow" value="2e2d8ff0-de47-415f-ab68-9bddcd09952b" />
     <property_simple key="idplugin" value="b3daa197-f539-22f1-bc5a-8442fa9334ec" />
     <property_simple key="idform" value="03e57976-b970-45ff-aec2-fa95ef274bd7" />
     <property_cdata key="linktext"><![CDATA[Форма 3 экз 1]]></property_cdata>
     <property_cdata key="headertext"><![CDATA[Демка, Форма 3 экз 1]]></property_cdata>
     <property_cdata key="description"><![CDATA[Описание пункта меню, задаваемое администратором]]></property_cdata>
     <property_cdata key="address"><![CDATA[Демонстрационный плагин / Модуль 3]]></property_cdata>
   </property_set>
 </data>
 </oktellxmlmapper></nowiki>


==Использование в сценариях сервера==

Возможно использование плагина в составе с серверной службой. Исполнение протекает посредством передачи управления сценариями внешним модулям через компонент «Плагин», доступный во всех типах сценариев системы. Передача управления происходит путем вызова метода [[Описание_базовых_элементов_интерфейса#PrepareShow|PrepareShow]], с передачей XML-параметра и ожиданием возврата XML-ответа. В составе параметра передается вся контекстная информация из сценария (зависит от типа исполняемого сценария), а также перечень значений для всех требуемых входных параметров, указанных в возвращаемом значении метода [[Описание_базовых_элементов_интерфейса#GetInputParams|GetInputParams]]. Значения входных параметров вычисляются в ходе реализации сценария. Соответствующие аргументы назначаются в редакторе сценариев при модификации компонента «Плагин». Там же происходит назначение переменных сценария для приема возвращаемых значений. Список возвращаемых значений, их кодов и типов определяется методом [[Описание_базовых_элементов_интерфейса#GetOutputParams|GetOutputParams]].

Структура параметров и возвращаемых значений при вызове методов GetInputParams и GetOutputParams в контексте работы с компонентами для серверных сценариев абсолютно идентична структуре при работе в режиме диалога. В качестве idform передается идентификатор соответствующего компонента.
 
Структура возвращаемого значения метода PrepareShow также идентична при работе в режиме диалога и в режиме сценариев. Передаваемый параметр в отличие от режима диалога имеет отличия в разделе common (контекстная информация сценария) и лишен блока fillinfo.

Подробно о параметрах в описании соответствующих методов.


==Сервисное взаимодействие==

Методы и события данного раздела служат для осуществления плотного взаимодействия plugin-программы и клиентского приложения Oktell. XML-содержимое описывает не только параметры, но и само действие (действия в общем случае). Не изменяя интерфейса подключения plugin-программ при помощи этих методов будут расширяться возможности взаимодействия, добавляться новые сервисы в клиентское приложение Oktell для использования в plugin-программах.


*'''<span style="color:blue">event</span> PluginQueryInvoker OnQuery'''. Событие управляющего объекта, обрабатываемое в клиентском приложении Oktell. Служит для выполнения сервисных специальных запросов в клиентском приложении Oktell по инициативе plugin-программы или какой либо из ее plugin-форм. Результат выполнения попадает в управляющий объект как возвращаемое значение метода-обработчика. Параметр и возвращаемое значение представляют собой строки с XML-содержимым. Некоторые запросы должны обязательно содержать указание идентификатора plugin-формы и ее экземпляра, переданные через параметр метода <span style="color:darkred">CreateControl</span> в момент создания.

Например могут быть осуществлены запросы в БД с возвратом некоторого набора данных, команды «Позвонить», «Переключить». В режиме модулей CRM команда на отображение специального текста в заголовке модуля, команда на отображение или смену вкладок на панели заголовка.

Именно этот режим будет претерпевать изменения и дополняться при необходимости развития.

Описание структуры параметров обширно и приведено в отдельной статье «[[Сервисное взаимодействие]]».


*'''<span style="color:blue">string</span> DoQuery ( <span style="color:blue">string</span> xml )'''. Событие приложения Oktell, обрабатываемое в управляющем объекте plugin-программы. Служит для выполнения сервисных специальных запросов в plugin-программе. Какие из них использовать и использовать ли вообще - дело управляющего объекта. Параметр и возвращаемое значение представляют собой строки с XML-содержимым.

Например в управляющий объект передаются события о смене активной вкладки в заголовке (сами вкладки появляются в приложении Oktell по событию OnQuery управляющего объекта). В управляющий объект также попадают события об отображении или скрытия той или иной формы, так как может потребоваться обновление данных, инициирование или остановка каких-либо таймеров и т.д.

Описание структуры параметров обширно и приведено в отдельной статье «[[Сервисное взаимодействие]]».

{|cellpadding="10" cellspacing="0" border="0"
| [[Встраиваемые_plugin-модули|Наверх]]
| [[Формат параметров и выходных значений|Формат параметров и выходных значений<<<]]
| [[Описание базовых элементов интерфейса]]
| [[Сервисное взаимодействие|>>>Сервисное взаимодействие]]
|-
|}