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 видам диаграмм:

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

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

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

    charts allLabels
    Рисунок 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 – задаёт настройки всплывающих пузырьковых подсказок, появляющихся при наведении курсора мыши на элемент данных диаграммы. Например:

    charts 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="&lt;span style='font-size:12px;'&gt;[[title]] in [[category]]:&lt;br&gt; &lt;span style='font-size:20px;'&gt;[[value]]&lt;/span&gt; [[optional]]&lt;/span&gt;"
                           dashLengthField="dashLengthColumn"
                           title="Income"
                           type="COLUMN"
                           valueField="income"/>
              <...>
          </chart:graphs>
      </chart:serialChart>
      charts balloon additiional
      Рисунок 3. additionalFields

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

      additionalFields="income,expense,vat"

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

      List<String> fields = Arrays.asList("income", "expense", "vat");
      ganttChart.setAdditionalFields(fields);
  • chart:chartScrollbar (для диаграмм с типом SerialChart и XYChart) – полоса прокрутки диаграммы.

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

      charts zoom
      Рисунок 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 будет использоваться для зуммирования оси категорий:

      charts valueScrollBar
      Рисунок 5. chart:valueScrollbar
      <chart:valueScrollbar autoGridCount="true"
                            color="BLACK"/>
      <chart:chartScrollbar autoGridCount="true"
                            color="DARKOLIVEGREEN"/>
  • chart:cursor – необязательный элемент для добавления курсора к диаграмме. Курсор следует за указателем мыши и отображает пузырьковые подсказки с данными в соответствующей точке диаграммы.

    charts 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 в углу диаграммы:

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

    charts 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 – элемент, описывающий легенду диаграммы, например:

    charts legend
    Рисунок 9. chart:legend
    <chart:legend autoMargins="false"
                  marginRight="20"
                  markerType="CIRCLE"
                  position="RIGHT"
                  valueText="[[category]]: [[value]] %"/>
  • chart:nativeJsonJSON-конфигурация диаграммы.

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

    charts 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.