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