White Tiger
WWW Board — система поддержки WWW-конференции

Информация для разработчика

[English version here] [Документация] [Демонстрация] [Тестирование] [Обновление] [Разработка]

Внимание: документ еще не закончен. Его доработка будет производиться постепенно, от версии к версии.

1. Введение
2. Некоторые принципы функционирования
3. Подпрограммы
4. Общие переменные
Приложения
    1. Форматы HTML-файлов форума
    2. Форматы конфигурационных файлов
    3. Сценарий администратора
    4. Использование условных инструкций в шаблонах

1. Введение

Система программной поддержки WWW-конференций White Tiger WWW Board (далее WTBoard) в настоящее время имеет достаточно широкие возможности, чтобы позволить пользователю с определенной степенью гибкости настроить форум. Однако абсолютно все в одной программе реализовать невозможно. Разработчик постепенно добавляет новые функции, но вы можете, не дожидаясь, пока это произойдет (если произойдет вообще), реализовать собственный скрипт, позволяющий достичь необходимого результата. Будем в дальнейшем называть такой скрипт дополнительным модулем (plug-in).
Ниже описываются некоторые принципы функционирования WTBoard, понимание которых необходимо для правильного написания plug-in. Также приведены подпрограммы, доступные для общего использования, описываются параметры их запуска и возвращаемые значения. Разработчик постарается в дальнейших версиях сохранить совместимость API, однако такой гарантии не дает.


2. Некоторые принципы функционирования

Все программные файлы WTBoard реализованы на Perl. Таким образом, для создания plug-in вам нужно иметь некоторые навыки программирования на этом языке, желательно версии 5.003 и выше.

...

Для использования общих подпрограмм WTBoard в вашем скрипте необходим следующий оператор:
require "wtbext.cgi";
Это даст вашему скрипту предписание использовать общий модуль wtbext.cgi и позволит обращаться к подпрограммам WTBoard.
Предварительно можно задать проверку на наличие этого файла и выход при ошибке:
if(!-e"wtbext.cgi"){print "\nError: not found wtbext.cgi";exit}
Для инициализации параметров форума необходим вызов подпрограммы params с параметром 5, то есть:
params(5);
Подпрограмма принимает в качестве входного единственный параметр, определяющий некоторые особенности инициализации. Для плагинов рекомендуется использовать значение 5; 1 используется основным скриптом, 2 — административным, 3 — сервисным, при значении 4 инициализация не производится, только устанавливается номер версии скрипта.
В результате полной отработки подпрограммы производится целый ряд действий, в число которых входят задание параметров форума по умолчанию, определение файлов данных активного форума в многофорумной системе, считывание файла данных <wtboard.txt> и преобразование указанных параметров в соответствующие переменные (различается в зависимости от ключа запуска подпрограммы), создание хешей %inip и %patp, содержащих параметры форума и шаблоны интерфейса соответственно, создание массивов @a и @cks с декодированными и разделенными параметрами командной строки, создание переменных со значениями соответственно командной строке, анализ и задание рабочего шаблона индексной строки, дополнительная обработка некоторых переменных, доступных для дальнейшего использования. В поставку программы входит скрипт wtbdev.cgi, который, будучи установлен наравне с остальными скриптами и запущен, выводит на экран весь спектр переменных (названия и значения), создающихся при запуске params(5). Рекомендуется не использовать для собственных переменных при разработке скриптов имена, совпадающие с организованными в params, если только это не обусловлено спецификой момента.

...

Обязательно проверяйте версию WTBoard. В основном осуществляется (но не гарантируется) обратная совместимость. Совместимость прямая, естественно, даже не ставится целью, WTBoard — слишком динамичная программа для этого.
Проверка версии производится с использованием переменной $internalversion, которая представляет собой четырехзначное число, соответствующее внешней нумерации версий. Так, версия 2.82a имеет значение 2821, 2.82b — 2822, 2.83b — 2831 (так как альфа-версии не было) и т. д. Новые версии выходят с увеличением номера, так что достаточно сравнения $internalversion с наперед заданной вашей переменной.
Внешняя нумерация версий WTBoard хранится в переменной $version. Текущую версию можно узнать из скрипта wtbext.cgi или «холостым» запуском wtboard.cgi.

...

Для обозначения конца строки используйте символ «\n». Это позволит с большей гибкостью применять ваш модуль как под операционными системами класса Unix, так и DOS/Windows. WTBoard оперирует также жестко определенными окончаниями: $cr — последовательность 0D0A (\r\n), $cl — символ 0A (\n) и $crd — символ 0D (\r).

...

Для удобства администрирования вашего плагина воспользуйтесь подпрограммами TITLEADMIN, OPTFIELD, OPTFIELD10, OPT2FIELD, OPTONOFF, OPTSUBMIT, OPTSELECT, SAVEVALUE, VERIFYADMIN, SAVEWRONG. Посредством первых шести довольно просто получается форма в духе стандартной административной формы программы. Пример использования можно взять на сайте (плагин WTCitate). Подробное описание вызова и параметров см. ниже.

...

Можно в параметры настроек пользователя добавить ключи, используемые вашим плагином. Параметры регистрируются в базе совокупностью символов-переключателей. При инициализации форума список параметров помещается в переменную $pars, а также расшифровывается по отдельным переменным, используемым основным скриптом.
Параметры задаются каждый одним символом. Используется несколько принципов — отсутствие параметра разрешает действие, отсутствие параметра запрещает действие, либо переключает с одного варианта на другой. Ситуация по умолчанию — отсутствие параметра.
Для плагинов в переменной $pars символы помещаются после заглавной Z, символы до нее используются самой WTBoard.
Вы можете добавить индивидуальные настройки своего плагина в общую форму индивидуальных настроек, для этого воспользуйтесь externalcall7 и externalcall8, при этом параметр externalcalls нужно поставить в положение on.

...

WTBoard при работе использует много переменных. Изначально не планировалась возможность работы с plug-ins, поэтому какой-то четкой системы наименования переменных нет до сих пор. Вполне может случиться так, что названия некоторых ваших переменных совпадут с внутренними переменными программы, в результате чего возможны непредсказуемые сбои в работе. Поэтому старайтесь именовать значения так, чтобы они гарантированно не пересекались с базовыми. В частности, вы можете добавлять к началу названия каждой переменной уникальный идентификатор, например: wwwpager_lpm_3=0.
Наиболее часто применяются следующие названия: @i, @j, @a, @b, @ini, @s, $s, $s1, $s2, $a, $cs, @cks и т. д. Переменные, объявленные к общему использованию, можно увидеть в результате работы скрипта wtbdev.cgi, поставляющегося в стандартном дистрибутиве.
Рекомендуется использовать хеши %inip, %patp и %inis, содержащие большинство параметров форума. Все они также дублируются в одноименных ключам хеша значениях, но в дальнейшем, возможно, это будет устранено. Перечисленные хеши содержат следующие группы данных:
  • %inip — все неинтерполируемые параметры форума, плюс настройки пользователя, плюс часть внутренних переменных программы, плюс интерполируемые begbody и endbody;
  • %patp — все интерполируемые параметры форума (т. е. шаблоны, определенные в секции [Board Strings]; перед первым использованием значения необходимо произвести его подготовку подпрограммой SUBSTIT (см. ниже);
  • %inis — административный хеш, содержит все параметры форума в неинтерполированном виде; значения из этого хеша используют подпрограммы администрации — OPTFIELD, OPTONOFF, OPTSELECT и т. д., он также должен быть определен при изменении настроек пользователя.



3. Подпрограммы

PARAMS. Вызов: params($caller).
Ключи: $caller — идентификатор вызывающего процесса. При $caller=2 ключи в шаблонах не интерполируются. Для plug-ins в общем случае предназначен $caller=5.
Описание. Подпрограмма считывания и определения всех параметров форума. Список названий и значений переменных для конкретного форума можно получить посредством установки и вызова скрипта wtbdev.cgi (расположение в дистрибутиве docs/wtbdev.cgi).

SUBSTIT. Вызов: substit($value[,$value2]).
Ключи: $value — интерполируемая строка;
$value2 — (необязательный параметр) заменяющая строка.
Описание. Подпрограмма подстановки значений на места ключевых слов, встречающихся в обозначенной строке. Производится интерполяция по всем ключам хеша %inip, оговоренным признаками $ или % (например, "this is sample reference %href text", — если определен $inip{'href'}, то ключ %href заменяется значением $inip{'href'}), а также некоторых дополнительных или динамически определенных переменных.
В случае, если длина $value2 больше нуля, $value заменяется им и интерполируется как описано.

SAVEVALUE. Вызов: savevalue($section,$option,$value).
Ключи: $section — раздел <wtboard.txt>, в котором определен параметр;
$option — наименование параметра;
$value — значение параметра, соответствует значению хеша $inip{$option}.
Описание. Подпрограмма сохранения параметра в файле конфигурации форума <wtboard.txt>. При наличии параметра в конфигурационном файле его значение заменяется новым. Если параметр отсутствует, ищется раздел, заданный переменной $section, и параметр создается в нем. При отсутствии раздела сначала создается он, затем параметр.

SAVECOPYRIGHT. Вызов: savecopyright($begin,$end,$value).
Ключи: $begin — признак начала фрагмента информации об авторских правах, относящегося к данному плагину, рекомендуется что-то вроде <your-plugin>;
$end — признак конца этого фрагмента, рекомендуется что-то вроде </your-plugin>;
$value — сама информация.
Описание. Подпрограмма сохранения информации об авторских правах плагина. Все копирайты плагинов хранятся в параметре copyright в файле настроек <wtboard.txt>. Поэтому необходимо явное указание начала и конца вашего фрагмента копирайта в этом параметре. Для этого рекомендуется использовать тегоподобные идентификаторы, между которыми будет заключаться ваш фрагмент.

VERIFYADMIN. Вызов: $mod=verifyadmin($login,$password).
Ключи: $mod — права доступа администратора;
$login — входное имя администратора;
$password — пароль администратора.
Описание. Подпрограмма верификации администратора с указанными login и password. Сверяет названные данные с учетными записями форума и выдает результат. При отсутствии учетной записи или неверном пароле возвращается -1 ($mod=-1), при полном доступе 0, в остальных случаях устанавливается строковая переменная, содержащая идентификаторы прав доступа администратора. Соответствующие права имеются, если идентификатор определен. Возможны следующие идентификаторы: a — все привилегии;
i — элементы интерфейса;
g — список игнорируемых хостов (игнор-лист), просмотр логов;
h — архивация форума;
e — редактирование файлов форума;
d — удаление сообщений;
n — создание и удаление новостных строк;
s — работа со структурой, восстановление основной страницы.
Единственный идентификатор a заменяет все вышеперечисленные, а также добавляет возможность изменения списка и правд доступа администраторов.

SAVEWRONG. Вызов: savewrong('EVENT',$login,$password,$email,$misc).
Ключи: EVENT — пятибуквенный идентификатор, как-либо обозначающий событие;
$login — имя клиента, при котором произошло событие;
$password — пароль клиента;
$email — адрес электронной почты клиента;
$misc — какая-либо иная информация, необходимая для регистрации.
Описание. Подпрограмма записи критических событий форума в файл <wtwrong.txt>: архивации, регистрации нового участника, неверных паролей участников и администраторов, попыток несанкционированного доступа и т. д.

TITLEADMIN. Вызов: titleadmin('MODE',$login,$stat).
Ключи: MODE — режим администрирования;
$login — имя администратора;
$password — права доступа администратора.
Описание. Подпрограмма вывода шапки административного раздела.

OPTONOFF. Вызов: optonoff('PARAMETER',$title,$desc).
Ключи: PARAMETER — наименование ключа хеша %inis, сопоставленного с параметром, которому присваивается либо значение on, либо значение off;
$title — название параметра;
$desc — описание (комментарий).
Описание. Подпрограмма вывода элемента формы администрирования для определения значения двоичного параметра. Необходимо предварительное задание тега формы и тега таблицы с шестью столбцами.

OPTFIELD. Вызов: optfield('PARAMETER',$title,$desc).
Ключи: PARAMETER — наименование ключа хеша %inis, сопоставленного с параметром;
$title — название параметра;
$desc — описание (комментарий).
Описание. Подпрограмма вывода элемента формы администрирования для определения значения строкового параметра. Задается поле шириной 40 символов. Необходимо предварительное задание тега формы и тега таблицы с шестью столбцами.

OPTFIELD10. Аналогично OPTFIELD, с тем отличием, что отображается поле ввода длиной 10 символов.

OPTFIELD20. Аналогично OPTFIELD, с тем отличием, что отображается поле ввода длиной 20 символов.

OPT2FIELD. Вызов: optfield('PARAMETER1',$title1,'PARAMETER2',$title2,$desc,$length1,$length2).
Ключи: PARAMETER1 — наименование ключа хеша %inis, сопоставленного с первым параметром;
$title1 — название первого параметра;
PARAMETER2 — наименование ключа хеша %inis, сопоставленного со вторым параметром;
$title2 — название второго параметра;
$desc — описание (комментарий);
$length1 — длина поля для первого параметра;
$length12 — длина поля для второго параметра.
Описание. Подпрограмма вывода элемента формы администрирования для определения значений двух строковых параметров. Ширина поля задается для каждого параметра отдельно. Необходимо предварительное задание тега формы и тега таблицы с шестью столбцами.

OPTSELECT. Вызов: optselect('PARAMETER',$title,$desc,$nvalues,$values,$descs).
Ключи: PARAMETER — наименование ключа хеша %inis, сопоставленного с параметром;
$title — название параметра;
$desc — описание (комментарий);
$nvalues — число элементов в списке;
$values — значения элементов;
$descs — описания (названия) элементов.
Описание. Подпрограмма вывода элемента формы администрирования для определения значения параметра, позволяющего выбор из некоторого количества возможных. Представляется в виде выпадающего списка с активным текущим значением. Значения и описания элементов можно задавать массивами. Необходимо предварительное задание тега формы и тега таблицы с шестью столбцами.

OPTSUBMIT. Вызов: optsubmit($login,$password,$oper,$fid,$stringsubmit).
Ключи: $login — имя входа администратора;
$password — пароль администратора;
$oper — предстоящая операция (обычно submit);
$fid — идентификатор форума;
$stringsubmit — отображаемое на кнопке сообщение.
Описание. Предписание отобразить кнопку отправления заполненной формы. Кроме того, указывает определенное число скрытых параметров, интерпретируемых в дальнейшем программой, содержащих параметры входа администратора. Необходимо предварительное задание тега формы.

SHOWNEWS. Вызов: &shownews.
Описание. Подпрограмма вывода новостей и извещений о появлении новых сообщений и ответов. Результат отработки процедуры зависит от глобальных установок форума, а также индивидуальных настроек пользователей. Глобальная переменная $newstype определяет характер выводимой информации:
  • при $newstype=1 выводятся только новостные строки;
  • при $newstype=2 выводятся только уведомления;
  • при $newstype=3 выводятся и новостные строки, и уведомления.
    • По умолчанию $newstype=3.

    VERIFYUSER. Вызов: $ret=verifyuser($title,$notaccess).
    Ключи: $title — строка, выводимая в заголовок html, соответствует второму значению в строке в файле <wtbaccess.txt>;
    $notaccess — объяснение отказа в доступе, соответствует третьему значению в строке в файле <wtbaccess.txt>.
    Описание. Подпрограмма проверки доступа пользователя с одного из запрещенных IP-адресов или с указанным в списке игнорирования cookie. Возвращает -1 при установке мониторинга, -2 при предписании полностью не допускать пользователя. Иначе 0.

    UPDATEUSER. Вызов: &updateuser.
    Описание. Производится обновление пользовательской записи в базе данных форума. Обновляются код времени, адрес электронной почты, IP-адрес и список параметров настройки. Имя, код имени и пароль не затрагиваются. При нулевой длине кода имени подпрограмма обновление не выполняется. Возвращаемых значений нет.

    FILESTP. Вызов: filestp($file) или $ret=filestp($file).
    Ключи: $file — путь к файлу сообщения.
    Описание. Производится разбор указанного файла и запись отождествленных значений в массив @stp согласно приведенной ниже таблице. Если указанное в $file сообщение не существует, возвращается -1.

    DELETEMES. Вызов: deletemes($delref,'on/off').
    Ключи: $delref — номер удаляемого сообщения, без расширения;
    on/off — предписывает удалять или не удалять файл.
    Описание. Подпрограмма удаляет сообщение с указанным номером и все подчиненные ему, правит файлы вышестоящих сообщений, индекс и структуру.
    При значении второго параметра on ссылка на сообщение удаляется из всех вышестоящих сообщений, из основной страницы, после чего удаляется файл. Если второй параметр принимает значение off либо не определен, удаляется только ссылка на файл с основной страницы и из структуры. Восстановление форума с потерей структуры восстановит ссылку на сообщение.
    ВНИМАНИЕ! Возможна некорректная работа данной подпрограммы, поэтому не забывайте проверить основную страницу форума после удаления сообщения.


    4. Общие переменные

    Полный список доступных для использования переменных скрипта, определяемых при запуске params, можно получить посредством скрипта wtbdev.cgi.
    Ниже даны комментарии к некоторым переменным.

    Версия.
    $version — символьное обозначение версии;
    $internalversion — численное обозначение версии. Рекомендуется, чтобы модуль проверял версию программы перед выполнением. Во всех ранних (до 2.451b) выпусках WTBoard эти две переменные не определены. В дальнейших версиях значение будет увеличиваться.

    Время.
    $curtime — время вызова скрипта, преобразованное из значений массива @t согласно формуле second+(minute+(hour+(day+(month+year*12)*32)*24)*60)*60. Все внутренние временные интервалы скрипта имеют подобное представление. Для преобразования дат служат подпрограммы COUNTS, EXTRTIME, PACKTIME.
    $utimes — код времени, соответствующий последнему посещению участником форума (обновляется в базе посредством подпрограммы UPDATEUSER).
    @t — временной массив текущего момента. Расклад следующий: [0] секунды, [1] минуты, [2] часы, [3] дни, [4] месяцы, [5] годы. Значение месяца ($t[4]) всегда на единицу меньше реального, это необходимо учитывать при подстановке. Год приводится в состояние полного летоисчисления.

    Администрирование.
    $login — входное имя администратора;
    $pass — пароль администратора;
    $stat — права доступа администратора.

    Пользователи.
    $utimes — см. выше.

    Внутренние переключатели.
    $newstype: 1 — показывать только новости, 2 — показывать только извещения о новых сообщениях и ответах, 3 — показывать и новости, и извещения. По умолчанию newstype=3.
    $formdata — определяет способ формирования данных при отправлении сообщения. 1 — x-www-url-encoded, 2 — multipart/form-data. По умолчанию formdata=1.
    $setlogin — переключатель установки полей для имени и пароля в форме создания сообщения. 1 — установить, 0 — не устанавливать. По умолчанию setlogin=1.
    $xsetlogin — строка, в соответствии с которой выводятся элементы формы «Имя» и «Пароль». Структуру см. в wtboard.cgi.
    $setemail — переключатель установки полей для адреса e-mail и чекбокса «Поместить в корень» в форме создания сообщения. 1 — установить, 0 — не устанавливать. По умолчанию setemail=1.
    $xsetemail — строка, в соответствии с которой выводятся элементы формы «E-mail» и «Поместить в корень». Структуру см. в wtboard.cgi.
    $setsubj — переключатель установки поля для темы в форме создания сообщения. 1 — установить, 0 — не устанавливать. По умолчанию setsubj=1.
    $xsetsubj — строка, в соответствии с которой выводится элемент формы «Тема». Структуру см. в wtboard.cgi.
    $cksdefined — флаг существования массива данных @cks. Сразу после определения массива устанавливается в значение 1. Если $cksdfeined истина, то подпрограмма params() завершается сразу. Таким образом, устраняется вероятность многократного вызова подпрограммы params() при отработке плагинов и, соответственно, ускоряется работа системы.

    Строки.
    @stp — массив значений, полученных в результате синтаксического анализа строки индекса и сопоставляемых ключам в параметре string при генерации строки индекса. Сопоставляется по идентификаторам с массивом @tag. При вызове подпрограммы filestp массив @stp определяется исходя из содержания соответствующего файла. В таблице показаны значения ключей, их соответствие массиву @tag и заполнение при вызове соответствующих программ. Обозначения: «+» — заполняется в обязательном порядке, «*» — заполняется при наличии соответственного ключа в параметре string, «-» — не заполняется, «?» — может быть не определено.

    ОписаниеСоответстующий
    ключ в @tag    		stringfilestp
    0Путь к сообщению через браузер (dirkonf/file.ext)$href*+
    1Тема сообщения$subj*+
    2Имя автора$name*+
    3Имя автора, заключенное в ссылку на адрес e-mail$nemail??
    4Час генерации формы$fhour*+
    5Час приема сообщения на сервере$shour++
    6Минута генерации формы$fmin*+
    7Минута приема сообщения на сервере$smin++
    8Секунда генерации формы$fsec*+
    9Секунда приема сообщения на сервере$ssec++
    10День недели генерации формы (слово)$fweek*+
    11День недели приема сообщения на сервере (слово)$sweek++
    12Число генерации формы$fday*+
    13Число приема сообщения на сервере$sday++
    14Месяц генерации формы$fmonth*+
    15Месяц приема сообщения на сервере$smonth++
    16Месяц генерации формы (название)$fwmonth*+
    17Месяц приема сообщения на сервере (название)$swmonth++
    18Двухсимвольное обозначение года$year++
    19Четырехсимвольное обозначение года$fullyear++
    20Количество ответов на сообщение$answers++
    21Метка новизны сообщения (если сообщение было помечено как новое)$new?-
    22Размер сообщения$length*+
    23Время создания сообщения, приведенное в соответствие с внутренним форматом времени скрипта$fxdata++
    24Содержимое сообщения (форматированный текст)$fxbody*+
    25Ссылка URL в сообщении$fxurl??
    26Название ссылки URL в сообщении$fxturl??
    27Ссылка на картинку в сообщении$fximg??
    28Имя файла сообщения, на которое текущее является ответомнет-?
    29Тема сообщения, на которое текущее является ответомнет-?
    30Имя автора сообщения, на которое текущее является ответомнет-?
    31Имя и адрес автора сообщения, на которое текущее является ответомнет-?
    32Час создания сообщения, на которое текущее является ответомнет-?
    33Минута создания сообщения, на которое текущее является ответомнет-?
    34Секунда создания сообщения, на которое текущее является ответомнет-?
    35Число создания сообщения, на которое текущее является ответомнет-?
    36Месяц создания сообщения, на которое текущее является ответомнет-?
    37Год создания сообщения, на которое текущее является ответомнет-?
    38Номер сообщения$number++
    39Дерево ответов на сообщение в формате структурынет-?
    40Список номеров вышестоящих сообщений, разделенных символом ;нет-?
    41Название файла сообщения$fxfile++
    42Физический путь к файлу сообщения (dirrealkonf/file.ext)нет++
    43Город, указанный автором сообщения$fxcity?-

     




    Приложения

    1. Форматы HTML-файлов форума

    Работа скриптов отчасти основана на строго определенном формате динамических и генерируемых html-файлов форума — это файл основной страницы (index.shtml) и файлы, содержащие сообщения.
    Поскольку при отработке некоторых процедур скрипты берут определенные строки файлов, не верифицируя их, неверный формат может пагубно отразиться на функционировании форума. Если ваш plug-in предусматривает перезапись динамических файлов, то он должен придерживаться изложенных ниже форматов.

    Основная страница (по умолчанию index.shtml) 

    --------------------------------------
{begindex}
<ul>
<!--home-->
<!--XXX--><li>{string}
<ul><!--XXX--><li>{string}
</ul>
<ul><!--XXX--><li>{string}
<ul><!--XXX--><li>{string}
</ul>
</ul>
{endindex}
--------------------------------------
    Соответственно ключевым словам, помещенным в фигурные скобки, подставляются интерполированные параметры, определенные в конфигурации форума. XXX — число, идентичное номеру сообщения, которое соответствует данной строке. Строка индекса занимает одну или две строки кода. В случае, если это корневое сообщение, оно определяется одной строкой. Подчиненное сообщение (ответ) структуризуется признаком списка (<ul>) в начале строки, по которому его можно идентифицировать. Следующей (второй) строкой идет закрытие списка, в результате чего список выравнивается. Первоначально обе строки ответа располагаются подряд. В дальнейшем их может разделять до нескольких десятков и даже сотен строк подчиненных сообщений. В результате рендеринга такого html-кода получается довольно логичное дерево сообщений и ответов на них.

    Корневое сообщение (номер XXX) 

    --------------------------------------
{begmes}

Отправлено <b><a href="mailto:{email}">{realn}</a></b> <i>{hh}:{mm}:{ss} {dd}/{mm}/{yyyy}</i>:<p><div align=justify>
<dd>
{body}
<p>{separator}
<p><!--{prev}/{time}/{weekday}/{length}--><a name=ans>Ответы и комментарии:</a><p>
</div><div align=left>
<ul>
<!--home-->
<!--XXX-->
<!--end-->
</ul>
<!--homeend-->
{endmes}
--------------------------------------
    Если адрес электронной почты не определен, то ссылка не ставится.
    Формат даты в сообщении строго фиксирован. В дальнейшем он используется при восстановлениях основной страницы.
    Фрагменты «Отправлено <b>» и «Ответы и комментарии:» соответствуют пятнадцатой и восемнадцатой строкам из файла ресурсов (<wtblang.txt>). При наличии файла ресурсов для другого языка строки, разумеется, будут иными.
    Скрытыми параметрами сообщения являются следующие технические ключи, используемые скриптом для получения о сообщении дополнительной информации:
    • {prev} — список номеров вышестоящих сообщений, разделенных символом «;»;
    • {time} — дата и время создания сообщения на сервере во внутреннем формате времени скрипта;
    • {weekday} — номер дня недели, в который сообщение было создано;
    • {length} — длина полезной части посылаемого сообщения, за исключением цитируемого текста и шаблонов.
    Фрагмент после <!--XXX--> предназначен для регистрации ответов на данное сообщение.

    Ответное сообщение (номер XXX) 

    --------------------------------------
{begmes}

Отправлено <b><a href="mailto:{email}">{realn}</a></b> <i>{hh}:{mm}:{ss} {dd}/{mm}/{yyyy}</i>
<div align=left>в ответ на: <a href={prevXXX}>{prevsubj}</a>, отправлено <b><a href="mailto:{prevemail}">{prevrealn}</a></b> <i>{hh}:{mm}:{ss} {dd}/{mm}/{yyyy}</i>:<p><div align=justify>
<dd>
{body}
<p>{separator}
<p><!--{prev}/{time}/{weekday}/{length}--><a name=ans>Ответы и комментарии:</a><p>
</div><div align=left>
<ul>
<!--home-->
<!--XXX-->
<!--end-->
</ul>
<!--homeend-->
{endmes}
--------------------------------------
    Все замечания относительно корневого сообщения справедливы. Кроме того, фрагменты «в ответ на: » и «отправлено <b>» соответствуют шестнадцатой и девятнадцатой строкам файла ресурсов.


    2. Форматы конфигурационных файлов

    Формат конфигурационных файлов имеет важное значение для исправной работы форума, что уже неоднократно было подтверждено за годы работы. Небольшие, но некорректные изменения могут вообще привести к краху форума. Его достаточно легко восстановить, однако это все равно неприятно. Поэтому необходимо как можно более тщательно проверять вносимые изменения. Или изменять только совсем уж очевидные вещи.
    Программа выполнена с упором на максимально простой способ изменения вида форума. От версии к версии код отлаживается и вычищается, расширяются возможности конфигурирования, совершенствуется синтаксис генерируемого HTML-кода. В этом немаловажная роль принадлежит конфигурационным файлам.

    wtbaccess.txt
    Начиная с версии 2.933b файл не несет смысловой нагрузки в связи с перенесением его функций в базу участников wtbnames.txt.* и оставлен для обеспечения совместимости.

    wtbadmin.txt
    Список администраторов и права их доступа к административной секции. Состоит из некоторого количества строк, каждая из которых определяет одного администратора. Значения в строке разделяются двойным знаком «точка с запятой» — ;;, строка заканчивается таким же знаком. Первое значение — имя администратора, второе — его пароль. Третье значение — список прав доступа (полное описание стандартных ключей доступа см. на административной странице). Вы можете назначить вашему плагину дополнительный ключ разрешения администрации, либо использовать уже существующие. Список прав доступа возвращается подпрограммой VERIFYADMIN.

    wtbini.txt
    Файл, содержащий названия конфигурационных файлов форума. Состоит из некоторого количества строк, каждая из которых определяет названия файлов для одного форума. Значения в строке разделяются знаком «точка с запятой» — ;, строка заканчивается таким же знаком. Первое значение в списке — идентификатор форума (соответствует в прочих местах ключу $fid). Их число не ограничено. Рекомендуется применять численный идентификатор, хотя это несущественно. Указание идентификатора, совпадающего с какими-то иными ключами программы, передающимися посредством браузера, может привести к непредсказуемым последствиям. При отсутствии идентификатора используется значение 0.
    Второе, третье, четвертое и т. д. значения определяют названия конфигурационных файлов форума в соедующей последовательности:
    wtbaccess.txt, wtbadmin.txt, wtblang.txt, wtblast.txt, wtbnames.txt,
    wtbnews.txt, wtboard.txt, wtbreplace.txt, wtbstruct.txt, wtwrong.txt

    wtblang.txt
    Языковой модуль программы. Большинство текстовых конструкций, используемых при работе, берутся из него. Исключение составляют только те значения, что определены в файлах wtboard.txt и wtbaccess.txt. Состоит из некоторого количества строчек, которые при запуске программы считываются в массив @lng. В нужных местах выводятся соответствующие элементы массива.
    Строки 301-400 зарезервированы для контекстных подсказок.

    wtblast.txt
    Файл, определяющий нумерацию сообщений. Содержит два значения. Первое (без идентификатора) соответствует номеру последнего сгенерированного файла. При генерации сообщения это значение считывается, проверяется на соответствие, после чего увеличивается на единицу и записывается в файл поверх старого.
    Второе значение идентифицируется ключом arc и соответствует дате последней проверки форума на достижение критериев автоархивации. Обычно обновляется раз в сутки.

    wtbnames.txt.*
    База участников wtbnames.txt.* хранится в формате базы данных SDBM и представляет собой пару файлов — wtbnames.txt.dir и wtbnames.txt.pag. Это позволяет плагину определить какие-то дополнительные ключи для каждого конкретного пользователя, используя идентификатор NAME. Однако следует иметь в виду, что общая длина пары ключ—значение не должна превышать 1000 символов. Это ограничение налагается форматом базы данных.
    База участников открывается при инициализации форума в хеш %wtbuser и остается открытой до конца отработки скрипта. Любое изменение значения хеша немедленно отражается в базе, поэтому при работе непосредственно с базой рекомендуется использовать временные промежуточные переменные.
    Любые операции, связанные с редактированием данных участников, рекомендуется проводить с помощью административного скрипта.

    wtbnews.txt
    Файл, содержащий новостные строки. Формат файла:
    yearb;;monthb;;dayb;;hourb;;minb;;yeare;;monthe;;daye;;houre;;mine;;message;;
    Переменные *b соответствуют времени, определяющему начало демонстрации новостной строки, переменные *e определяют последний срок. Даты записываются в формате, понятном пользователю. Значение message состоит обычно не только из самого сообщения, но также из частей HTML-кода, форматирующих его отображение в браузере.

    wtboard.txt
    Файл основных настроек форума. Важнейший элемент программы, неверные параметры, указанные в нем, могут привести к неисправностям в работе.
    Файл состоит из нескольких секций:
  • [Board Options] — общие параметры.
  • [Service Options] — некоторые опции сервисных функций.
  • [Form Options] — значения, определяющие размеры полей в формах ввода сообщений.
  • [Board Colors] — значения цветов форума.
  • [Board Strings] — шаблоны HTML-контента форума.
  • [Archives Section] — раздел для записи названий каталогов архивов.
  • [Plugin Options] — раздел для хранения параметров дополнительных модулей.
    Добавление и изменение значений параметров производится подпрограммой SAVEVALUE.
    При инициализации подпрограммой PARAMS производится считывание файла и создание хешей %inip (содержащего все параметры форума, кроме секции [Board Strings]) и %patp (содержащего шаблоны из секции [Board Strings]), затем соответствующих переменных (для совместимости с предыдущими версиями), содержащих те же значения. Вызов params(2) создает также хеш %inis, содержащий все параметры форума в неинтерполированном виде, что необходимо при администрировании.

    wtbreplace.txt — файл со списком контекстной замены.
    В файле <wtbreplace.txt> определяется список контекстной замены. Используется следующий формат строк:
    xxx;;yyy
    или
    KKxxx;;yyy
    где KK — управляющие символы замены (не более трех), xxx — строка, подлежащая замене, yyy — заменяющая строка.
    Управление заменой производится с помощью нескольких специальных символов: # @ * ; % ! < > \. Их предназначение в следующем:
    #   предписывает производить замену только в заголовке (теме) сообщений;
    @   предписывает производить замену только в теле сообщения;
    *   предписывает производить замену и в теле сообщения, и в заголовке (значение по умолчанию, подразумевается при отсутствии всяких ключей);
    ;   строка комментария;
    %   рекомендует рассматривать шаблон поиска как регулярное выражение, по умолчанию отключен;
    !   позволяет участнику форума отключить данный элемент контекстной замены для своих сообщений;
    <   предписывает производить замену только при генерации формы ответа в цитируемом тексте;
    >   предписывает производить замену только при приеме сообщения на сервере;
    \   применим в первой позиции в том случае, если нужно заменять фрагмент, содержащий один из перечисленных спецсимволов.
    Управляющих символов может быть не более пяти, например: #%>XXX;;YYY — производить замену XXX на YYY только в заголовках только при приеме сообщения на сервере, рассматривая XXX как регулярное выражение; \*ONE;;+TWO — всегда заменять *ONE на +TWO. При этом символы #, @ и *, если они есть, должны быть в начале, % следует после них, направление замены < и > указывается в последнюю очередь.

    wtbstruct.txt — файл со структурой сообщений форума.

    wtwrong.txt — файл для записи критических событий форума.


    3. Сценарий администратора

    Для более удобного редактирования конфигурации подключаемых модулей рекомендуется применять доступные в wtbext.cgi подпрограммы. Подробнее детали создания формы описаны выше. Кроме того, WTBoard с версии 2.933b поддерживает сценарий администратора — фрагмент кода скрипта модуля, рассматриваемый перлом как комментарий, но понимаемый административной частью программы как определенные директивы. Рекомендуется использовать эту возможность, чтобы облегчить администратору вызов режима администрирования скрипта.
    В общем виде сценарий выглядит следующим образом:
    # admin.section begin
    # admin.requireversion={internalversion}
    # admin.skip={module_parameter}
    # admin.name={Module Name}
    # admin.version={version}
    # admin.description={Description}
    # admin.administrator={login}
    # admin.password={password}
    # admin.operation={operation}
    # admin.section end
    Порядок и синтаксис строк должен быть именно в таком порядке. Необязательный параметр — # admin.skip={module_parameter}, его наличие предписывает пропустить дальнейшие строки секции. В качестве «module_parameter» используется название любого параметра, если значение параметра определено, то секция пропускается. Это хорошо использовать для определения того факта, был уже установлен данный модуль или нет.
    Команды подразумевают следующее:
    admin.section begin — носит чисто комментарный характер;
    admin.requireversion — сравнивает указанное значение с внутренней переменной скрипта $internalversion, если последняя меньше, то секция пропускается;
    admin.skip — рассмотрен чуть выше;
    admin.name — название модуля;
    admin.version — версия модуля;
    admin.description — описание действия модуля в этой секции;
    admin.administrator — название ключа, который модуль использует для авторизации администратора при входе в конфигурацию; это не само имя администратора;
    admin.password — название пароля, который модуль проверяет при авторизации; это не сам пароль;
    admin.operation — название операции, которую предусматривает данная секция;
    admin.section end — конец сценария, при обнаружении этой команды скрипт прекращает сканирование файла.
    Если модуль предусматривает несколько режимов администрации, их следует располагать друг за другом, соблюдая порядок команд.
    Идентификатор форума, имя и пароль администратора подставляются автоматически соответственно введенным при входе в администрацию, поэтому команды admin.administrator и admin.password подразумевают названия ключей.
    Ниже приведен пример сценария, позволяющего включить в форму администрирования коды, выполняющие вызовы, аналогичные следующему:
    http://www.host.com/cgi-bin/wtbcitate.cgi?fid=0&administrator=LOGIN&pass=PASS
    и следующему
    http://www.host.com/cgi-bin/wtbcitate.cgi?fid=0&administrator=LOGIN&pass=PASS&oper=setup
    Пример сценария:
    # admin.section begin; начало
    # admin.requireversion={2933}; минимально требуемая версия
    # admin.skip={citate_file}; если в wtboard.txt определен параметр citate_file, перейти к NEXT
    # admin.name={White Tiger Citate}; название модуля
    # admin.version={1.21a}; версия модуля
    # admin.description={Установка модуля цитат}; описание режима
    # admin.administrator={administrator}; название ключа имени
    # admin.password={pass}; название ключа пароля
    # admin.operation={setup}; название режима
    # admin.requireversion={2933}; NEXT, следующая секция, переходит сюда
    # admin.name={White Tiger Citate}; название модуля
    # admin.version={1.21a}; версия модуля
    # admin.description={Настройка модуля цитат}; название режима
    # admin.administrator={administrator}; название ключа имени
    # admin.password={pass}; название ключа пароля
    # admin.operation={}; название операции, ставится как значение ключа oper (может быть пустым!)
    # admin.section end; конец сценария



    4. Использование условных инструкций в шаблонах

    WTBoard поддерживает условные инструкции в шаблонах, определяемых в секции [Board Strings], а также в параметрах $begbody, $endbody. Синтаксис весьма прост:
    %key{value}key%
    Если значение $inip{key} определено и не равно нулю, value выносится за скобки и интерполируется обычным образом в составе шаблона. В противном случае вся инструкция удаляется. Зеркальное завершение инструкции сделано для возможности использования вложенных условий.
    Возможно противоположное действие:
    %REVERSEkey{value}key%
    Если значение $inip{key} не определено или равно нулю, value выносится за скобки и интерполируется обычным образом в составе шаблона. В противном случае вся инструкция удаляется.
    Предусмотрены также следующие специальные инструкции, обрабатываемые в первую очередь:

      %file{filename}file% — вставить содержимое указанного файла.
    Условные инструкции проверяются по всем шаблонам секции [Board Strings] (т. е. хешу %patp) до интерполяции ключей. Поэтому если, например, в каком-либо файле, вставляемом посредством инструкции, указаны стандартные ключи WTBoard, они также будут интерполированы в обычном порядке.

    назад

    Файл создан 28 октября 1999 года. Последний раз дополнялся 15 сентября 2000 года.
    Copyright © 1998-2002, White Tiger.