Краткое описание пакета
=======================

Пакет разработан как бибилиотека небольших адаптеров для разных темных
целей. 

Адаптер mtime
-------------

Адаптер mtime предназначен для получения врмемени модификации объекта.
Время модификации определяются на уровне IPersistent, что является
достаточно точным способом. Хотя, с временем модификации не обошлось без
уловок.

Адаптер адаптирует интерфейс IPersistent к IMTime, состав интерфейса
IMTime:

    mtime 
        Время последней модификации объекта

    strftime(format)
        Вернуть время, в формате определяемой строкой format, формат 
        которой совпадает с man strftime

Адаптер path
------------

Предназначен для получения пути от корневого объекта Zope до текущего.
Адаптирует любые объекты к интерфейсу IPath, в состав которого входят
следующие свойства:

    path
        Путь из имён (__name__) от корневого объекта до текущего

    titledpath
        Путь из названий (title) объектов от корневого до текущего

Для получения значений свойства title используется адаптер title.

Адаптер title
-------------

Предназначен для получения свойства title любого объекта. Адаптирует любой
объект к интерфейсу ITitle, в состав которого входят следующие свойства:

    title
        Название объекта

Если свойства нет в
явном виде, вместо него возвращается свойство title объекта, приведённого к
интерфейсу IZopeDublinCore. Если привести объект к IZopeDublinCore невозможно,
возвращается свойство __name__ объекта либо имя класса, экземпляром которого
является объект.


Адаптер nsinterface
-------------------
   
Определяется пространство имен nsinterface, позволяя приводить
текущий объект к нужному интерфейсу. Пример использования::

    <tal:block define="path context/++nsinterface++ng.adapter.IPath/path">
    
    </tal:block>
    
Применяется, в основном, в отладочных целях.

Адаптер namechooser
-------------------

Активация адаптера для контейнера позволяет выбрать в качестве названия
создаваемого объекта название, полученное от адаптера IDocTitle. Активация
адаптера производится присвоением контейнера интерфейса
ng.adapter.interfaces.INameChooserAble.

Несколько адаптеров к интерфейсу INameChooser
---------------------------------------------
Активация любой из этих адаптеров для контейнера приводит к тому, 
что имя объектов, создаваемых в этом контейнере будет выбираться на
основе названия, полученного от адаптеа IDocTitle. Чтобы активировать адаптер, контейнеру
должен быть назначен один из трех нижеперечисленных интерфейсов-маркеров:

NameChooser 
    Адаптер активируется интерфейсом ng.adapter.interfaces.INameChooserAble. Адаптер устанавливает __name__ в 
    значение, полученное от IDocTitle без каких-либо изменений.
    
NameChooserSafe    
    Адаптер активируется интерфейсом ng.adapter.interfaces.INameChooserAble. Перед установкой в качестве __name__, адаптер
    изменяет строку, полученную от IDocTitle так, чтобы исключить символы, не рекомендуемые к испоьлзованию в URL: '/', '?' и 
    некоторые другие. Кроме того, адаптер нормирует пробелы (выбрасывает повторные, концевые и ненужные).
    
NameChooserSafeWithoutSpaces
    Адаптер активируется интерфейсом ng.adapter.interfaces.INameChooserAble. Перед установкой в качестве __name__, адаптер
    изменяет строку, полученную от IDocTitle так, чтобы исключить символы, не рекомендуемые к испоьлзованию в URL: '/', '?' и 
    некоторые другие. Кроме того, адаптер заменяет пробелы на символ "_".
    
Адаптер pager
-------------
Позволяет легко строить пейджеры по спискам, приводимым к IPagerSource, так
как делает, по возможности быстро, все возможные вычисления, и предоставляет
готовые результаты как методы.

Продукт вклчает в себя готовые адаптеры от компонент и интерфейсами
IContainer, IOrderedContainer, а также ResultSet, возвращаемым Catalog'ом.
Так как ResultSet никакого интерфейса не предоставляет, то в последнем
случае приходится делать прямой вызов адаптера.

Список методов IPager
.....................

    setPagerParameters(revert=None, orphan=None,size=None)
        Установить параметры пейджера, в том числе:
        
        revert
            Отображать в обратную сторону;
            
        orphan
            Допустимое перекрытие страниц;            
         
        size 
            Длина страницы;
         
        have_before
            Истинно, если есть страница до текущей;

        befores
            Список ключей, с которых начинаются страницы до тккущей;
            
        beforeURLs
            Список URL'ов страниц до текущей;

        before
            Предыдущая страница;

        beforeURL = Field()
            URL предыдущей страницы;

        chunk
            Список компонент отображаемых на текущей странице;

        after
            Ключ первого элементы следующей страницы;
            
        afterURL
            URL следующей страницы;
            
        afters 
            Список ключей первых элемнтов следующих страниц;

        afterURLs
            Список URL'ов следующих страниц;

        have_after
            Истинно, если есть следующая страница;

        len 
            Общее количество элементов в списке;
        
Пример кода::

  <tal:block tal:condition="python:len(context) > 0">
    <table cellspacing="0" cellpadding="3" bgcolor="#CCDDFF" width="100%" 
        border="1" bordercolor="black" bordercolordark="#CCDDFF">
	    <tr><td>
		    <p class="docttl">Вложенные материалы
		</td></tr>
			
		<tal:block define="pager context/@@pager">
		<tal:block define="q python:pager.setPagerParameters(revert=True)"/>
			
		<tr tal:condition="pager/have_before"><td align="left">
			    <a href="" tal:attributes="href pager/beforeURL"> &lt;&lt;&lt;&lt;&lt;&lt;</a>
			  <tal:block repeat="item python:zip(range(1,10),pager.beforeURLs)">
			    [<a href="" tal:attributes="href python:item[1]" tal:content="python:item[0]"/>]
              </tal:block>			    
	    </td></tr>
			
		<div tal:repeat="item pager/chunk">
		    tal:block tal:on-error="structure python:'<tr><td>'+item.__name__+'</td></tr>'" 
		    tal:content="structure item/@@short"/>
		</div>

		<tr tal:condition="pager/have_after"><td align="right">
		    <tal:block repeat="item python:zip(range(1,10),pager.afterURLs)">
			    [<a href="" tal:attributes="href python:item[1]" tal:content="python:item[0]"/>]
            </tal:block>			    
			<a href="" tal:attributes="href pager/afterURL">  &gt;&gt;&gt;&gt;&gt; </a>
	    </td></tr>
      </tal:block>
			
    </table>

  </tal:block>

Адаптер recordsize
------------------

Предназначен получения размера записи объекта в базе данных ZODB. Адаптирует
любой объект к интерфейсу IRecordSize, в состав которого входят следующие
свойства:

    size 
        Размер объекта

Размер объекта вычисляется преобразованием в формат, близкий к используемому в 
базе данных ZODB. 

Адаптер adaptiveurl
-------------------

Предназначен для получения абсолютнного URL-а объекта. В отличие от вызова
absoluteURL может построить URL объекта, находящегося на другом виртуальном
сайте той же самой инстанции Zope. Для диагностики используется факт
непустого **getVirtualHostRoot()** и подъем в сочетании с подъемом до
вершины сайта. В этом случае используется url, построенный до объекта,
адаптируемого к интерфейсу IAdapteveURLRoot (обычно такой объект имеет или
форму редактирования поля adaptiveurl, или получает URL адаптером из
[name:ng.app.registry:реестра])

Использование адаптера полностью аналогично absoluteURL. Он может быть вызван 
как функция двух аргументов::

    from ng.adapter.adaptiveurl.adaptiveurl import adaptiveURL
    
    def url(self, context, request) :
        return adaptiveURL(context,request)
    
Или как вид::

    <a href="" tal:attributes="href context/@@adaptive_url"> КУКУ </a>
        
Поведение адаптера:

 Если объект находится внутри текущего виртуального хоста
    Поведение идентично absoluteURL.
    
 Если объект находится вне текущего виртуального хоста
    Адаптер возвращает url построенный от первого объекта, приводимого
    к интерфейсу IAdapteveURLRoot.            

 Если виртуального хоста нет - поведение идентично absoluteURL.
 
В отличие от absoluteURL, наш адаптер не может быть использован
для построения breadcrumbs.


Адаптер nullsublocation
-----------------------

При выполнении ряда операций с объектами предоставляющими интерфейс IReadContainer 
происходит распространение событий, соответствующих этим операциям, по всем объектам,
вложенным в контейнер. Это может быть нежелательным поведением, например, для 
фиктивных контейнеров (которые не содержат объекты непосредственно, а только эмулируют
их содержание). 

Для предотвращения распространения событий по вложенным объектам предлагается нуль-адаптер
ISublocation, который всегда возвращает пустой иттератор. Что бы его использовать, нужно 
зарегистрировать его для порожденного от IReadContainer интерфейса класса, например::

    <adapter
        for=".interfaces.IObjectQueue"
        factory="ng.adapter.nullsublocations.nullsublocations.NullSublocations"
        />
                  
                  
Адаптер checktocontain
----------------------
Определяет пространство имен **++checktocontain++**, позволяющее определить допустимость
вхождения указанного в параметрах класса в контекст. Обычно используется в различных
вариациях меню, например::

    <menuItem
        menu = "profilemenu"
        title = "Add Image"
        for = "ng.content.article.interfaces.ICommonContainer"
        action = "+/AddPhoto.html="
        filter = "context/++checktocontain++ng.app.photo.photo.Photo"
        permission = "zope.ManageContent"
        />

В параметре **filter** этого примера указан код, возвращающий значение истинности "Истинно", если
класс **ng.app.photo.photo.Photo** может быть содержимым контейнера **context**.

Адаптер requestcache
--------------------
Адаптер реквеста **IHTTPRequest** к интерфейсу **IRequestCache**, который предоставляет
функции для управления кешировнием:

cache(period=600)
    Устанавливат заголовки для кеширования в течении **period** секунд;
    
nocache()
    Устанавливает заголовке запрещающие кеширование вообще.
    
Адаптер предоставляет вид **@@requestcache**, при использовании
вида параметры кеширования могут настраиваться через параметры реестра **IRegistry**:

request_cache_use (True/False)
    Запретить или разрешить использование кеширования. Если параметр
    установлен в False, то заголовки кеширования не устанавливаются вообще;
    
request_cache_period (int)
    Установить период кеширования;
    
request_cache_use_as_nocache (True/False)
    Запретить использование кеширования. Если параметер установлен в True, то 
    будут устанавливаться заголовки, запрещающие кеширование, такие же, как 
    при вызове метода **nocache**.
    

Пакет инструментов toolchanger
------------------------------
Пакет **toolchanger** предназначен для минимизации операций выбора вида (вкладки) 
при навигации по сайту. 

Каждый компонент сайта имеет несколько видов, предоставляющих уникальные
возможности взаимодействия с ним. Специальный адаптер - toolURL - позволяет
построить URL с учетом однажды сделанного пользователем выбора. Пример
использования::

    <tal:block tal:repeat="ob context/values">
        <a href="" tal:attributes="ob/@@toolURL" tal:content="ob/title"/> 
    </tal:block>


Алгоритм выбора вида предполагает однородность имен видов: т.е. виды с
одинаковым именем выполняют сходные операции даже у разных компонентов. 
Тогда однажды сделанный пользователем выбор - это тот выбор, который следует
сохранять при перемещении по другим объектам сайта. Выбор пользвоателя
запоминается в URL. Вызов в примере выше проверяет возможность вызова того
же метода у другого объекта, и, если возможность есть, вызывает его. Если
нет - вызывает метод по умолчанию. Использование такого подхода позволяет
резко упростить навигацию по сайту.

Однородность имен видов откуда не следует и должна быть обеспечена
при проектировании сайта.



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

