Пакет ng.app.smartbanner
========================
Дизайн большинства современных сайтов предусматривает специально отведённое
место для отображения баннеров, ссылающихся на родственные ресурсы, ресурсы
спонсоров или какие-то особо популярные разделы сайта. Пакет
**ng.app.smartbanner** позволяет легко поддерживать коллекцию подобных
баннеров.

Пакет **ng.app.smartbanner** обладает следующими особенностями:

1. В качестве баннера не обязательно должно выступать изображение.  При
   наличии кода баннера его можно скопировать в поле **code**
   экземпляра **smartbanner**, после чего баннер будет формироваться
   на основании этого кода;

2. Контейнер с баннерами расположен в сайт-менеджере и баннеры не доступны в
   штатном режиме работы. Доступ к хранилищу обеспечивается посредством
   посредством специально разработанного [keyword:namespace:пространства
   имён] ++img++;

3. Пакет предоставляет возможность отображать баннеры по расписанию. 
   Пользоваться этим можно, но нужно помнить, что это все-таки не
   коммерческая система баннерных показов, поэтому эта функциональность
   имеет некоторые ограничения;

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

Пакет не может считать клики, показы или выполнять еще какую-либо работу
такого рода. Это очень простая система.

Настройка пакета
----------------
Настройка пакета проста как грабли и включает в себя следующие шаги:

1. Создать хранилище баннеров и зарегистрировать его под интерфейсом::

     ng.app.smartbanner.smartbannercontainer.interfaces.ISmartBannerContainer
     
2. Так как smartbannercontainer находится в недоступном месте сайта, то
   необходимо настроить способ доступа к баннерам, что делается установкой
   необходимых значений атрибутам use_fake_place и fake_place_root;

3. Создать в нем все баннеры **smartbanner** и заполнить их;

4. Решить какой способ отображение - линейку или случайный баннер - вы будете
   использовать;
   
5. Вписать в страницу соответствующий код, для линейки баннеров::

        <div tal:content="structure context/@@smartbannerview"/>
    
   для одного баннерного места::
        
        <div tal:content="structure context/++imgrand++/@@smartbannerview"/>
           
На этом настройка пакета закончена и им можно пользоваться. Ниже следуют
скучные технические подробности.

Тонкая настройка компонентов пакета
------------------------------------
Рассмотрим каждый компонент подробно.

    smartbanner
        Каждый **smartbanner** - это картинка, для которой можно задать
        несколько типовых атрибутов. Для отображения картинки используется
        темплейт, в виде строки формата PYTHON, который может быть
        использован для коррекции способа отображения баннера или же может
        быть полностью заменен на код баннера, даже не содержащего картинки,
        что часто приходится делать с баннерами систем статистики, такими
        как SpyLog, LiveInternet и других.
    
        Продукт определяет интерфейс **ISmartImageData**, позволяющий задать
        дополнительные данные для отображения картинки (баннера). Этот
        интерфейс накладывается на объект **Image**, что и превращает его в
        баннер. Схема интерфейса **ISmartImageData** содержит следующие
        поля:
        
            url
                URL ресурса, на который будет указывать баннер;
            
            alt
                Альтернативный текст баннера;
            
            border
                Отображать/не отображать границу;
            
            code
                html-код, используемый для отображения баннера. По умолчанию
                задано значение, использующее данные всех полей схемы, поэтому
                менять его без явной необходмости не следует
            
            begin_time
                Время начала показа баннера;
            
            end_time
                Время окончания показа баннера;

            begin_date
                Дата, начиная с которой баннер будет показываться на сайте;

            end_date
                Дата, после которой баннер не будет показываться на сайте;
                
            disable
                Если этот флаг установлен, баннер не показывается на сайте;                
                
            rate
                Приоритет баннера при использовании случайного
                показа баннеров.                
                
        Обратите внимание на величины end_time и begin_time. Наивное
        понимание смысла этих величин говорит о том, что end_time всегда
        больше begin_time, так как иначе end_time никогда не будет
        достигнут.  На самом деле это не так: шкала времени замкнута в
        кольцо, и если end_time меньше чем begin_time, то это время будет
        достигнуто в течении следующих суток. Это удобный способ указания
        интервалов, включающих в себя полночь.

        Компонент **smartbanner** может быть добавлен только в
        **smartbanercontainer**.
        
    smartbannercontainer
        Контейнер для хранения баннеров позволяющий задать фиктивный
        корневой объект для отображения баннеров и выбрать алгоритм
        случайного выбора.  Схема **ISmartBannerContainerData** содержит
        следующие поля:
        
            use_fake_place

                Этот флаг показывает, что в качестве URL изображения будет
                использоваться не точный URL этого изображения на сайте, а
                URL, построенный добавлением специального префикса
                **fake_place_root** к имени изображение контейнере с
                баннерами;
                
            fake_place_root
                Эта переменная содержит тот самый префикс, который
                используется для доступа к баннерам, при указании флага
                **use_fake_place**, обычное значение: "/++img++";


            algorithm
                Эта переменная позволяет выбрать алгоритм, который будет
                использоваться при случайном показе баннеров, если
                используется такой способ. Существующие алгоритмы описаны
                ниже.

        Указанные поля схемы используются при вызове вида
        **smartbannerview** для объектов **smartbanner**.
        
    smartbannernamespace
        Специальное пространство имён ++img++, благодаря наличию которого
        обращаться к баннерам пакета можно из любого места сайта с помощью
        примерно такой конструкции::
            
            http://<НЕВАЖНО>/++img++<ИМЯ БАННЕРА>
        
        В остальном это обычный [keyword:адаптер пространства имён]. Для его
        функционирования на сайте должна быть зарегистрирована утилита
        **ISmartBannerContainer** (см **smartbannercontainer**).
    
    smartbannerview 
        Вид, отображающий все баннеры, имеющиеся в **smartbannercontainer**
        в виде строки баннеров. Вызывается из любого места сайта (кроме
        объектов **smartbanner**, поскольку для них существует вид с
        аналогичным именем) с помощью дописывания к строке браузера
        @@smartbannerview. Как и пространство имён ++img++, использование
        данного вида требует регистрации утилиты **ISmartBannerContainer**. 
        Этот вид легко вызвать в любом месте шаблона, например, следующим
        образом::
        
            <div tal:content="structure context/@@smartbannerview"/>
               
        Такой вызов отобразит на сайте строку баннеров, отобранных из хранилища.

    smartbannerrandnamespace
        Специальное пространство имен ++imgrand++, выбирающий баннер из
        хранилища случайным образом. Чтобы отобразать этот баннер удобно
        использовать вид **smartbannerview**, например, следующим образом::
        
            <div tal:content="structure context/++imgrand++/@@smartbannerview"/>
            
        Вместо этой конструкции на сайте появится баннер, выбираемый
        случайным образом из хранилища.

Алгоритммы случайного выбора баннеров
-------------------------------------
На сегодняшний день реализовано два таких алгоритма - **Random** и
**Round**, каждый алгоритм это именованный адаптер ISmartBannerContainer к
ISmartBannerAlgorithm, что дает вам свободу проектировать свои собственные
алгоритмы. Дадим немного технических подробностей:

Random
    Классический случайный алгоритм, основанный на случайном (равномерном)
    отборе элемента определенного сорта из кучи, в которой каждый сорт
    представлен количеством элементов, пропорциональном значению **rate**.
    
Round
    Алгоритм, основанный на том, что куча, описанная в алгоритме Random,
    перемещивается и из нее поочереди отбираются элементы.
    
Преимущество алгоритма **random** - он не требует сохранения состояния,
однако, возможны длинные последовательности повторяющихся элементов, что
может отрицательно восприниматься владельцами сайта.

Преимущество алгоритма **round** - длинные последовательности повторяющихся
элементов исключены, максимальное количество повторений - удвоенное значение
**rate**, однако, это алгоритм сохраняющий состояние, и его работа в
многопоточном режиме не была как следует протестирована.



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

###[name:литредактор]
