Login   Register  
PHP Classes
elePHPant
Icontem

File: as-diagrams.rus.htm

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Classes of Alexander Selifonov  >  Bar chart drawing  >  as-diagrams.rus.htm  >  Download  
File: as-diagrams.rus.htm
Role: Documentation
Content type: text/plain
Description: Manual in russian
Class: Bar chart drawing
Generate bar charts with only HTML and icon images
Author: By
Last change: New features added
Date: 2007-01-16 05:29
Size: 17,141 bytes
 

Contents

Class file image Download
<HTML>
<HEAD><TITLE>as-diagrams: модуль вывода диаграмм (bar charts)</TITLE>
<META http-equiv="Content-Type" Content="text/html; charset=windows-1251">
<!-- link href="styles.css" rel="stylesheet" type="text/css" -->
<STYLE TYPE="text/css">
<!--
  body     { font-family:arial,helvetica;font-size:12px; }
  pre { color:#0000FF; }
  td   { font-family:arial,helvetica;font-size:12px;}
  tr.odd   { background-color: #F0F0F8; color:#000000; }
  tr.even  { background-color: #E0E0F0; color:#000000; }
  h4       { background-color: #E0E0F0; color:#000000;
           text-align: left; }
  h5       { background-color: #E0E0F0; color:#000000;
           text-align: center; }
-->
</STYLE>

</head>
<BODY>
<H3>as-diagrams: модуль вывода диаграмм (bar charts)</H3>

<div align=right><a href="as-diagrams.htm">English version</a><br><br></div>

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

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

<br>
<H3>Установка модуля as-diagrams на сайт</H3>
<ol>
  <li>Загрузив дистрибутив as-diagrams.zip, распакуйте его во временную папку.
  Если планируется его использование во многих страничках сайта, имеет смысл скопировать
  основной файл <b>as-diagrams.php</b> в одну из папок, перечисленных в переменной include_path
  Вашего настроечного php.ini.
  В противном случае положите php-модуль в одну папку со скриптом, из которого будете его вызывать.
  </li>
  <li>Скопируйте содержимое папки <b>img</b> в вашу папку общих картинок сайта (относительный путь
  к этой папке надо будет задать в переменной <b>$imgpath</b>) класса CAsBarDiagram.</li>
  <li>Откройте в текстовом редакторе файл as-diagrams.php и отредактируйте строки :
  <pre>
   var $bt_total = 'Totals'; // localize here or include into separate file
   var $imgpath = '/img/'; // place all 'diagram' images in this "folder"
  </pre>
  <br>$bt_total = ... - здесь задается заголовок для столбца Итогов (например, "Итого")
  <br>$imgpath = ... - Ваш "виртуальный" путь к папке с картинками
  </li>
  <li>При необходимости привести цвета и шрифты к общему дизайну, отредактируйте в файле as-diagrams.php
  CSS-блок (стили tr.barodd, tr.bareven, tr.barhead, td.barhead)
  </li>
</ol>

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

<H3>Использование модуля в своих скриптах</H3>
<p>
Выводить диаграммы можно как на основе заранее подготовленного двумерного массива данных,
(предварительно вызвав необходимые SQL-запросы к своим таблицам или другим способом),
так и передавая в класс CAsBarDiagram текст SQL запросов для того, чтобы данные были собраны
силами самого класса.
<ol>
  <li>Не забываем подключить класс к своему скрипту :<br>
  <b>require_once('as-diagrams.php');</b>
  </li>
  <li>Объявляем переменную класса CAsBarDiagram и если нужно, задаем рабочие параметры:
  <pre>
     $graph = new CAsBarDiagram;
     $graph->bwidth = 15; // ширина одного "столбика" в пикс.
     $graph->showdigits = 0; // отключить вывод таблицы с числовыми значениями (по умолч. включено)
     $graph->bt_total = 'Итого'; // текст для заголовка итоговой колонки
     $graph->precision = 0;  // сколько знаков после дес.точки выводить в таблице числовых значений
     $graph->showtotals = 0;  // если не нужно выводить колонку итогов
  </pre>
  </li>

  <li><a name='LEGENDS'>Готовим одно-двумерные массивы значений, которые будут выполнять роль "легенды" по оси X ($legend_x)
  и по оси Y (имеются в виду значения в одной выводимой группе).
  <br>Одномерный массив-легенда содержит "ключевые" значения для собираемых данных,
  а в двумерном "ключ" должен быть в элементе $legend_x[$row][0], а его текстовое представление,
  которое должно выводиться на графике - в $legend_x[$row][1].

  <br>Заметим, что двумерные массивы легенды (ключ,значение) нужны лишь в случае,
  если вы планируете собирать данные для вывода с помощью вызова GatherData().

  <pre>
    $legend_x = array('розничные продажи','оптовые продажи', 'продажи через интернет');
    $legend_y = array( array('01','январь'),array('02','февраль'),array('03,','март'),
      array('04','апрель'),array('05','май') );
  </pre>
  </li>
  <li>Далее можно поступать двумя вариантами:
    <br>1) собирать данные самостоятельно, наполняя массив $data[x][y] своими значениями
      и вызывать метод отрисовки графика, передав ему собранный массив:
    <pre>
       $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, 'Результаты продаж');
    </pre>
    <br>
    2) подготовив SQL-запрос,  передать его в объект класса CAsBarDiagram:
    <pre>

       $graph->InitData($legend_x, $legend_y); // внутренний массив заполняется нулями
       $graph->GatherData($sql_query, $legend_x, $legend_y);
       // ... можно вызвать многократно, наполняя массив постепенно
       $graph->DiagramBar($legend_x, $legend_y, 0, $data_title);
    </pre>
    При работе по второму методу данные, полученные в SQL-запросе, заносятся во внутренний массив класса,
    и для их отображения вызывается метод DiagramBar() с пустым значением или скалярной переменной вместо массива
    (3-ий параметр метода).
  </li>
</ol>

<h3>Методы и переменные класса CAsBarDiagram</h3>

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

<p><b>GatherData($sqltext, $legend_x, $legend_y [, $position_y])</b> - заполняет внутренний массив данными из
  переданного SQL-запроса. При наличии необходимых таблиц можно получить все данные
  в одном агрегирующем запросе.
  Для этого первое поле полученного курсора должно соответствовать значениям в legend_x,
  второе - $legend_y, а третье - быть искомым числовым значением, заносимым в массив.
  <br>Пример агрегирующего запроса (MySQL)
  <pre>
    SELECT MONTH(sale_date) AS mnt, product, SUM(sales_val) FROM sales
       WHERE YEAR(sale_date)=2005 GROUP BY mnt,product
  </pre>
  Если нужно с помощью запроса заполнить только один "столбец" массива, (возвращаемый запросом курсор имеет два поля -
  ключевое значение по legend_x и искомое числовое значение), то в четвертом параметре ($position_y)
  необходимо указать номер заполняемого столбца данных (начиная с 0).
  В случае, если в курсоре, возвращаемом запросом, три и более поля, параметр $position_y игнорируется.

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

<br><b>$data</b> - двумерный массив данных. $data[x][y] - значение "столбика № "y"
внутри выводимой колонки X.

<a name='SHOWDIGITS' />
<p><b>$showdigits</b> - включение/отключение вывода "цифровой" части диаграммы
  (таблицы с числовым представлением данных, использованных для отрисовки столбиков)

<a name='SHOWPERCENTS' />
<p><b>$ShowPercents</b> - Назначив любое непустое значение элементам этого массива, вы включите
  формирование строк "процентного отношения". Эти строки будут содержать отношение значений
  в строке N-1 к строке N, умноженное на 100.
  <br>
  В этой строке (выводимой в "цифровой" части) будут выведены отношения значений ячеек,
   выраженные в процентах -  $data[n-1]/$data[n]. Эта функция была введена, когда
  понадобилось отображать процент выполнения плана, и при этом одна строка данных содержит
  значения фактических показателей, а следующая - соответствующие плановые данные.
  Как использовать :<br>
  Допустим, есть строка данных "факта", имеющая заголовок "Факт 2005" в соответствующей строке заголовков $legend_y,
  и строка с планом, (заголовок в $legend_y - "План 2005").
  Чтобы в цифровой области после строки плана были выведены показатели выполнения в процентах,
  перед вызовом метода DiagramBar() сделаем присвоение:
  <pre>
    $graph->ShowPercents['План 2005'] = '2005/Выполнено, %';
  </pre>
  Если присвоенная строка состоит из одного символа (1 или '*'), заголовок для
  строки процентов формируется из заголовков соответствующих строк данных,
  в противном случае ее содержимое и будет использовано в качестве заголовка
  (как в нашем примере)
  <br> Пример:
  <pre>
     $graph->ShowPercents[План 2004'] = 'Выполнение плана 2004';
     $graph->ShowPercents[План 2005'] = 'Выполнение плана 2005';
     // Будут выведены две строки с процентными показателями!
     $graph->DiagramBar($legend_x, $legend_y, 0, $data_title);
  </pre>
  Если массив ShowPercents непустой к моенту вызова DiagramBar(),
  цифровая область будет выведена независимо от значения переменной showdigits.

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

<a name="drawempty">
<p><b>$drawempty_x, $drawempty_y</b> - переменные задают режим отрисовки "пустых" колонок (с нулевыми значениями)
  и строк (в цифровой части) соответственно.
  По умолчанию равны 1, т.е. отображаются все колонки, даже с одними нулевыми значениями, и все строки.
  Переменные нужно установить до вызова DiagramBar(). Для установки режима "скрывать пустые колонки,строки"
  можно воспользоваться методами HideEmptyXY($Hide=1),HideEmptyX($Hide=1),HideEmptyY($Hide=1)
 <pre>
     $grarh->drawempty_y = 0;
     $graph->HideEmptyY(); // оба оператора имеют одинаковый эффект
 </pre>

<p>Следующие три переменные класса служат для превращения заголовков "легенды" в HTML-ссылки.</p>
<ul>
  <li><b>legendx_url</b> - здесь задается основная строка URL, с макросом "{ID}", который для каждого залоговка
   заменяется на соответствующее значение.
   <pre>
     $grarh = new CAsBarDiagram;
     $graph->legendx_url = 'detailedinfo.php?info_id={ID}';
   </pre>
   После задания этой переменной все наименования столбцов в выведенной диаграмме будут &lt;A HREF&gt;-ссылками

   </li>
  <li><b>legendx_onClick</b> - строка для события onClick=... в ссылке. Используется, если вместо перехода
    по ссылке нужно выполнить javascript-функцию. Например, для открытия popup-окна (при "клике"
    по тексту заголовка)  можно задать строку вида:
   <pre>
     $graph->legendx_onClick = "window.open('details.php?id={ID}', '_blank','height=300,width=400');";
   </pre>
  </li>
  <li><b>legendx_id</b> - значения для подстановки вместо "{ID}" в адресах и значениях onClick.
  Если переменная не содержит массива, будут использованы сами строки заголовков столбцов.
  <br>В случае подготовленных <b>двумерных</b> массивов легенд нужда в legendx_id отпадает.
  </li>
</ul>

<br>
Ниже приводится работающий пример.
<pre>
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);

</pre>
<br>
Результат работы может выглядеть следующим образом:
<br><br><div align=center>
<img src="sample.png" border=1 bgcolor=blue>
</div>

<br><br><!-- sample output ens -->
Дополнительные замечания по работе с модулем as-diagrams:
<ul>
  <li>Отображаемые данные могут иметь отрицательные значения, в этом случае
  график будет иметь вторую, "минусовую" часть. Масштабы по обеим частям выбираются
  автоматически.<br><br></li>
  <li>Чтобы управлять шириной одного столбика диаграммы, задайте свое значение (в пикселах)
  в переменной <b>$bwidth</b> до вызова функции DiagramBar();
  <li>Если число строк в подготовленном массиве данных велико и приводит
  к отрисовке слишком широкой страницы, ширина столбика может быть автоматически
  понижена. Максимальной допустимой шириной окна при этом
  считается 1024 пиксела (стандартное разрешение монитора 1024 x 768).
  Если Вы хотите заблокировать эту функцию "подстройки", найдите и закомментируйте строку
  в модуле <b>as-diagrams.php</b>, имеющую вид :
  <pre>
  "var $autoshrink = 1024;"
  </pre>
  Либо задайте здесь свое значение максимальной ширины "экрана".
  <br></li>

  <li>Как Вы заметили, ось Y всегда имеет 4 "деления" (в одну сторону от нуля). Каждый "шаг"
  имеет высоту 60 пикселов (таким образом, общая высота Y-полуоси графика равна 240 px).
  Файл "<b>bar-bg240.png</b>" используется как фоновый для основной зоны графиков.
  Если понадобится сменить фон, просто отредактируйте этот файл.

  Если же нужно изменить "базовую" высоту (240px), придется выполнить больше действий:
  нарисовать новый файл фона, сохранить его под именем <b>bar-bgNNNN.png</b>
  (высота картинки должна быть 1/4 от желаемой новой полной высоты),
  и задать новое значение высоты в переменной <b>$graf_height</b> до вызова DiagramBar():
  <br><b>$graf_height = NNNN;</b>
  <br> где NNNN - новая высота для полу-оси Y.
  <br>Помните, что если данные содержат и положительные, и отрицательные значения,
  график может быть выше в два раза.
  <br></li>

  <li>По умолчанию "столбики" раскрашены "растянутыми" изображениями bar-xxxxx.png.
  Если нужно расположить картинку фона "плиткой", задайте непустое значение в переменной
  <b>$btilemode</b> до вызова DiagramBar():
  <b>$btilemode=1;</b>
  <br>Вероятно, для этого случая Вам понадобятся свои изображения вместо включенных в дистрибутив.
  </li>

  <li>Если Вы планируете выводить диаграммы для значений менее 1, точность представления
  дробной части имеет значение. В этом случае можно задать число дес.знаков в переменной
  <b>$precision</b> до вызова функции DiagramBar():
  <br><b>$gtaph->precision = 4;</b>
  <br>Значение по умолчанию 2.

</ul>
<br>

<H4>История (версии)</H4>

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

<h5>1.0.10 (17.01.2006)</h5>
<ul>
  <li>Добавлена возможность вывода итогов по столбцам (в области числового представления данных)
   Для этого переменная <b>showtotals</b> теперь имеет "побитовое" значение: бит 0 отвечает за итоги справа,
      бит 1 - за итоги снизу</li>
  <li>возможность вывода нескольких строк "процентного отношения"
      (в области числового представления данных)
  </li>
<!--  <li></li> -->
</ul>

<br>
<H4>Ссылки</H4>
<ul>
  <li><a href="http://as-works.narod.ru/php/">Домашняя страница автора, библиотека PHP-модулей</a></li>
  <li><a href="http://www.lutanho.net/diagram/" target="_blank">LT Diagram Builder</a> -
      отличный движок для построения различных видов диаграмм и вывода графиков функций
      Есть версии javascript, PHP и ASP. PHP версия использует библиотеку GD.
  </li>
  <li><a href="http://w100w.com/english/asp/graphs_and_charts/" target="_blank">w100w.com,
  список разработок для вывода графики</a>
  </li>
</ul>
<br><br><br><p>
<hr>
<div align=center><font size=-2>Copyright &copy; Alexander Selifonov, <a href="http://as-works.narod.ru">as-works.narod.ru</a>
</font></div>
</HTML></BODY>