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 astatus - статус автора на форуме innerHtml заменяется на статус
  48 acomment - комментарий к нику, введенный автором при регистрации.
  49          innerHtml заменяется на комментарий
  50 msubject - тема сообщения. Заменяется innerHtml
  51 mtext - текст сообщения. innerHtml заменяется на отформатированный текст
  52 mreply - ссылка на скрипт ответа. Атрибут href будет заменен на
  53                 корректную url. Элемент id заменяется на reply<идентификатор
  54                 сообщения>
  55
  56 Например:
  57
  58    <div class="message" id="0001">
  59    <a name="00001" class="manchor"></a>
  60    <h2 class="msubject>Тема сообщения</h2>
  61    Автор <span class="mauthor">В Пупкин</span>
  62    (<span class="acomment">Пользователь форума</acomment>,
  63    <span class"astatus">Модератор</span>)
  64    <img align=left class=avatar src="/forum/users/v_pupkin.jpg">
  65    <div class="mtext">
  66    Текст сообщения с <b>выделениями</b>
  67    </div>
  68    <a href="/forum/f1/topic1.html#0001" class="mlink">ссылка на это
  69    сообщение</a>
  70    <a href="/cgi-bin/forum/f1/topic1.html?reply=reply&id=0001"
  71    сlass="mreply">ответить</a>
  72    <form class="actions" name="fa0001" action="/cgi-bin/forum/f1/topic1.html">
  73     <!-- .... см ниже .... -->
  74         <input type="hidden" name="id" value="0001">
  75         <input type="hidden" name="author" value="В. Пупкин">
  76         <input type="submit" name="edit" value="Редактировать">
  77         <input type="submit" name="delete" value="Удалить">
  78         <input type="submit" name="move" value="Переместить в другую тему">
  79    </form>
  80    </div>
  81
  82  Кроме того, в элементе c классом message должна присутствовать форма
  83  с классом actions.
  84  В ней должны присутсвовать следующие поля
  85  1. Скрытое поле id
  86  2. Скрытое поле author
  87  3. Кнопка edit
  88  4. Кнопка delete
  89  5. Кнопка move
  90  6. Кнопка reply (заменяет собой ссылку с классом mreply)
  91
  92
  93
  94  Клиент-сайд скрипт должен уметь скрывать кнопку move, если пользователь
  95  не является модератором, а также кнопки edit и delete, если
  96  пользователь не является модератором или автором сообщения(т.е. значение куки
  97  sluser не совпадает с содержимым скрытого поля author)
  98
  99
 100  Определять какие кнопки и ссылки являются ссылками на  форумный скрипт
 101  и должны скрываться и показываться в зависимости от прав доступа,
 102  следует по атрибуту href ссылки и атрибуту action формы в сочетании с
 103  атрибутом name у соответствующей кнопки. (кнопкой считаются input
 104  type=submit и input type=image).
 105
 106  В разделе head у шаблона должны присутствовать тэги link вида
 107 1. <link href="forum" rel="forum-script">
 108  По общим правилам подстановки серверный скрипт при обработке шаблона
 109  заменит href этого элемента на собственную url.
 110
 111  Соответственно формы с action равной этой URL следует рассматривать
 112  как подлежащие обработке и искать в них кнопки с именами,
 113  соответствующими именам операций. И ссылки с href=эта url?параметры
 114  В ссылке следует искать параметр вида имя-операции.
 115 2. <link href="forum" rel="forum-user-list">
 116         Содержимое href этого скрипта может быть использовано client-side
 117         скриптом для формирования ссылки на страничку локального
 118         пользователя форума (в случае если имя пользователя начинается с
 119         http:://, это OpenID-пользователь и его страничка находстия по URL,
 120         совпрадающей с именем пользователя.
 121
 122
 123
 124
 125  Если кука sluser не определена,
 126  то желательно также скрыть кнопку reply и ссылку с классом mreply, если
 127  только в шаблоне формы reply не предусмотрены поля, позволяющие
 128  залогиниться в момент отправки реплики.
 129
 130  Для получения информации о правах текущего пользователя в форуме нужно
 131  запросить (через XMLHttpRequest) файл perms.txt из текущей директории
 132  (где расположена текущая страница) и выше по иерархии вплоть до корня
 133  форма. Корнем форума является директория, где расположен файл .forum
 134  (не обязательно доступный для чтения по http. Ответ сервера 403 как и
 135  ответ 200 надо рассматривать как "файл найден")
 136
 137  Кроме того на странице могут присутствовать элементы a с классами
 138  next и prev.  В случае если тема разрослась более чем на одну страницу,
 139  их href-атрибуты заменяются на ссылки на предыдущую следующую страницу.
 140  Если тема состоит из одной страницы, ссылки будут вести на неё же.
 141
 142  Как вариант, можно использовать классы bnext и bprev. Если нет
 143  предыдущей/следующей страницы, элементы a с такими классами будут
 144  заменены на span.
 145
 146 Страница списка тем (головная страница форума)
 147
 148 Может иметь элемент с классом message, описывающий форум в целом (его
 149 создатель, вводный текст и т.д.
 150
 151 Шаблоном описания конкретной темы является элемент с классом topic,
 152 устроенный аналогично message (показывается текст и автор первой реплики
 153 темы) с той разницей, что элемент с классом subject должен быть ссылкой.
 154
 155 Внутри элемента с классом topic должна присутствовать форма
 156 с кнопками edit delete move setrights и скрытым полем  id.
 157 Кнопку setrights следует показывать только пользователю с правами
 158 администратора.
 159
 160
 161 Кроме этого, cтраница должна иметь ссылку с классом newtopic или форму с именем
 162 newtopic и кнопкой submit с именем newtopic
 163
 164
 165 Страница списка форумов (головная страница сайта, страница форума с
 166 подразделами)
 167
 168 Устроена аналогично странице списка тем.
 169
 170 Элемент списка форумов должен иметь класс forum, а форма/ссылка для
 171 создания нового форума соотвесттвенно имя/класс newforum.
 172
 173 Допускается также ситуация когда на одной странице присутствует и список
 174 форумов, и список тем. (В этом случае если физически отсутствуют либо
 175 те, либо другие, соответствующему элементу-шаблону выставляется
 176 style="visibility: hidden");
 177
 178 Кроме этого на всех страницах рекомендуется иметь элемент-ссылку, который
 179 отображает текущее имя пользователя. Этот элемент должен
 180 конфигурироваться client-side cкриптом и показывать либо текст
 181 "Зарегистрироваться" и аналогичный и вести на
 182 /cgi-bin/forum/<адрес текущей страницы?login=1
 183 либо имя пользователя и вести на
 184 /cgi-bin/forum/<aдрес текущей страницы?user=1
 185
 186 Шаблоны служебных страниц (т.е. форм регистрации, логина и т.д.)
 187
 188 Служебные страницы форума (т.е. формы, выводимые скриптами) также
 189 оформляются с помощью HTML-шаблонов. Если страница выдается в результате
 190 POST-запроса уже содержащего требуемые данные, значения соответствующих
 191 элементов ввода заменяются на эти данные.
 192
 193 В случае если во введенных данных произошла ошибка, сообщение об ошибке
 194 скрипт вписывает в элемент с классом error вместо его innerHtml
 195
 196 Во всем шаблоне формы производится подстановка информации о текущем
 197 пользователе, аналогично тому, как она производится в элементе с классом
 198 message в шаблоне темы.
 199
 200 Как правило, все скрипты получают следующую информацию
 201 1. Поле с именем операции и произвольным непустым значением
 202   Возможные операции
 203   reply
 204   edit
 205   delete
 206   move
 207   newtopic
 208   newforum
 209   getrights
 210   login
 211   register
 212   userlist
 213   profile
 214   setrights
 215
 216
 217 2. Поле id с идентификатором комментария/темы/форума
 218
 219 Это поле должно быть обязательно проброшено через форму как скрытое
 220 поле.
 221
 222 3. Поле returnto - url куда направить пользователя после успешного
 223 завершения операции.  Если эта форма присутствует в шаблоне, но скрипт
 224 вызывается без соответствующего значения в url или postdata, это поле
 225 заполняется значением заголовка referer http-запроса.
 226
 227  Скрипт регистрации (операция login)
 228  Форма с именем login содержит поля name и password
 229  Может также содержать  checkbox с именем ipbind (привязка
 230  авторизационной куки к IP)
 231
 232  (OpenID пока не описываем)
 233
 234  Кнопка submit называется login
 235
 236  Форма регистрации нового пользователя (операция register, форма с
 237  именем register)
 238  Содержит поля user
 239  pass1 pass2 comment
 240  avatar (поле ввода URL) или avatarfile(file upload field)
 241  email
 242  Может также содержать любые дополнительные поля информации о
 243  пользователе (кроме поля status). Они будут сохранены в списке пользователей
 244  и могут потом выводиться в шаблонах рядом с информацией об авторе.
 245  Скрытое поле required содержит список полей, которые обязательно
 246  требуются при регистрации. Поля user, pass1 и pass2 туда включать не
 247  следует.
 248  Скрытое поле ignore содержит список полей, которые НЕ НУЖНО
 249  сохранять в качестве информации о пользователе.
 250
 251 Скрипт отправки комментария
 252
 253   поля subject text (тэг textarea)
 254   Можно также включать (динамически добавлять) поля file upload image1
 255   image2 etc.
 256   кнопка submit называется reply
 257
 258 Скрипт создания новой темы или нового форума
 259
 260   поля subject text imageN и urlname. В последнее поле следует запретить
 261   ввод символов нелатинского алфавита '/' и '?'
 262
 263 Cкрипт просмотра списка пользователей (опция userlist)
 264
 265    Элемент с классом user содержит элементы с классами, имена которых
 266    соответствуют именам свойств пользователей.
 267    Если внутри элемента присутствует элемент с классом formoder или
 268    foradmin, то при просмотре страницы пользователем, не имеющим
 269    соответствующих прав, этот кусок выкусывается на сервере.
 270    Должен присутствовать элемент  именем profile имеющий тип a.
 271    Его атрибут href заменяется на ссылку на скрипт редактирования
 272    профайла. Форм этот шаблон вообще не содержит
 273
 274 Скрипт раздачи прав модерирования (setrights)
 275
 276   Дает права модераторов на определенный форум/тему, или права
 277   администраторов.
 278
 279   В результате заполнения формы поле с именем moderators должно
 280   содержать список модераторов для данной темы (соответствующей
 281   url страницы id) поле с именем  administrators список всех
 282   администраторов данного сайта.
 283
 284 Скрипт редактирования свойств пользователя.
 285   Аналогичен скрипту регистрации, но администратору еще видно поле
 286   status. (пользователю - тоже видно, но input или select заменяется на
 287   обычный текст)
 288
 289   Может присутствовать кнопка resetpassword (показывается только
 290   администраторам)
 291
 292
 293 Встраивание служебных форм непосредственно в страницы форума
 294
 295   Форма, содержащая вышеперечиленные поля, имеющая метод POST и имеющая в поле
 296   action="forum/<url страницы, где она размещена)
 297   может быть встроена непосредственно в страницу темы или списка
 298   тем/списка форумов. Желательно чтобы она делалась видимой только при
 299   нажатии кнопки. Отправка этой формы приводит к выполнению необходимого
 300   действия без  показа страницы скрипта.
 301
 302 Служебные шаблоны
 303
 304 Шаблон с именем error.html используется для выдачи фатальных ошибок
 305 скрипта. (когда нет возможности показать форму). Он должен содержать
 306 элемент с классом error, innerHTML которого будет заменен на сообщение
 307 об ошибке.