doc/templates.txt

   1 Описание шаблонов форума
   2
   3 Шаблоны форума представляют собой обыкновенные HTML-файлы.
   4 В них должны присутствовать элементы с определенными классами и поля
   5 форм с определенными именами. Скрипты форума вставляют в эти файлы
   6 информацию руководствуясь классами элементов и именами полей форм.
   7
   8 Во всех шаблонах производится правка относительных URL в элементах
   9 img src, a href, link href, form action.
  10 В URL начинающихся со слова templates заменяются на значение templateurl
  11 из конфигурации форума, URL, начинающиеся со слова users - на userurl,
  12 со слова forum - на путь к скрипту форума. Остальные относительные (т.е.
  13 не начинающиеся c http: или / url дополняются путем к корневому каталогу
  14 форума. Cсылки вида forum?параметры будут заменены на
  15 url-скрипта/url-страницы?параметры
  16
  17
  18 Шаблоны страниц:
  19
  20 1. Страница темы
  21
  22 title - в элемент с таким классом помещается заголовок темы. Тот же
  23 самый заголовок помещается в элемент <title> в <head>
  24
  25 Например
  26         <h1 class="title">Тема форума</H1>
  27
  28 message
  29  На странице темы должен присутствовать блоковый элемент с классом
  30  message. Подстановка конкретного сообщения производится внутрь этого
  31  элемента. При появлении в теме следующего сообщения этот элемент
  32  копируется и копия вставляется сразу после предыдущего.
  33
  34  Элементу приписывается атрибут id, содержащий уникальный идентификатор
  35  данного сообщения
  36
  37 Внутри элемента с классом message должны содержаться следующие элементы
  38
  39 manchor - якорь на который будут формироваться ссылки на это сообщение.
  40                 Атрибут name заменяется на идентификтаор этого сообщения
  41 mlink - ссылка на это сообщение. Атрибут href заменяется на
  42 author - ник автора сообщения. innerHtml заменяется на ник автора
  43                 Следует учитывать что в случае openId авторизации в этот элемент
  44                 будет помещен элемент a со ссылкой на домашнюю страницу
  45 mdate  - дата публикации сообщения  innerHtml заменяется на дату
  46 avatar - элемент img атрибут src  которого заменияется на аватар автора,
  47         или на templates/1x1.gif если у автора нет аватара.
  48 ap-status - статус автора на форуме innerHtml заменяется на статус
  49 ap-comment - комментарий к нику, введенный автором при регистрации.
  50          innerHtml заменяется на комментарий
  51 И прочие классы с префиксом ap-, innerHtml которых заменяеняется
  52 на соответствущие поля из профайла автора. Если поле имеет в имени
  53 подчерк, допустимо вместо подчерка использовать дефис "-" в названии
  54 класа.
  55
  56
  57 msubject - тема сообщения. Заменяется innerHtml
  58 mtext - текст сообщения. innerHtml заменяется на отформатированный текст
  59 mreply - ссылка на скрипт ответа. Атрибут href будет заменен на
  60                 корректную url. Элемент id заменяется на reply<идентификатор
  61                 сообщения>
  62
  63 Например:
  64
  65    <div class="message" id="0001">
  66    <a name="00001" class="manchor"></a>
  67    <h2 class="msubject>Тема сообщения</h2>
  68    Автор <span class="mauthor">В Пупкин</span>
  69    (<span class="acomment">Пользователь форума</acomment>,
  70    <span class"astatus">Модератор</span>)
  71    <img align=left class=avatar src="/forum/users/v_pupkin.jpg">
  72    <div class="mtext">
  73    Текст сообщения с <b>выделениями</b>
  74    </div>
  75    <a href="/forum/f1/topic1.html#0001" class="mlink">ссылка на это
  76    сообщение</a>
  77    <a href="/cgi-bin/forum/f1/topic1.html?reply=reply&id=0001"
  78    сlass="mreply">ответить</a>
  79    <form class="actions" name="fa0001" action="/cgi-bin/forum/f1/topic1.html">
  80     <!-- .... см ниже .... -->
  81         <input type="hidden" name="id" value="0001">
  82         <input type="hidden" name="author" value="В. Пупкин">
  83         <input type="submit" name="edit" value="Редактировать">
  84         <input type="submit" name="delete" value="Удалить">
  85         <input type="submit" name="move" value="Переместить в другую тему">
  86    </form>
  87    </div>
  88
  89  Кроме того, в элементе c классом message должна присутствовать форма
  90  с классом actions.
  91  В ней должны присутсвовать следующие поля
  92  1. Скрытое поле id
  93  2. Скрытое поле author
  94  3. Кнопка edit
  95  4. Кнопка delete
  96  5. Кнопка move
  97  6. Кнопка reply (заменяет собой ссылку с классом mreply)
  98
  99
 100
 101  Клиент-сайд скрипт должен уметь скрывать кнопку move, если пользователь
 102  не является модератором, а также кнопки edit и delete, если
 103  пользователь не является модератором или автором сообщения(т.е. значение куки
 104  sluser не совпадает с содержимым скрытого поля author)
 105
 106
 107  Определять какие кнопки и ссылки являются ссылками на  форумный скрипт
 108  и должны скрываться и показываться в зависимости от прав доступа,
 109  следует по атрибуту href ссылки и атрибуту action формы в сочетании с
 110  атрибутом name у соответствующей кнопки. (кнопкой считаются input
 111  type=submit и input type=image).
 112
 113  В разделе head у шаблона должны присутствовать тэги link вида
 114 1. <link href="forum" rel="forum-script">
 115  По общим правилам подстановки серверный скрипт при обработке шаблона
 116  заменит href этого элемента на собственную url.
 117
 118  Соответственно формы с action равной этой URL следует рассматривать
 119  как подлежащие обработке и искать в них кнопки с именами,
 120  соответствующими именам операций. И ссылки с href=эта url?параметры
 121  В ссылке следует искать параметр вида имя-операции.
 122 2. <link href="forum" rel="forum-user-list">
 123         Содержимое href этого скрипта может быть использовано client-side
 124         скриптом для формирования ссылки на страничку локального
 125         пользователя форума (в случае если имя пользователя начинается с
 126         http:://, это OpenID-пользователь и его страничка находстия по URL,
 127         совпрадающей с именем пользователя.
 128
 129
 130
 131
 132  Если кука sluser не определена,
 133  то желательно также скрыть кнопку reply и ссылку с классом mreply, если
 134  только в шаблоне формы reply не предусмотрены поля, позволяющие
 135  залогиниться в момент отправки реплики.
 136
 137  Для получения информации о правах текущего пользователя в форуме нужно
 138  запросить (через XMLHttpRequest) файл perms.txt из текущей директории
 139  (где расположена текущая страница) и выше по иерархии вплоть до корня
 140  форма. Корнем форума является директория, где расположен файл .forum
 141  (не обязательно доступный для чтения по http. Ответ сервера 403 как и
 142  ответ 200 надо рассматривать как "файл найден")
 143
 144  Кроме того на странице могут присутствовать элементы a с классами
 145  next и prev.  В случае если тема разрослась более чем на одну страницу,
 146  их href-атрибуты заменяются на ссылки на предыдущую следующую страницу.
 147  Если тема состоит из одной страницы, ссылки будут вести на неё же.
 148
 149  Как вариант, можно использовать классы bnext и bprev. Если нет
 150  предыдущей/следующей страницы, элементы a с такими классами будут
 151  заменены на span.
 152
 153 Страница списка тем (головная страница форума)
 154
 155 Может иметь элемент с классом annotation, описывающий форум в целом (его
 156 создатель, вводный текст и т.д. устроенный внутри аналогично элементу
 157 списка форумов (см ниже). Если в шаблоне присутствует элемент meta
 158 name="description", то туда помещается текстовое представление аннотации
 159 форума.
 160
 161 Если в шаблоне присутствуют элементы с классом top-page, то они будут
 162 сохранены только на головной странице форума, а при создании подфорумов
 163 будут из их оглавлений удаляться.
 164
 165 Шаблоном описания конкретной темы является элемент с классом topic,
 166 Содержащий элемент с классом title (название темы, должно быть
 167 ссылкой), abstract (аннотация темы)
 168 author (ссылка), date (дата создания темы), tlink (якорь для ссылок на
 169 элемент списка тем ), last-updated и msgcount.
 170
 171 Внутри элемента с классом topic должна присутствовать форма
 172 с кнопками edit delete move setrights и скрытым полем  id.
 173 Кнопку setrights следует показывать только пользователю с правами
 174 администратора.
 175
 176
 177
 178 элемент с классом topic должен быть заключен в элемент с классом
 179 topiclist.
 180
 181 При отсутствии тем на странице элементу с классом topiclist сервер
 182 приписывает атрибут style="display: none;".
 183
 184 При добавлении новой темы элемент с классом topic копируется и
 185 вставляется непосредственно за предыдущим
 186
 187
 188 Кроме этого, cтраница должна иметь ссылку на форумный скрипт с
 189 параметром newtopic=1 или форму с именем
 190 topicinfo и кнопкой submit с именем newtopic
 191
 192 Список подфорумов устроен аналогично списку тем.
 193
 194 Элемент списка форумов должен иметь класс forum, а форма/ссылка для
 195 создания нового форума соотвесттвенно имя/класс newforum, а объемлющий
 196 элемент, который скрывается при отсутствии подфорумов - класс forumlist
 197
 198 В шаблоне элемента списка форумов может присутствовать элемент img
 199 с классом logo. Если такой элемент обнаружен, то при наличии в
 200 директории форума файла logo с расширением png, jpg или gif,  в src
 201 пропиcывается ссылка на этот файл. Иначе прописывается ссылка на
 202 templates/1x1.gif
 203
 204 Допускается также ситуация когда на одной странице присутствует и список
 205 форумов, и список тем. (В этом случае если физически отсутствуют либо
 206 те, либо другие, соответствующему элементу-шаблону выставляется
 207 style="display: none");
 208
 209 Кроме этого на всех страницах рекомендуется иметь элемент-ссылку, который
 210 отображает текущее имя пользователя. Этот элемент должен
 211 конфигурироваться client-side cкриптом и показывать либо текст
 212 "Зарегистрироваться" и аналогичный и вести на
 213 /cgi-bin/forum/<адрес текущей страницы?login=1
 214 либо имя пользователя и вести на
 215 /cgi-bin/forum/<aдрес текущей страницы?user=1
 216
 217 Шаблоны служебных страниц (т.е. форм регистрации, логина и т.д.)
 218
 219 Служебные страницы форума (т.е. формы, выводимые скриптами) также
 220 оформляются с помощью HTML-шаблонов. Если страница выдается в результате
 221 POST-запроса уже содержащего требуемые данные, значения соответствующих
 222 элементов ввода заменяются на эти данные.
 223
 224 В случае если во введенных данных произошла ошибка, сообщение об ошибке
 225 скрипт вписывает в элемент с классом error вместо его innerHtml
 226
 227 Во всем шаблоне формы производится подстановка информации о текущем
 228 пользователе, аналогично тому, как она производится в элементе с классом
 229 message в шаблоне темы.
 230
 231 Как правило, все скрипты получают следующую информацию
 232 1. Поле с именем операции и произвольным непустым значением
 233   Возможные операции
 234   reply
 235   edit
 236   delete
 237   move
 238   newtopic
 239   newforum
 240   getrights
 241   login
 242   register
 243   userlist
 244   profile
 245   setrights
 246
 247
 248 2. Поле id с идентификатором комментария/темы/форума
 249
 250 Это поле должно быть обязательно проброшено через форму как скрытое
 251 поле.
 252
 253 3. Поле returnto - url куда направить пользователя после успешного
 254 завершения операции.  Если эта форма присутствует в шаблоне, но скрипт
 255 вызывается без соответствующего значения в url или postdata, это поле
 256 заполняется значением заголовка referer http-запроса.
 257
 258 Обработка форматированного (размеченного) текста:
 259
 260 В некоторые поля форм (текст реплики, подпись пользователя) должен
 261 вводиться форматированный текст.
 262
 263 Такому полю должно соответствовать поле с именим имя_format (например,
 264 полю text соотвествует поле text_format, полю signature -
 265 signature_format). Поле format может принимать одно из трех значений
 266 - html, bbcode и text. Если поле format имеет значение html, то
 267 содержимое соответствующего текстового поля рассматривается как html,
 268 подвергается чистке от небезопасных тэгов и сохраняется в таком виде.
 269 Если поле format имеет значение text, то спецсимволя эскейпятся, а
 270 переводы строки заменяются на теги <br>.
 271
 272 Если поле имеет значение bbcode, то обрабатываются управляющие
 273 последовательности bbcode.
 274
 275 Наличие URL в тексте проверяется независимо от формата.
 276
 277
 278  Скрипт входа в систему (операция login)
 279  Форма с именем login содержит поля name и password
 280  Может также содержать  checkbox с именем bindip (привязка
 281  авторизационной куки к IP)
 282
 283  При авторизации по OpenID используется поле openidsite.
 284  Его значение интерпретируется как шаблон для операции sprintf, который
 285  должен содержать один спецификатор формата %s, куда подставляется имя
 286  пользователя.
 287
 288  Если поле openidsite имеет пустое значение, пользователь
 289  рассматривается как локальный. Если непустое, то как
 290  openid-пользователь.
 291
 292  Кнопка submit называется login
 293
 294  Форма регистрации нового пользователя (операция register, форма с
 295  именем register)
 296  Содержит поля user
 297  pass1 pass2 comment
 298  Может также содержать любые дополнительные поля информации о
 299  пользователе. Они будут сохранены в списке пользователей
 300  и могут потом выводиться в шаблонах рядом с информацией об авторе.
 301  Скрытое поле required содержит список полей, которые обязательно
 302  требуются при регистрации. Поля user, pass1 и pass2 туда включать не
 303  следует.
 304  Скрытое поле ignore содержит список полей, которые НЕ НУЖНО
 305  сохранять в качестве информации о пользователе. Поля user, pass1, pass2
 306  и bindip туда включать не нужно. Так же если в форме присутствуют поля
 307  avatar и avatarfile, поле avatarfile будет автоматически включено в
 308  этот список, а поле avatar при наличии зааплоаженного файла будет
 309  заменено на URL к этому файлу.
 310
 311  Параметр restricted_userinfo в конфигурационном файле форума позволяет
 312  задать список полей, которые пользователь не имеет права редактировать
 313  сам, все равно в процессе регистрации или при редактировании профиля.
 314
 315  Поля, которые, при их наличии, обрабатываются скриптом форума
 316  специальным образом
 317
 318  1. avatar/avatarfile - картинка пользователя. Поле avatarfile
 319  (зааплоаженная картинка) имеет приоритет над avatar (внешняя URL)
 320  В случае если задано avatarfile, в информации о пользователе
 321  сохраняется поле avatar с URL к этой картинке
 322
 323  2. signature - обычно поле с форматированным текстом. Дописывается в
 324  конец каждого созданного данным пользователем сообщения
 325
 326  3. email - если не пусто, то  проверяется на корректность посредством
 327     модуля EMail::Valid
 328
 329  4. status - если имеет значение disabled, то данному пользователю
 330  запрещен вход на форум до тех пор, пока администратор форума не изменит
 331  статус. В случае, если требуется подтверждение регистрации модератором
 332  рекомендуется прописывать это поле в restricted_user_info и указывать в
 333  конфигурациии форума default_status = disabled,
 334
 335 Скрипт отправки комментария
 336
 337 Операция reply
 338   поля subject
 339   text (тэг textarea)
 340   text_format
 341   Можно также включать (динамически добавлять) поля file upload image1
 342   image2 etc.
 343   кнопка submit называется reply.
 344   Данная форма может также включать поля формы login. Т.е.
 345   поддерживается аутентификация пользователя одновременно с отправкой
 346   комментария.
 347
 348   В силу технических ограничений,  одновременно с регистрацией по OpenID
 349   невозможен upload файлов и отправка комментариев длинной более 2-4Кб.
 350   Точный предел размера комментария зависит от длины URL форума  и
 351   пределов размера URL, установленных при компиляции веб-сервера форума
 352   и веб-сервера openid-сервера.
 353
 354
 355 Скрипт создания новой темы или нового форума
 356
 357   поля
 358   subject
 359   text
 360   text_format
 361   urlname.
 362   При создании форума еще может присутствовать file upload field
 363   logo. Зааплоаженный туда файл помещается в директрию форума
 364   с именем logo и расширением соответствующим расширению исходного
 365   файла.
 366
 367
 368   В последнее поле следует запретить
 369   ввод символов нелатинского алфавита '/' и '?'
 370
 371 Cкрипт просмотра списка пользователей (опция userlist)
 372
 373    Элемент с классом user содержит элементы с классами, имена которых
 374    соответствуют именам свойств пользователей.
 375    Если внутри элемента присутствует элемент с классом formoder или
 376    foradmin, то при просмотре страницы пользователем, не имеющим
 377    соответствующих прав, этот кусок выкусывается на сервере.
 378    Должен присутствовать элемент  именем profile имеющий тип a.
 379    Его атрибут href заменяется на ссылку на скрипт редактирования
 380    профайла. Форм этот шаблон вообще не содержит
 381
 382 Скрипт раздачи прав модерирования (setrights)
 383
 384   Дает права модераторов на определенный форум/тему, или права
 385   администраторов.
 386
 387   В результате заполнения формы поле с именем moderators должно
 388   содержать список модераторов для данной темы (соответствующей
 389   url страницы в pathinfo) поле с именем  administrators список всех
 390   администраторов данного сайта.
 391
 392 Скрипт редактирования свойств пользователя.
 393   Аналогичен скрипту регистрации, но администратору еще видно поле
 394   status. (пользователю - тоже видно, но input или select заменяется на
 395   обычный текст)
 396
 397   Может присутствовать кнопка resetpassword (показывается только
 398   администраторам)
 399
 400
 401 Встраивание служебных форм непосредственно в страницы форума
 402
 403   Форма, содержащая вышеперечиленные поля, имеющая метод POST и имеющая в поле
 404   action="forum/<url страницы, где она размещена)
 405   может быть встроена непосредственно в страницу темы или списка
 406   тем/списка форумов. Желательно чтобы она делалась видимой только при
 407   нажатии кнопки. Отправка этой формы приводит к выполнению необходимого
 408   действия без  показа страницы скрипта.
 409
 410 Служебные шаблоны
 411
 412 Шаблон с именем error.html используется для выдачи фатальных ошибок
 413 скрипта. (когда нет возможности показать форму). Он должен содержать
 414 элемент с классом error, innerHTML которого будет заменен на сообщение
 415 об ошибке.