### as-diagrams: модуль вывода диаграмм (bar charts)

English version

Предлагаемый PHP класс позволяет собирать и выводить Ваши данные в виде диаграмм - "столбиков" не используя графические библиотеки типа GD, что позволяет уменьшить нагрузку на сервер и размещать свои страницы у провайдеров, не обеспечивающих поддержку gd.

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

### Установка модуля as-diagrams на сайт

1. Загрузив дистрибутив as-diagrams.zip, распакуйте его во временную папку. Если планируется его использование во многих страничках сайта, имеет смысл скопировать основной файл as-diagrams.php в одну из папок, перечисленных в переменной include_path Вашего настроечного php.ini. В противном случае положите php-модуль в одну папку со скриптом, из которого будете его вызывать.
2. Скопируйте содержимое папки img в вашу папку общих картинок сайта (относительный путь к этой папке надо будет задать в переменной $imgpath) класса CAsBarDiagram.
3. Откройте в текстовом редакторе файл as-diagrams.php и отредактируйте строки :

          var $bt_total = 'Totals'; // localize here or include into separate file
          var $imgpath = '/img/'; // place all 'diagram' images in this "folder"

   $bt_total = ... - здесь задается заголовок для столбца Итогов (например, "Итого")
   $imgpath = ... - Ваш "виртуальный" путь к папке с картинками
4. При необходимости привести цвета и шрифты к общему дизайну, отредактируйте в файле as-diagrams.php CSS-блок (стили tr.barodd, tr.bareven, tr.barhead, td.barhead)

Если Ваш WEB-сервер уже поддерживает PHP 4.x, скрипт готов к работе. Теперь посмотрим, как его использовать.

### Использование модуля в своих скриптах

Выводить диаграммы можно как на основе заранее подготовленного двумерного массива данных, (предварительно вызвав необходимые SQL-запросы к своим таблицам или другим способом), так и передавая в класс CAsBarDiagram текст SQL запросов для того, чтобы данные были собраны силами самого класса.

1. Не забываем подключить класс к своему скрипту :
   require_once('as-diagrams.php');
2. Объявляем переменную класса CAsBarDiagram и если нужно, задаем рабочие параметры:

            $graph = new CAsBarDiagram;
            $graph->bwidth = 15; // ширина одного "столбика" в пикс.
            $graph->showdigits = 0; // отключить вывод таблицы с числовыми значениями (по умолч. включено)
            $graph->bt_total = 'Итого'; // текст для заголовка итоговой колонки
            $graph->precision = 0;  // сколько знаков после дес.точки выводить в таблице числовых значений
            $graph->showtotals = 0;  // если не нужно выводить колонку итогов

3. Готовим одно-двумерные массивы значений, которые будут выполнять роль "легенды" по оси X ($legend_x) и по оси Y (имеются в виду значения в одной выводимой группе).
   Одномерный массив-легенда содержит "ключевые" значения для собираемых данных, а в двумерном "ключ" должен быть в элементе $legend_x[$row][0], а его текстовое представление, которое должно выводиться на графике - в $legend_x[$row][1].
   Заметим, что двумерные массивы легенды (ключ,значение) нужны лишь в случае, если вы планируете собирать данные для вывода с помощью вызова GatherData().

           $legend_x = array('розничные продажи','оптовые продажи', 'продажи через интернет');
           $legend_y = array( array('01','январь'),array('02','февраль'),array('03,','март'),
             array('04','апрель'),array('05','май') );

4. Далее можно поступать двумя вариантами:
   1) собирать данные самостоятельно, наполняя массив $data[x][y] своими значениями и вызывать метод отрисовки графика, передав ему собранный массив:

              $data = array( array(200,300,120), array(450,500,100), array(650,200,300),
                             array(380,200,90), array(750,340,200));
              $graph->DiagramBar($legend_x, $legend_y, $data, 'Результаты продаж');

   2) подготовив SQL-запрос, передать его в объект класса CAsBarDiagram:

              $graph->InitData($legend_x, $legend_y); // внутренний массив заполняется нулями
              $graph->GatherData($sql_query, $legend_x, $legend_y);
              // ... можно вызвать многократно, наполняя массив постепенно
              $graph->DiagramBar($legend_x, $legend_y, 0, $data_title);

   При работе по второму методу данные, полученные в SQL-запросе, заносятся во внутренний массив класса, и для их отображения вызывается метод DiagramBar() с пустым значением или скалярной переменной вместо массива (3-ий параметр метода).

### Методы и переменные класса CAsBarDiagram

InitData($legend_x, $legend_y) - выполняет очистку внутреннего массива накопленных значений для вывода. Необходима, если нужно многократно выводить диаграммы, пользуясь при этом одним и тем же экземпляром класса CAsBarDiagram. Размерности массива становится равными длинам переданных массивов "легенд" $legend_x, $legend_y

GatherData($sqltext, $legend_x, $legend_y [, $position_y]) - заполняет внутренний массив данными из переданного SQL-запроса. При наличии необходимых таблиц можно получить все данные в одном агрегирующем запросе. Для этого первое поле полученного курсора должно соответствовать значениям в legend_x, второе - $legend_y, а третье - быть искомым числовым значением, заносимым в массив.
Пример агрегирующего запроса (MySQL)

        SELECT MONTH(sale_date) AS mnt, product, SUM(sales_val) FROM sales
           WHERE YEAR(sale_date)=2005 GROUP BY mnt,product

Если нужно с помощью запроса заполнить только один "столбец" массива, (возвращаемый запросом курсор имеет два поля - ключевое значение по legend_x и искомое числовое значение), то в четвертом параметре ($position_y) необходимо указать номер заполняемого столбца данных (начиная с 0). В случае, если в курсоре, возвращаемом запросом, три и более поля, параметр $position_y игнорируется.

DiagramBar($legend_x, $legend_y, [$data|0, [$data_title]]) - отображение диаграммы. Если в третьем параметре передан массив, его значения используются для отображения. Если передано любое скалярное значение, используются данные, накопленные с помощью предыдущих вызовов метода GatherData();
$data - двумерный массив данных. $data[x][y] - значение "столбика № "y" внутри выводимой колонки X.

$showdigits - включение/отключение вывода "цифровой" части диаграммы (таблицы с числовым представлением данных, использованных для отрисовки столбиков)

$ShowPercents - Назначив любое непустое значение элементам этого массива, вы включите формирование строк "процентного отношения". Эти строки будут содержать отношение значений в строке N-1 к строке N, умноженное на 100.
В этой строке (выводимой в "цифровой" части) будут выведены отношения значений ячеек, выраженные в процентах - $data[n-1]/$data[n]. Эта функция была введена, когда понадобилось отображать процент выполнения плана, и при этом одна строка данных содержит значения фактических показателей, а следующая - соответствующие плановые данные. Как использовать :
Допустим, есть строка данных "факта", имеющая заголовок "Факт 2005" в соответствующей строке заголовков $legend_y, и строка с планом, (заголовок в $legend_y - "План 2005"). Чтобы в цифровой области после строки плана были выведены показатели выполнения в процентах, перед вызовом метода DiagramBar() сделаем присвоение:

        $graph->ShowPercents['План 2005'] = '2005/Выполнено, %';

Если присвоенная строка состоит из одного символа (1 или '*'), заголовок для строки процентов формируется из заголовков соответствующих строк данных, в противном случае ее содержимое и будет использовано в качестве заголовка (как в нашем примере)
Пример:

         $graph->ShowPercents[План 2004'] = 'Выполнение плана 2004';
         $graph->ShowPercents[План 2005'] = 'Выполнение плана 2005';
         // Будут выведены две строки с процентными показателями!
         $graph->DiagramBar($legend_x, $legend_y, 0, $data_title);

Если массив ShowPercents непустой к моенту вызова DiagramBar(), цифровая область будет выведена независимо от значения переменной showdigits. Если переменной $graph->ShowPercents задано непустое значение, "цифровая" часть диаграммы будет выводиться независимо от значения в переменной $graph->showdigits.

$drawempty_x, $drawempty_y - переменные задают режим отрисовки "пустых" колонок (с нулевыми значениями) и строк (в цифровой части) соответственно. По умолчанию равны 1, т.е. отображаются все колонки, даже с одними нулевыми значениями, и все строки. Переменные нужно установить до вызова DiagramBar(). Для установки режима "скрывать пустые колонки,строки" можно воспользоваться методами HideEmptyXY($Hide=1),HideEmptyX($Hide=1),HideEmptyY($Hide=1)

         $grarh->drawempty_y = 0;
         $graph->HideEmptyY(); // оба оператора имеют одинаковый эффект

Следующие три переменные класса служат для превращения заголовков "легенды" в HTML-ссылки.

- legendx_url - здесь задается основная строка URL, с макросом "{ID}", который для каждого залоговка заменяется на соответствующее значение.

           $grarh = new CAsBarDiagram;
           $graph->legendx_url = 'detailedinfo.php?info_id={ID}';

  После задания этой переменной все наименования столбцов в выведенной диаграмме будут <A HREF>-ссылками
- legendx_onClick - строка для события onClick=... в ссылке. Используется, если вместо перехода по ссылке нужно выполнить javascript-функцию. Например, для открытия popup-окна (при "клике" по тексту заголовка) можно задать строку вида:

           $graph->legendx_onClick = "window.open('details.php?id={ID}', '_blank','height=300,width=400');";

- legendx_id - значения для подстановки вместо "{ID}" в адресах и значениях onClick. Если переменная не содержит массива, будут использованы сами строки заголовков столбцов.
  В случае подготовленных двумерных массивов легенд нужда в legendx_id отпадает.

Ниже приводится работающий пример.

    require_once('as-diagrams.php'); // включить в тело своего скрипта !
    //...
    $data_title = 'Test bar diagram'; // title for the diagram

    // sample data array
    $data = array();

    $data[] = array(900, 1300,1600);
    $data[] = array(1200,1800,2500);
    $data[] = array(1400,2000,2800);
    $data[] = array(1900,2900,3900);
    $data[] = array(2500,3500,4500);

    $legend_x = array('Yanuary','February','March','April','May');
    $legend_y = array('pens','pensils','staplers');

    $graph = new CAsBarDiagram;
    $graph->bwidth = 10; // set one bar width, pixels
    $graph->bt_total = 'Summary'; // 'totals' column title, if other than 'Totals'
    // $graph->showtotals = 0;  // uncomment it if You don't need 'totals' column
    $graph->precision = 0;  // decimal precision
    // call drawing function
    $graph->DiagramBar($legend_x, $legend_y, $data, $data_title);

Результат работы может выглядеть следующим образом:
Дополнительные замечания по работе с модулем as-diagrams:

- Отображаемые данные могут иметь отрицательные значения, в этом случае график будет иметь вторую, "минусовую" часть. Масштабы по обеим частям выбираются автоматически.
- Чтобы управлять шириной одного столбика диаграммы, задайте свое значение (в пикселах) в переменной $bwidth до вызова функции DiagramBar();
- Если число строк в подготовленном массиве данных велико и приводит к отрисовке слишком широкой страницы, ширина столбика может быть автоматически понижена. Максимальной допустимой шириной окна при этом считается 1024 пиксела (стандартное разрешение монитора 1024 x 768). Если Вы хотите заблокировать эту функцию "подстройки", найдите и закомментируйте строку в модуле as-diagrams.php, имеющую вид :

        "var $autoshrink = 1024;"

  Либо задайте здесь свое значение максимальной ширины "экрана".
- Как Вы заметили, ось Y всегда имеет 4 "деления" (в одну сторону от нуля). Каждый "шаг" имеет высоту 60 пикселов (таким образом, общая высота Y-полуоси графика равна 240 px). Файл "bar-bg240.png" используется как фоновый для основной зоны графиков. Если понадобится сменить фон, просто отредактируйте этот файл. Если же нужно изменить "базовую" высоту (240px), придется выполнить больше действий: нарисовать новый файл фона, сохранить его под именем bar-bgNNNN.png (высота картинки должна быть 1/4 от желаемой новой полной высоты), и задать новое значение высоты в переменной $graf_height до вызова DiagramBar():
  $graf_height = NNNN;
  где NNNN - новая высота для полу-оси Y.
  Помните, что если данные содержат и положительные, и отрицательные значения, график может быть выше в два раза.
- По умолчанию "столбики" раскрашены "растянутыми" изображениями bar-xxxxx.png. Если нужно расположить картинку фона "плиткой", задайте непустое значение в переменной $btilemode до вызова DiagramBar(): $btilemode=1;
  Вероятно, для этого случая Вам понадобятся свои изображения вместо включенных в дистрибутив.
- Если Вы планируете выводить диаграммы для значений менее 1, точность представления дробной части имеет значение. В этом случае можно задать число дес.знаков в переменной $precision до вызова функции DiagramBar():
  $gtaph->precision = 4;
  Значение по умолчанию 2.

#### История (версии)

##### 1.0.11 (16.01.2007)

- Новая фича: массив "легенд" по осям X ($legend_x[]) и Y ($legend_y[]) может быть двумерным - тогда первый элемент в строке (legend_x[ii][0]) должен содержать "ключевое" значение атрибута, а второй (legend_x[ii][1]) - его текстовое представление, выводимое на диаграмме. Подробно - см. выше. При двумерных массивах легенд отпадает необходимость в дополнительных массивах ID-значений legendx_id, legendy_id.
- В класс добавлена новые переменные $drawempty_x, $drawempty_y, и соответственно, функции для их задания CAsBarDiagram::HideEmptyXY(param=1),HideEmptyX(param=1), HideEmptyY(param=1), задающие режим вывода либо подавления пустых колонок/строк (при ненулевом значении пустые колонки не подавляются). По умолчанию пустые колонки не подавляются. Если нужно обратное, до вызова DiagramBar() выполнить нужный метод;

##### 1.0.10 (17.01.2006)

- Добавлена возможность вывода итогов по столбцам (в области числового представления данных) Для этого переменная showtotals теперь имеет "побитовое" значение: бит 0 отвечает за итоги справа, бит 1 - за итоги снизу
- возможность вывода нескольких строк "процентного отношения" (в области числового представления данных)

#### Ссылки

- Домашняя страница автора, библиотека PHP-модулей
- LT Diagram Builder - отличный движок для построения различных видов диаграмм и вывода графиков функций Есть версии javascript, PHP и ASP. PHP версия использует библиотеку GD.
- w100w.com, список разработок для вывода графики

Copyright © Alexander Selifonov, as-works.narod.ru