chart_configuration.adoc

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

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

Диаграммы можно описывать как в {main_man_url}/screen_descriptors.html[XML-дескрипторе], так и в {main_man_url}/screen_controllers.html[контроллере] экрана. Для описания в дескрипторе необходимо подключить соответствующий 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, в которых можно указать текст надписи и его свойства. Надписи можно размещать в любом месте на диаграмме, например:

  

  Figure 1. chart:allLabels

  link:../../../source/chart/chart_allLabels.xml[role=include]

• chart:balloon – задаёт настройки всплывающих пузырьковых подсказок, появляющихся при наведении курсора мыши на элемент данных диаграммы. Например:

  

  Figure 2. chart:balloon

  link:../../../source/chart/chart_balloon.xml[role=include]

  Текст подсказки указывается в атрибуте balloonText для каждого графа.

  • additionalFields

    Для подстановки данных используются поля, уже использованные в диаграмме, такие как titleField, valueField, category, value, description, percents, open и т.п., а также теги HTML.

    Кроме того, вы можете использовать и другие атрибуты сущности из контейнера данных диаграммы с помощью атрибута additionalFields. Этот атрибут позволяет добавить отдельные атрибуты сущности к запросу данных для диаграммы и передать их значения в UI, чтобы вы могли прямо использовать имена атрибутов сущностей в конфигурации диаграммы.

    В следующем примере title – это заголовок графа, category – значение по оси категорий, value значение по оси значений, а optional – атрибут сущности IncomeExpenses, загруженный для подстановки в balloonText:

    link:../../../source/chart/chart_additionalFields.xml[role=include]

    

    Figure 3. additionalFields

    Список дополнительных полей указывается декларативно через запятую:

    additionalFields="income,expense,vat"

    или можно передать список в контроллере экрана:

    link:../../../source/chart/chart_additionalFields.java[role=include]

• chart:chartScrollbar (для диаграмм с типом [serial_chart] и [xy_chart]) – полоса прокрутки диаграммы.

  • Можно использовать скроллбар для прокрутки конкретного графа:

    

    Figure 4. chart:chartScrollbar

    link:../../../source/chart/chart_chartScrollbar.xml[role=include]

  • Элемент chart:chartScrollbarSettings позволяет настроить конфигурацию полосы прокрутки:

    link:../../../source/chart/chart_chartScrollbar2.xml[role=include]

  • Кроме того, диаграммы с типом [gantt_chart] могут дополнительно иметь элемент chart:valueScrollbar для прокрутки оси значений, в то время как chart:chartScrollbar будет использоваться для зуммирования оси категорий:

    

    Figure 5. chart:valueScrollbar

    link:../../../source/chart/charts_valueScrollBar.xml[role=include]

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

  

  Figure 6. chart:cursor

  link:../../../source/chart/chart_cursor.xml[role=include]

• chart:data – необязательный элемент для добавления данных, используется преимущественно для прототипирования диаграмм.

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

  

  Figure 7. chart:export

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

  

  Figure 8. chart:guides

  link:../../../source/chart/chart_guides.xml[role=include]

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

  

  Figure 9. chart:legend

  link:../../../source/chart/chart_legend.xml[role=include]

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

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

  

  Figure 10. chart:titles

  link:../../../source/chart/chart_titles.xml[role=include]

• chart:responsive – подключение плагина, позволяющего сделать диаграммы отзывчивыми.

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

  Элемент responsive содержит вложенные элементы rules, в которых задаются правила отклика диаграмм. Вы можете настроить скрытие/отображение легенды, заголовков осей, разделителей, заголовков диаграмм, ползунков масштаба, перемещение подписей с осей внутрь графика и т.п.:

  link:../../../source/chart/responsive.xml[role=include]

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

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

link:../../../source/chart/chart_configure.java[role=include]

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