WTG Zebra 1.00. Руководство по API.
Содержание раздела:
1. API Zebra
2. Формат файлов резерва
2.1. Общий формат файлов резерва
2.2. Формат файлов дампа АС
2.3. Формат файлов резерва форумов
Encyclopaedia Zebra
(4676312) Добавление кодовых страниц
(3467848) Календарь
(2G6HJ1J) Дополнительные индивидуальные свойства постеров в Zebra Forum
(A1VE7Y1) Использование подпрограммы выборки постеров форумов
Zebra имеет достаточно гибкое и расширяемое
API (application programming interface), что позволяет осуществить многие,
порой весьма хитрые вещи, не реализованные в самой Zebra, за счет настройки
параметров либо подключения внешних модулей, разработанных или
адаптированных для Zebra. Так, за счет тесного взаимодействия с ядром работают
Zebra Site (интеграция которого очень сильна, поскольку он является практически
обязательным модулем), Zebra Forum (функционирование которого целиком выстроено
на использовании предоставляемых Zebra возможностей).
1. API Zebra
API комплекса WTG Zebra реализуется
процедурами, вынесенными в несколько оверлейных модулей, сообразуясь с частотой
и необходимостью их использования. Например, процедуры, практически
гарантированно вызываемые при каждом запуске Zebra, находятся в модуле
zx0.cgi; другие, не требуемые для каждого вызова, определены
в модуле
zx1.cgi. Кроме того, часть процедур вынесена в библиотеку
Zebra.pm, стандартно подключаемой к компонентам при инициализации
Zebra.
2. Формат файлов резерва
В Zebra для резервного хранения баз или портирования информации
на другой сайт применяются обычные текстовые файлы, в которые в определенном формате
сохраняются записи баз Zebra. Применяются три формата:
общий формат файлов резерва,
дамп базы АС;
файл резерва форумов.
Ниже будут приведены описания каждого формата.
2.1. Общий формат файлов резерва
В самом начале файла идет техническая необязательная информация для
административной части. Она отмечена символом «точка с запятой»,
начиная с первой позиции строки. Например:
; Zebra (C) XXI, White Tiger Group
; Web: http://www.wtg.ru
; Zebra ini file. For join to the base rename this file into zauto.inc,
; put into your data-directory and run Zebra Administration
; Version 0.12 (0126)
; Date: Thu Dec 5 22:22:22 2002
;
; description=Zebra main configuration
; requiredversion=0126
; end
Здесь
Version указание версии, с помощью которой был сгенерирован
данный файл резерва;
Date дата генерации файла;
description
описание файла резерва, которое будет отображаться в административной части в
разделе
«Резервирование и обновление»;
requiredversion требование к минимальной версии, в которой должен
обрабатываться данный файл резерва при подключении (требование может быть завышенным,
поскольку совместимость файлов резерва с ранними версиями Zebra достаточно высока).
Наличие строки
; requiredversion=XXXX обязательно, по ней определяется
принадлежность данного текстового файла к текстовым файлам резерва Zebra первого типа.
Далее начинаются собственно записи. Они разделены на блоки. Блок
начинается записью типа:
[X:YYYYYYYY]
Что обозначает, что дальше идут записи, наименования которых
начинаются с буквы
X, а пишутся они в базу типа
YYYYYYYY. Например:
[1:dan1forum]
Значит, все последующие ключи этого блока будут записываться в базу
zUSERKEYdan1forum.db, и в начало названий ключей будет приписываться
1. Обратите внимание, что запись может выглядеть и так:
[XXXXXXXX:YYYYYYYY]
Тогда во внимание берется только первый символ фрагмента
XXXXXXXX, в
то время как
YYYYYYYYY обрабатывается полностью.
Еще один пример, из файла zebra.ini
[_:ini]
_descdb_dan1forum=Zebra Forum index
_descdb_dan3forum=Zebra Forum bodies
_descdb_ini=Zebra main configuration
_alocales=Русский%%%English
[I:ini]
en_profile_blue=Blue
en_profile_gray=Gray
en_profile_green=Green
В результате в базу
zUSERKEYini.db будут записаны следующие ключи:
__descdb_dan1forum со значением
Zebra Forum index,
__descdb_dan3forum со значением
Zebra Forum bodies,
__descdb_ini со значением
Zebra main configuration,
__alocales с двумя значениями, разделенными нулевым
символом:
Русский и
English,
ien_profile_blue со значением
Blue,
ien_profile_gray со значением
Gray,
ien_profile_green со значением
Green.
Если база
zUSERKEYini.db на момент такой записи отсутствует, она
будет создана.
Последовательность
%%% преобразуется в нулевой символ. Если где-то
встречается
% в качестве обязательного
знака, и при этом возможно появление последоваетельности
%%%%, то не подлежащий
преобразованию символ отбивается обратным слэшем:
\%.
По умолчанию осуществляется
дополнение базы, то есть, если запись
ien_profile_blue уже существует в базе, она останется нетронутой, но если
она отсутствует, то добавляется. На это поведение могут влиять модификаторы.
Определены модификаторы, которые могут стоять в первой позиции строки записи.
Рассмотрим на примерах.
+en_profile_blue=Cyan (запись безусловно заменяется новой)
*en_profile_blue=Cyan (запись дополняется новым значением, если оно
отсутствует в списке, перечисленном с разделителем нулевым значением)
/en_profile_blue=Cyan (из списка значений удаляется указанное,
разделитель нулевой символ)
+en_profile_blue= (пустое значение в таком случае запись просто удаляется)
# (в первой или второй позиции строки строка игнорируется)
Есть также глобальные инструкции, чье поведение действует с момента
их обнаружения в файле резерва:
__replace, заменять все необозначенные особо значения;
если значение предварено
* или
/, оно обрабатывается согласно действию
модификаторов, отсутствие модификатора в таком случае равнозначно
+;
__noreplace, отменяет действие модификатора
__replace;
__action, предписывает запустить процедуру из внешней библиотеки;
__end, дальнейшая обработка файла резерва прерывается.
Запись стандартно занимает одну строку. Однако в некоторых случаях это может оказаться
неудобным. Поэтому предусмотрен альтернативный вариант задания записи:
_identificator={
блок тело записи, состоящий
из неограниченного количества строк
}_identificator
Если в блоке записи встречаются строки, в первой или второй позиции которых находится
символ
#, такие строки игнорируются.
2.2. Формат файлов дампа АС
2.3. Формат файла резерва форумов
Форумы являются одним из наиболее динамичных элементов любого сайта,
и с программной точки зрения это приводит к нескольким существенным моментам:
слишком частое обращение к форумам создает существенную нагрузку на сервер,
слишком частое обращение к базам данных может привести к коллизиям и,
как следствие, нарушению целостности баз данных, а значит, к неработоспособности форума и потере
информации.
Решение первой проблемы состоит в уменьшении количества объектов и анализируемых
постеров, кэшировании и прочих методах снижения затрат на обработку запроса. Вторая проблема,
помимо этого, может быть решена регулярным резервным копированием баз данных форумов.
Для осуществления резервирования баз данных форумов стандартная процедура резервного
копирования баз Zebra не годится, поскольку она осуществляет обработку
всей базы данных,
независимо от того, было ранее сохранено значение некоторой записи или нет. В случае небольших
размеров баз форумов такой подход тоже оправдывает себя, однако в случае, если в базе содержатся
десятки тысяч постеров, затраты на резервное копирование становятся нецелесообразны.
В этом случае имеет смысл так называемое «продолжающееся резервирование»,
при котором на каждый момент резервирования сохраняется информация о точке создания резерва, и
в следующем сеансе резервирования оно начинается именно с этой точки, то есть с постера, следующего
за тем, что был зарезервирован последним. Преимущества очевидны вместо передергивания всех
записей базы форумов анализируются только максимум несколько сотен последних.
По достижении файлом резерва некоторого критического размера он переименовывается,
следующие постеры резервируются в новый файл.
В случае, если сбой все-таки произошел, базы форумов нетрудно восстановить из имеющихся
резервных файлов, при этом, как правило, сохраняются все идентификаторы постеров соответственно
тем, что были до резервирования.
Параметры резервирования форумов настраиваются в разделе администрирования форумов
«Импорт и экспорт».
Формат файла резерва форумов подразумевает наличие трех секций.
1. Техническая информация, сведения о версии и дате создания файла. Например:
; Zebra (C) XXI, White Tiger Group
; Web: http://www.wtg.ru
; Zebra Forum partional backup file.
; Do not modify this file, only for restoration with Zebra Forum
; restoration components. See the documentation for more
; detailed instructions of this operation.
; Version 0.13 (0134)
; Date: Sun Nov 2 13:27:08 2003
2. Секция спецификаций, например:
[INFO]
date=66482602027:Sun Nov 2 13:27:08 2003
version=0.13 (0134)
danversion=0.51
dan=counter_forum,<...>
dan=defaultlanguage_forum,<...>
dan=info_forum,<...>
dan=model_forum,<...>
dan=rolealias_forum,<...>
dan=rolecorr_forum,<...>
dan=rolename_forum,<...>
dan=rolerest_forum,<...>
dan=rolevector_forum,<...>
dan=type_forum,<...>
dan=typealias_forum,<...>
dan=typerest_forum,<...>
rolelast=140
typelast=11
propertylast=121938
forum=0x0000090A:test:Тестовый
В этом разделе содержатся код даты проведения сеанса резервирования,
спецификации модели DAN форума, а также некоторые сведения о текущих параметрах
состояния DAN. Здесь же указывается, какие идентификаторы имеют форумы во внутреннем
формате DAN и внешнем формате WTGZ Forum, а также наименования соответствующих форумов.
3. Секция постеров. При этом каждый постер кодируется отдельной подсекцией,
содержащей примерно следующую информацию:
[0x00000035]
subject=Re [2]: test
body=T>> akla=0D=0AT> zda=0D=0AT> s=0D=0AZxjZKLX=0D=0A
created=0x00000034:66469981930
author=0x0001DA6F:userusermailru
authorip=0x00000002:127.0.0.1
forum=0x0000090A:test
parent=0x0000002A:Re: test
previous=0x0000002A:Re: test
request=0x0000E727:3
requested=0x0001D845:66471152563
requestroot=0x0000E727:3
size=0x000002C1:7
Заголовок секции соответствует идентификатору данного постера в момент резервирования,
и он же будет сохранен в случае дальнейшего восстановления форума из резервной копии.
Мультиязычные элементы из списка кодируются в соответствии со стандартом Quoted-printable.
Все секции и подсекции отделяются друг от друга пустой строкой. Если пустая строка
присутствует внутри секции, результат не определен.
Encyclopaedia Zebra
(4676312)
Добавление кодовых страниц
Поддержка кодовых страниц в Zebra осуществляется на уровне
перекодирования согласно сопоставленным таблицам из таблицы по умолчанию.
Таблица по умолчанию всегда соответствует странице
windows-1251.
Для добавления кодовой страницы требуется составить подключаемый файл
Zebra
zauto.ini следующего вида (например, для KOI8-r):
[_:ini]
_charset-koi8-r=бвчздецъйклмнопртуфхжигюыэЪщшьасБВЧЗДЕЦЪЙКЛМНОПРТУФХЖИГЮЫЭЯЩШЬАС
Расположение символов должно соответствовать следующему раскладу
таблицы
windows-1251:
АБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯабвгдежзийклмнопрстуфхцчшщъыьэюя
В Zebra по умолчанию сразу устанавливаются кодовые страницы KOI8-r,
ISO-8859-5, Alt-866 (DOS).
(3467848)
Календарь
Для отображения календаря требуется:
на уровне компонента:
подключить внешнюю библиотеку
zx1.cgi;
вызвать процедуру
zs_calendar($month,$year),
здесь
$month месяц,
$year полный
год, для которых формируется календарь; если аргументы опустить, будут
приняты текущий месяц и год;
в описании страницы:
определить в месте расположения календаря совокупность
ключей для его установки.
При создании календаря используются следующие ключи списка
int.
month_prev, номер предыдущего относительно активного месяца
wmonth_prev, название предыдущего относительно активного месяца
fullyear_prev, полный номер года, соответствующий предыдущему относительно активного месяца
year_prev, номер года, соответствующий предудыщему относительно активного месяца
month_current, номер активного месяца
wmonth_current, название активного месяца
fullyear_current, полный номер активного года
year_current, номер активного года
|
month_next, номер следующего относительно активного месяца
wmonth_next, название следующего относительно активного месяца
fullyear_next, полный номер года, соответствующий следующему относительно активного месяца
year_next, номер года, соответствующий следующему относительно активного месяца
week_X, определено, если в месяце есть X-я неделя; содержит номер недели (само X)
weekmonth_X, номер месяца для X-й недели
weekwmonth_X, название месяца для X-й недели
weekfullyear_X, полный номер года для X-й недели
weekyear_X, номер года для X-й недели
weekpassed_X, определено, если X-я неделя месяца активна или уже прошла
|
Параметры дней месяца рассматриваются несколько особенным образом.
Формирование их в любом случае начинается с понедельника. Если первое число
месяца приходится на середину или конец недели, начальные элементы списка
не определены, и первое число может быть установлено, например, в
day_6 (для субботы). Таким образом, может быть рассмотрено до
38 значений
X, при этом в
day_38 попадает 31 число месяца.
При составлении описания календаря следует руководствоваться этими
соображениями. Также нужно иметь в виду, что описание может получиться
громоздким (в то же время результат его обработки готовый календарь
будет в несколько раз меньше). Пример описания календаря можно
найти в ресурсе
f.s.tree.showindex.dsc.ru в дистрибутивном каталоге
Zebra.
day_X, определено, если соответствующий день месяца существует; в
X заносится число;
dday_X, определено, если соответствующий день месяца существует; в
X заносится число с учетом ведущего нуля;
wday_X, содержит название дня недели;
month_X, номер месяца, соответствующий числу;
wmonth_X, название месяца, соответствующего числу;
fullyear_X, полный номер года, соответствующего числу;
year_X, номер года, соответствующего числу;
passed_X, определено, если число активно или уже прошло.
(2G6HJ1J)
Дополнительные индивидуальные свойства постеров в Zebra Forum
В WTGZ Forum допустимо внедрять параметры постеров, не предусмотренные изначально
в программе. Дополнительные параметры (при наличии таковых) являются индивидуальными
для каждого постера. Их можно редактировать наряду со стандартными характеристиками
постера, а также применять сортировку по каждому из них.
Сами параметры устанавливаются посредством стиля форума в разделе «Параметры формы»,
пункт «Добавить свойство». В первом поле устанавливается идентификатор параметра,
во втором его наименование. Если параметры уже определены в стиле, их можно удалить. При этом
удаление параметра как такового из самих постеров не осуществляется, но их значения полностью
игнорируются.
Для применения параметров необходимо определить в шаблоне формы в соответствии
с дизайном следующий фрагмент:
<input type="text" name="ampvalue_AMPID" value="$ampvalue_AMPID">
Здесь
AMPID идентификатор свойства.
В шаблонах постера, индекса и т.д. следует использовать ключ
$ampvalue_AMPID.
При этом можно применять ключ
$ampname_AMPID, чтобы автоматически устанавливать
наименование свойства. Можно и не применять.
Включить режим сортировки по дополнительному свойству можно в параметрах стиля.
В случае, если требуется сделать это через адресную строку, следует убедиться в наличии
такой возможности (то есть проверить, что в параметрах форума включена опция
«Разрешить настройку через адресную строку») и далее использовать следующий ключ:
orderindex=10&additionalsort=AMPID
Примечание: amp additional message parameters.
(A1VE7Y1)
Использование подпрограммы выборки постеров форумов
В WTGZ Forum реализована сервисная подпрограмма, предназначенная
для внедрения отобранных в соответствии с какими-либо условиями постеров в любой шаблон
или описание Zebra. Она может быть запущена вне зависимости от
того, активен форумный модуль или нет.
Для вызова подпрограммы необходимо использовать
строку вида:
%#zfx1::getmessage(MODE[,NUM],FODUMID1,FORUMID2,FORUMID3...)#%
Здесь
MODE режим выборки;
FORUMIDX
список форумов, из которых производится выборка.
Если список форумов не указан, рассматриваются все постеры базы.
Режимы выборки
MODE:
1 выбрать случайный постер;
2 выбрать случайную тему;
3 выбрать список из последних
NUM постеров;
4 выбрать список из последних
NUM тем.
В режимах 1 и 2 устанавливаются ключи типа
msg (
msgmid,
msgsubject,
msgcreatedate и т.д.) и общий ключ
msg,
в режимах 3 и 4 условие множественного типа
msglist с аналогичными ключами.
Примеры.
Для отбора последних пяти начатых тем с форума
forum можно
включить такой фрагмент:
%#zfx1::getmessage(4,5,forum)#%
%MULTIPLEmsglist{
Постер: $msgmid $msgsubject <$msgmidhref>
Форум: $msgfid $msgforum
Автор: $msgauthor
Создано: $msgcreateshortdate
Содержимое: $msgbody
Картинка: $msgpicture
}msglist%
Для отбора любого постера с форума
forum справедливо следующее:
%#zfx1::getmessage(1,forum)#%
%msg{
Постер: $msgmid $msgsubject <$msgmidhref>
Форум: $msgfid $msgforum
Автор: $msgauthor
Создано: $msgcreateshortdate
Содержимое: $msgbody
Картинка: $msgpicture
}msg%
Для отбора любой темы из базы форумов справедливо следующее:
%#zfx1::getmessage(2)#%
%msg{
Постер: $msgmid $msgsubject <$msgmidhref>
Форум: $msgfid $msgforum
Автор: $msgauthor
Создано: $msgcreateshortdate
Содержимое: $msgbody
Картинка: $msgpicture
}msg%
Примечание: Команда %#zfx1::getmessage#% равнозначна
команде %#zfx1::getmessage(1)#%.
Чтобы осуществить отображение постера в соответствии с возможными критериями
в любом ресурсе на сайте, независимо от Zebra, требуется выполнить следующее.
1. Создать в Zebra Site (Zebra Site -> Управление группами и ресурсами -> Добавить
текстовый ресурс) страницу примерно следующего содержания:
%#zfx1::getmessage(1,forum)#%
%msg{
Постер: $msgmid $msgsubject <$msgmidhref>
Форум: $msgfid $msgforum
Автор: $msgauthor
Создано: $msgcreateshortdate
Содержимое: $msgbody
Картинка: $msgpicture
}msg%
Назовем ее, например,
message. Параметры вызываемой подпрограммы
можно изменять в соответствии с целью. В теле страницы, разумеется, можно всячески
варьировать отображаемый текст в соответствии с предоставляемыми Zebra Forum возможностями.
2. Осуществить вызов модуля Zebra Site с созданной страницей, например,
вставкой в shtml-файл следующего фрагмента:
<!--#include virtual="/cgi-bin/zs.cgi?page=message"-->