Callback-теги

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

содержимое_тега

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

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

/* тестовый PHP-скрипт : test1.php */

// путь к файлам библиотеки,

define('INCLUDE_DIR',  'parse/');

// инициализация библиотеки

require_once(INCLUDE_DIR.'init.inc.php');

// инициализация исходной строки

$str = 'strtoupper>this is a test';

// вызов функции "parseTag"

echo parseTag($str);

?>

Результат работы функции "parseTag" :

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 : MyFunc>F j, Y, g:i a

Today is : MyFunc>D M j G:i:s

          ';

// вызов функции "parseTag"

echo parseTag($str);

?>

Результат работы функции "parseTag" :

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

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

имя_функции {атрибуты_тега}>

содержимое_тега

Единственным обязательным атрибутом является атрибут "name", остальные атрибуты необязательны и зависят от определения самой функции. Стандартными функциями-обработчиками считаются функции "parseStr", "parseFile" и "parseTag". Это означает, что допускается использование тегов вида :

parseStr>

содержимое_тега

parseFile>

содержимое_тега

parseTag>

содержимое_тега

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

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

·         // новое название callback-тега

define('DEFAULT_TAGNAME', 'mytag');

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

·         // новое название callback-тега

·         $new_pars = array('tagorigin' => 'mytag');

·          

·         // изменить правила парсинга

$GlobalParser->init($new_pars);

Теперь библиотека будет обрабатывать callback-теги вида :

содержимое_тега

ПРИМЕЧАНИЕ. Название тега - case-insensitive, имена и значения атрибутов тега - case-sensitive.

Дополнительные функции-обработчики

Наверх

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

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

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

Чтобы воспользоваться этими функциями, необходимо подключить их в качестве дополнительных функций-обработчиков :

// список дополнительных функций-обработчиков

$new_pars = array('makeBool', 'makeRepeat', 'fileInclude');

// добавить дополнительные функции-обработчики

$GlobalParser->init($new_pars);

ПРИМЕЧАНИЕ: По умолчанию все эти уже функции подключены в файле "init.inc.php".

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

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

                name=fileInclude

               [ save=имя_глобальной_переменной ]

               [ func=имя_функции ]

               [ ffunc=имя_дополнительной_функции ]>

имя_файла

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

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

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

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

included_file.html

We came here by calling "fileInclude" function

Today date is F j, Y, g:i a

/* тестовый 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);

?>

Результат работы функции "parseTag" :

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-тег

included_file.html

тут же вызывается функция "fileInclude", где

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

С помощью функции "fileInclude" содержимое файла "included_file.html" считывается в строку, и к этой строке применяется функция "parseTag". Строка, полученная в результате, подставляется вместо callback-тега.

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

               name=makeRepeat

               var=имя_переменной

               [ save=имя_глобальной_переменной ]

               [ func=имя_функции ]

               [ ffunc=имя_дополнительной_функции ]>

содержимое_тега

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

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

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

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

/* тестовый 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);

?>

Результат работы функции "parseTag" :

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

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