Описание продукта reference :

    Введение:
    
        Суть современного веб - это многочисленные связи между страницами,
        которые создаются ссылками на эти страницы. Объекты Zope - это
        модель такого веб, и при работе с которой довольно часто (если не
        сказать повсеместно) возникает необходимость введения аналогичных
        сущностей - связей. Один из способов такого связывания дается
        продуктом reference, который позволяет осмысленным образом связывать
        между собой любые объекты Zope.
    
    Пример задачи, решаемой с помощью reference:
    
        Данный пример должен помочь вам осознать, что без использования
        данного продукта не должен обходиться ни один сайт, а создание
        ссылок между объектами каким-то другим способом - либо трата
        времени, либо попытка изобретения уже реально существующего
        велосипеда.
        
        Итак, предположим, что у нас есть 2 объекта, к примеру A и B,
        содержащие некоторую родственную информацию, причём такую, что,
        например, после ознакомления с информацией из объекта А посетитель
        непременно захочет ознакомиться и с информацией из объекта Б, а если
        и не захочет, то целесообразно информацию из объекта Б постителю,
        как минимум, порекомендовать как родственную той, на которую он
        смотрит.
        
        Естественным решением данной проблемы является, как было сказано выше,
        создание некоторого объекта (связи), в котором будет храниться информация
        об одном из связываемых объектов, информация о типе связи, а также
        информация, которая будет отображаться для каждого из объектов в виде
        приглашения посмотреть родственный объект.
        
        Например, объект А содержит описание кошачьих консервов, а объект B
        описание сухого корма для кошек. Соответственно, объект связь будет
        хранить ссылки на объекты A и B, а также текст "См.также информацию
        по сухому корму" для объекта А и текст "См. также информацию о кошачьих
        консервах" для объекта B. Вот такая задача, помочь в решении которой
        призван продукт reference.
    
    Идея продукта:
    
        Как было сказано выше, для создания связи создается специальный
        объект, который называется "связь". Этот объект содержит ссылки на
        пару других объектов, образуя, таким образом, связь между ними.
        Связи между объектами являются типизированнными -- для каждого типа
        связей можно сделать ряд настроек, общих для всех связей этого типа.
        Отличительной особенностью типа является то, какие _типы_ объектов
        связываются и как они при этом называются.
        
        Такого устройства ссылок вполне достаточно для того, чтобы
        использовать продукт просто и эффективно. Рассмотрим этапы, на
        которые подразделяется использование продукта и опишем то, что
        требуется сделать на каждом из них.
        
    Использование:
    
        1. Конфигурирование в zcml:
        
           Первое, что необходимо сделать для использования продукта, это
           определиться с тем, между какими объектами будут создаваться ссылки.
           После того, как это произошло, необходимо запрограммировать
           придуманное в zcml файле с помощью директив reference (директива
           продукта) и class (директива zope). Директива reference имеет
           следующие атрибуты:
           
               name -- имя класса, который будет представлять собой связь;

               title1 -- текст, характеризующий первый объект из связываемых;

               title2 -- текст, характеризующий второй объект из связываемых;
        
               interface1 -- интерфейс первого из связываемых объектов;

               interface2 -- интерфейс второго из связывемых объектов;

               iscommutative -- ссылка выглядит неотличимо в обе стороны (все
                   равно с какой стороны ее ставить;
               
               isreflexive -- ссылка может указывать на себя (в настоящий
                   момент не используется);
               
           Как видно, эта директива создаёт класс связи и сохраняет
           в нём всю необходимую информацию для того, чтобы повязать элементы,
           предоставляющие указанные интерфейсы данных классов.
            
           После объявления нового класса, для этого класса, как и для
           всех остальных, необходимо указать предоставляемый им интерфейс и
           права доступа для его использования, что делается стандартным для
           zope3 образом с помощью директивы class.
            
           Последним действием, которое необходимо выполнить для получения
           возможности связывать объекты, предоставляющие некоторый интерфейс,
           является принудительное добавление к таким объектам интерфейсов
           reference.referenceannotation.interfaces.IReferable и
           zope.annotation.interfaces.IAtributeAnnotatable
           с помощью субдирективы implements директивы class, что также
           делается стандартным для zope образом.
            
           Пример указанных директив для связи, например, двух каких-либо
           объектов Folder (об этом подробнее в следующем разделе), может
           выглядеть так (обратите внимание, что связывыются интерфейсы, а
           не конкретные объекты):
            
               <reference
                   name="folder2folder"
                   title1="См.также"
                   title2="См.также"
                   interface1="zope.app.folder.interfaces.IFolder"
                   interface2="zope.app.folder.interfaces.IFolder"
                   iscommutative="True"
                   isreflexive="True"
               />
            
               <class
                   class="reference.referencezcml.metaconfigure.folder2folder">
                 <require
                     interface="reference.reference.interfaces.IReferenceBase"
                     permission="zope.ManageContent"
                 />
                   
               </class>

               <class
                   class="zope.app.folder.folder.Folder">
                 <implements
                     interface="reference.reference.interfaces.IReferenceBase"
                 />
                 <implements
                     interface="zope.annotation.interfaces.IAttributeAnnotatable"
                 />                    
               </class>

           Указанный zcml-код позволяет указать то, что необходимо
           предоставить возможность связывать между собой 2 любых объекта,
           предоставляющих интерфейс IFolder.
           
        2. Установка продукта и ссылок
        
           Продукт на основе референс представляет собой, по сути дела, один
           единственный zcml-файл, в котором, в указанном выше виде задаются
           необходимые параметры возможных связей. Пример такого файла можно
           найти в папке demo, который содержит примеры zcml-директив,
           позволяющих впоследствии создать ссылки между самими различными
           объектами. Для активирования этого продукта скопируйте файл из папки
           reference/demo/etc в ZOPE_INSTANCE/etc/package-includes и
           перезапустите zope. Если zope запустился, значит подукт успешно
           установлен.
           
           Остальные действия, необходимые для создания и
           использования ссылок между конкретными объектами следует
           проделывать руками, находясь в скине и сейчас мы узнаем как. В
           качестве примера опишем связывание двух папок, zcml-директивы для
           чего были описаны выше.

           Зайдите в zope, авторизуйтесь под администратором, создайте папку
           с именем test, создайте в ней сайт, добавьте в сайт-менеджер
           созданного сайта генератор уникальных идентификаторов (Unique Id
           Utility) с именем intids и зарегистрируйте его без имени с
           интерфейсом zope.app.intid.interfaces.IIntIds. Перейдите в
           созданную папку test (выйдите из сайт-менеджера), и создайте в ней
           2 объекта типа "Папка" (Folder) с идентификаторами A и B.

           Всё необходимое для связывания готово, теперь наша цель -- сделать
           так, чтобы папка A была связана с папкой B, а папка B, в свою
           очередь, была связана с папкой A. Приступим.

           Зайдите в папку А, перейдите на вкладку References. Обратите
           внимание на то, что все поля двух таблиц пустые и под одним из
           полей есть кнопка Paste (вставить), а под другим Copy (Копировать).
           Нажмите кнопку Copy для того, чтобы скопировать текущий объект
           (папка А) в буфер обмена. Перейдите в папку B, перейдите на
           вкладку References, нажмите кнопку Paste. В результате на месте
           кнопки paste появится список всех возможных ссылок между двумя
           объектами с данными интерфейсами (в нашем случае это объекты с
           интерфейсами IFolder, с каждым из которых связаны строки
           "см.также"). Отметьте флажок рядом с желаемым типом связи и
           нажмите кнопку "Add References". После этого можно смело считать,
           что ссылки установлены.
           
           В таблице имеющихся связей должна появиться ссылка на объект A
           с именем "см.также". Щёлкнув по этой ссылке вы попадёте на
           вкладку References объекта B, где щёлкнув по ссылке на объект А
           с именем "см.также" (именно эти имена и задавались в zcml
           директиве атрибутами title1 и title2) вы сможете при желании
           вернуться обратно к объекту A.

        3. Использование в дизайне

### Использование в дизайне означает способ, при помощи которого предоплагается кодировать ссылки
### в дизайне. Ну, правда, сейчас такого способа нет. Т.е. он есть, но мне не нравится

    Заключение:
    
        Как видно из описания, продукт reference решает крайне важную и
        повсеместно встречающуюся задачу, что делает его незаменимым
        инструментом для использования на любом сайте.
    
конец документа
