]> www.wagner.pp.ru Git - oss/stilllife.git/blob - doc/templates.txt
Implemented (but not debugged) profile editing
[oss/stilllife.git] / 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         или на templates/1x1.gif если у автора нет аватара.
48 ap-status - статус автора на форуме innerHtml заменяется на статус
49 ap-comment - комментарий к нику, введенный автором при регистрации.
50          innerHtml заменяется на комментарий
51 И прочие классы с префиксом ap-, innerHtml которых заменяеняется 
52 на соответствущие поля из профайла автора. Если поле имеет в имени 
53 подчерк, допустимо вместо подчерка использовать дефис "-" в названии
54 класа.  
55
56
57 msubject - тема сообщения. Заменяется innerHtml           
58 mtext - текст сообщения. innerHtml заменяется на отформатированный текст 
59 mreply - ссылка на скрипт ответа. Атрибут href будет заменен на
60                 корректную url. Элемент id заменяется на reply<идентификатор
61                 сообщения>
62                 
63 Например:
64
65    <div class="message" id="0001">
66    <a name="00001" class="manchor"></a>
67    <h2 class="msubject>Тема сообщения</h2>
68    Автор <span class="mauthor">В Пупкин</span>
69    (<span class="acomment">Пользователь форума</acomment>, 
70    <span class"astatus">Модератор</span>)
71    <img align=left class=avatar src="/forum/users/v_pupkin.jpg">
72    <div class="mtext">
73    Текст сообщения с <b>выделениями</b>
74    </div>
75    <a href="/forum/f1/topic1.html#0001" class="mlink">ссылка на это
76    сообщение</a> 
77    <a href="/cgi-bin/forum/f1/topic1.html?reply=reply&id=0001"
78    сlass="mreply">ответить</a>
79    <form class="actions" name="fa0001" action="/cgi-bin/forum/f1/topic1.html">
80     <!-- .... см ниже .... -->
81         <input type="hidden" name="id" value="0001">
82         <input type="hidden" name="author" value="В. Пупкин">
83         <input type="submit" name="edit" value="Редактировать">
84         <input type="submit" name="delete" value="Удалить">
85         <input type="submit" name="move" value="Переместить в другую тему">
86    </form>
87    </div>
88   
89  Кроме того, в элементе c классом message должна присутствовать форма
90  с классом actions.
91  В ней должны присутсвовать следующие поля
92  1. Скрытое поле id
93  2. Скрытое поле author  
94  3. Кнопка edit
95  4. Кнопка delete
96  5. Кнопка move
97  6. Кнопка reply (заменяет собой ссылку с классом mreply)
98
99
100
101  Клиент-сайд скрипт должен уметь скрывать кнопку move, если пользователь
102  не является модератором, а также кнопки edit и delete, если
103  пользователь не является модератором или автором сообщения(т.е. значение куки
104  sluser не совпадает с содержимым скрытого поля author)
105
106
107  Определять какие кнопки и ссылки являются ссылками на  форумный скрипт
108  и должны скрываться и показываться в зависимости от прав доступа,
109  следует по атрибуту href ссылки и атрибуту action формы в сочетании с
110  атрибутом name у соответствующей кнопки. (кнопкой считаются input
111  type=submit и input type=image).
112
113  В разделе head у шаблона должны присутствовать тэги link вида
114 1. <link href="forum" rel="forum-script">
115  По общим правилам подстановки серверный скрипт при обработке шаблона
116  заменит href этого элемента на собственную url.
117
118  Соответственно формы с action равной этой URL следует рассматривать
119  как подлежащие обработке и искать в них кнопки с именами,
120  соответствующими именам операций. И ссылки с href=эта url?параметры
121  В ссылке следует искать параметр вида имя-операции. 
122 2. <link href="forum" rel="forum-user-list">
123         Содержимое href этого скрипта может быть использовано client-side
124         скриптом для формирования ссылки на страничку локального
125         пользователя форума (в случае если имя пользователя начинается с
126         http:://, это OpenID-пользователь и его страничка находстия по URL,
127         совпрадающей с именем пользователя.
128
129
130
131
132  Если кука sluser не определена,
133  то желательно также скрыть кнопку reply и ссылку с классом mreply, если
134  только в шаблоне формы reply не предусмотрены поля, позволяющие
135  залогиниться в момент отправки реплики.
136
137  Для получения информации о правах текущего пользователя в форуме нужно
138  запросить (через XMLHttpRequest) файл perms.txt из текущей директории
139  (где расположена текущая страница) и выше по иерархии вплоть до корня
140  форма. Корнем форума является директория, где расположен файл .forum
141  (не обязательно доступный для чтения по http. Ответ сервера 403 как и
142  ответ 200 надо рассматривать как "файл найден")
143
144  Кроме того на странице могут присутствовать элементы a с классами
145  next и prev.  В случае если тема разрослась более чем на одну страницу,
146  их href-атрибуты заменяются на ссылки на предыдущую следующую страницу.
147  Если тема состоит из одной страницы, ссылки будут вести на неё же.
148
149  Как вариант, можно использовать классы bnext и bprev. Если нет
150  предыдущей/следующей страницы, элементы a с такими классами будут
151  заменены на span. 
152
153 Страница списка тем (головная страница форума)
154
155 Может иметь элемент с классом annotation, описывающий форум в целом (его
156 создатель, вводный текст и т.д. устроенный внутри аналогично элементу
157 списка форумов (см ниже). Если в шаблоне присутствует элемент meta
158 name="description", то туда помещается текстовое представление аннотации
159 форума.
160
161 Если в шаблоне присутствуют элементы с классом top-page, то они будут
162 сохранены только на головной странице форума, а при создании подфорумов
163 будут из их оглавлений удаляться.
164
165 Шаблоном описания конкретной темы является элемент с классом topic,
166 Содержащий элемент с классом title (название темы, должно быть
167 ссылкой), abstract (аннотация темы)
168 author (ссылка), date (дата создания темы), tlink (якорь для ссылок на
169 элемент списка тем ), last-updated и msgcount.  
170
171 Внутри элемента с классом topic должна присутствовать форма
172 с кнопками edit delete move setrights и скрытым полем  id. 
173 Кнопку setrights следует показывать только пользователю с правами
174 администратора.
175
176
177
178 элемент с классом topic должен быть заключен в элемент с классом
179 topiclist.
180
181 При отсутствии тем на странице элементу с классом topiclist сервер
182 приписывает атрибут style="display: none;".
183
184 При добавлении новой темы элемент с классом topic копируется и
185 вставляется непосредственно за предыдущим
186
187
188 Кроме этого, cтраница должна иметь ссылку на форумный скрипт с
189 параметром newtopic=1 или форму с именем 
190 topicinfo и кнопкой submit с именем newtopic
191
192 Список подфорумов устроен аналогично списку тем.
193
194 Элемент списка форумов должен иметь класс forum, а форма/ссылка для
195 создания нового форума соотвесттвенно имя/класс newforum, а объемлющий
196 элемент, который скрывается при отсутствии подфорумов - класс forumlist 
197
198 В шаблоне элемента списка форумов может присутствовать элемент img
199 с классом logo. Если такой элемент обнаружен, то при наличии в
200 директории форума файла logo с расширением png, jpg или gif,  в src
201 пропиcывается ссылка на этот файл. Иначе прописывается ссылка на
202 templates/1x1.gif
203
204 Допускается также ситуация когда на одной странице присутствует и список
205 форумов, и список тем. (В этом случае если физически отсутствуют либо
206 те, либо другие, соответствующему элементу-шаблону выставляется
207 style="display: none");
208
209 Кроме этого на всех страницах рекомендуется иметь элемент-ссылку, который
210 отображает текущее имя пользователя. Этот элемент должен
211 конфигурироваться client-side cкриптом и показывать либо текст
212 "Зарегистрироваться" и аналогичный и вести на 
213 /cgi-bin/forum/<адрес текущей страницы?login=1
214 либо имя пользователя и вести на 
215 /cgi-bin/forum/<aдрес текущей страницы?user=1
216
217 Шаблоны служебных страниц (т.е. форм регистрации, логина и т.д.)
218
219 Служебные страницы форума (т.е. формы, выводимые скриптами) также
220 оформляются с помощью HTML-шаблонов. Если страница выдается в результате
221 POST-запроса уже содержащего требуемые данные, значения соответствующих
222 элементов ввода заменяются на эти данные.
223
224 В случае если во введенных данных произошла ошибка, сообщение об ошибке
225 скрипт вписывает в элемент с классом error вместо его innerHtml
226
227 Во всем шаблоне формы производится подстановка информации о текущем
228 пользователе, аналогично тому, как она производится в элементе с классом 
229 message в шаблоне темы.
230
231 Как правило, все скрипты получают следующую информацию 
232 1. Поле с именем операции и произвольным непустым значением
233   Возможные операции
234   reply
235   edit
236   delete
237   move
238   newtopic
239   newforum
240   getrights
241   login
242   register
243   userlist
244   profile
245   setrights
246   
247
248 2. Поле id с идентификатором комментария/темы/форума
249
250 Это поле должно быть обязательно проброшено через форму как скрытое
251 поле.
252
253 3. Поле returnto - url куда направить пользователя после успешного
254 завершения операции.  Если эта форма присутствует в шаблоне, но скрипт
255 вызывается без соответствующего значения в url или postdata, это поле
256 заполняется значением заголовка referer http-запроса.
257
258 Обработка форматированного (размеченного) текста:
259
260 В некоторые поля форм (текст реплики, подпись пользователя) должен
261 вводиться форматированный текст.
262
263 Такому полю должно соответствовать поле с именим имя_format (например, 
264 полю text соотвествует поле text_format, полю signature -
265 signature_format). Поле format может принимать одно из трех значений
266 - html, bbcode и text. Если поле format имеет значение html, то
267 содержимое соответствующего текстового поля рассматривается как html,
268 подвергается чистке от небезопасных тэгов и сохраняется в таком виде.
269 Если поле format имеет значение text, то спецсимволя эскейпятся, а
270 переводы строки заменяются на теги <br>.
271
272 Если поле имеет значение bbcode, то обрабатываются управляющие
273 последовательности bbcode.
274
275 Наличие URL в тексте проверяется независимо от формата.
276
277
278  Скрипт входа в систему (операция login)
279  Форма с именем login содержит поля name и password
280  Может также содержать  checkbox с именем bindip (привязка
281  авторизационной куки к IP)
282
283  При авторизации по OpenID используется поле openidsite.
284  Его значение интерпретируется как шаблон для операции sprintf, который
285  должен содержать один спецификатор формата %s, куда подставляется имя
286  пользователя.
287
288  Если поле openidsite имеет пустое значение, пользователь
289  рассматривается как локальный. Если непустое, то как
290  openid-пользователь.
291
292  Кнопка submit называется login
293
294  Форма регистрации нового пользователя (операция register, форма с
295  именем register)
296  Содержит поля user 
297  pass1 pass2 comment 
298  Может также содержать любые дополнительные поля информации о
299  пользователе. Они будут сохранены в списке пользователей
300  и могут потом выводиться в шаблонах рядом с информацией об авторе.  
301  Скрытое поле required содержит список полей, которые обязательно
302  требуются при регистрации. Поля user, pass1 и pass2 туда включать не
303  следует.
304  Скрытое поле ignore содержит список полей, которые НЕ НУЖНО
305  сохранять в качестве информации о пользователе. Поля user, pass1, pass2
306  и bindip туда включать не нужно. Так же если в форме присутствуют поля 
307  avatar и avatarfile, поле avatarfile будет автоматически включено в
308  этот список, а поле avatar при наличии зааплоаженного файла будет
309  заменено на URL к этому файлу.
310  
311  Параметр restricted_userinfo в конфигурационном файле форума позволяет
312  задать список полей, которые пользователь не имеет права редактировать
313  сам, все равно в процессе регистрации или при редактировании профиля.
314
315  Поля, которые, при их наличии, обрабатываются скриптом форума
316  специальным образом
317
318  1. avatar/avatarfile - картинка пользователя. Поле avatarfile
319  (зааплоаженная картинка) имеет приоритет над avatar (внешняя URL)
320  В случае если задано avatarfile, в информации о пользователе
321  сохраняется поле avatar с URL к этой картинке
322
323  2. signature - обычно поле с форматированным текстом. Дописывается в
324  конец каждого созданного данным пользователем сообщения
325
326  3. email - если не пусто, то  проверяется на корректность посредством 
327     модуля EMail::Valid
328
329  4. status - если имеет значение disabled, то данному пользователю
330  запрещен вход на форум до тех пор, пока администратор форума не изменит
331  статус. В случае, если требуется подтверждение регистрации модератором
332  рекомендуется прописывать это поле в restricted_user_info и указывать в
333  конфигурациии форума default_status = disabled,
334
335 Скрипт отправки комментария
336         
337 Операция reply  
338   поля subject 
339   text (тэг textarea)
340   text_format
341   Можно также включать (динамически добавлять) поля file upload image1
342   image2 etc.
343   кнопка submit называется reply.
344   Данная форма может также включать поля формы login. Т.е.
345   поддерживается аутентификация пользователя одновременно с отправкой
346   комментария.
347
348   В силу технических ограничений,  одновременно с регистрацией по OpenID
349   невозможен upload файлов и отправка комментариев длинной более 2-4Кб.
350   Точный предел размера комментария зависит от длины URL форума  и
351   пределов размера URL, установленных при компиляции веб-сервера форума
352   и веб-сервера openid-сервера.
353
354
355 Скрипт создания новой темы или нового форума
356   
357   поля 
358   subject 
359   text 
360   text_format
361   urlname.
362   При создании форума еще может присутствовать file upload field
363   logo. Зааплоаженный туда файл помещается в директрию форума
364   с именем logo и расширением соответствующим расширению исходного
365   файла.
366
367
368   В последнее поле следует запретить
369   ввод символов нелатинского алфавита '/' и '?'
370
371 Cкрипт просмотра списка пользователей (опция userlist)
372
373    Элемент с классом user содержит элементы с классами, имена которых 
374    соответствуют именам свойств пользователей. 
375    Если внутри элемента присутствует элемент с классом formoder или
376    foradmin, то при просмотре страницы пользователем, не имеющим
377    соответствующих прав, этот кусок выкусывается на сервере.
378    Должен присутствовать элемент  именем profile имеющий тип a.
379    Его атрибут href заменяется на ссылку на скрипт редактирования
380    профайла. Форм этот шаблон вообще не содержит
381
382 Скрипт раздачи прав модерирования (setrights)   
383
384   Дает права модераторов на определенный форум/тему, или права
385   администраторов.       
386
387   В результате заполнения формы поле с именем moderators должно
388   содержать список модераторов для данной темы (соответствующей
389   url страницы в pathinfo) поле с именем  administrators список всех
390   администраторов данного сайта.
391
392 Скрипт редактирования свойств пользователя.
393   Аналогичен скрипту регистрации, но администратору еще видно поле
394   status. (пользователю - тоже видно, но input или select заменяется на
395   обычный текст)
396   
397   Может присутствовать кнопка resetpassword (показывается только
398   администраторам)
399
400
401 Встраивание служебных форм непосредственно в страницы форума
402
403   Форма, содержащая вышеперечиленные поля, имеющая метод POST и имеющая в поле
404   action="forum/<url страницы, где она размещена)
405   может быть встроена непосредственно в страницу темы или списка
406   тем/списка форумов. Желательно чтобы она делалась видимой только при
407   нажатии кнопки. Отправка этой формы приводит к выполнению необходимого
408   действия без  показа страницы скрипта.
409
410 Служебные шаблоны
411
412 Шаблон с именем error.html используется для выдачи фатальных ошибок
413 скрипта. (когда нет возможности показать форму). Он должен содержать
414 элемент с классом error, innerHTML которого будет заменен на сообщение
415 об ошибке.