Представленная библиотека представляет собой очередную попытку отделить содержание от оформления. Основная идея не нова - использовать специальное оформление внутри статического HTML-текста, что позволит при обработке этого текста заменить специально оформленные разделы на динамически формируемые данные из PHP-скрипта. Другими словами, мы создаем свой собственный "стиль разметки" HTML-текста, а затем этот специально подготовленный HTML-текст обрабатывается из PHP-скрипта. Простейший пример: требуется показывать на сайте текущую дату. Естественно, что сами данные (день, месяц, год, время) будут меняться, поскольку формируются динамически, однако их оформление, скорей всего, будет одним и тем же (предположим, большая синяя надпись в красной рамке). Самым удобным решением - каким-то образом "подсказать" PHP-скрипту, где именно нужно вывести данные, не касаясь стиля их оформления. Для этого в представленной библиотеки используются как простые замены (специальные последовательности символов), так и специальные HTML-теги.

Для того, чтобы PHP-скрипт мог использовать библиотеку, в нем должны быть две строчки:

// путь к файлам библиотеки из исполняемого PHP-скрипта
define('INCLUDE_DIR',  'parse/');
// инициализация библиотеки
require_once(INCLUDE_DIR.'init.inc.php');

Библиотека работает так же, как и все остальные библиотеки, занимающиеся парсингом HTML-текста, с добавлением в этот текст данных, полученных из PHP-скрипта :

• Функция "parseStr" - ищет в исходной строке все вхождения вида

  <#имя_переменной#>

  и заменяет их переменными или константами из PHP-скрипта с совпадающими именами (имена переменных и констант case-sensitive).
  Например, если в PHP-скрипте существует такая запись:

  $var = '1234';

  то при вызове в этом PHP-скрипте функции "parseStr", все вхождения вида <#var#> в исходной строке будут заменены на значение переменной $var:

  // инициализация переменной $var 
  $var = '1234';
  	
  // вызов функции "parseStr"
  echo parseStr('Variable $var has value <#var#>');
  // результат работы функции "parseStr"
  Variable $var has value 1234 

  Аналогичным образом подставляются значения констант:

  // инициализация константы MY_CONST 
  define('MY_CONST', 1234);
  	
  // вызов функции "parseStr"
  echo parseStr('Constant MY_CONST has value <#MY_CONST#>');
  // результат работы функции "parseStr"
  Constant MY_CONST has value 1234 

  ПРИМЕЧАНИЕ: Символы начала переменной/константы ( <# ) и символы окончания переменной/константы ( #> ) могут быть изменены двумя способами:
  • изменить значения соответствующих констант в файле "const.inc.php":

    // новые параметры начала и окончания переменных/констант
    // в PHP-скрипте
    define('DEFAULT_VARNAME_START', '{');
    define('DEFAULT_VARNAME_END', '}');

  • изменить правила парсинга, вызвав функцию "init":

    // новые параметры начала и окончания переменных/констант
    // в PHP-скрипте
    $new_pars = array('varstart' => '{', 'varend' => '}');
    // изменить правила парсинга
    $GlobalParser->init($new_pars);

• Функция "parseFile" - считывает содержимое файла в строку, после чего эта строка передается на обработку функции "parseStr", и
• Функция "parseTag" - обрабатывает теги специального вида. Мы будем называть эти теги "callback-тегами".

Мы будем использовать термин "callback-теги", когда будем говорить о специальных тегах, используемых в библиотеке, поскольку их назначение близко к вызову callback функций. Использование callback-тегов позволяет вызывать PHP-функции во время парсинга. Callback-тег - это парный тег, который определяет сам разработчик. Имя callback-тега хранится в настройках библиотеки. Самый простой callback-тег выглядит так:

<callback name=имя_функции>содержимое_тега</callback>

Как это работает? Каждый раз, когда функция "parseTag" встречает callback-тег в процессе парсинга, она вызывает PHP-функцию с указанным именем (имя функции хранится в аттрибуте "name"). Вызываемая функция должна принимать один параметр - в качестве этого параметра в функцию передается "содержимое_тега". Если функция принимает больше, чем один параметр, то все параметры, начиная со второго должны иметь значения по умолчанию. Результатом вызываемой функции должна быть строка или число. Этот результат будет подставлен вместо callback-тега.

Пример вызова стандартной PHP-функции "strtoupper" :

<? /* тестовый PHP-скрипт : test1.php */
// путь к файлам библиотеки, 
define('INCLUDE_DIR',  'parse/');
// инициализация библиотеки
require_once(INCLUDE_DIR.'init.inc.php');
// инициализация исходной строки
$str = '<callback name=strtoupper>this is a test</callback>';
// вызов функции "parseTag"
echo parseTag($str);
?>

THIS IS A TEST
 

Пример использования функции "MyFunc", определенной разработчиком :

<? /* тестовый PHP-скрипт : test2.php */
// путь к файлам библиотеки, 
define('INCLUDE_DIR',  'parse/');
// инициализация библиотеки
require_once(INCLUDE_DIR.'init.inc.php');
// определение функции, принимающей 1 параметр
function MyFunc($format){ 
	return date($format);
}
// инициализация исходной строки
$str = '
Today is : <callback name=MyFunc>F j, Y, g:i a</callback><BR>
Today is : <callback name=MyFunc>D M j G:i:s</callback>
          ';
// вызов функции "parseTag"
echo parseTag($str);
?>

Today is : September 23, 2002, 1:08 pm
Today is : Mon Sep 23 13:08:08
 

Библиотека может обрабатывать и более сложные callback-теги. Общий вид callback-тега:

<callback {атрибуты_тега} name=имя_функции {атрибуты_тега}>
содержимое_тега
</callback>

<callback name=parseStr>
содержимое_тега
</callback>
<callback name=parseFile>
содержимое_тега
</callback>
<callback name=parseTag>
содержимое_тега
</callback>

Изменить название callback-тега можно двумя способами:

• изменить значения соответствующей константы в файле "const.inc.php":

  // новое название callback-тега
  define('DEFAULT_TAGNAME', 'mytag');

• изменить правила парсинга, вызвав функцию "init":

  // новое название callback-тега
  $new_pars = array('tagorigin' => 'mytag');
  // изменить правила парсинга
  $GlobalParser->init($new_pars);

<mytag {другие атрибуты} name=имя_функции {другие атрибуты}>
содержимое_тега
</mytag>

Разработчик может самостоятельно определить дополнительные функции-обработчики и соответствующие им теги.

В библиотеке уже определены несколько дополнительных функций-обработчиков, которые охватывают наиболее часто встречающиеся ситуации:

• "fileInclude" - возвращает содержимое файла, считанное в строку по заданному имени файла;
• "makeRepeat" - применяет заданную функцию к каждому элементу заданного массива; результат работы функции поэлементно накапливается и возвращается в виде строки после обработки последнего элемента массива;
• "makeBool" - в зависимости от заданной переменной возвращает один из двух возможных результатов.

// список дополнительных функций-обработчиков
$new_pars = array('makeBool', 'makeRepeat', 'fileInclude');
// добавить дополнительные функции-обработчики
$GlobalParser->init($new_pars);

Каждой из описанных функций соответствует свой предопределенный callback-тег.
Рассмотрим каждую из них более подробно.

Функция "fileInclude" обрабатывает callback-тег вида (в квадратных скобках указаны необязательные атрибуты):

<callback 
	    	name=fileInclude 
		[ save=имя_глобальной_переменной ] 
		[ func=имя_функции ]
		[ ffunc=имя_дополнительной_функции ]> 
имя_файла
</callback>

• save=имя_глобальной_переменной
  если этот атрибут указан, то в $GLOBALS [ имя_глобальной_переменной ] будет записан результат работы функции "fileInclude";
• func=имя_функции
  если этот атрибут указан, то к строке, в которую предварительно считано содержимое заданного файла, будет применена заданная этим атрибутом функция;
• ffunc=имя_дополнительной_функции
  если этот атрибут указан, то прежде чем начать работу с файлом, к имени файла будет применена заданная этим атрибутом функция.

<!-- главный обрабатываемый файл "main_file.html" -->
This is the demo how to call "fileInclude" function by "callback"-tag:<BR><BR>
<callback name=fileInclude func=parseTag>included_file.html</callback>
<!--  подключаемый файл "included_file.html" -->
We came here by calling "fileInclude" function <BR>
Today date is <em><callback name=date>F j, Y, g:i a</callback></em>
<? /* тестовый PHP-скрипт : test3.php */
// путь к файлам библиотеки, 
define('INCLUDE_DIR',  'parse/');
// инициализация библиотеки
require_once(INCLUDE_DIR.'init.inc.php');
// инициализация исходной строки с помощью функции "parseFile"
$str = parseFile('main_file.html');
// вызов функции-обработчика "parseTag" в PHP-скрипте 
echo parseTag($str);
?>

This is the demo how to call "fileInclude" function by "callback"-tag:

We came here by calling "fileInclude" function
Today date is September 22, 2002, 11:53 pm
 

Как это работает?
С помощью функции "parseFile" мы считываем содержимое файла "main_file.html" в строку и сохраняем эту строку в переменной $str. Затем начинаем обрабатывать полученную строку с помощью фукнции "parseTag".
Как только функция "parseTag" встречает в тексте callback-тег

<callback name=fileInclude func=parseTag>
included_file.html</callback> 

• included_file.html - имя заданного файла;
• parseTag - функция, которая будет применена к содержимому файла "included_file.html".

Функция "makeRepeat" обрабатывает callback-тег вида (в квадратных скобках указаны необязательные атрибуты):

<callback 
		name=makeRepeat 
		var=имя_переменной 
		[ save=имя_глобальной_переменной ] 
		[ func=имя_функции ]
		[ ffunc=имя_дополнительной_функции ]> 
содержимое_тега
</callback>

• var=имя_переменной (обязательный атрибут)
  имя переменной-массива, который обрабатывается поэлементно;
• save=имя_глобальной_переменной
  если этот атрибут указан, то в $GLOBALS [ имя_глобальной_переменной ] будет записан результат работы функции "makeRepeat";
• func=имя_функции
  если этот атрибут указан, то к содержимому_тега будет применена функция, заданная этим атрибутом, столько раз, сколько элементов содержит массив;
• ffunc=имя_дополнительной_функции
  если этот атрибут указан, то по окончании обработки элементов массива к результирующей строке, в которую накапливались результаты обработки содержимого_тега, будет применена заданная этим атрибутом функция.

<!-- главный обрабатываемый файл "testrepeat_file.html" -->
This is the demo how to call "makeRepeat" function by "callback"-tag:<BR><BR>
<table border=0>
<callback name=makeRepeat var=colors func=parseStr ffunc=parseTag>
<tr><td>This is color <span style="color:<#elem#>"><em><#idx#></em>
</span></td></tr>
</callback>
</table>
<? /* тестовый PHP-скрипт : test4.php */
// путь к файлам библиотеки, 
define('INCLUDE_DIR',  'parse/');
// инициализация библиотеки
require_once(INCLUDE_DIR.'init.inc.php');
// инициализация массива
$colors = array('red' => 'red', 'green' => 'green',
 'blue' => 'blue', 'yellow' => '#ffdd00');
// инициализация исходной строки 
$str = join('', file('testrepeat_file.html'));
// вызов функции-обработчика "parseTag" в PHP-скрипте 
echo parseTag($str);
?>

This is the demo how to call "makeRepeat" function by "callback"-tag:

This color is red

This color is green

This color is blue

This color is yellow

 

Как это работает? Как только функция "parseTag" встречает в тексте callback-тег

<callback name=makeRepeat var=colors func=parseStr ffunc=parseTag>
<tr><td>This is color <span style="color:<#elem#>"><em><#idx#></em>
</span></td></tr>
</callback>

• $colors - имя заданного массива;
• parseStr - функция, которая будет применяться к строке

  <tr><td>This is color <span style="color:<#elem#>"><em><#idx#></em>
  </span></td></tr>

  столько раз, сколько элементов в массиве $colors; причем при каждом вызове функции "parseStr" в переменной $idx будет храниться индекс текущего обрабатываемого элемента массива, а в переменной $elem будет храниться значение текущего обрабатываемого элемента массива, и обе эти переменных можно использовать для замен <#elem#> или <#idx#> в обрабатываемом файле "testrepeat_file.html" (что, собственно, и происходит).
  В начале функции "makeRepeat" определяется переменная возврата $res, которая сначала равна пустой строке, но на каждой итерации в эту переменную добавляется результат работы функции "parseStr" для текущего обработанного элемента массива.
• parseTag - функция, которая будет применена переменной возврата $res по окончании обработки массива.

ПРИМЕЧАНИЕ. С помощью функции "makeRepeat" можно также обрабатывать двумерные массивы, как ассоциативные, так и нумерованные.

Функция "makeBool" обрабатывает callback-тег вида (в квадратных скобках указаны необязательные атрибуты):

<callback 
		name=makeBool 
		var=имя_переменной 
		[ delim=разделитель ] 
		[ type=invert ] 
		[ save=имя_глобальной_переменной ] 
		[ func=имя_функции ]> 
true-часть 
[ разделитель ]
[ false-часть ]
</callback>

• var=имя_переменной (обязательный атрибут)
  имя переменной, которая будет проверена на непустоту;
  true-часть и false-часть - это две альтернативы; только одна из них будет обработана, в зависимости от того, установлен ли атрибут "type", и пуста ли заданная переменная;
  true-часть обрабатывается, если:
  • заданная переменная имеет ненулевое (непустое) значение и атрибут "type" не установлен;
  • заданная переменная пуста, но type=invert;
  в противном случае обрабатывается false-часть;
• delim=разделитель
  если этот атрибут указан, то он должен содержать в качестве разделителя строку; эта строка будет использоваться в качестве разделителя между true- и false-частью; если этот атрибут не установлен, будет использоваться разделитель по умолчанию ( );
• type=invert
  если этот атрибут указан и равен "invert", то вместо проверки на непустоту заданная переменная проверяется на пустоту.
• save=имя_глобальной_переменной
  если этот атрибут указан, то в $GLOBALS [ имя_глобальной_переменной ] будет записан результат работы функции "makeBool";
• func=имя_функции
  если этот атрибут указан, то к обрабатываемой части будет применена функция, заданная этим атрибутом.

Пример вызова функции "makeBool" :

<!-- главный обрабатываемый файл "testbool_file.html" -->
This is the demo how to call "makeBool" function by "callback"-tag:<BR><BR>
The color of the string below depends on $color value. <BR>
If $color is empty, then the string below is
 <em><strong>black</strong></em>.<BR>
Otherwise, the string has the same color that $color value. <BR>
<span style="color:<callback 
				name=makeBool 
				var=color 
				func=parseStr><#color#> black</callback>">
<strong>Test the color</strong>
</span>
<? /* тестовый PHP-скрипт : test5.php */
// путь к файлам библиотеки, 
define('INCLUDE_DIR',  'parse/');
// инициализация библиотеки
require_once(INCLUDE_DIR.'init.inc.php');
// инициализация переменной $color 
// попробуйте поменять значения этой переменной, 
// чтобы увидеть, как изменится цвет тестовой строки
$color = 'magenta';
// инициализация исходной строки 
$str = join('', file('testbool_file.html'));
// вызов функции-обработчика "parseTag" в PHP-скрипте 
echo parseTag($str);
?>

This is the demo how to call "makeBool" function by "callback"-tag:

The color of the string below depends on $color value.
If $color is empty, then the string below is black.
Otherwise, the string has the same color that $color value.
Test the color
 

Как это работает? Как только функция "parseTag" встречает в тексте callback-тег

<callback 
	name=makeBool 
	var=color 
	func=parseStr><#color#> black</callback>