Задание информационной панели datapanel в Showcase

Материал из Course Orchestra
Перейти к: навигация, поиск
Showcase

Создание решений на КУРС:Showcase

Создание панели

Описание информационной панели может находится:

1. в xml файле в папке userdata\datapanelstorage;

2. возвращаться процедурой Celesta вида

def proc(context, session):
    ...

3. возвращаться хранимой процедурой вида:

CREATE PROC 
	@main_context varchar(MAX)='',
	@session_context xml='',
	@data xml ='' output,
        @error_mes varchar(MAX) ='' output

Второй и третий способы дают возможность:

  1. динамически менять содержимое панели в зависимости от main_context и session_context,
  2. облегчает создание панелей, основанных на правах доступа, хранящихся в БД
  3. облегчает создание панелей, содержащих данные из БД.

Выбор места, откуда будет идти загрузка данных, определяется именем панели, заданным в действии. Если имя заканчивается на xml - загрузка идет из файла, если на .cl или .celesta — то будет вызвана процедура Celesta, в противном случае - будет вызвана хранимая процедура БД.

Структура панели

Структура панели описывается xml-файлом, структура которого определяется файлом схемы datapanel.xsd, находящемся в папке: webapps\\%webappname%\WEB-INF\classes\schemas. На информационной панели могут быть одна или более вкладок с различным содержанием. Вкладка может содержать один или несколько элементов. Под элементом информационной панели мы подразумеваем данные, представленные в одной из следующих форм:

  1. Таблица (тип grid);
  2. График (тип chart);
  3. Произвольный html-текст (тип webtext);
  4. Данные, отображенные на карте (тип geomap);
  5. Элемент для ввода данных с помощью xforms (тип xforms);
  6. UI-плагин (начиная с версии 2.1.2).

Примерный вид xml-файла, описывающего информационную панель (начиная с версии 1.9.6)

<?xml version="1.0" encoding="UTF-8"?>
<datapanel>
	<tab id="06" name="XForms. Селектор" layout="VERTICAL">
		<element id="61" type="xforms" template="Showcase_Template_selector.xml"
			proc="xforms_proc1">
			<proc id="proc1" name="xforms_saveproc1" type="SAVE" />
			<proc id="proc2" name="xforms_submission1" type="SUBMISSION" />
		</element>
		<element id="62" type="webtext" proc="webtext_filter_and_add"
			hideOnLoad="true" showLoadingMessage="true"/>					
	</tab>
    <tab id="01" name="Табличная раскладка" layout="TABLE" style="yyy" styleClass="css-class">
		<tr id="r01" height="500px" style="border-width: medium" styleClass="css-class">
			<td id="d0101" width="10%" style="border-width: medium" styleClass="css-class" >
				<element id="0101" type="geomap" proc="geomap_bal"
					cacheData="true" style="border-width: medium" styleClass="css-class" />					
			</td>	
			<td id="d0102" width="300px" style="border-width: medium" styleClass="css-class" rowspan="2" > 
				<element id="0102" type="geomap" proc="geomap_bal"
					cacheData="false" />					
			</td>							
		</tr>	
		<tr id="r02" height="200px" style="border-width: medium" styleClass="css-class">	
			<td id="d0201" width="100px" style="border-width: medium" styleClass="css-class" colspan="2">
				<element id="0103" type="grid" proc="grid_portals" />
                                <element id="0104" type="plugin" proc="plugin_data" plugin="radar" transform="plugin.xsl">
                                   <proc id="010401" name="plugin/radarhandler.py" type="POSTPROCESS" />
                                </element>
			</td>
		</tr>			
	</tab>
</datapanel>

Данный xml файл имеет многоуровневую древовидную структуру:

  • Корневой элемент — datapanel;
  • Следующий уровень — tab вкладка;
  • Следующий уровень - tr и td - описывает расположение элементов на вкладке (о них подробнее рассказано в подразделе "Табличная раскладка");
  • Далее идет уровень конкретных элементов панели - element;
  • Каждый элемент в свою очередь может содержать дополнительные процедуры (proc) и ссылки на другие элементы (related).

Вкладка может иметь следующие атрибуты:

  • Уникальный внутри панели идентификатор id;
  • Имя для отображения name;
  • Раскладка элементов внутри вкладки layout (об этой опции подробнее рассказано в подразделе "Табличная раскладка");
  • Существует ряд универсальных необязательных атрибутов, которые могут быть указаны на уровнях tab, td, tr, element:
    * styleClass - CSS-стиль, который будет привязан к элементу веб-страницы, связанному с элементом панели
    * style - встроенный (inline) стиль, который будет привязан к элементу веб-страницы, связанному с элементом панели

Существует и третий способ задания CSS-стиля - привязать стиль к id. Для tr и td атрибут id совпадает с реальным идентификатором на странице, а для element "реальный" id формируется по шаблону: dpe_%panelid%_%elementid%, где panelid - имя файла панели без расширения.

Атрибуты элементов содержимого вкладки (тэги <element>) имеют следующие атрибуты:

  • Обязательный идентификатор id (уникальный внутри панели);
  • Обязательный атрибут type – тип элемента один из следующих: grid, chart, webtext, geomap, xforms, plugin;
  • Атрибут proc – хранимая процедура, загружающая информацию для элемента
  • Для элементов типа webtext и plugin может быть задан необязательный атрибут transform, который указывает на xslt-преобразование, которое необходимо применить к полученному из процедуры xml. Значение атрибута transform - это путь к источнику преобразования.
  • Для plugin-элемента (начиная с версии 2.1.2) должен быть задан атрибут plugin с именем плагина. Имя плагина совпадает с названием каталога плагина.
  • Необязательный атрибут hideOnLoad=true у элемента означает, что при загрузке вкладки данный элемент "в порядке очередности" грузить не надо (то есть прорисовку данного элемента изначально пропускаем), а дождаться события которое само перерисует данный элемент. Элемент с таким тэгом называется зависимым, а элемент, от которого он зависит - главным. Главный элемент должен находиться на той же вкладке, что и зависимый. Зависимость означает, что данный элемент должен заполняться после элемента, от которого он зависит, а также то, что его содержимое может зависеть от текущего контекста "главного" элемента. Фактически, данная опция служит для оптимизации быстродействия.
  • Необязательный атрибут neverShowInPanel=true обозначает то, что элемент никогда не будет отображен внутри вкладки панели, а будет отображаться в модальном окне. Следует отличать его от атрибута hideOnLoad, который нужен для оптимизации загрузки зависимых элементов. Т.об. логически это два разных признака.
  • Необязательный атрибут showLoadingMessage - данная опция появилась начиная с версии 1.9.6. Данная опция определяет, показывать ли сообщение о загрузке элемента. Запрет на показ сообщения приводит к тому, что элемент будет обновлен только после получения данных от сервера. Это нужно, если вы хотите избежать мигания панели. Но это плохо, если загрузка элемента происходит достаточно долго. Значение по умолчанию (если атрибут не задан) - false.
  • Необязательный атрибут showLoadingMessageForFirstTime - данная опция появилась начиная с версии 3.0.1.3616. Она определяет, показывать ли сообщение о загрузке элемента перед его первым появлением. Значение по умолчанию (если атрибут не задан) - true.

Дополнительные процедуры

Элементы с типом xforms и грид могут содержать внутри себя описание дополнительных процедур (атрибут proc). На данный момент поддерживаются процедуры типа:

  1. SAVE - процедура для сохранения данных.
  2. UPLOAD - загрузка данных на сервер.
  3. DOWNLOAD - выгрузка данных с сервера.
  4. METADATA - процедура для загрузки метаданных. Может быть задана для грида, в этом случае загрузка данных будет идти в 2 этапа - сначала метаданные, потом данные.
  5. POSTPROCESS - пост-обработка данных в Jython процедуре. На данный момент пост-обработка может быть только у plugin элементов!

Кроме типа описание процедуры содержит ее id и ее имя в БД (в атрибуте name).

Проверка и трансформация данных, передаваемых с помощью процедур

Для всех типов процедур кроме METADATA можно задать XSD схему (атрибут schema) и XSL трансформацию (атрибут transform). Задание этих атрибутов имеет смысл только для данных в формате XML! В случае задания атрибутов на сервере сразу после получения данных (от клиента или из БД) выполняется проверка схемы документа, после чего выполняется трансформация данных. Оба атрибута являются необязательными. Их можно задавать по отдельности.

Данный функционал работает только в XForms. Для грида он пока не реализован!

Зависимые элементы (related)

Для любых элементов панели можно задать список related (<related id="[id зависимого элемента]">). Это ссылка на элемент, от состояния которого зависит текущий элемент. Таких related элементов может быть несколько, но ссылки возможны только на элементы данной вкладки. Ссылки на себя запрещены. additional и filter контексты related элементов будут переданы в процедуру создания данного элемента в составе session_context. О формате session_context можно почитать в разделе Задание контекста.

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

  1. Шаблоны - %userdata%\xforms;
  2. XSL-преобразования - %userdata%\xslttransforms;
  3. XSD-схемы - %userdata%/schemas.

Табличная раскладка

Начиная с версии 1.9.1 элементы в инф. панели можно располагать в табличной раскладке. Для этого в свойствах вкладку нужно указать атрибут layout="TABLE". Если атрибут layout не указан, то используется "старая" вертикальная раскладка (layout="VERTICAL"). В одной инф. панели могут быть вкладки различных типов.

Элементы tr и td соответствуют одноименным элементам HTML. Роль тэга table в этом случае играет тэг tab.

Тэги tab, tr, td, element могут содержать атрибуты style, styleClass, которые отображаются в атрибуты HTML элементов style и class. Атрибут id у tab, tr, td является необязательным и также отображается в соответствующий атрибут HTML элемента. За их уникальность в пределах страницы отвечает создатель решения. Атрибут id для element идентифицирует элемент, является обязательным и отображается в HTML c добавлением имени инф. панели.

ВНИМАНИЕ:

  1. если в свойствах style элемента tab не указан width, то оно устанавливается по умолчанию равным 100%.
  2. В каждой ячейке таблицы <td> может находиться только один элемент Showcase

В отличие от HTML высота задается для строки в целом, ширина - для ячейки. Это сделано из-за того, что задание разных высот для каждой ячейки в одной и той же строке не имеет смысла. Атрибуты colspan и rowspan у ячеек соответствуют одноименным атрибутам HTML.

За композицию табличной раскладки (вычисление координат и размеров ячеек на основе свойств width, height, rowspan, colspan) отвечает браузер клиента.

Особенности формирования отдельных элементов

XML файл для элемента информационной панели типа webtext может формироваться тремя способами:

  1. Хранимой процедурой на SQL сервере;
  2. При помощи xslt-трансформации;
  3. При помощи хранимой процедуры, к которой применена xslt трансформация.

XML файл для элемента информационной панели типа xforms может формироваться двумя способами:

  1. При помощи шаблона xforms, который содержит некие статичные начальные данные;
  2. При помощи хранимой процедуры, которая передает начальные данные в шаблон xforms.

Подробнее о процедурах для различных типов элементов описано в соответствующих разделах.

Кэширование данных информационной панели

Кэширование данных может быть включено для отдельных элементов панели. Данный вариант имеет два преимущества:

  1. Можно гибко настраивать, что именно нужно кэшировать;
  2. При любом действии всегда можно четко понять - нужно кэшировать данный элемент или нет.

Атрибут элемента cacheData - признак того, что нужно сохранять данные элемента и не обращаться к серверу повторно при возврате на вкладку или панель элемента. На выполнение действий с типом RELOAD_ELEMENTS данная опция не влияет. Нужно отметить, что и в режиме cacheData = true есть возможность принудительного обновления элемента с помощью соответствующей JSNI функции (см. ниже). Элементы кэшируются по составному ключу, включающему в себя FullId элемента и main context.

refreshByTimer - признак того, нужно ли обновлять содержимое элемента по таймеру. При этом время обновления отсчитывается от последнего из 3 событий: 1) последней загрузки данных элемента, инициированной из UI, 2) выполнения действия, обновившего данные текущего элемента, 3) последнего обновления по таймеру.

refreshInterval - интервал обновления элемента в секундах. Используется только если refreshByTimer=true.


Принудительное обновление элемента инф. панели

Для того чтобы реализовать возможность принудительного обновления элемента, необходимо в хранимой процедуре задающей элемент инф. панели создать html контрол (например, кнопку), и по событию клика вызвать функцию getAdditionalContextFeedbackJSNIFunction(String Id), где Id - идентификатор элемента, который нужно обновить.

Например, можно задать параметр @webtextdata, задающий webtext с кнопкой обновления:

set @webtextdata=CAST('<div>

<button onclick="refreshElementFromBaseFeedbackJSNIFunction(''520'')">Обновить</button>


<h1>Обновление данных по таймеру</h1> <h1>Текущее время: '+@t+'</h1></div>' as xml)

В гриде, графике и карте html-контролы можно задавать в Header и Footer.