pc.uz
Поиск
Расширенный поиск
РегистрацияЗабыли пароль? Запомнить
Товары Каталог компаний Публикации Объявления События Полезные сервисы Наши вакансии
Суббота, 23 июня 2018 г.
USD: 7883.99   EUR: 9150.95
Версия для печати
2007-03-08 16:44:39

xBB v. 0.24 - PHP-библиотека для работы с BBCode. Часть 4. API

  1. Общие сведения
  2. Список тегов
  3. Быстрый старт
  4. API
  5. Применение CSS
  6. Условия использования и инсталляция

API

Объект класса bbcode может быть инициализирован без параметров:

$bb = new bbcode

Или с параметрами следующих типов:

  1. Строка с тегами BBCode:
    $text 'Строка с тегами [b][i]BBCode[/i][/b].';
    $bb = new bbcode($text); 

  2. Массив с синтаксическим разбором BBCode. Описание этого массива смотрите в описании свойства syntax. Инициализация аналогична:

    $text 'Строка с тегами [b][i]BBCode[/i][/b].';
    $bb1 = new bbcode($text);
    $bb2 = new bbcode($bb1 -> syntax);
    if (
    $bb1 -> get_html() == $bb2 -> get_html()) {
        echo 
    'Один и тот же HTML';

  3. Массив с деревом элементов BBCode. Описание этого массива смотрите в описании свойства tree. Инициализация аналогична:

    $text 'Строка с тегами [b][i]BBCode[/i][/b].';
    $bb1 = new bbcode($text);
    $bb2 = new bbcode($bb1 -> tree);
    if (
    $bb1 -> get_html() == $bb2 -> get_html()) {
        echo 
    'Один и тот же HTML';
Если конструктор класса получает массив, то считает его результатом синтаксического анализа какого-то ББКода и сохраняет в $this -> syntax или в $this -> tree в зависимости от структуры. Если получает непустую строку, то сохраняет ее в $this -> text. По полученному аргументу вычисляет все три свойства.

Свойства класса bbcode

  • tag - имя тега, которому сопоставлен данный экземпляр класса. Или пустая строка, если объект не сопоставлен конкретному тегу. Это свойство может понадобиться вам, если захотите добавить свой тег, или переопределить какой-то из сущуествующих. Более подробные пояснения смотрите ниже.

  • attrib - массив пар
    [имя атрибута] => значение атрибута

    для тега, которому сопоставлен экземпляр класса. Если объект не сопоставлен конкретному тегу, то этот массив пуст. Это свойство может понадобиться вам, если захотите добавить свой тег, или переопределить какой-то из сущуествующих. Более подробные пояснения смотрите ниже.

  • text - текст с обрабатываемым ББКодом. Этот текст ложится сюда при инициализации объекта, и меняется при каждом вызове конструктора класса или метода parse.

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

    /*
    Получаем текст BBCode, парсим его, и результат парсинга сохраняем в файле
    (это в примере. Лучше - в базе данных). Это позволит не парсить один и тот же
    текст дважды.
    */
    $text = isset($_POST['text']) ? $_POST['text'] : '';
    require_once 
    'ваш/путь/bbcode.lib.php';
    $bb = new bbcode($text);
    $fp fopen('./bb_syntax''wb');
    fwrite($fpserialize($bb -> syntax));
    fclose($fp); 

    Теперь, для восстановления исходного BBCode нам понадобится свойство text:

    /*
    Берем из файла (для примера) результат парсинга BBCode, восстанавливаем
    исходный BBCode и выдаем его для редактирования
    */
    $syntax unserialize(file_get_contents('./bb_syntax'));
    require_once 
    'ваш/путь/bbcode.lib.php';
    $bb = new bbcode($syntax);
    echo 
    '<textarea cols="100" rows="30">';
    echo 
    htmlspecialchars($bb -> text);
    echo 
    '</textarea>'

    В следующем примере берем из файла результат парсинга BBCode, генерируем HTML и выводим его на печать:

    $syntax unserialize(file_get_contents('./bb_syntax'));
    require_once 
    'ваш/путь/bbcode.lib.php';
    $bb = new bbcode($syntax);
    echo 
    $bb -> get_html(); 

  • syntax - массив, содержащий синтаксический разбор ББКода. Заполняется при вызове конструктора класса или при вызове метода parse. Имеет следующую структуру:

    Array
    (
        ...
        [i] => Array  // [i] - целочисленный ключ начиная с 0
            (
                [type] => тип элемента: 'text', 'open', 'close' или 'open/close'
                          'text'  - элемент соответствует тексту между тегами
                          'open'  - элемент соответствует открывающему тегу
                          'close' - элемент соответствует закрывающему тегу
                          'open/close' - элемент соответствует закрытому тегу
                                         (например такому: [img="..." /])
                [str]  => строковое представление элемента: текст между тегами
                          или тег (например: '[FONT color=red size=+1]')
                [name] => имя тега. Всегда в нижнем регистре. Например: 'color'.
                          Значение [name] отсутствует для элементов типа 'text'
                          и может быть пустой строкой для элементов типа
                          'close'. В последнем случае элемент будет
                          соответствовать тегу '[/]', который будет считаться
                          закрывающим для последнего незакрытого перед ним.
                [attrib] => Array         // Это значение существует только для
                    (                     // элементов типов 'open' и
                        ...               // 'open/close'
                        ...
                        [имя атрибута] => значение атрибута. Например:
                        ...               [color] => red
                                          Имя атрибута всегда в нижнем регистре.
                                          Значение атрибута может быть пустой
                                          строкой. Имя тега тоже присутствует в
                                          списке атрибутов. Это для того, чтобы
                                          можно было работать, например, с
                                          такими тегами - [color="#555555"]
                    )
                [layout] => Array                 // Это значение несуществует
                    (                             // для элементов типа 'text'.
                        [0] => Array              // Массив содержит пары
                            (                     // ( тип строки , строка )
                                [0] => 0          // Типы могут быть следующие:
                                [1] => [          // 0 - скобка ('[' или ']')
                            )                     // 1 - слэш '/'
                        ...                       // 2 - имя тега
                        [i] => Array              //     (например - 'FONT')
                            (                     // 3 - знак '='
                                [0] => тип строки // 4 - строка из пробельных
                                [1] => строка     //     символов
                            )                     // 5 - кавычка или апостроф,
                        ...                       //     ограничивающая значение
                                                  //     атрибута
                    )                             // 6 - имя атрибута
            )                                     // 7 - значение атрибута
        ...
    )

    Свойство syntax может помочь вам, во-первых, оптимизировать свои скрипты. Пример, как это сделать, смотрите выше. Во-вторых, это свойство будет вам полезно, если захотите реализовать какую-то нестандартную операцию над BBCode. Например, - вырезать все теги.

  • tree - массив, содержащий нормализованное дерево ББКода. Получается из syntax в результате его логического анализа:

    1. syntax преобразовывается в правильную скобочную структуру
    2. Затем преобразовываются в текст все элементы, которым запрещено находиться в данном месте. (Например, теги, вложенные в [nobb])
    3. Одномерный массив преобразуется в дерево.
    Вот структура массива tree:

    Array
    (
        ...
        [i] => Array      i - целочисленный ключ начиная с 0
            (
                [type] => тип элемента. Может иметь только два значения: 'item'
                          и 'text'. В первом случае элемент соответствует
                          какому-то тегу. Во втором случае элемент является
                          строкой текста без тегов.

                [name] => имя тега в нижнем регистре. Например: 'h1'. [name]
                          определен только для элементов типа 'item' и
                          отсутствует для элементов типа 'text'.

                [attrib] => Array         Список значений атрибутов. Определен
                    (                     только для элементов типа 'item' и
                        ...               отсутствует для элементов типа 'text'.
                        ...
                        [имя атрибута] => значение атрибута. Например:
                        ...               [align] => center
                        ...               Имя атрибута всегда в нижнем регистре.
                                          Значение атрибута может быть пустой
                                          строкой. Имя тега тоже присутствует в
                                          списке атрибутов. Это для того, чтобы
                                          можно было работать, например, с
                    )                     такими тегами - [align=right]

                [val] => Array            Дерево подэлементов данного элемента.
                    (                     Существует только для элементов типа
                        ...               'item' и отсутствует для элементов
                        [i] => Array      типа 'text'. Структура полностью
                        ...               идентична структуре свойства
                        ...               $this -> tree.
                    )
                [str] => строка текста без тегов.
                         Напрмер: 'Хорошо живет на свете Виннипух'.
                         [str] существует только для элементов типа 'text' и не
                         существует для элементов типа 'item'.
            )
        ...
    )

    Свойство tree содержит более полный разбор BBCode, чем свойство syntax. Но если из syntax возможно однозначно восстановить исходный текст BBCode, то из tree это, скорее всего, окажется невозможно.

    Вам обязательно понадобится свойство tree, если вы будете создавать свои теги.

  • tags - это свойство - ассоциированный массив пар

    'имя_тега' => имя класса, реализующего соответствующий тег

    Все теги, разрешенные в ББКоде, должны быть представлены в этом массиве. Следующий пример показывает, как можно исключить из обработки какой-либо тег:

    // Обрабатываем текст BBCode без тега [h1]
    $text '[h1]BBCode[/h1] Пишем про [b]ББКод[/b]';
    require_once 
    'ваш/путь/bbcode.lib.php';
    $bb = new bbcode;
    unset(
    $bb -> tags['h1']);
    $bb -> parse($text);
    echo 
    $bb -> get_html(); 

    Процедура добавления тега несколько более сложна. Поэтому будет описана отдельно.

  • children - массив имен тегов, которым разрешено быть вложенными в данный. Если данный объект не сопоставлен какому-либо тегу, то это - массив имен тегов, которым разрешено находиться в корне дерева элементов.

  • mnemonics - массив мнемоник - смайлики и прочие условные обозначения, которые должны заменяться на что-то. Ключ - мнемоника, значение - на что заменяется. Например:

    ':-)' => '<img src="smile.gif" />'

  • autolinks - опция, включающая автоматические ссылки. По умолчанию установлена в true (автоматические ссылки включены). Для отключения ссылок должна быть установлена в false. Пример:

    $text 'Статья про [b]BBCode[/b] - http://www.pc.uz/documents/text/732.html';
    require_once 
    'ваш/путь/bbcode.lib.php';
    $bb = new bbcode($text);
    // Отключаем автоматические ссылки:
    $bb -> autolinks false;
    echo 
    $bb -> get_html() . '<br />';
    // Включаем автоматические ссылки:
    $bb -> autolinks true;
    echo 
    $bb -> get_html(); 

  • is_close - свойство, устанавливающее значение по умолчанию для дочерних классов (тегов), для которых означает следующее:

    • true  - данный тег всегда закрыт (например, - [hr])
    • false - данный тег может не быть закрытым
    Это свойство может понадобится вам при конструировании собственных тегов.

  • lbr - свойство, устанавливающее значение по умолчанию для дочерних классов (тегов), - число переводов строк, которые должны игнорироваться перед тегом. Это свойство может понадобится вам при конструировании собственных тегов. Например, тег [h1] сам по себе создает разрыв перед собой, значит обработчик, должен проигнорировать перед ним один разрыв, поставленный пользователем в исходном коде. Этот факт указан в описании специального класса:

    var $lbr 1
    По умолчанию значение этого свойства установлено в 0.

  • rbr - свойство, устанавливающее значение по умолчанию для дочерних классов (тегов), - число переводов строк, которые должны игнорироваться после тега. Это свойство может понадобится вам при конструировании собственных тегов. Например, тег [h1] сам по себе создает разрыв после себя, равный примерно двум переводам строк, значит обработчик, должен проигнорировать после него два разрыва, поставленных пользователем в исходном коде. Этот факт указан в описании специального класса:

    var $rbr 2
    По умолчанию значение этого свойства установлено в 0.

Методы класса bbcode

  • get_tokens() - Функция парсит текст BBCode (который берет из $this -> text) и возвращает масив пар "число (тип лексемы) - лексема", где типы лексем могут быть следующие:

    1. - открывющая квадратная скобка ("[")
    2. - закрывающая квадратная cкобка ("]")
    3. - двойная кавычка ('"')
    4. - апостроф ("'")
    5. - равенство ("=")
    6. - прямой слэш ("/")
    7. - последовательность пробельных символов (" ", "\t", "\n", "\r", "\0" или "\x0B")
    8. - последовательность прочих символов, не являющаяся именем тега
    9. - имя тега

  • parse(mixed code) - парсер BBCode. Совершает синтаксический разбор BBCode, инициализирует свойства syntax и tree. Необязательный аргумент code может быть строкой с текстом BBCode или массивом типа syntax или массивом типа tree. Если code не указан, то синтаксическому разбору подвергается $this -> text. Пример использования:

    $text 'Строка с тегами [b][i]BBCode[/i][/b].';
    $bb = new bbcode;
    // Парсим $text:
    $bb -> parse($text);
    // Выводим HTML:
    echo $bb -> get_html(); 

  • specialchars(string string) - конвертирует специальные символы в строке string в мнемоники BBCode. Вот таблица трансляции:

    СпецсимволМнемоника
    [@l;
    ]@r;
    "@q;
    '@a;
    @@at;

  • unspecialchars(string string) - конвертирует мнемоники BBCode в строке string в специальные символы. Это - обратная функция для specialchars.

  • must_close_tag(string current, string next) - логическая функция. Проверяет, должен ли тег с именем current закрыться перед началом тега с именем next. Возвращает true, если должен закрыться и false в противном случае.

  • normalize_bracket(array syntax) - превращает массив со структурой как у свойства syntax в правильную скобочную структуру. У возвращаемого массива отсутствует элементы 'layout', но присутствуют элементы 'level', куда пишется уровень вложенности тега.

  • get_tree() - обрабатывает массив $this -> syntax, перезаписывает свойство tree и возвращает дерево элементов.

  • get_syntax(array tree) - конвертит дерево элементов BBCode в массив со структурой свойства syntax и возвращает результат. Необязательный аргумент tree обязан иметь ту же структруру, что и свойство tree. Если аргумент не указан, то обрабатывается $this -> tree.

  • insert_smiles(string text) - обрабатывает строку text: мнемонизирует HTML-код, заменяет разрывы строк на <br />, вставляет смайлики (перечисленные в массиве mnemonics) и "автоматические ссылки" (если опция autolinks установлена в true).

  • highlight() - возвращает подсвеченный BBCode. Пример использования:

    $text 'Строка с тегами [b][i]BBCode[/i][/b].';
    $bb = new bbcode($text);
    // Выводим подсвеченный BBCode:
    echo $bb -> highlight(); 

  • get_html(array elems) - генерирует и возвращает HTML-код. Необязательный аргумент elems обязан иметь ту же структруру, что и свойство tree. Если аргумент не указан, то обрабатывается $this -> tree. Пример использования:

    $text 'Строка с тегами [b][i]BBCode[/i][/b].';
    $bb = new bbcode($text);
    // Выводим HTML:
    echo $bb -> get_html(); 

Как создать тег

Чтобы добавить еще один тег, нужно, во-первых, написать дочерний класс к классу bbcode, реализующий специфику вашего тега, и, во-вторых, добавить имя вашего тега и соответствющего ему класса в массив tags. В следующем общем примере продемонстрировано практически все, что может вам понадобиться при описании нового тега(ов):

/* Класс для тегов [mytag=Имя friends=Друзья]...[mytag] и
   [yourtag=Имя friends=Друзья]...[yourtag] */
class my_bbcode extends bbcode {
    
/* Являются ли теги [mytag] и [yourtag] всегда закрытым
       (наподобие [hr]) */
    
var $is_close false;
    
/* Число разрывов строк, которые должны быть игнорированы перед тегом
       [mytag] или [yourtag] */
    
var $lbr 1;
    
/* Число разрывов строк, которые должны быть игнорированы после тега
       [mytag] или [yourtag] */
    
var $rbr 1;
    
/* Перечисляем теги, открытие которых должно привести к автоматическому
       закрытию тега [mytag] или [yourtag] */
    
var $ends = array('*','td','th','tr');
    
/* Перечисляем теги, которые должны быть автоматически закрыты при открытии
       тега [mytag] или [yourtag] */
    
var $stop = array('a','b','u','s');
    
/* Перечисляем теги, которым разрешено быть вложенными непосредственно в тег
       [mytag] или [yourtag] */
    
var $children = array('b','color','i','u','url');
    
/* Перечисляем теги, непосредственно в которые разрешено вкладывать теги
       [mytag] и [yourtag] */
    
var $parent = array('align','td');
    
/* Разрешено ли использовать теги [mytag] и [yourtag] в корне дерева
       элементов BBCode.
       (Не всем разрешено. Например, тегу [td] запрещено) */
    
var $top_level true;
    
/* Описываем конвертацию в HTML */
    
function get_html() {
        
$result '<p>';
        
/* $this -> tag - имя текущего тега. Всегда доступно.
           $this -> attrib - массив значений атрибутов. Всегда доступен.
           Имеет структуру: 'имя_атрибута' => значение атрибута */
        
if ('mytag' == $this -> tag) {
            
$result .= 'Меня зовут '.$this -> attrib['mytag'].'<br />';
        } else {
            
$result .= 'Тебя зовут '.$this -> attrib['yourtag'].'<br />';
        }
        if (isset(
$this -> attrib['friends'])) {
            
$result .= 'Друзья: '.$this -> attrib['friends'].'<br />';
        }
        
/* parent::get_html($this -> tree) - Возвращает HTML, сгенерированный из
                                             содержимого тега. */
        
$result .= parent::get_html($this -> tree).'</p>';
        return 
$result;
    }

Написав этот класс, можно пользоваться тегами [mytag] и [yourtag]:

$bb = new bbcode;
// Включаем новые теги в список поддерживаемых тегов:
$bb -> tags['mytag'] = 'my_bbcode';
$bb -> tags['yourtag'] = 'my_bbcode';
// Тестируем:
$text 'Пробуем: [mytag=Вася friends="Петя и Коля"]Ура![/mytag]
Вторая проба: [yourtag=Лена]Красота - [b]великая[/b] сила![/yourtag]'
;
$bb -> parse($text);
echo 
$bb -> get_html(); 

Еще несколько замечаний:

  • Свойство is_close указывать необязательно. Оно по умолчанию установлено в false.

  • Свойство lbr указывать необязательно. Оно по умолчанию установлено в 0.

  • Свойство rbr указывать необязательно. Оно по умолчанию установлено в 0.

  • Свойство stop указывать необязательно.

  • Свойство children указывать необязательно. Если оно не указано, то в данный тег можно будет вложить любой тег, который указан в свойстве children родительского класса.

  • Свойство parent указывать необязательно.

  • Свойство top_level указывать необязательно. Если оно неуказано, то вопрос, разрешать ли тегу быть вложенным в корень дерева элементов BBCode, будет зависеть от того, указан ли этот тег в свойстве children объекта родительского класса.

  • Если новый тег включить в список поддерживаемых тегов после того, как был распарсен текст с BBCode, то этот тег не будет обрабатываться.

  • Вы можете не только добавлять собственные теги, но и переопределять умолчальные. Например, если вы хотите переопределить тег [code], то должны написать свой альтернативный класс для этого тега и заменить на него умолчальный:

    $bb = new bbcode;
    // Назначаем тегу [code] свой альтернативный класс my_code:
    $bb -> tags['code'] = 'my_code'

Скачать zip-архив со скриптом, тестами и набором смайликов можно здесь.

Прочитано: 9963 раз(а)  |  Комментариев: 2  |  Средняя оценка (макс. 7): нет (Голосов: 0)
Вы не авторизованы для голосования
xbb
Еще по теме:

Комментарии к статье (2).
2010-05-20 20:39:45, Vitus [админ]:
Гость_Руслан
Это и есть пример ббКОДА??
А вот что бы вставить рисунок в мой текст....
существует ли возможность выбирать рисунок на собственном компьютере и загружать его вам на хостинг.. для того что бы он отобразился в моём этом сообщении.. приэтом указывать его размеры

Статья уже устарела. Все вопросы по bbcode на сайт автора http://xbb.uz
2010-05-19 22:37:28, Гость_Руслан:
Это и есть пример ббКОДА??
А вот что бы вставить рисунок в мой текст....
существует ли возможность выбирать рисунок на собственном компьютере и загружать его вам на хостинг.. для того что бы он отобразился в моём этом сообщении.. приэтом указывать его размеры
В этой теме комментарии отключены.
Регистрация в каталоге Обратная связь Размещение на сайте Приглашаем авторов! О проекте Наши партнеры
Все товары, подлежащие обязательной сертификации, сертифицированы, лицензируемые услуги - лицензированы. © ООО «Norma»; 2018. Все права защищены.
YP
Рейтинг@Mail.ru
Uzinfocom Datacenter
Add engine