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