Руководство разработчика

(% style="color: rgb(51,51,51);" %)Данное руководство содержит теоретические сведения о расширении возможностей [[Платформы НЕЙРОСС>>doc:neyross.WebHome]] в части построения отчетов, в частности добавления в Платформу новых шаблонов отчётов.

2

3

(% style="color: rgb(51,51,51);" %)Пошаговая инструкция по созданию простого набора шаблонов приведена на странице [[doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.Как создать свой набор шаблонов.WebHome]].

4

5

6

(% style="color: rgb(51,51,51);" %)Квалификация разработчика, необходимая для выполнения описываемых в руководстве действий, зависит от решаемых задач. Для создания простых отчётов выборки данных из базы данных (SQL) или модификации существующих шаблонов средствами визуального редактора достаточно квалификации опытного пользователя ПК и знаний SQL. Для создания собственных форм или полей ввода параметров, для выборки данных не из базы данных, а, например, XML-файла, потребуется опыт разработчки программных средств и знание языка Scala (Java).

7

8

9

== {{id name="Руководстворазработчика|Отчёты-Общиесведения"/}}(% style="color: rgb(51,51,51);" %)Общие сведения(%%) ==

10

11

В составе Платформы НЕЙРОСС присутствует веб-приложение «Отчеты», которое позволяет:

12

13

1. загрузить шаблоны отчётов,

14

1. настроить подключение к источникам данных (SQL),

15

1. для выбранного источника данных и выбранного шаблона отчётов заполнить форму параметров формирования отчёта,

16

1. сгенерировать отчёт выбранного формата (PDF, XLS и пр.) по заданному источнику данных и шаблону отчёта.

17

18

//Шаблон отчёта// — совокупность файлов, содержащих необходимое для Платформы НЕЙРОСС описание того, как формировать отчёт.

19

20

Шаблоны отчётов загружаются в Платформу в форме //наборов//. Набор шаблонов — это zip-архив, в котором размещены файлы с определением набора и шаблонов отчётов.

21

22

Для добавления в Платформу новых «пользовательских» шаблонов отчётов необходимо создать соответствующий набор с такими шаблонами и загрузить его в программу. Средствами своего набора разработчик может:

23

24

1. Добавить в Платформу свои шаблоны отчётов.

25

1. Произвольным образом формировать отчёты (в рамках своих шаблонов):

26

11. формировать произвольные запросы к базе / базам данных,

27

11. задавать полностью произвольное визуальное оформление отчёта,

28

11. использовать источники данных, отличные от SQL баз данных,

29

11. поддержать новые форматы экспорта отчётов в дополнение к XLS, PDF и HTML.

30

1. Изменять внешний вид форм ввода параметров:

31

11. настраивать существующие поля ввода данных,

32

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

33

11. использовать свои стили оформления для формы ввода входных параметров,

34

11. и даже формировать форму ввода параметров произвольным образом.

35

36

Основной сценарий формирования отчётов в Платформе — подключение к базе данных (SQL) и формирование отчётов с помощью программных компонентов JasperReports Library. При этом разработка шаблонов отчётов преимущественно осуществляется в визуальном редакторе Jaspersoft Studio.

37

38

Краткое руководство на русском языке по созданию отчётов с помощью JasperReports и Jaspersoft Studio [[доступно по ссылке>>doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.Краткое руководство по JasperReports.WebHome]].

39

40

Подробная информация по Jaspersoft Studio на английском языке приведена на официальном сайте jaspersoft.com в разделе Resources.

41

42

43

Настоящее руководство ориентировано только на использование JasperReports Library и Jaspersoft Studio. Формирование отчётов средствам НЕ JasperReports возможно, но обычно не востребовано. Соответствующий сценарий выходит за рамки данного руководства.

44

45

46

== {{id name="Руководстворазработчика|Отчёты-Структуранаборашаблонов"/}}(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)Структура набора шаблонов\\(%%) ==

47

48

(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51); color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)Набор шаблонов — это zip-архив, который(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %) должен содержать следующие папки и файлы:

49

50

51

definitions/ // папка с шаблонами

52

<папка шаблона 1>/

53

... // другие файлы шаблона

54

report.conf // определение шаблона

55

<папка шаблона 2>/

56

...

57

libs/ // папка дополнительных java-библиотек

58

*.jar // jar-файлы дополнительных библиотек

59

deployment.conf // определение набора

60

61

62

(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)Файл {{code language="none"}}deployment.conf{{/code}} содержит определение набора, этот файл обязательно должен присутствовать в составе архива. Если файла нет, то Платформа НЕЙРОСС не примет загружаемый zip-архив. Подробное описание данного файла приведено в разделе [[#Определение набора шаблонов>>doc:||anchor="Руководстворазработчика|Отчёты-Определениенаборашаблонов"]].

63

64

(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)Для каждого шаблона в наборе должна быть отдельная подпапка в директории {{code language="none"}}definitions{{/code}}. (% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51); color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)В этой подпапке должен присутствовать файл определения шаблона — {{code language="none"}}reports.conf{{/code}}. Подробное описание поддиректории шаблона отчёта приведено в разделе [[#Шаблон отчёта>>doc:||anchor="Руководстворазработчика|Отчёты-Шаблонотчёта"]].

65

66

(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51); color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)В директории {{code language="none"}}libs{{/code}} могут размещаться jar-файлы, используемые в наборе. При использовании нестандартных компонентов ввода параметров или реализации собственной логики формирования отчёта на языке Scala / Java соответствующий код должен быть собран и в форме jar-файлов помещён в данную директорию. Подробная информация по использованию библиотек приведена в разделе [[#Программные компоненты>>doc:||anchor="Руководстворазработчика|Отчёты-Программныекомпоненты"]].

67

68

=== {{id name="Руководстворазработчика|Отчёты-Определениенаборашаблонов"/}}(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)Определение набора шаблонов\\(%%) ===

69

70

(% style="color: rgb(51, 51, 51); color: rgb(51, 51, 51)" %)Текстовый файл {{code language="none"}}deployment.conf{{/code}} должен состоять из пар {{code language="none"}}ключ=значение{{/code}}, размещённых на отдельных строках. При создании набора необходимо корректно задать в файле значения для следующих ключей:

71

72

(% class="wrapped" %)

|=(((

Ключ

)))|=(((

Значение

)))|=(((

Комментарий

)))|=(((

Пример значения

)))

|(((

deployment.key

)))|(((

Строковой идентификатор набора

88

)))|(((

89

Для каждого набора такой идентификатор должен быть уникальным. При обновлении набора (например, добавлении в набор новых шаблонов или изменении существующих) //не следует// менять этот идентификатор, достаточно изменять версию набора (см. ключ {{code language="none"}}deployment.version{{/code}}).

90

91

Идентификатор позволяет различить наборы разных видов. При загрузке набора выполняется проверка идентификатора. Если набор с таким идентификатором уже был загружен в Платформу НЕЙРОСС, то выполняется обновление набора. Если нет, то выполняется установка нового набора.

92

93

Следует выбирать идентификатор набора в соответствии с [[правилами именования пакетов в java>>url:https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html||shape="rect"]].

94

)))|(((

95

ultima.reports.itrium

)))

|(((

deployment.title

)))|(((

Название набора

)))|(((

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

105

106

Рекомендуется выбирать удобочитаемое название набора.

107

)))|(((

108

Типовые формы отчётов к Itrium

)))

|(((

deployment.version

)))|(((

Версия набора

)))|(((

Строка с номером версии. Выводится в пользовательском интерфейсе в списке загруженных наборов.

118

119

Рекомендуется придерживаться общих [[правил нумерации версий программного обеспечения>>url:https://ru.wikipedia.org/wiki/%D0%9D%D1%83%D0%BC%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D1%8F_%D0%B2%D0%B5%D1%80%D1%81%D0%B8%D0%B9_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%BD%D0%BE%D0%B3%D0%BE_%D0%BE%D0%B1%D0%B5%D1%81%D0%BF%D0%B5%D1%87%D0%B5%D0%BD%D0%B8%D1%8F||shape="rect"]].

)))|(((

0.6.0

)))

Пример файла {{code language="none"}}deployment.conf{{/code}} из набора [[типовых шаблонов СКУД ITRIUM>>doc:neyross.АРМ НЕЙРОСС Отчеты.Шаблоны отчетов.Шаблоны СКУД к ITRIUM.WebHome]] приведён ниже:

125

126

127

deployment.key=ultima.reports.itrium

128

deployment.title=Типовые формы отчётов к Itrium

129

deployment.version=0.6.0

Формат файла {{code language="none"}}deployment.conf{{/code}} должен отвечать требованиям к файлу конфигурации [[scala-библиотеки config>>url:https://github.com/lightbend/config||shape="rect"]]. Учитывайте эти требования при использовании в файле специальных символов и т.д.

134

135

136

=== {{id name="Руководстворазработчика|Отчёты-Шаблонотчёта"/}}Шаблон отчёта ===

137

138

Для каждого шаблона в наборе должна быть отдельная подпапка в директории definitions. В этой подпапке должен присутствовать файл определения шаблона — reports.conf. Текстовый файл {{code language="none"}}report.conf{{/code}} должен состоять из пар ключ=значение, размещённых на отдельных строках. При создании шаблона необходимо корректно задать в файле значения для следующих ключей:

139

140

(% class="wrapped" %)

|=(((

Ключ

)))|=(((

Значение

)))|=(((

Комментарий

)))|=(((

Пример значения

)))

|(((

definition.class

)))|(((

Тип реализации шаблона отчёта

156

)))|(((

157

Это имя программного компонента, который будет отвечать за формирование отчёта по данному шаблону.

158

159

Подробное описание данного параметра приведено ниже.

160

)))|(((

161

162

extensions.reports.itrium.ReportDefinition

)))

|(((

definition.htmlPaging

)))|(((

ЗАРЕЗЕРВИРОВАНО

)))|(((

ЗАРЕЗЕРВИРОВАНО

Значение __всегда__ должно быть равно {{code language="none"}}false{{/code}}.

)))|(((

false

)))

|(((

definition.supportedFormats

183

184

)))|(((

185

Список поддерживаемых форматов

186

)))|(((

187

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

188

189

За поддержку форматов отвечает класс реализации. Стандартная реализация поддерживает форматы PDF и XLS. Через данный параметр можно ограничить форматы экспорта, например, если шаблон не позволяет формировать корректный XLS-файл. В своей реализации разработчик может поддержать и другие форматы экспорта.

)))|(((

["pdf","xls"]

)))

Параметр {{code language="none"}}definition.class{{/code}} является ключевым. В данном параметре необходимо указать имя программного компонента, который будет отвечать за подготовку и формирование отчёта по создаваемому шаблону. Разработчику доступно несколько готовых реализаций / компонентов, которые он может использовать в своём шаблоне. Разработчик может выбрать одно из следующих значений {{code language="none"}}definition.class{{/code}}:

197

198

(% class="wrapped" %)

|=(((

Значение

)))|=(((

Описание

)))

|(((

extensions.reports.GenericJasperReportDefinition

207

208

)))|(((

209

__Базовая реализация__ шаблона отчёта с применением JasperReports Library со следующими возможностями:

210

211

1. ключ, название, описание шаблона задаются в файле {{code language="none"}}report.conf{{/code}} (см. далее);

212

1. отчёт формируется в соответствии с jasper-шаблоном средствами JasperReports Library;

213

1. можно формировать отчёты в форматах PDF, XLS (Excel) и HTML (для предпросмотра);

214

1. можно использовать разные шаблоны для предпросмотра и экспорта в PDF / XLS;

215

1. в форме ввода параметров поддерживаются параметры из jasper-шаблона общих типов: строка, число, выбор опций и др.;

216

1. разработчик может добавить свои поля ввода в форме программного модуля.

217

218

Все другие реализации шаблонов обычно унаследованы от базовой и лишь расширяют базовые возможности.

219

220

Подробнее см. страницу [[doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.Базовый шаблон отчёта с JasperReports.WebHome]].

)))

|(((

extensions.reports.itrium.ReportDefinition

225

226

)))|(((

227

Стандартная реализация шаблона отчёта к базе данных Платформы ITRIUM. Используется в модуле [[doc:neyross.АРМ НЕЙРОСС Отчеты.Шаблоны отчетов.Шаблоны СКУД к ITRIUM.WebHome]], но также может использоваться и в других пользовательских модулях отчётов к ITRIUM.

228

229

Обладает всеми возможностями базовой реализации (см. выше) и также позволяет использовать следующие поля ввода на форме ввода параметров:

230

231

1. Выбор одного или нескольких элементов из конфигурации ITRIUM заданного типа.

232

1. Выбор одного или нескольких значений перечислимого свойства ITRIUM заданного типа.

233

1. Выбор одного или нескольких узлов / серверов сети НЕЙРОСС из конфигурации ITRIUM.

234

1. Выбор одной или нескольких организаций и связанных / несвязанных подразделений из конфигурации ITRIUM.

235

1. Выбор одного или нескольких пропусков с возможностью поиска по ФИО и номеру карты.

236

237

Для использования данной реализации шаблона необходимо включить в модуль соответствующий jar-файл (см. [[#Программные компоненты>>doc:||anchor="Руководстворазработчика|Отчёты-Программныекомпоненты"]]).

238

239

Подробнее см. страницу [[doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.Шаблон отчёта к ITRIUM с JasperReports.WebHome]].

240

)))

241

|(((

242

<Имя класса собственной разработки>

243

)))|(((

244

При желании разработчик может создать свой класс и указать его имя в значении для ключа {{code language="none"}}definition.class{{/code}}. В данном классе разработчик может либо расширить одну из существующих реализаций (стандартную, реализацию к ITRIUM), либо реализовать полностью свой алгоритм формирования отчёта.

245

)))

246

247

В зависимости от указанного значения {{code language="none"}}definition.class{{/code}} в файле {{code language="none"}}report.conf{{/code}} может потребоваться указать и другие параметры. См. описание конкретной реализации шаблонов.

248

249

Пример файла {{code language="none"}}report.conf{{/code}} из [[модуля типовых шаблонов СКУД ITRIUM>>doc:neyross.АРМ НЕЙРОСС Отчеты.Шаблоны отчетов.Шаблоны СКУД к ITRIUM.WebHome]] приведён ниже:

250

251

252

definition.class=extensions.reports.itrium.ReportDefinition

253

definition.htmlPaging=false

254

definition.supportedFormats=["pdf","xls"]

255

256

definition.generic.key="ultima.reports.itrium:byAccessPoints"

257

definition.generic.title="События по точкам доступа"

258

definition.generic.description="Список событий доступа по одной или нескольким выбранным точкам доступа / пропускам"

259

260

definition.jasper.design = {

main: "O5.jasper",

html: "O5.jasper"

}

Формат файла {{code language="none"}}report.conf{{/code}} должен отвечать требованиям к файлу конфигурации [[scala-библиотеки config>>url:https://github.com/lightbend/config||shape="rect"]]. Учитывайте эти требования при использовании в файле специальных символов и т.д.

269

270

271

Кроме {{code language="none"}}report.conf{{/code}} в поддиректории шаблона отчёта также могут располагаться и другие файлы, необходимые для подготовки отчёта. Например *.jasper-файлы (в случае использования JasperReports Library). Состав файлов зависит от выбранной реализации шаблона отчёта.

272

273

=== {{id name="Руководстворазработчика|Отчёты-Программныекомпоненты"/}}Программные компоненты ===

274

275

При загрузке набора шаблонов Платформа НЕЙРОСС распаковывает zip-архив и загружает все классы из всех jar-файлов (библиотек Java) из директории {{code language="none"}}libs{{/code}} в модуле. Эти классы могут быть использованы:

276

277

1. для расширения или создания собственной реализации формирования отчёта;

278

1. для реализации новых полей ввода параметров;

279

1. для выборки данных, вычислений или преобразования / форматирования данных по вызову из шаблона JasperReports.

280

281

282

Для каждого модуля классы и jar-файлы загружаются независимо (для каждого модуля используется независимый [[class loader>>url:https://docs.oracle.com/javase/8/docs/api/java/lang/ClassLoader.html||shape="rect"]]). Таким образом не может возникнуть коллизии между разными классами с одинаковыми именами или разными версиями одних и тех же классов в нескольких наборах шаблонов.

283

284

285

Разработчик может самостоятельно реализовать соответствующие Java-классы, собрать jar-файл (один или несколько) и включить его в состав набора, поместив все необходимые jar-файлы в директорию {{code language="none"}}libs{{/code}} zip-архива набора.

286

287

Для пунктов 1 и 2 выше разработчику необходимы определения классов API (программного интерфейса), используемых в Платформе НЕЙРОСС. Такие классы поставляются в артефакте (библиотеке) {{code language="none"}}ultima-reports-api{{/code}} вместе с исходным кодом. Каждая версия Платформы НЕЙРОСС использует свою версию API. Последнюю версию {{code language="none"}}ultima-reports-api{{/code}} можно загрузить по ссылке ниже.

288

289

(% class="wrapped" %)

|=(((

Версия программы

)))|=(((

Версия API

)))|=(((

Документация

)))|=(((

Файлы

)))

|(((

Платформа НЕЙРОСС 19.2

)))|(((

1.4.2

)))|(((

[[doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.ultima-reports-api\:1\.4\.2.WebHome]]

305

)))|(((

306

[[attach:ultima-reports-api_1.4.2_180719.zip]]

307

)))

308

309

Список версий API для предыдущих версий программ приведён ниже. За получением ZIP-файлов просим обращаться к специалистам компании ИТРИУМ.

310

311

312

(% class="wrapped" %)

|=(((

Версия программы

)))|=(((

Версия API

)))|=(((

Документация

)))|=(((

Файлы

)))

|(((

Платформа НЕЙРОСС 18.3

)))|(((

1.2.2

)))|(((

[[doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.ultima-reports-api\:1\.2\.2.WebHome]]

328

)))|(((

329

ultima-reports-api_1.2.2_061218.zip

)))

|(((

НЕЙРОСС Отчёты 3.9

)))|(((

1.1.7

)))|(((

[[doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.ultima-reports-api\:1\.1\.7.WebHome]]

337

)))|(((

338

ultima-reports-api_1.1.7_270918.zip

)))

|(((

НЕЙРОСС Отчёты 1.3.1

)))|(((

1.0.15

)))|(((

—

)))|(((

По запросу

)))

Библиотека API актуальной версии присутствует в составе Платформы НЕЙРОСС.

353

354

Включать её в модуль (в директорию {{code language="none"}}libs{{/code}}) дополнительно не требуется.

355

356

357

Классы [[базовой реализации шаблона отчёта с JasperReports Library>>doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.Базовый шаблон отчёта с JasperReports.WebHome]] входят в API, поэтому для базовой реализации дополнительных jar-файлов включать в директорию {{code language="none"}}libs{{/code}} не требуется. Но, например, реализация полей ввода, используемых в [[типовых шаблонах СКУД к ITRIUM>>doc:neyross.АРМ НЕЙРОСС Отчеты.Шаблоны отчетов.Шаблоны СКУД к ITRIUM.WebHome]], не входит в API. Соответствующие классы реализованы и упакованы в [[отдельный jar-файл>>doc:neyross.Настройка Платформы НЕЙРОСС.Настройка функций подготовки отчётов.Руководство разработчика | Отчёты.Шаблон отчёта к ITRIUM с JasperReports.WebHome]], который при их использовании необходимо поместить в директорию {{code language="none"}}libs{{/code}} в наборе шаблонов.

Wiki source code of Руководство разработчика | Отчёты