Конфигурация диаграмм - Платформа CUBA. Отображение диаграмм и карт

2.1. Конфигурация диаграмм

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

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

<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
        xmlns:chart="http://schemas.haulmont.com/charts/charts.xsd"
        ...>

Соответствие элементов XML видам диаграмм:

chart:xyChart – XYChart
chart:serialChart – SerialChart
chart:pieChart – PieChart
chart:funnelChart – FunnelChart
chart:gaugeChart – AngularGaugeChart
chart:radarChart – RadarChart
chart:ganttChart – GanttChart
chart:stockChart – StockChart

Каждый вид диаграммы имеет свой набор атрибутов и методов, которые повторяют функционал соответствующих диаграмм библиотеки AmCharts. Документация по свойствам и методам диаграмм находится по адресу http://docs.amcharts.com/3/javascriptcharts.

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

chart:allLabels – содержит вложенные элементы label, в которых можно указать текст надписи и его свойства. Надписи можно размещать в любом месте на диаграмме, например:

Рисунок 1. chart:allLabels

<chart:allLabels>
    <chart:label x="200"
                 y="700"
                 text="You can place a label at any position on the chart"
                 color="DARKBLUE"
                 align="CENTER"
                 rotation="-30"/>
</chart:allLabels>

chart:balloon – задаёт настройки всплывающих пузырьковых подсказок, появляющихся при наведении курсора мыши на элемент данных диаграммы. Например:
Рисунок 2. chart:balloon
<chart:graphs> <chart:graph balloonText="[[category]]: [[value]] m/s" bullet="ROUND" fillAlphas="0.3" valueField="value"/> </chart:graphs> <chart:balloon adjustBorderColor="false" color="WHITE" horizontalPadding="10" verticalPadding="8"/>
Текст подсказки указывается в атрибуте balloonText для каждого графа.
- additionalFields
 
 Для подстановки данных используются поля, уже использованные в диаграмме, такие как titleField, valueField, category, value, description, percents, open и т.п., а также теги HTML.
 
 Кроме того, вы можете использовать и другие атрибуты сущности из контейнера данных диаграммы с помощью атрибута additionalFields. Этот атрибут позволяет добавить отдельные атрибуты сущности к запросу данных для диаграммы и передать их значения в UI, чтобы вы могли прямо использовать имена атрибутов сущностей в конфигурации диаграммы.
 
 В следующем примере title – это заголовок графа, category – значение по оси категорий, value значение по оси значений, а optional – атрибут сущности IncomeExpenses, загруженный для подстановки в balloonText:
 
 <chart:serialChart additionalFields="optional" addClassNames="true" categoryField="year" dataContainer="incomeExpensesDc" startDuration="1"> <chart:graphs> <chart:graph alphaField="alpha" balloonText="[[title]] in [[category]]: [[value]] [[optional]]" dashLengthField="dashLengthColumn" title="Income" type="COLUMN" valueField="income"/> <...> </chart:graphs> </chart:serialChart>
 
 Рисунок 3. additionalFields
 
 Список дополнительных полей указывается декларативно через запятую:
 
 additionalFields="income,expense,vat"
 
 или можно передать список в контроллере экрана:
 
 List<String> fields = Arrays.asList("income", "expense", "vat"); ganttChart.setAdditionalFields(fields);

chart:chartScrollbar (для диаграмм с типом SerialChart и XYChart) – полоса прокрутки диаграммы.
- Можно использовать скроллбар для прокрутки конкретного графа:
 
 Рисунок 4. chart:chartScrollbar
 
 <chart:chartScrollbar graph="g1" autoGridCount="true" scrollbarHeight="30"/>
- Элемент chart:chartScrollbarSettings позволяет настроить конфигурацию полосы прокрутки:
 
 <chart:chartScrollbarSettings graph="stockGraph" usePeriod="10mm" position="TOP"/>
- Кроме того, диаграммы с типом GanttChart могут дополнительно иметь элемент chart:valueScrollbar для прокрутки оси значений, в то время как chart:chartScrollbar будет использоваться для зуммирования оси категорий:
 
 Рисунок 5. chart:valueScrollbar
 
 <chart:valueScrollbar autoGridCount="true" color="BLACK"/> <chart:chartScrollbar autoGridCount="true" color="DARKOLIVEGREEN"/>

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

Рисунок 6. chart:cursor

<chart:chartCursor cursorAlpha="1"
                   cursorColor="#258cbb"
                   cursorPosition="MOUSE"
                   limitToGraph="g1"
                   pan="true"
                   valueLineAlpha="0.2"
                   valueLineBalloonEnabled="true"
                   valueLineEnabled="true"
                   valueZoomable="true"/>

chart:data – необязательный элемент для добавления данных, используется преимущественно для прототипирования диаграмм.
chart:export – необязательный элемент для подключения функциональности экспорта диаграмм. Реализация экспорта по умолчанию представляет собой кнопку download в углу диаграммы:

Рисунок 7. chart:export

chart:guides – горизонтальные/вертикальные направляющие.

Рисунок 8. chart:guides

<chart:guides>
    <chart:guide category="2001"
                 dashLength="2"
                 fillAlpha="0.2"
                 fillColor="#CC0000"
                 inside="true"
                 label="fines for speeding increased"
                 labelRotation="90"
                 toCategory="2003"/>
    <chart:guide category="2007"
                 dashLength="2"
                 inside="true"
                 label="motorcycle fee introduced"
                 labelRotation="90"
                 lineAlpha="1"
                 lineColor="#CC0000"/>
</chart:guides>

chart:legend – элемент, описывающий легенду диаграммы, например:

Рисунок 9. chart:legend

<chart:legend autoMargins="false"
              marginRight="20"
              markerType="CIRCLE"
              position="RIGHT"
              valueText="[[category]]: [[value]] %"/>

chart:nativeJson – JSON-конфигурация диаграммы.

chart:titles – заголовки осей, например:

Рисунок 10. chart:titles

<chart:titles>
    <chart:title alpha="1"
                 bold="true"
                 color="DARKSLATEGREY"
                 size="20"
                 tabIndex="0"
                 text="Main title"/>
    <chart:title alpha="0.5"
                 color="BISQUE"
                 size="12"
                 text="Subtitle"/>
</chart:titles>

chart:responsive – подключение плагина, позволяющего сделать диаграммы отзывчивыми.
Он позволяет на лету изменять внешний вид диаграммы, автоматически подстраивая её под изменения разрешения экрана. Больше информации о плагине responsive вы можете найти на сайте AmCharts.

Элемент responsive содержит вложенные элементы rules, в которых задаются правила отклика диаграмм. Вы можете настроить скрытие/отображение легенды, заголовков осей, разделителей, заголовков диаграмм, ползунков масштаба, перемещение подписей с осей внутрь графика и т.п.:
<chart:responsive enabled="true"> <chart:rules> <chart:rule maxWidth="400"> <![CDATA[ { "precision": 2, "legend": { "enabled": false }, "valueAxes": { "inside": true } } ]]> </chart:rule> </chart:rules> </chart:responsive>

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

Таким же образом можно описывать диаграммы в контроллере экрана. Можно как указывать отдельные свойства, так и добавлять составные объекты:

pieChart.setWidth("700px");
pieChart.setTitleField("description")
        .setValueField("value")
        .setStartAngle(312)
        .setLegend(new Legend()
                .setMarkerType(MarkerType.CIRCLE)
                .setPosition(LegendPosition.RIGHT)
                .setMarginRight(80))
        .addLabels(
                new Label()
                    .setText("Sample Chart")
                    .setSize(26)
                    .setBold(true)
                    .setAlign(Align.CENTER),
                new Label()
                    .setText("extra information")
                    .setAlign(Align.RIGHT))
        .setLabelTickColor(Color.GOLDENROD)
        .setColors(Arrays.asList(
                    Color.valueOf("#446493"),
                    Color.valueOf("#5E3D2C"),
                    Color.valueOf("#D0A557")))
        .setDataProvider(dataProvider);

Строки сообщений, используемых для отображения диаграмм, можно переопределить или локализовать в главном пакете сообщений модуля web. Несколько готовых локализаций доступны на CUBA GitHub.