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

1

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

2

3

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

4

5

6

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

7

8

9

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

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="Руководстворазработчика|Отчёты-Структуранаборашаблонов"/}}Структура набора шаблонов\\(%%) ==

47

48

Набор шаблонов — это zip-архив, который должен содержать следующие папки и файлы:

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

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

63

64

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

65

66

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

67

68

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

69

70

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

|=(((

Ключ

)))|=(((

Значение

)))|=(((

Комментарий

)))|=(((

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

)))

|(((

deployment.key

)))|(((

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

87

)))|(((

88

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

89

90

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

91

92

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

93

)))|(((

94

ultima.reports.itrium

)))

|(((

deployment.title

)))|(((

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

)))|(((

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

104

105

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

106

)))|(((

107

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

)))

|(((

deployment.version

)))|(((

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

)))|(((

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

117

118

Рекомендуется придерживаться общих [[правил нумерации версий программного обеспечения>>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]] приведён ниже:

124

125

126

deployment.key=ultima.reports.itrium

127

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

128

deployment.version=0.6.0

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

133

134

135

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

136

137

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

|=(((

Ключ

)))|=(((

Значение

)))|=(((

Комментарий

)))|=(((

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

)))

|(((

definition.class

)))|(((

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

154

)))|(((

155

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

156

157

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

158

)))|(((

159

160

extensions.reports.itrium.ReportDefinition

)))

|(((

definition.htmlPaging

)))|(((

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

)))|(((

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

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

)))|(((

false

)))

|(((

definition.supportedFormats

181

182

)))|(((

183

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

184

)))|(((

185

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

186

187

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

)))|(((

["pdf","xls"]

)))

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

|=(((

Значение

)))|=(((

Описание

)))

|(((

extensions.reports.GenericJasperReportDefinition

204

205

)))|(((

206

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

207

208

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

209

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

210

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

211

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

212

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

213

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

214

215

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

216

217

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

)))

|(((

extensions.reports.itrium.ReportDefinition

222

223

)))|(((

224

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

225

226

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

227

228

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

229

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

230

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

231

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

232

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

233

234

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

235

236

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

237

)))

238

|(((

239

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

240

)))|(((

241

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

242

)))

243

244

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

245

246

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

247

248

249

definition.class=extensions.reports.itrium.ReportDefinition

250

definition.htmlPaging=false

251

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

252

253

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

254

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

255

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

256

257

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"]]. Учитывайте эти требования при использовании в файле специальных символов и т.д.

266

267

268

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

269

270

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

271

272

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

273

274

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

275

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

276

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

277

278

279

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

280

281

282

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

283

284

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

|=(((

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

)))|=(((

Версия API

)))|=(((

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

)))|=(((

Файлы

)))

|(((

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

)))|(((

1.4.2

)))|(((

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

301

)))|(((

302

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

303

)))

304

305

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

|=(((

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

)))|=(((

Версия API

)))|=(((

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

)))|=(((

Файлы

)))

|(((

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

)))|(((

1.2.2

)))|(((

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

322

)))|(((

323

ultima-reports-api_1.2.2_061218.zip

)))

|(((

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

)))|(((

1.1.7

)))|(((

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

331

)))|(((

332

ultima-reports-api_1.1.7_270918.zip

)))

|(((

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

)))|(((

1.0.15

)))|(((

—

)))|(((

По запросу

)))

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

346

347

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

348

349

350

Классы [[базовой реализации шаблона отчёта с 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 Руководство разработчика | Отчёты