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 mauthor - ник автора сообщения. 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 скрипт вписывает в элемент с классом errmsg вместо его 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  Содержит поля name
 205  password password2 comment avatar (file upload field)
 206  email
 207  Может также содержать любые дополнительные поля информации о
 208  пользователе (кроме поля status). Они будут сохранены в списке пользователей
 209  и могут потом выводиться в шаблонах рядом с информацией об авторе.
 210
 211 Скрипт отправки комментария
 212
 213   поля subject text (тэг textarea)
 214   Можно также включать (динамически добавлять) поля file upload image1
 215   image2 etc.
 216   кнопка submit называется reply
 217
 218 Скрипт создания новой темы или нового форума
 219
 220   поля subject text imageN и urlname. В последнее поле следует запретить
 221   ввод символов нелатинского алфавита '/' и '?'
 222
 223 Cкрипт просмотра списка пользователей (опция userlist)
 224
 225    Элемент с классом user содержит элементы с классами, имена которых
 226    соответствуют именам свойств пользователей.
 227    Если внутри элемента присутствует элемент с классом formoder или
 228    foradmin, то при просмотре страницы пользователем, не имеющим
 229    соответствующих прав, этот кусок выкусывается на сервере.
 230    Должен присутствовать элемент  именем profile имеющий тип a.
 231    Его атрибут href заменяется на ссылку на скрипт редактирования
 232    профайла. Форм этот шаблон вообще не содержит
 233
 234 Скрипт раздачи прав модерирования (setrights)
 235
 236   Дает права модераторов на определенный форум/тему, или права
 237   администраторов.
 238
 239   В результате заполнения формы поле с именем moderators должно
 240   содержать список модераторов для данной темы (соответствующей
 241   url страницы id) поле с именем  administrators список всех
 242   администраторов данного сайта.
 243
 244 Скрипт редактирования свойств пользователя.
 245   Аналогичен скрипту регистрации, но администратору еще видно поле
 246   status. (пользователю - тоже видно, но input или select заменяется на
 247   обычный текст)
 248
 249   Может присутствовать кнопка resetpassword (показывается только
 250   администраторам)
 251
 252
 253 Встраивание служебных форм непосредственно в страницы форума
 254
 255   Форма, содержащая вышеперечиленные поля, имеющая метод POST и имеющая в поле
 256   action="/cgi-bin/forum/<url страницы, где она размещена)
 257   может быть встроена непосредственно в страницу темы или списка
 258   тем/списка форумов. Желательно чтобы она делалась видимой только при
 259   нажатии кнопки. Отправка этой формы приводит к выполнению необходимого
 260   действия без  показа страницы скрипта.