Добавил замену "." в имени пользователя на "\.", поскольку, попадая в регулярное...

[oss/stilllife.git] / doc / templates.txt

diff --git a/doc/templates.txt b/doc/templates.txt
index bc3b56f8bc85ecfdfc0c1821154d95e849dcd82d..a9952445328a2f14fbdd5036778fd9ac12d5d4a7 100644 (file)
--- a/doc/templates.txt
+++ b/doc/templates.txt
@@ -43,10 +43,17 @@ author - ник автора сообщения. innerHtml заменяется
                Следует учитывать что в случае openId авторизации в этот элемент
                будет помещен элемент a со ссылкой на домашнюю страницу 
 mdate  - дата публикации сообщения  innerHtml заменяется на дату
                Следует учитывать что в случае openId авторизации в этот элемент
                будет помещен элемент a со ссылкой на домашнюю страницу 
 mdate  - дата публикации сообщения  innerHtml заменяется на дату

-avatar - элемент img атрибут src  которого заменияется на аватар автора
-astatus - статус автора на форуме innerHtml заменяется на статус
-acomment - комментарий к нику, введенный автором при регистрации.
+avatar - элемент img атрибут src  которого заменияется на аватар автора,
+       или на templates/1x1.gif если у автора нет аватара.
+ap-status - статус автора на форуме innerHtml заменяется на статус
+ap-comment - комментарий к нику, введенный автором при регистрации.

          innerHtml заменяется на комментарий
          innerHtml заменяется на комментарий

+И прочие классы с префиксом ap-, innerHtml которых заменяеняется 
+на соответствущие поля из профайла автора. Если поле имеет в имени 
+подчерк, допустимо вместо подчерка использовать дефис "-" в названии
+класа.  
+
+

 msubject - тема сообщения. Заменяется innerHtml          
 mtext - текст сообщения. innerHtml заменяется на отформатированный текст 
 mreply - ссылка на скрипт ответа. Атрибут href будет заменен на
 msubject - тема сообщения. Заменяется innerHtml          
 mtext - текст сообщения. innerHtml заменяется на отформатированный текст 
 mreply - ссылка на скрипт ответа. Атрибут href будет заменен на


@@ -93,8 +100,9 @@ mreply - ссылка на скрипт ответа. Атрибут href буд
 
  Клиент-сайд скрипт должен уметь скрывать кнопку move, если пользователь
  не является модератором, а также кнопки edit и delete, если
 
  Клиент-сайд скрипт должен уметь скрывать кнопку move, если пользователь
  не является модератором, а также кнопки edit и delete, если

- пользователь не является автором сообщения, т.е. значение куки
- sluser не совпадает с содержимым скрытого поля author
+ пользователь не является модератором или автором сообщения(т.е. значение куки
+ sluser не совпадает с содержимым скрытого поля author)
+

 
  Определять какие кнопки и ссылки являются ссылками на  форумный скрипт
  и должны скрываться и показываться в зависимости от прав доступа,
 
  Определять какие кнопки и ссылки являются ссылками на  форумный скрипт
  и должны скрываться и показываться в зависимости от прав доступа,


@@ -102,35 +110,36 @@ mreply - ссылка на скрипт ответа. Атрибут href буд
  атрибутом name у соответствующей кнопки. (кнопкой считаются input
  type=submit и input type=image).
 
  атрибутом name у соответствующей кнопки. (кнопкой считаются input
  type=submit и input type=image).
 

- Ð\92 Ñ\80азделе head Ñ\83 Ñ\88аблона должен пÑ\80иÑ\81Ñ\83Ñ\82Ñ\81Ñ\82воваÑ\82Ñ\8c Ñ\82Ñ\8dг link вида
- <link href="forum" rel="forum-script">
+ Ð\92 Ñ\80азделе head Ñ\83 Ñ\88аблона должнÑ\8b пÑ\80иÑ\81Ñ\83Ñ\82Ñ\81Ñ\82воваÑ\82Ñ\8c Ñ\82Ñ\8dги link вида
+1. <link href="forum" rel="forum-script">

  По общим правилам подстановки серверный скрипт при обработке шаблона
  заменит href этого элемента на собственную url.
  По общим правилам подстановки серверный скрипт при обработке шаблона
  заменит href этого элемента на собственную url.

+

  Соответственно формы с action равной этой URL следует рассматривать
  как подлежащие обработке и искать в них кнопки с именами,
  соответствующими именам операций. И ссылки с href=эта url?параметры
  В ссылке следует искать параметр вида имя-операции. 
  Соответственно формы с action равной этой URL следует рассматривать
  как подлежащие обработке и искать в них кнопки с именами,
  соответствующими именам операций. И ссылки с href=эта url?параметры
  В ссылке следует искать параметр вида имя-операции. 

+2. <link href="forum" rel="forum-user-list">
+       Содержимое href этого скрипта может быть использовано client-side
+       скриптом для формирования ссылки на страничку локального
+       пользователя форума (в случае если имя пользователя начинается с
+       http:://, это OpenID-пользователь и его страничка находстия по URL,
+       совпрадающей с именем пользователя.

 
 
 
 

- Для того чтобы узнать является ли текущий пользователь модератором
- данного форума, нужно запросить с сервера (через XmlHttpRequest)
- файл .moderators лежащий рядом с текущим файлом и далее вверх по
- иерархии. Эти файлы представляют собой простые текстовые файлы с именем 
- пользователя в каждой строке.

 
 

- В корне форума имеется аналогичный файл .admins.
-
- Можно также запросить файл .banned.
-
- Все эти действия являются необязательными. Если на клиентской стороне
- они не будут выполнены и у пользователя появится возможность нажать на
- кнопку выполнения операции, на которую у него нет прав, операция будет
- заблокирована на сервере.
-
- 

 
  Если кука sluser не определена,
 
  Если кука sluser не определена,

- то желательно также скрыть кнопку reply и ссылку с классом mreply.
+ то желательно также скрыть кнопку reply и ссылку с классом mreply, если
+ только в шаблоне формы reply не предусмотрены поля, позволяющие
+ залогиниться в момент отправки реплики.
+
+ Для получения информации о правах текущего пользователя в форуме нужно
+ запросить (через XMLHttpRequest) файл perms.txt из текущей директории
+ (где расположена текущая страница) и выше по иерархии вплоть до корня
+ форма. Корнем форума является директория, где расположен файл .forum
+ (не обязательно доступный для чтения по http. Ответ сервера 403 как и
+ ответ 200 надо рассматривать как "файл найден")

 
  Кроме того на странице могут присутствовать элементы a с классами
  next и prev.  В случае если тема разрослась более чем на одну страницу,
 
  Кроме того на странице могут присутствовать элементы a с классами
  next и prev.  В случае если тема разрослась более чем на одну страницу,


@@ -143,12 +152,21 @@ mreply - ссылка на скрипт ответа. Атрибут href буд
 
 Страница списка тем (головная страница форума)
 
 
 Страница списка тем (головная страница форума)
 

-Может иметь элемент с классом message, описывающий форум в целом (его
-создатель, вводный текст и т.д.
+Может иметь элемент с классом annotation, описывающий форум в целом (его
+создатель, вводный текст и т.д. устроенный внутри аналогично элементу
+списка форумов (см ниже). Если в шаблоне присутствует элемент meta
+name="description", то туда помещается текстовое представление аннотации
+форума.
+
+Если в шаблоне присутствуют элементы с классом top-page, то они будут
+сохранены только на головной странице форума, а при создании подфорумов
+будут из их оглавлений удаляться.

 
 Шаблоном описания конкретной темы является элемент с классом topic,
 
 Шаблоном описания конкретной темы является элемент с классом topic,

-устроенный аналогично message (показывается текст и автор первой реплики
-темы) с той разницей, что элемент с классом subject должен быть ссылкой.
+Содержащий элемент с классом title (название темы, должно быть
+ссылкой), abstract (аннотация темы)
+author (ссылка), date (дата создания темы), tlink (якорь для ссылок на
+элемент списка тем ), last-updated и msgcount.  

 
 Внутри элемента с классом topic должна присутствовать форма
 с кнопками edit delete move setrights и скрытым полем  id. 
 
 Внутри элемента с классом topic должна присутствовать форма
 с кнопками edit delete move setrights и скрытым полем  id. 


@@ -156,22 +174,37 @@ mreply - ссылка на скрипт ответа. Атрибут href буд
 администратора.
 
 
 администратора.
 
 

-Кроме этого, cтраница должна иметь ссылку с классом newtopic или форму с именем 
-newtopic и кнопкой submit с именем newtopic

 
 

+элемент с классом topic должен быть заключен в элемент с классом
+topiclist.
+
+При отсутствии тем на странице элементу с классом topiclist сервер
+приписывает атрибут style="display: none;".
+
+При добавлении новой темы элемент с классом topic копируется и
+вставляется непосредственно за предыдущим

 
 

-Страница списка форумов (головная страница сайта, страница форума с
-подразделами)

 
 

-Устроена аналогично странице списка тем.
+Кроме этого, cтраница должна иметь ссылку на форумный скрипт с
+параметром newtopic=1 или форму с именем 
+topicinfo и кнопкой submit с именем newtopic
+
+Список подфорумов устроен аналогично списку тем.

 
 Элемент списка форумов должен иметь класс forum, а форма/ссылка для
 
 Элемент списка форумов должен иметь класс forum, а форма/ссылка для

-создания нового форума соотвесттвенно имя/класс newforum. 
+создания нового форума соотвесттвенно имя/класс newforum, а объемлющий
+элемент, который скрывается при отсутствии подфорумов - класс forumlist 
+
+В шаблоне элемента списка форумов может присутствовать элемент img
+с классом logo. Если такой элемент обнаружен, то при наличии в
+директории форума файла logo с расширением png, jpg или gif,  в src
+пропиcывается ссылка на этот файл. Иначе прописывается ссылка на
+templates/1x1.gif

 
 Допускается также ситуация когда на одной странице присутствует и список
 форумов, и список тем. (В этом случае если физически отсутствуют либо
 те, либо другие, соответствующему элементу-шаблону выставляется
 
 Допускается также ситуация когда на одной странице присутствует и список
 форумов, и список тем. (В этом случае если физически отсутствуют либо
 те, либо другие, соответствующему элементу-шаблону выставляется

-style="visibility: hidden");
+style="display: none");

 
 Кроме этого на всех страницах рекомендуется иметь элемент-ссылку, который
 отображает текущее имя пользователя. Этот элемент должен
 
 Кроме этого на всех страницах рекомендуется иметь элемент-ссылку, который
 отображает текущее имя пользователя. Этот элемент должен


@@ -222,12 +255,39 @@ message в шаблоне темы.
 вызывается без соответствующего значения в url или postdata, это поле
 заполняется значением заголовка referer http-запроса.
 
 вызывается без соответствующего значения в url или postdata, это поле
 заполняется значением заголовка referer http-запроса.
 

- Скрипт регистрации (операция login)
+Обработка форматированного (размеченного) текста:
+
+В некоторые поля форм (текст реплики, подпись пользователя) должен
+вводиться форматированный текст.
+
+Такому полю должно соответствовать поле с именим имя_format (например, 
+полю text соотвествует поле text_format, полю signature -
+signature_format). Поле format может принимать одно из трех значений
+- html, bbcode и text. Если поле format имеет значение html, то
+содержимое соответствующего текстового поля рассматривается как html,
+подвергается чистке от небезопасных тэгов и сохраняется в таком виде.
+Если поле format имеет значение text, то спецсимволя эскейпятся, а
+переводы строки заменяются на теги <br>.
+
+Если поле имеет значение bbcode, то обрабатываются управляющие
+последовательности bbcode.
+
+Наличие URL в тексте проверяется независимо от формата.
+
+
+ Скрипт входа в систему (операция login)

  Форма с именем login содержит поля name и password
  Форма с именем login содержит поля name и password

- Может также содержать  checkbox с именем ipbind (привязка
+ Может также содержать  checkbox с именем bindip (привязка

  авторизационной куки к IP)
 
  авторизационной куки к IP)
 

- (OpenID пока не описываем)
+ При авторизации по OpenID используется поле openidsite.
+ Его значение интерпретируется как шаблон для операции sprintf, который
+ должен содержать один спецификатор формата %s, куда подставляется имя
+ пользователя.
+
+ Если поле openidsite имеет пустое значение, пользователь
+ рассматривается как локальный. Если непустое, то как
+ openid-пользователь.

 
  Кнопка submit называется login
 
 
  Кнопка submit называется login
 


@@ -235,27 +295,77 @@ message в шаблоне темы.
  именем register)
  Содержит поля user 
  pass1 pass2 comment 
  именем register)
  Содержит поля user 
  pass1 pass2 comment 

- avatar (поле ввода URL) или avatarfile(file upload field)
- email 

  Может также содержать любые дополнительные поля информации о
  Может также содержать любые дополнительные поля информации о

- пользователе (кроме поля status). Они будут сохранены в списке пользователей
+ пользователе. Они будут сохранены в списке пользователей

  и могут потом выводиться в шаблонах рядом с информацией об авторе.  
  Скрытое поле required содержит список полей, которые обязательно
  требуются при регистрации. Поля user, pass1 и pass2 туда включать не
  следует.
  Скрытое поле ignore содержит список полей, которые НЕ НУЖНО
  и могут потом выводиться в шаблонах рядом с информацией об авторе.  
  Скрытое поле required содержит список полей, которые обязательно
  требуются при регистрации. Поля user, pass1 и pass2 туда включать не
  следует.
  Скрытое поле ignore содержит список полей, которые НЕ НУЖНО

- сохранять в качестве информации о пользователе.
+ сохранять в качестве информации о пользователе. Поля user, pass1, pass2
+ и bindip туда включать не нужно. Так же если в форме присутствуют поля 
+ avatar и avatarfile, поле avatarfile будет автоматически включено в
+ этот список, а поле avatar при наличии зааплоаженного файла будет
+ заменено на URL к этому файлу.
+ 
+ Параметр restricted_userinfo в конфигурационном файле форума позволяет
+ задать список полей, которые пользователь не имеет права редактировать
+ сам, все равно в процессе регистрации или при редактировании профиля.
+
+ Поля, которые, при их наличии, обрабатываются скриптом форума
+ специальным образом
+
+ 1. avatar/avatarfile - картинка пользователя. Поле avatarfile
+ (зааплоаженная картинка) имеет приоритет над avatar (внешняя URL)
+ В случае если задано avatarfile, в информации о пользователе
+ сохраняется поле avatar с URL к этой картинке
+
+ 2. signature - обычно поле с форматированным текстом. Дописывается в
+ конец каждого созданного данным пользователем сообщения
+
+ 3. email - если не пусто, то  проверяется на корректность посредством 
+    модуля EMail::Valid
+
+ 4. status - если имеет значение disabled, то данному пользователю
+ запрещен вход на форум до тех пор, пока администратор форума не изменит
+ статус. В случае, если требуется подтверждение регистрации модератором
+ рекомендуется прописывать это поле в restricted_user_info и указывать в
+ конфигурациии форума default_status = disabled,

 
 Скрипт отправки комментария
        
 
 Скрипт отправки комментария
        

-  поля subject text (тэг textarea)
+Операция reply 
+  поля subject 
+  text (тэг textarea)
+  text_format

   Можно также включать (динамически добавлять) поля file upload image1
   image2 etc.
   Можно также включать (динамически добавлять) поля file upload image1
   image2 etc.

-  кнопка submit называется reply
+  кнопка submit называется reply.
+  Данная форма может также включать поля формы login. Т.е.
+  поддерживается аутентификация пользователя одновременно с отправкой
+  комментария.
+
+  В силу технических ограничений,  одновременно с регистрацией по OpenID
+  невозможен upload файлов и отправка комментариев длинной более 2-4Кб.
+  Точный предел размера комментария зависит от длины URL форума  и
+  пределов размера URL, установленных при компиляции веб-сервера форума
+  и веб-сервера openid-сервера.
+

 
 Скрипт создания новой темы или нового форума
   
 
 Скрипт создания новой темы или нового форума
   

-  поля subject text imageN и urlname. В последнее поле следует запретить
+  поля 
+  subject 
+  text 
+  text_format
+  urlname.
+  При создании форума еще может присутствовать file upload field
+  logo. Зааплоаженный туда файл помещается в директрию форума
+  с именем logo и расширением соответствующим расширению исходного
+  файла.
+
+
+  В последнее поле следует запретить

   ввод символов нелатинского алфавита '/' и '?'
 
 Cкрипт просмотра списка пользователей (опция userlist)
   ввод символов нелатинского алфавита '/' и '?'
 
 Cкрипт просмотра списка пользователей (опция userlist)


@@ -276,7 +386,7 @@ Cкрипт просмотра списка пользователей (опци
 
   В результате заполнения формы поле с именем moderators должно
   содержать список модераторов для данной темы (соответствующей
 
   В результате заполнения формы поле с именем moderators должно
   содержать список модераторов для данной темы (соответствующей

-  url страницы id) поле с именем  administrators список всех
+  url страницы в pathinfo) поле с именем  administrators список всех

   администраторов данного сайта.
 
 Скрипт редактирования свойств пользователя.
   администраторов данного сайта.
 
 Скрипт редактирования свойств пользователя.