Введение

Панель управления имеет встроенный механизм для формирования различных отчетов. Под отчетом понимается представление статистических данных в виде списков с графиками или без них. Отчет может состоять из трех элементов интерфейса: формы, списка и диаграммы. Форма нужна для выбора периода или объекта статистики; в таблице выводятся данные, и по ним строится диаграмма; предполагается, что данные можно скрывать (показывать в развернутом / компактном виде) Данная статья посвящена описанию механизма отчетов, метаданных отчетов и формата выходных данных отчетов.

Для появления в списке всех отчетов, ваш отчет должен состоять из минимум двух частей: xml-описания плагина и обработчика.    Файл xml-описания формирует внешний вид плагина, его вывод в интерфейс и должен соответствовать правилам слияния xml, чтобы иметь возможность встроиться в интерфейс панели. Именно в нем описываются названия колонок / полей, подсказки и так далее. Описание структуры XML и Xmlinstall .

Обработчик, вызов которого прописан в  xml-описании, выполняет какие-либо действия, формирует вывод и передает его панели. Обработчик может быть написан на любом удобном для вас языке (PHP / Perl / Python и т.д). Если обработчик не возвращает панели корректный xml-документ, то он считается вернувшим ошибку и не может быть использован. Обработчики вызываются при старте панели и при выполнении функции, к которой они привязаны. Так, если мы хотим добавить наш отчет в общее меню, мы будем ориентироваться на момент срабатывания event'a reportlist.

Пример xml-описания отчета

<metadata name="journal.stat" type="report" level="30" firstrun="no">
 	 <toolbar>
		 <toolbtn func="journal" type="back" img="t-back" name="back"/>
	 </toolbar>
	 <form>
		 <period/>
	 </form>
	 <band name="function">
		 <diagram name="func" label="funcname" data="percentage" type="pie"/>
		 <col name="funcname" type="data" total="count" link="yes"/>
		 <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
		 <band name="user">
			 <diagram name="user" label="username" type="histogram">
				 <line data="percentage"/>
			 </diagram>
			 <col name="username" type="data" total="count"/>
			 <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
		 </band>
	 </band>
 </metadata>

Отчет

Для описания отчета необходимо создать дочерний элемент в разделе metadata.

атрибут name

наименование отчета, ключевой атрибут.

атрибут type

обязательный параметр, всегда равен 'report'.

атрибут firstrun

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

Текстовое описание к отчету

Для добавления текстового описания к отчету в список сообщений messages в xml отчета необходимо добавить сообщение с именем report_info, например:

<msg name="report_info">Подробный отчет о расходах</msg>

Это описание будет отображено при наведении курсора на отчет в общем списке и на форме самого открытого отчета.

Форма отчета (элемент form)

Данный элемент метаданных описывает поля формы. Описание формы отчета аналогично описанию обычных форм Обязательно используйте валидаторы для проверки вводимых значений. Так, валидатор check="date" в сочетании с маской  mask="9999-99-99" проверяет вводимые значения на соответствие формату “дата YYYY-MM-DD”, валидатор check="int"  проверяет, что было введено целое число. Подробнее: Валидаторы

Описание структуры данных отчета (элемент band)

Структура данных и интерфейса вывода данных отчета описывается с помощью элемента band, имеющего следующую структуру:

 <band>
   <query/>
   <action/>
   <diagram/>
   <col/>
   [[<band>]]
 </band>

Элементы band могут быть вложенными в band более высокого уровня. Один из band самого верхнего уровня может не содержать элемента query или action в том случае, если в программе уже есть функция, соответствующая имени отчета. Все вложенные элементы band должны иметь либо элемент action, либо элемент query. Элементы action и query не могут находиться вместе в одном и том же band.

атрибут name

имя band, ключевой атрибут.

атрибут hidden

если равно "yes" — то будет скрыта таблица с данными.

Описание к таблице

с данными в раздел messages XML-файла панели управления нужно добавить сообщение с именем table_[BANDNAME]

Описание к графику

в раздел messages XML-файла панели управления нужно добавить сообщение с именем diagram_[DIAGRAMNAME]

Описание к отчету

в раздел messages XML-файла панели управления нужно добавить сообщение с именем report_info

Элемент col

Представляет колонку данных в таблице отчета. Если в элементе метаданных (band) верхнего уровня содержится только одна колонка, её данные будут использованы в качестве заголовков для дочерних данных.

атрибут name

имя колонки данных, ключевой атрибут.

атрибут type

тип колонки, если указано "data", то колонка будет представлена колонкой в таблице данных.

атрибут convert

алгоритм кодирования для столбца. Все значения в этом столбце будут преобразованы с использованием заданного алгоритма. На данный момент реализован только punycode — алгоритм преобразования из punycode в последовательность символов в кодировке UTF-8.

атрибут link

если равно "yes", то в колонке будет ссылка (якорь) на дочерние элементы данных.

атрибут sort

задаёт тип сортировки данных в колонке. Возможные значения: alpha (алфавитная сортировка; по умолчанию), digit (сортировка в порядке числового возрастания)

атрибут sorted

если sorted="yes", таблица по умолчанию отсортирована по этой колонке. sorted="desc" сортировать по убыванию.

атрибут total

задаёт тип итогов, отображаемых внизу таблицы с данными. Возможные значения: count (количество строк, имеющих данные в этой колонке), sum (сумма значений строк в данной колонке (для числовых колонок)), sumsuffix (cумма значений строк в данной колонке с обработкой суффиксов и convert="money"), avg (средние значение строк в данной колонке)

атрибут nestedreport

добавляет ссылку в колонке на другой отчет(функцию), который будет указан в значение атрибута (Также будет переданы параметры elid — значение в колонке (или атрибут id из elem), colname — название колонки, и все параметры формы отчета).

Элемент query

Содержит sql-запрос, по которому выводится информация. В запросе необходимо использовать псевдонимы для столбцов, чтобы привязать их к элементу col. Например, "s.name as name" будет привязан к столбцу "<col name="name" ...". В sql запросе можно использовать параметры с формы отчета, а также если query расположен во вложенном band, значения band, расположенном на уровень выше. Имена параметров должны стоять в двойных квадратных скобках. Например:

  .....
  <form>
    <field name="testinput">
      <input name="testinput" type="text"/>
    </field>
  </form>
  <band name="project">
    <query>select id , name from project where account = [[account]]</query>
    <col name="name" type="data"/>
      <band name="testdata">
        <query>
          select .... from ... where param=[[testinput]] and project=[[project.id]]
        </query>
  .....

При использовании отчетов с заданными запросами к БД, необходимо указать источник данных для этих запросов. Чтобы установить источник данных в программе, воспользуйтесь функцией isp_api::SetReportSource(). По умолчанию, все запросы <query></query> обращаются к текущей базе данных панели без дополнительных уточнений.

Элемент action

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

  .....
  <band name="testdata">
    <action>
      testaction
    </action>
  .....

Элемент diagram

Содержит информацию о диаграмме к текущему бэнду.

Атрибуты элемента diagram

@name

имя диаграммы.

@label

говорит, из какой колонки таблицы брать подписи к диаграмме.

@title

отображать заголовок на графике.

@data

говорит, из какой таблицы брать данные для построения диаграммы, присутствует только у типа pie.

@type

задает тип диаграммы — pie, histogram,line, column, area, steppedarea.

@min

Задает нижний вертикальный предел для графика (только для type="line" и type="histogram").

@max

Задает верхний вертикальный предел для графика (только для type="line" и type="histogram").

@others

Задает минимальный процент для отображения на круге, все данные ниже этого процента будут отображаются как "другое" (только для type="pie", задается дробным числом например 20% это 0.2)

Элемент line

Содержит информацию о том, откуда брать данные для диаграммы, присутствует только у элементов histogram, line, column, area, steppedarea. У диаграммы может быть несколько элементов line.

Атрибуты элемента line

@data

говорит, из какой таблицы брать данные для построения диаграммы.

@color

задает цвет линии/столбца, для применения цвета необходимо, чтобы цвет был задан у каждого элемента line.

Описание выходных данных отчета (элемент reportdata)

Данные отчета формируются в соответствии с описанной структурой отчета (элементы band).

В корне отчета должен содержаться элемент <reportdata>, который будет содержать данные отчета. Данные конкретного элемента данных (band) должны содержаться в элементе с именем, соответствующем атрибуту "name" того элемента описания данных, к которому они относятся. Каждая строка данных отчета содержится в элементе elem и представлена набором данных, заключенных в элементы с именем, соответствующим атрибуту "name" соответствующей колонки отчета. Данные вложенных элементов данных должны находиться внутри того же элемента elem, по отношению к которому эти данные являются дочерними.

Предположим, у нас имеется следующее описание отчета в теге metadata (в качестве примера приведем отчет по использованию функций, используемый в COREmanager):

  <band name="function">
    <diagram name="func" label="funcname" data="percentage" type="pie"/>
    <col name="funcname" type="data" total="count" link="yes"/>
    <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
    <band name="user">
      <diagram name="user" label="username" type="histogram">
        <line data="percentage"/>
      </diagram>
      <col name="username" type="data" total="count"/>
      <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
    </band>
  </band>

Пример данных отчета для подобного описания:

  <reportdata>
    <function>
      <elem>
        <funcname>mgr.edit</funcname>
        <percentage>100.00</percentage>
        <user>
          <elem>
            <username>root</username>
            <percentage>100.00</percentage>
          </elem>
        </user>
      </elem>
    </function>
  </reportdata>

В приведенном примере имеется элемент описания данных верхнего уровня (function), для него имеется один элемент данных. Для элемента описания данных второго уровня (user) имеется элемент данных, соответствующий описанию данных второго уровня (band3).

Результирующая xml может иметь следующий вид:

  <metadata name="journal.stat" type="report" level="30" firstrun="no" mgr="core">
    <band name="function">
      <diagram name="func" label="funcname" data="percentage" type="pie"/>
      <col name="funcname" type="data" total="count" link="yes"/>
      <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
      <band name="user">
        <diagram name="user" label="username" type="histogram">
          <line data="percentage"/>
        </diagram>
        <col name="username" type="data" total="count"/>
        <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
      </band>
    </band>
  </metadata>
  <reportdata>
    <function>
      <elem>
        <funcname>mgr.edit</funcname>
        <percentage>100.00</percentage>
        <user>
          <elem>
            <username>root</username>
            <percentage>100.00</percentage>
          </elem>
        </user>
      </elem>
    </function>
  </reportdata>

Пример вывода отчета с приведенными данными:

Список

Список в отчете несколько отличается от обычного. У него есть сортировка, строка статуса, на странице может быть более одного списка; может содержать ссылки на вложенные отчеты, а также якоря на ниже расположенные отчеты. По умолчанию список располагается по середине страницы и в ширину имеет около 600px, но он также может быт открыт на всю ширину страницы.

Диаграмма

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

Виды диаграмм

Диаграмма может быть вида pie, histоgram, column, area, stepped area и line.

Pie (Пирог)

Представляет из себя так называемый "пирог" — круг, разделенный на сектора.

Пример из orion, используется библиотека Google Charts:

Histogram(Гистограмма)

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

Пример из orion:

Line (Линия)

Представляет из себя одну или более ломанную линию.

Пример из orion:

Area

Пример:

Stepped Area

Пример:

Column

Пример:

Версия для печати

В панели есть возможность получить версию для печати и pdf-версию отчета.

Для получения печатной версии необходимо к списку параметров отчета добавить out=print, для pdf версии добавить out=pdf. Перед добавлением необходимо убедиться, что панель поддерживает версию pdf. надо смотреть в desktop параметр <pdf>on</pdf> и только тогда выводить ссылку на pdf версию. Также смотрите: Настройки вывода документа в PDF. 

Пример отчета

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