Краткое описание пакета ng.content.annotation
=============================================

Пакет предоставляет коллекцию контент-аннотаций, позволяющих снабжать
текстовые материалы, публикуемые с использованием пакета
[name:ng.content.article], дополнительными описаниями, в формате "название -
значение", зависящими от той роли, которую играет статья на сайте. В
настоящее время реализованы аннотации для словарной статьи, события и
продукта.

Список аннотаций
----------------

    dict
        Аннотация "словарная статья" предназначена для статей, используемых
        под описания определений словаря. Использование аннотации
        включается для компонентов с интерфейсом **IDictAnnotationAble**.
        Аннотация предоставляет следующие поля:
        
        keyword: Tuple of TextLine
            Список ключевых слов, связанных с данной статьей;

        area : TextLine from Choice
            Тематическая область, которой принадлежит данный термин, хотя по
            смыслу поле аналогично т.н. "тегу", в настоящий момент оно
            используется в рамках эксперимента по полуавтоматическому
            тегированию;

        wikiword: TextLine
            Слово, используемое для поиска значения слова на wikipedia,
            самом большом, на сегодняшний день, толковом словаре в Интернет;
            
        gender: TextLine from Choice
            Пол словарной статьи, в настоящее время жестко прошит и может
            быть 'Male','Middle' или 'Female', что используется при разрешении
            споров о правилах написания некоторых терминов на русском языке;
            
        suffixes: TextLine
            Суффиксы (родительного падежа), используется при разрешении споров
            о правилах написания некоторых терминов на русском языке;


    event
        Аннотация "событие" используется для анонсирования будущих событий. 
        Использование аннотации включается для компонентов с интерфейсом
        **IEventAnnotationAble**. Аннотация предоставляет следующие поля:
        
        data : DateTime
            Дата и время начала события
            
        durablility : TextLine
            Продолжительность события
            
        place : Text
            Место проведения события

    product
        Аннотация "продукт" используется для описания продуктов на нашем
        сайте. Использование аннотации включается для компонентов с
        интерфейсом **IProductAnnotationAble**. Аннотация включает в себя
        следующие поля:
        
        title : TextLine
            Точное название продукта (такое, которое используется при поиске
            пакетов, например на [keyword:PyPI]);
             
        ispypi : Bool
            Если это флаг установлен, то продукт размещен на [keyword:PyPI];
            
        repository : URI
            Репозиторий продукта, ссылка может быть пустой;

        archive : URI
            Архив, откуда можно скачать пакет с продуктом, обычно пустая ссылка;

    docshort
        Аннотация "краткое описание документа" используется для облегчения
        интеграции продуктов со стандартами иерархии **ng**. Поля аннотации
        аналогичны описанным в [name:ng.content.article.txt] для IDocShort.

    profile
        Аннотация "профиль пользователя" позволяет использовать статью или 
        раздел в качестве профиля пользователя :), она хранит информацию о
        пользователе, имеющим аккаунт на сайте. Использование аннотации включается
        для компонентов с интерфейсом **IProfileAnnotationAble**. Аннотация
        включает в себя следующие поля:
        
        email
            Адрес электронной почты;

        nickname
            Ник;

        interest
            Область интересов, выбирается из списка,
            может быть выбрано несколько областей интересов;

        city
            Город, в котором находится пользователь;

        birthday
            Дата рождения;

        sex
            Выбор одного из вариантов;
            

    friendship
        Позволяет поддерживать отношения "дружбы" между профилями
        пользователей (или другими аналогичными объектами, в принципе это не
        важно).

    friendobjectqueue
	Позволяет вести ленту сообщений друзей, список которых определеятся
	аннотацией **friendship**.

    ### [name:недописано]

Интеграция аннотаций с другими продуктами
-----------------------------------------

Ассоциирование с аннотациями выполнено по технологии, описанной в статьях
[name:Аннотации.txt] и [name:Адаптация как способ ассоциации компонент.txt],
поэтому для ассоциации каждой из перечисленных аннотаций с другим компонентом
достаточно того, чтобы этот компонент адаптировался к **IAnnotations** и
предоставлял интерфейс, "включающий" использование соответствующей аннотации
(приведен в списке видов аннотаций выше). Возможно динамическое переключение
интерфейсов и активация соответствующих аннотаций. При этом у компонента
появляются новые вкладки, соответствующие активированным аннотациям.
Динамическое переключение выполняется вложенным продуктом
**ng.content.annotation.annotationswitcher**, для активации которого
достаточно декларировать то, что класс реализует интерфейс
**IAnnotationSwitcher** (и интерфейс **IAttributeAnnotatable** или
аналогичный) и указать права доступа к ним::

  <class class="ng.content.remotearticle.remotearticle.remotearticle.RemoteArticle">
    <implements 
        interface="ng.content.annotation.annotationswitcher.interfaces.IAnnotationSwitcher" 
        />
    <implements 
        interface="zope.annotation.interfaces.IAttributeAnnotatable" 
        />
    <require 
        interface="ng.content.annotation.annotationswitcher.interfaces.IAnnotationSwitcher" 
        permission="zope.View" 
        />
    <require 
        set_schema="ng.content.annotation.annotationswitcher.interfaces.IAnnotationSwitcher" 
        permission="zope.ManageContent" 
        />
  </class>

Расширение списка аннотаций
---------------------------

Список аннотаций легко может быть расширен при соблюдении двух условий:

 1. Продукт с новой аннотацией сделан в соответствии с рекомендациями статьи
    [name:Аннотации.txt] (продукт [name:ng.content.annotation] является
    хорошей иллюстрацией к этой статье);
    
 2. Интерфейс активации аннотации привязан к интерфейсу
    **IAnnotationSwitcher** декларацией следующего вида::
    
        class IAnnotationSwitcherDict(IAnnotationSwitcher,IDictAnnotationAble) :
            """Use as dictionary """

    и явно зарегистрирован как интерфейс::
    
          <interface
            interface=".interfaces.IAnnotationSwitcherDict"
            />

    Тогда он автоматически включится в меню управления аннотациями.
         

Заключение
----------

Хотя **ng.content.annotation** написан с исключительным прицелом на
использование с **ng.content.article**, использованная технология
модуляризации позволяет легко объеденить его с любым продуктом при
минимальных трудозатратах. Возможность расширения списка аннотаций
является дополнительным качеством, обеспечивающим живучесть продуктов на его
основе.

Более удобного редактирования можно достичь используя формы, основанные на
продукте [name:ng.zcmlmultiform]: в этом случае поля всех форм будут
открываться на одной странице.
