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  следует по атрибуту href ссылки и атрибуту action формы в сочетании с
 102  атрибутом name у соответствующей кнопки. (кнопкой считаются input
 103  type=submit и input type=image).
 104
 105  В разделе head у шаблона должен присутствовать тэг link вида
 106  <link href="forum" rel="forum-script">
 107  По общим правилам подстановки серверный скрипт при обработке шаблона
 108  заменит href этого элемента на собственную url.
 109  Соответственно формы с action равной этой URL следует рассматривать
 110  как подлежащие обработке и искать в них кнопки с именами,
 111  соответствующими именам операций. И ссылки с href=эта url?параметры
 112  В ссылке следует искать параметр вида имя-операции.
 113
 114
 115  Для того чтобы узнать является ли текущий пользователь модератором
 116  данного форума, нужно запросить с сервера (через XmlHttpRequest)
 117  файл .moderators лежащий рядом с текущим файлом и далее вверх по
 118  иерархии. Эти файлы представляют собой простые текстовые файлы с именем
 119  пользователя в каждой строке.
 120
 121  В корне форума имеется аналогичный файл .admins.
 122
 123  Можно также запросить файл .banned.
 124
 125  Все эти действия являются необязательными. Если на клиентской стороне
 126  они не будут выполнены и у пользователя появится возможность нажать на
 127  кнопку выполнения операции, на которую у него нет прав, операция будет
 128  заблокирована на сервере.
 129
 130
 131
 132  Если кука sluser не определена,
 133  то желательно также скрыть кнопку reply и ссылку с классом mreply.
 134
 135  Кроме того на странице могут присутствовать элементы a с классами
 136  next и prev.  В случае если тема разрослась более чем на одну страницу,
 137  их href-атрибуты заменяются на ссылки на предыдущую следующую страницу.
 138  Если тема состоит из одной страницы, ссылки будут вести на неё же.
 139
 140  Как вариант, можно использовать классы bnext и bprev. Если нет
 141  предыдущей/следующей страницы, элементы a с такими классами будут
 142  заменены на span.
 143
 144 Страница списка тем (головная страница форума)
 145
 146 Может иметь элемент с классом message, описывающий форум в целом (его
 147 создатель, вводный текст и т.д.
 148
 149 Шаблоном описания конкретной темы является элемент с классом topic,
 150 устроенный аналогично message (показывается текст и автор первой реплики
 151 темы) с той разницей, что элемент с классом subject должен быть ссылкой.
 152
 153 Внутри элемента с классом topic должна присутствовать форма
 154 с кнопками edit delete move setrights и скрытым полем  id.
 155 Кнопку setrights следует показывать только пользователю с правами
 156 администратора.
 157
 158
 159 Кроме этого, cтраница должна иметь ссылку с классом newtopic или форму с именем
 160 newtopic и кнопкой submit с именем newtopic
 161
 162
 163 Страница списка форумов (головная страница сайта, страница форума с
 164 подразделами)
 165
 166 Устроена аналогично странице списка тем.
 167
 168 Элемент списка форумов должен иметь класс forum, а форма/ссылка для
 169 создания нового форума соотвесттвенно имя/класс newforum.
 170
 171 Допускается также ситуация когда на одной странице присутствует и список
 172 форумов, и список тем. (В этом случае если физически отсутствуют либо
 173 те, либо другие, соответствующему элементу-шаблону выставляется
 174 style="visibility: hidden");
 175
 176 Кроме этого на всех страницах рекомендуется иметь элемент-ссылку, который
 177 отображает текущее имя пользователя. Этот элемент должен
 178 конфигурироваться client-side cкриптом и показывать либо текст
 179 "Зарегистрироваться" и аналогичный и вести на
 180 /cgi-bin/forum/<адрес текущей страницы?login=1
 181 либо имя пользователя и вести на
 182 /cgi-bin/forum/<aдрес текущей страницы?user=1
 183
 184 Шаблоны служебных страниц (т.е. форм регистрации, логина и т.д.)
 185
 186 Служебные страницы форума (т.е. формы, выводимые скриптами) также
 187 оформляются с помощью HTML-шаблонов. Если страница выдается в результате
 188 POST-запроса уже содержащего требуемые данные, значения соответствующих
 189 элементов ввода заменяются на эти данные.
 190
 191 В случае если во введенных данных произошла ошибка, сообщение об ошибке
 192 скрипт вписывает в элемент с классом error вместо его innerHtml
 193
 194 Во всем шаблоне формы производится подстановка информации о текущем
 195 пользователе, аналогично тому, как она производится в элементе с классом
 196 message в шаблоне темы.
 197
 198 Как правило, все скрипты получают следующую информацию
 199 1. Поле с именем операции и произвольным непустым значением
 200   Возможные операции
 201   reply
 202   edit
 203   delete
 204   move
 205   newtopic
 206   newforum
 207   getrights
 208   login
 209   register
 210   userlist
 211   profile
 212   setrights
 213
 214
 215 2. Поле id с идентификатором комментария/темы/форума
 216
 217 Это поле должно быть обязательно проброшено через форму как скрытое
 218 поле.
 219
 220 3. Поле returnto - url куда направить пользователя после успешного
 221 завершения операции.  Если эта форма присутствует в шаблоне, но скрипт
 222 вызывается без соответствующего значения в url или postdata, это поле
 223 заполняется значением заголовка referer http-запроса.
 224
 225  Скрипт регистрации (операция login)
 226  Форма с именем login содержит поля name и password
 227  Может также содержать  checkbox с именем ipbind (привязка
 228  авторизационной куки к IP)
 229
 230  (OpenID пока не описываем)
 231
 232  Кнопка submit называется login
 233
 234  Форма регистрации нового пользователя (операция register, форма с
 235  именем register)
 236  Содержит поля user
 237  pass1 pass2 comment
 238  avatar (поле ввода URL) или avatarfile(file upload field)
 239  email
 240  Может также содержать любые дополнительные поля информации о
 241  пользователе (кроме поля status). Они будут сохранены в списке пользователей
 242  и могут потом выводиться в шаблонах рядом с информацией об авторе.
 243  Скрытое поле required содержит список полей, которые обязательно
 244  требуются при регистрации. Поля user, pass1 и pass2 туда включать не
 245  следует.
 246  Скрытое поле ignore содержит список полей, которые НЕ НУЖНО
 247  сохранять в качестве информации о пользователе.
 248
 249 Скрипт отправки комментария
 250
 251   поля subject text (тэг textarea)
 252   Можно также включать (динамически добавлять) поля file upload image1
 253   image2 etc.
 254   кнопка submit называется reply
 255
 256 Скрипт создания новой темы или нового форума
 257
 258   поля subject text imageN и urlname. В последнее поле следует запретить
 259   ввод символов нелатинского алфавита '/' и '?'
 260
 261 Cкрипт просмотра списка пользователей (опция userlist)
 262
 263    Элемент с классом user содержит элементы с классами, имена которых
 264    соответствуют именам свойств пользователей.
 265    Если внутри элемента присутствует элемент с классом formoder или
 266    foradmin, то при просмотре страницы пользователем, не имеющим
 267    соответствующих прав, этот кусок выкусывается на сервере.
 268    Должен присутствовать элемент  именем profile имеющий тип a.
 269    Его атрибут href заменяется на ссылку на скрипт редактирования
 270    профайла. Форм этот шаблон вообще не содержит
 271
 272 Скрипт раздачи прав модерирования (setrights)
 273
 274   Дает права модераторов на определенный форум/тему, или права
 275   администраторов.
 276
 277   В результате заполнения формы поле с именем moderators должно
 278   содержать список модераторов для данной темы (соответствующей
 279   url страницы id) поле с именем  administrators список всех
 280   администраторов данного сайта.
 281
 282 Скрипт редактирования свойств пользователя.
 283   Аналогичен скрипту регистрации, но администратору еще видно поле
 284   status. (пользователю - тоже видно, но input или select заменяется на
 285   обычный текст)
 286
 287   Может присутствовать кнопка resetpassword (показывается только
 288   администраторам)
 289
 290
 291 Встраивание служебных форм непосредственно в страницы форума
 292
 293   Форма, содержащая вышеперечиленные поля, имеющая метод POST и имеющая в поле
 294   action="forum/<url страницы, где она размещена)
 295   может быть встроена непосредственно в страницу темы или списка
 296   тем/списка форумов. Желательно чтобы она делалась видимой только при
 297   нажатии кнопки. Отправка этой формы приводит к выполнению необходимого
 298   действия без  показа страницы скрипта.
 299
 300 Служебные шаблоны
 301
 302 Шаблон с именем error.html используется для выдачи фатальных ошибок
 303 скрипта. (когда нет возможности показать форму). Он должен содержать
 304 элемент с классом error, innerHTML которого будет заменен на сообщение
 305 об ошибке.