doc/templates.txt

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