Управление сайтом

KVS предоставляет движок с огромным спектром возможностей по созданию и настройке страниц сайта. Основные достоинства движка перечислены ниже:

• Беспрецендентная скорость работы достигается за счет двух-уровневого кэширования содержимого страниц. Стратегия кэширования может быть изменена в любой момент времени, что позволяет снять нагрузку на сервер при увеличении трафика. Существует несколько важных аспектов кэширования, которые обязательно необходимо прочитать и понять, прежде чем работать с настройкой сайта. Они будут описаны в разделе о кэшировании.
• Построение страниц сайта на основе блоков позволяет быстро настроить необходимый функционал каждой страницы. Это сможет сделать любой человек, знающий основы верстки и понимающий концепцию движка Kernel Video Sharing.
• При необходимости расширения базового функционала, вы можете написать свои собственные блоки и использовать их на сайте. Для этого не нужно разбираться с тысячами строк кода, достаточно лишь понять несколько базовых правил создания блоков.
• Любые новые блоки, разработанные позднее, могут быть подключены в любое место сайта без вероятности повредить существующий и работающий функционал.
• Встроенный анализ производительности сайта позволяет находить наиболее уязвимые с точки зрения производительности страницы и блоки сайта и оптимизировать их на лету.

Движок KVS использует 4 сущности для построения сайта:

• Компоненты страниц - это части верстки, которые могут использоваться во многих местах. Компоненты страниц просто отображают HTML код, следуя логики, которая задается в шаблоне компонента. Это применяется для общих элементов сайта (например, шапка, нижняя часть, форма поиска, которая может отображаться на многих страницах и т.д.). Компоненты используются в шаблонах других сущностей, например на страницах и в блоках. Таким образом, если вам нужно поменять что-либо в шапке сайта (обычно это название проекта и верстка шапки), это можно поменять в соответствующем компоненте страниц, и изменения подействуют для всех страниц, которые используют данный компонент в своем шаблоне.
• Блоки - это основные логические модули страниц. Каждый блок предоставляет логически завершенный кусочек функционала сайта и может использоваться на любых страницах. Основное отличие блоков от компонентов страниц заключается в том, что блоки предоставляют выполнение бизнес логики (работа с базой данных, подготовка результатов для отображения, обработка форм, отправленных пользователями) и отображение результатов выполнения данной бизнес логики (шаблон с версткой), в то время как компоненты страниц содержат только отображение каких-либо данных или элементов дизайна. Большинство блоков поддерживает набор конфигурационных параметров, которыми можно управлять поведением блока (например, ограничить кол-во элементов в блоке списка, или включить визуальную защиту при входе в личную зону). Каждый блок кроме параметров поддерживает определенный уровень кэширования и может кэшироваться отдельно.
• Рекламные места - это слоты для отображения рекламы. Вы можете настроить сколько угодно рекламных мест на сайте и привязать к каждому из них рекламу.
• Страницы - это основные элементы структуры сайта, каждая страница может содержать любое кол-во компонентов, блоков и рекламных мест (или может просто содержать статический HTML код). Страницы поддерживают кэширование второго уровня, при включении которого результат отображения страницы полностью помещается в оперативную память и в течение настроенного интервала времени пользователи видят сохраненный в кэше HTML код (статику).
• Группы страниц - возможность разбивать страницы на группы для удобства работы в панели администрирования.

Структура страницы сайта.

Для того, чтобы наглядно представить себе все основные сущности сайта, рассмотрим скриншот выше. Все что отображается на скриншоте - это отдельная страница, которая доступна по отдельному адресу. В самом верху страницы находится шапка. Шапка - это компонент страниц, поскольку она не несет в себе никакой логики, только выводит верхнюю часть HTML кода страницы. В шапке вставлено рекламное место, в котором отображается один баннер. Если к этому рекламному месту привязать несколько баннеров, то они будут ротироваться. Ниже шапки отображается блок списка видео (list_videos), который выводит 9 последних просмотренных видео. Чем отличается блок от компонента страниц очевидно - блок обращается в базу данных для того, чтобы вывести некоторую информацию, а компонент страниц просто отображает HTML код. Справа от блока списка видео отображается компонент страниц с формой поиска видео и под ним блок облака тэгов (tags_cloud).

В качестве другого примера рассмотрим страницу Community, на которой мы хотим отобразить такую информацию:

• 3 рекомендуемых к просмотру премиум видео
• 20 последних зарегистрированных пользователей сайта
• 3 наиболее активных пользователя
• 10 последних добавленных фотоальбомов
• 10 самых популярных фотоальбомов

Код шаблона страницы будет иметь приблизительно такой вид:

{{* Устанавливаем значение переменной page_title, которая используется в компоненте страниц header_general *}}
{{assign var=page_title value="Community"}}

{{* Подключаем компонент страниц header_general, который отображает шапку страницы *}}
{{include file="header_general.tpl"}}

<div id="data">
    <div id="wide_col">
        {{* Подключаем блок list_videos для отображения 3 премиум видео *}}
        {{insert name="getBlock" block_id="list_videos" block_name="Recommended premium videos"}}

        {{* Подключаем блок list_members для отображения 20 последних пользователей *}}
        {{insert name="getBlock" block_id="list_members" block_name="Latest members"}}

        {{* Подключаем блок list_albums для отображения 10 последних фотоальбомов *}}
        {{insert name="getBlock" block_id="list_albums" block_name="Latest albums"}}

        {{* Подключаем блок list_albums для отображения 10 популярных фотоальбомов *}}
        {{insert name="getBlock" block_id="list_albums" block_name="Most popular albums"}}
    </div>
    <div id="side_col">
        {{* Подключаем блок list_members для отображения 3 активных пользователей *}}
        {{insert name="getBlock" block_id="list_members" block_name="Active members"}}
    </div>
</div>

{{* Подключаем компонент страниц footer_general, который отображает нижнюю часть страницы *}}
{{include file="footer_general.tpl"}}

Кроме непосредственного подключения блоков в шаблоне страницы необходимо также настроить их параметры для данной страницы (например, блоку list_videos указать, что нужно выводить только 3 видео и обязательно премиум и т.д.) и при необходимости шаблоны блоков для данной страницы (логику отображения данных). Это будет детально рассмотрено в следующих разделах.

Использование компонентов страниц на сайте

Компоненты страниц представляют собой используемые во многих местах элементы и компоненты верстки сайта. Поскольку страниц сайта может быть очень много и большинство из них будет иметь схожие элементы дизайна (например, шапка, блок поиска, и др.), то для простоты и удобства использования такие элементы дизайна рекомендуется выносить в компоненты страниц, которые затем использовать в нужных местах.

Компоненты страниц могут использоваться в любых местах, где ожидается шаблон Smarty (в шаблонах страниц, шаблонах блоков и даже в шаблонах самих компонентов). Для подключения компонента используется стандартная директива Smarty:

{{include file="%PAGE_COMPONENT_EXTERNAL_ID%.tpl"}}

В данном примере токен %PAGE_COMPONENT_EXTERNAL_ID% должен быть заменен на идентификатор требуемого компонента, например header_general:

{{include file="header_general.tpl"}}

Во время обработки страницы данная директива будет заменена движком Smarty на содержимое шаблона указанного компонента. Это позволяет использовать любые переменные в шаблоне компонента страниц, значения которых могут быть установлены в месте непосредственного использования компонента. Для примера, рассмотрим шапку сайта, которая содержит информацию о названии страницы. Шапка не может содержать конкретное название страницы, поскольку она используется на разных страницах сайта с разными названиями. Поэтому вместо конкреного названия следует использовать переменную (например, page_title), значение которой будет устанавливаться в шаблоне конкретной страницы непосредственно перед подключением компонента шапки на страницу. Код шаблона компонента шапки может выглядеть так:

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <!-- Выводим значение переменной page_title в названии страницы -->
    <title>{{$page_title}} - My Tube Site</title>
</head>
<body>

Для того, чтобы при отображении страницы переменная page_title заменилась на нужное значение, необходимо присвоить ей это значение перед подключением компонента. Это может быть сделано таким образом (страница со списком премиум видео):

{{* Устанавливаем значение переменной page_title *}}
{{assign var=page_title value="Premium Videos"}}

{{* Подключаем компонент страниц header_general, который отображает шапку страницы *}}
{{include file="header_general.tpl"}}

....

Работа с компонентами страниц в панели администрирования

Файлы компонентов страниц хранятся в директории /template в корне проекта. Для создания компонентов Apache должен иметь права на создание файлов в данной директории. Для редактирования какого-либо компонента Apache должен иметь права на редактирование файла шаблона данного компонента.

Для создания компонента страниц вы можете воспользоваться любым из 3 способов:

• Создать компонент вручную в панели администрирования, указав его идентификатор и код шаблона.
• Сделать дубликат уже существующего компонента. Для этого вы можете воспользоваться опцией Сделать копию в контекстном меню исходного компонента в панели администрирования. Вам необходимо ввести только название идентификатора нового компонента.
• Скопировать файл с расширением .tpl в директорию /template в корне проекта. И установить на него привилегии 666.

Поля данных, которые поддерживаются компонентами:

• Идентификатор - уникальный идентификатор компонента, может содержать ограниченный набор символов (a-z, A-Z, 0-9, _). Данный идентификатор используется для сохранения кода шаблона компонента на сервере в файле с расширением .tpl. Идентификатор не может быть изменен после создания компонента. Если возникла необходимость переименовать компонент, то следует сделать его копию, затем переключиться на компонент с новым идентификатором во всех местах, где использовался старый, после этого появится возможность удалить старый компонент.
• Код шаблона - код шаблона Smarty (или просто HTML код) для данного компонента. В шаблоне компонента страниц не допускается подключать какие-либо блоки - блоки могут быть подключены только в шаблонах страниц.

Во время работы с содержимым страниц и блоков вы можете подключать даже несуществующие компоненты страниц (через директиву Smarty {{include ...}}). В этом случае необходимый компонент будет создан автоматически с пустым шаблоном. Все что вам нужно будет сделать - это просто задать для него шаблон позже.

Удаление компонентов страниц допускается только при отсутствии ссылок на них в других сущностях сайта (страницах, блоках или других компонентах).

Обзор компонентов страниц в дизайне по умолчанию

Данная таблица содержит краткое описание и предназначение компонентов страниц, которые используются в дизайне по умолчанию. Часть из приведенных ниже компонентов недоступна в младших пакетах функциональности.

Многие компоненты поддерживают так называемые "внешние переменные". Что это значит? Если компонент имеет несколько вариаций, которые отличаются небольшими фрагментами (например, названия списков видео разные, но сами списки видео отображаются одинаково), то нет смысла делать по одному компоненту для каждого списка видео со своим названием. Достаточно сделать один компонент, но вместо названия списка вывести значение из переменной, которое будет устанавливаться перед подключением компонента. Например, компонент шапки поддерживает внешнюю переменную для HTML названия страницы:

<title>{{$page_title}} / Kernel Tube</title>

Перед подключением компонента шапки необходимо установить значение этой переменной, которое должно быть выведено внутри компонента:

{{assign var="page_title" value="Community"}}
{{include file="header_general.tpl"}}

Общая информация о блоках

Блоки являются основными логическими модулями страниц. В отличие от компонентов страниц блоки предоставляют логику выборки / сохранения данных, а также большой спектр параметров конфигурации данной логики. Функциональность движка позволяет в любой момент времени изменить логику работы сайта путем изменения значений параметров блоков, а также добавления новых блоков на страницы и написания своих собственных блоков.

Список всех блоков и полную информацию о них с примерами использования можно посмотреть на странице Обзор блоков в разделе UI сайта панели администрирования. При открытии подробных данных о блоке можно получить информацию по его использованию, список и описание всех параметров блока, а также различные примеры конфигурации блока.

Блоки могут быть условно классифицированы по нескольким признакам. Например, по типу отображаемого контента блоки можно разделить на:

• Блоки листинга - блоки, которые отображают список каких-либо сущностей, например list_categories - отображает список категорий, video_comments - отображает список комментариев к видео, и т.д. Данные блоки выделяются тем, что они все поддерживают пагинацию (переход по страницам листинга) внутри блока, а также к ним можно подключать сторонний блок пагинации (для сохранения преемственности со старыми версиями софта).
• Блоки отображения данных - блоки, которые отображают данные какой-либо сущности, например, member_profile_view - отображает данные профиля пользователя, album_view - отображает данные фотоальбома и т.д.
• Блоки редактирования данных / форм - блоки, которые отображают форму для заполнения, например, logon - отображает форму входа в личную зону, video_edit - отображает форму создания / редактирования видео и т.д. Особенностью этих блоков является то, что они не поддерживают кэширование.

По уровню доступа блоки условно могут быть разделены на следующие группы:

• Блоки публичного доступа - блоки доступные всем посетителям сайта при любых условиях, например, list_categories - отображает список категорий, invite_friend - отображает форму приглашения друга и т.д.
• Блоки приватного доступа - блоки, которые при любых условиях требуют, чтобы пользователь был залогинен, например, member_profile_edit - отображает формы управления данными профиля, list_messages - отображает список сообщений внутренней почты и т.д. В случае запроса незалогиненным пользователем страницы с данным блоком, пользователь будет перенаправлен на страницу логина (конфигурируется через параметр блока), а затем после логина он вернется на запрошенную ранее страницу с приватным блоком.
• Блоки комбинированного доступа - блоки, которые могут быть как публичными, так и приватными в зависимости от параметров их конфигурации, например, list_videos при отображении закладок видео текущего пользователя является приватным блоком, а при отображении списка премиум видео - публичным.

Переменные с данными блока доступны только в самом шаблоне блока и недоступны извне. Если вам необходимо вывести какие-либо данные блока в шаблоне страницы, вам необходимо использовать глобальное хранилище, которое называется $storage. Почти все блоки использует глобальное хранилище данных на странице для сохранения туда некоторых результатов своей работы, чтобы они могли быть использованы на странице (снаружи блока). В шаблоне каждой страницы доступна глобальная переменная $storage, которая может использоваться для доступа к результатам блока (например, блок video_view помещает в глобальное хранилище некоторую информацию о видео, которое он отображает, например, название, описание, тэги и др.

Важно! Переменная $storage блока доступна только после места подключения блока в страницу.

Как узнать какие данные блока доступны для использования в шаблоне блока или на странице через его глобальное хранилище $storage? Для этого существует отладчик страниц, более подробную информацию вы найдете далее в руководстве.

Использование блоков на страницах сайта

Для подключения блока на странице необходимо использовать следующий синтаксис в коде шаблона страницы:

{{insert name="getBlock" block_id="%BLOCK_ID%" block_name="%UNIQUE_BLOCK_NAME%"}}

В данном примере токен %BLOCK_ID% должен быть заменен на идентификатор блока (block ID) требуемого блока, например, list_videos, а токен %UNIQUE_BLOCK_NAME% на любое уникальное имя блока для данной страницы:

{{insert name="getBlock" block_id="list_videos" block_name="Most Popular Videos"}}

Важно! При изменении названия блока произойдет удаление блока со старым названием и добавление блока с новым названием, а это значит что старые настройки блока на этой странице не сохранятся. Старайтесь сразу давать блокам актуальные названия.

Вы можете подключать любое количество блоков любых типов на одной странице, главное чтобы названия блоков были уникальны в контексте страницы:

{{* Первый блок list_videos *}}
{{insert name="getBlock" block_id="list_videos" block_name="Most Popular Videos"}}

{{* Еще один блок list_videos *}}
{{insert name="getBlock" block_id="list_videos" block_name="Top Rated Videos"}}

{{* Третий блок list_videos *}}
{{insert name="getBlock" block_id="list_videos" block_name="Premium Videos"}}

{{* Список трейдеров *}}
{{insert name="getBlock" block_id="top_referers" block_name="Traders Text Links"}}

...

При простом подключении блока на странице он будет вызываться и отображать результат непосредственно в том месте шаблона страницы, где вы его вставили. В некоторых случаях необходимо заставить блок выполниться в начале страницы, например, для того, чтобы показать данные из хранилища $storage блока в заголовке страницы (title, description, keywords). Этого можно добиться, используя дополнительный параметр assign директивы {{insert ...}}. При использовании этого параметра результат выполнения блока будет не отображаться в текущем месте шаблона страницы, а помещаться в переменную, указанную в значении параметра assign. Этот результат выполнения можно будет вывести в любом месте страницы, используя стандартный вывод Smarty:

{{* Вызов блока просмотра видео в самом начале страницы и присвоение результата в переменную video_view_result *}}
{{insert name="getBlock" block_id="video_view" block_name="View Video" assign="video_view_result"}}

{{* Дальше идет много всего, например использование $storage блока video_view *}}
...

{{* Теперь нужно вывести результат блока просмотра видео *}}
{{$video_view_result|smarty:nodefaults}}

...

Этого достаточно, чтобы показать название видео в заголовке страницы, т.к. после отработки блока можно использовать данные из его глобального хранилища storage:

{{* Вызов блока просмотра видео в самом начале страницы и присвоение результата в переменную video_view_result *}}
{{insert name="getBlock" block_id="video_view" block_name="View Video" assign="video_view_result"}}

{{* Присваиваем переменной page_title название видео доступное в глобальном хранилище *}}
{{assign var="page_title" value=$storage.video_view_video_view.title}}

{{* Подключаем компонент шапки, который отобразит значение из переменной page_title *}}
{{include file="header_general.tpl"}}

{{* Теперь нужно вывести результат блока просмотра видео *}}
{{$video_view_result|smarty:nodefaults}}

...

Как видно из примера, каждый блок использует глобальное хранилище данных под своим уникальным ключем (в примере это $storage.video_view_video_view). Нет никакого смысла понимать механизм формирования этих ключей, поскольку панель администрирования выводит эти ключи для каждого блока в таблице блоков данной страницы сайта. При необходимости использовать глобальное хранилище - ключ можно скопировать из таблицы. Вы также можете воспользоваться отладчиком страницы, чтобы увидеть какие данные доступны для использования в хранилище $storage блока (см. главу про отладку страниц сайта).

Для удаления блока со страницы достаточно удалить из кода шаблона страницы директиву, которая его вставляет. При этом файлы блока на самом деле удаляться не будут. Это сделано для того, чтобы можно было быстро восстановить блок на странице в случае его ошибочного удаления. Если вы вставите снова директиву подключения блока с такими же параметрами (имеются ввиду параметры директивы block_id и block_name) - блок будет восстановлен со всеми деталями его конфигурации. Если вы все же хотите финально удалить файлы блока (мы рекомендуем это делать, если вы проверили что блок удален корректно) - то откройте Список страниц и вы увидите, что в боковом меню появится новая опция Подчистить файлы, рядом с которой также показано количество файлов для очистки. Зайдите на эту опцию и удалите неиспользуемые файлы блоков.

Важно! После удаления файлов блоков (файл шаблона и файл конфигурации) на странице Подчистить файлы - восстановить детали удаленного блока будет невозможно. В случае необходимости восстановления вам придется заново создать и настроить блок на странице.

Параметры конфигурации и шаблоны блоков

Параметры конфигурации блока определяют его поведение на странице. Почти все блоки поддерживают большое кол-во параметров конфигурации (кроме разве что самых простых блоков). Шаблон блока предназначен для отображения данных, подготовленных блоком, либо наоборот, подготавливает данные для бизнес логики блока (это скорее относится к блокам, которые отображают различные формы для заполнения). Важно понимать, что разные блоки на странице (даже блоки одного типа) могут иметь кaрдинально разные параметры и шаблоны. Таким образом, параметры блока и его шаблон определяют логику поведения и отображения конкретного блока на конкретной странице.

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

Страница редактирования блока поддерживает следующие поля:

• Название блока - название блока на данной странице, поле не редактируется. Название блока берется из директивы подключения блока, которая была вставлена в шаблон страницы. Если вы измените название блока в директиве - то это будет уже другой блок с другими параметрами и шаблоном.
• Уникальный ID блока - внутренний идентификатор блока на странице.
• Тип блока - идентификатор типа блока, поле не редактируется. Рядом с идентификатором типа блока находятся ссылки для отображения описания блока и его шаблона по умолчанию. Шаблон по умолчанию описывает основные аспекты отображения блока, поэтому вы можете его использовать в качестве примера верстки блока.
• Использует компоненты - перечисляет все компоненты страниц, которые подключаются в шаблоне данного блока.
• Код шаблона - указывает код шаблона Smarty для данного блока на данной странице. В шаблоне блока вы можете использовать подключение компонентов страниц и рекламных мест, но не можете подключать другие блоки. Если вы не знаете, какие переменные можно использовать в шаблоне блока для отображения той или иной информации, откройте для данной страницы отладчик и там вы увидите все доступные переменные и их актуальные значения (см. главу про отладку страниц сайта).
• Время жизни кэша - длительность жизни кэша в секундах, которая указывает, как долго данный блок будет использовать кэш на данной странице. Если указано значение 0 - то блок кэшироваться не будет. Для блоков, которые не поддерживают кэширование данное поле не доступно для редактирования.
• Выключить кэшированиe для зарегистрированных пользователей - позволяет выключить кэширование этого блока для зарегистрированных пользователей сайта. Если эта галочка включена, то вы можете настраивать чтобы шаблон блока показывал различное содержимое различным пользователям сайта (например, выводить в шаблоне блока "Привет, <имя пользователя>". Мы не рекомендуем использовать эту опцию для блоков списков, поскольку они дают основную нагрузку на базу данных.
• Параметры конфигурации - таблица с поддерживаемыми параметрами и их значениями для данного блока (если блок имеет параметры конфигурации). Для того, чтобы включить параметр необходимо включить соответствующий чекбокс и ввести необходимое значение (для булевских параметров значение не требуется, такие параметры просто включаются / выключаются). Включенные параметры помечаются жирным шрифтом.

Среди разнообразных параметров стоит выделить так называемые var-параметры, которые используются во многих блоках, например, var_from - для пагинации, var_video_dir - для отображения видео и т.д. Данные параметры ссылаются на названия HTTP параметров, которые следует использовать блоку на данной странице для своей работы. Рассмотрим пример с блоком списка видео list_videos. Для того, чтобы отобразить список видео по какой-либо категории, блоку необходимо знать идентификатор этой категории. Категория может быть идентифицирована 2-мя способами: по числовому идентификатору и директории. Предположим, что мы хотим отобразить список видео по директории категории (как обычно и делается для создания красивых ссылок на сайте). Для этого блоку необходимо знать, в каком HTTP параметре передается директория категория для отображения, за что отвечает параметр блока var_category_dir, который указывает блоку в каком HTTP параметре искать значение директории категории. Это значит, что если для данного параметра установлено значение dir, то ссылка на страницу с текущим блоком должна содержать значение директории категории в HTTP параметре dir, т.е. /page_id.php?dir=category_directory_value. Аналогичное правило справедливо для всех var-параметров.

Почему бы не сделать фиксированными названия HTTP параметров, которые понимаются блоками? Здесь есть 2 аспекта, которые мы учли. Во-первых, само по себе включение параметра в настройках блока может влиять на работу блока, даже если значение для него не передается в HTTP запросе. Во-вторых, схема с указанием параметров, в которых блоку передаются данные, позволяет вывести несколько списков видео по разным категориям - например, можно сделать страницу, на которой отобразятся 3 списка видео по 3 наиболее популярным категориям у вас на сайте. Для этого вам придется передать на страницу директории (или ID) 3-х категорий, естественно в разных HTTP параметрах. Вероятно, вам вряд ли понадобится такая функциональность, но тем не менее движок KVS позволяет ее реализовать.

К счастью, в подавляющем большинстве случаев значение соответствующего var-параметра можно оставить как оно предлагается по умолчанию. Вам необходимо только учитывать, что для корректного поведения блока на странице ссылка на эту страницу должна содержать необходимые блоку значения var-параметров. Если на вашем сайте используется mod_rewrite для ссылок (что скорее всего), то правила mod_rewrite должны также учитывать необходимые блоку var-параметры.

var-параметры являются одним из ключевых звеньев движка сайта KVS, поскольку они обеспечивают блоки необходимой для работы информацией, а также используются для кэширования блоков и страниц. Названия и значения var-параметров по умолчанию настроены таким образом, чтобы подходящие друг к другу блоки могли работать совместно на одной странице. Так, например, блоки video_view, video_comments, list_videos и top_referers имеют параметры с одинаковым названием и значением var_video_dir и var_video_id. При подключении этих блоков на одной странице и включении во всех блоках одного из данных параметров блоки будут отображать информацию о видео, комментарии к видео, список похожих видео и список рефереров, подходящих к видео по категории соответственно.

В большинстве случаев одинаковые блоки на разных страницах имеют похожий внешний вид, за исключением конечного ряда элементов (например, название списка видео может быть разным на каждой странице - но в целом все списки видео выглядят одинаково). В таких случаях логику отображения блока (шаблон) стоит вынести в компонент страниц, а в самом шаблоне блока подключить этот компонент. Различающиеся элементы (как название) следует вывести через переменные Smarty, значение которым должно быть присвоено непосредственно перед подключением компонента на странице. Это сделано в дизайне по умолчанию, где существует несколько компонентов страниц для отображения наиболее часто используемых блоков (например, компоненты list_videos_block_common.tpl и list_videos_block_internal.tpl, которые используются блоком list_videos).

Блоки списков и пагинация

Почти половина существующих в KVS блоков является блоками списка. Блоки списка отличаются от других блоков тем, что они поддерживают возможность отображать только часть списка и навигацию по страницам списка (пагинацию), хотя могут быть также настроены на отображение полного списка объектов (сколько есть).

Все блоки списка поддерживают пагинацию внутри самого блока, а также поддерживают возможность пагинации через ajax без перезагрузки страницы (в шаблонах по умолчанию это не используется). Для включения пагинации в блоке списка должен быть включен параметр блока var_from, который указывает блоку в каком HTTP параметре приходит информация о текущей странице (по умолчанию var_from=from). Кроме этого параметра блока, вы можете также использовать другие параметры пагинации, которые поддерживаются каждым блоком списка:

• items_per_page - количество объектов списка на одной странице. Исходя из этого значения и общего количества имеющихся у списка объектов будет рассчитано количество страниц списка.
• links_per_page - количество номеров страниц в навигации, отображаемых на одной странице.

После настройки параметров блока вам также необходимо добавить в шаблон блока отображение ссылок пагинации (по умолчанию шаблоны блоков не содержат этого). Для этого вы можете просто подключить в нужном месте шаблона блока компонент страниц pagination_block_common (который содержит логику отображения списка страниц):

...

{{* Подключаем пагинацию вверху списка *}}
{{include file="pagination_block_common.tpl"}}

{{* Дальше идет сам список *}}
{{foreach name=data item=item from=$data}}
...
{{/foreach}}

{{* Подключаем вторую пагинацию снизу списка - это пример того, что можно в блоке 2 раза подключить *}}
{{include file="pagination_block_common.tpl"}}

...

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

http://your_domain.com/popular_videos/
http://your_domain.com/popular_videos/1/
http://your_domain.com/popular_videos/2/
... и т.д.

Альтернативно вы можете настроить другую схему ссылок, полная информация об этом есть в FAQ.

Для того, чтобы эти ссылки работали корректно, необходимы корректные правила mod_rewrite, которые созданы для всех существующих списков. Если вы добавляете новые списки либо изменяете адреса страниц для существующих, вам необходимо следить за тем, чтобы правила mod_rewrite для пагинации были указаны верно.

Несмотря на то, что пагинация поддерживается всеми блоками списка, она может также отображаться отдельным блоком pagination. Во-первых, это необходимо для совместимости со старыми версиями KVS. Во-вторых, отдельный блок пагинации поддерживает некоторые расширенные возможности пагинации для особых случаев (информация об этом есть в документации блока pagination).

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

В завершение разговора о пагинации рассмотрим пагинацию через ajax. Для этого вам нужно внести всего 2 изменения в концепцию пагинации описанную выше:

• Во-первых, весь шаблон (HTML код) блока списка должен быть обернут в div с уникальным идентификатором блока: <div id="{{$block_uid}}">
      ...
  </div>
• Во-вторых, вместо подключения компонента страниц pagination_block_common, вам необходимо подключить компонент pagination_block_ajax: {{include file="pagination_block_ajax.tpl"}}

Глобальные блоки

При подключении блока на странице сайта, вам необходимо задать его параметры и шаблон, которые будут использоваться блоком на данной странице. Зачастую при работе с сайтом возникает необходимость использовать одинаково настроенные блоки на многих страницах сайта. Например, вы можете показывать облако тэгов на разных страницах, либо топ 10 поисковых запросов по сайту за последние 7 дней. Чтобы избежать дублирования в настройках таких блоков и их шаблонах, KVS предоставляет возможность создавать глобальные блоки сайта и подключать их на разных страницах.

Глобальные блоки создаются вручную на списке Глобальных блоков в разделе UI сайта. Вы должны выбрать тип блока и указать его название. Затем вы можете зайти на страницу редактирования этого блока и настроить его шаблон и параметры один раз.

Для вставки глобального блока на любой странице сайта необходимо использовать специальный синтаксис глобального блока:

{{insert name="getGlobal" global_id="%UNIQUE_BLOCK_ID%"}}

Директива для подключения глобального блока отображается прямо на списке глобальных блоков, вам необходимо лишь скопировать ее и вставить в нужное место шаблона страницы. Если вы в какой-то момент захотите изменить шаблон или параметры глобального блока - внесенные изменения затронут все страницы, где используется данный блок.

Важно! Подключать глобальные блоки как и обычные блоки можно только в шаблонах страниц.

Использование рекламных мест на сайте

KVS предоставляет простой модуль управления рекламой, функциональности которого достаточно для большинства нужд.

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

Для подключения рекламного места в шаблоне страницы, компонента или блока используется такая директива:

{{insert name="getAdv" place_id="%ADVERTISING_LOCATION_EXTERNAL_ID%"}}

В данном примере токен %ADVERTISING_LOCATION_EXTERNAL_ID% должен быть заменен на идентификатор требуемого рекламного места, например top_banner:

{{insert name="getAdv" place_id="top_banner"}}

Работа с рекламой в панели администрирования

Поля данных, которые поддерживаются рекламными местами:

• Название - название рекламного места для панели администрирования.
• Идентификатор - уникальный идентификатор, который будет использоваться для подключения рекламного места на сайте. Может содержать ограниченный набор символов (a-z, A-Z, 0-9, _).

Поля данных, которые поддерживаются рекламой:

• Название - название рекламы для панели администрирования.
• Рекл. место - позволяет выбрать рекламное место, к которому будет привязана данная реклама. Реклама будет отображаться только в выбранном рекламном месте.
• Статус - включение / выключение рекламы. На сайте будет отображаться только реклама в активном статусе.
• Дата показа - позволяет указать интервал дат, в течение которого будет показываться данная реклама. Если дата показа не указана, то реклама будет отображаться постоянно. Возможно также указать только дату начала показа, либо только дату окончания показа.
• HTML код - рекламный контент (только статический HTML код).
• URL выхода - позволяет включить подсчет кликов по данной рекламе в статистике. Если это поле используется, то HTML код для рекламы должен содержать токен %URL% везде, где ожидается URL выхода. В этом случае токен будет заменен на внутренний скрипт редиректа, которой зачтет клик в статистике и сделает редирект на рекламу.

Общая информация о страницах

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

Каждая страница имеет свой уникальный идентификатор, на основе которого создается PHP файл страницы и ее шаблон отображения. PHP файл страницы используется для указания ссылок на нее.

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

Ссылки на страницу должны содержать все необходимые параметры для ее работы (этими параметрами на самом деле являются включенные var-параметры всех блоков данной страницы, как было описано выше. В большинстве случаев в шаблонах по умолчанию используются абстрактные ссылки, которые перекрываются через mod_rewrite, всвязи с чем многие необходимые странице параметры подставляются на основе частей URL-ов, например для ссылки на страницу просмотра видео /videos/123/my-uploaded-video/ применяется такое правило перенаправления:

RewriteRule ^videos/([0-9]+)/([^/]+)/$ /view_video.php?id=$1&dir=$2 [L,QSA]

Это правило говорит о том, что ссылка /videos/123/my-uploaded-video/ будет перенаправлена на страницу с идентификатором view_video (PHP файл страницы view_video.php), при этом в качестве параметра id будет использоваться число после videos/, а в качестве параметра dir будет использоваться последняя часть URL-а, т.е. в нашем примере будет осуществлен такой вызов:

/view_video.php?id=123&dir=my-uploaded-video

Далее этот вызов подхватится движком, который вызовет все блоки на данной странице с параметрами id=123 и dir=my-uploaded-video. Блоки выведут всю необходимую информацию, базируясь на значениях данных параметров. В приведенном примере блок video_view, который находится на данной странице, отобразит информацию о видео с айди 123, если директория этого видео совпадает с директорией, переданной в параметре dir. Если же директория не совпадает, то блок сделает 301 редирект на это же видео, но с корректной директорией.

Аналогичным образом происходит обработка всех страниц сайта, которые созданы через панель администрирования.

Дополнительно к правилам mod_rewrite есть также глобальные настройки, в которых требуется указать паттерны для ссылок на страницы просмотра различных объектов (видео, фотоальбомов, моделей и т.д.). Эти паттерны используются для создания ссылок на просмотр видео и других объектов на сайте и из панели администрирования. Эти настройки находятся на странице Настройки сайта в разделе Настройки панели администрирования. Заданные в настройках паттерны должны иметь соответствующие правила mod_rewrite, чтобы ссылки на генерировали 404 ошибок.

Работа со страницами в панели администрирования

Файлы страниц хранятся в корне домена на сервере (PHP файл) и в директории /template (файл шаблона).

Если Apache не имеет привилегий на создание файлов в корне сайта, перед созданием страницы вам необходимо вручную скопировать ее шаблон PHP файла из /admin/tools/page_template.php в корневую директорию проекта и переименовать его в PHP файл страницы. Переименованный файл должен иметь имя %external_id%.php, где в качестве токена %external_id% нужно использовать тот идентификатор, который вы будете использовать при создании страницы (например, если вы хотите создать страницу с идентификатором my_new_page, то перед ее созданием вы должны скопировать шаблон PHP файла в файл /my_new_page.php в корневой директории проекта). Если вы не скопировали PHP файл страницы в нужное место и KVS не может сделать это самостоятельно - вы увидите ошибку при попытке создания страницы.

Аналогичным образом перед удалением страницы вы должны удалить ее PHP файл из корневой директории проекта, только тогда вы сможете удалить саму страницу целиком.

Список страниц является основным в разделе UI сайта панели администрирования. Список отображает иерархическую структуру страниц с блоками на них (строки, относящиеся к страницам выделены жирным), а также позволяет изменять базовые настройки кэширования страниц и блоков. Список содержит следующие столбцы:

• Название страницы / блока - название страницы либо блока в засимости от строки.
• ID блока - идентификатор блока на странице (для строк, которые показывают информацию о блоках).
• Кэш - время жизни кэша страницы либо блока в секундах. Поскольку некоторые блоки не поддерживают кэширование, поле кэша не будет редактируемым для таких блоков, а также для страниц, которые содержат такие блоки.
• Сжатие - указывает, используется ли сжатие кэша (только для строк страниц).
• Загрузок - показывает кол-во запросов каждой страницы сайта с момента последнего сброса статистики производительности. Это значение можно расценивать как относительную популярность той или иной страницы.
• Производительность - показывает статистику производительности каждой страницы сайта с момента последнего ее сброса.

Создать новую страницу можно 2 способами:

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

При добавлении / редактировании страницы поддерживают следующие поля:

• Название - название страницы для панели администрирования.
• Идентификатор - уникальный идентификатор страницы, может содержать ограниченный набор символов (a-z, A-Z, 0-9, _). Данный идентификатор используется для PHP файла и шаблона страницы. Идентификатор не может быть изменен после создания страницы.
• Статус - позволяет выключить страницу. При запросе выключенной страницы на сайте будет отображаться 404 ошибка, как будто такой страницы не существует.
• Время жизни кэша - время кэширования страницы в оперативной памяти. Если указано значение 0 - то страница кэшироваться не будет. Для страниц, содержащих блоки, которые не поддерживают кэширование, данное поле не редактируется.
• Включить сжатие MemCache - указывает, использовать ли для данной страницы сжатие кэша. Включенная опция позволяет уменьшить загрузку оперативной памяти, однако приводит к небольшой потери производительности страницы.
• XML содержимое - указывает, что данная страница будет выводить данные в XML формате. Используется для организации любых XML фидов.
• Запретить доступ для - предоставляет возможность запретить доступ к данной странице для определенного круга пользователей сайта.
• При запрете перенаправлять по URL-у - если вы включили запрет доступа к странице для части пользователей, вы можете указать URL, по которому они должны быть перенаправлены в случае несанкционированного доступа. Если ничего не указано, то страница отображит 403 ошибку.
• Правила из .htaccess - поле доступно только для существующих страниц и показывает правила из корневого .htaccess файла, с которыми ассоциируется данная страница.
• Использует компоненты - перечисляет все компоненты страниц, которые подключаются в шаблоне данной страницы.
• Код шаблона - код шаблона Smarty для данной страницы. В шаблонах страниц можно использовать подключение блоков, компонентов страниц и рекламных мест.
• Содержимое страницы и стратегия кэширования - таблица со списком блоков, которые подключены на данную страницу, а также для каждого блока список включенных параметров, их значений и описание для каждого параметра. Таблица позволяет быстро изменить значение любого включенного параметра для любого блока на странице, а также время жизни кэша блока. Для включения или выключения какого-либо из параметров блока вам нужно зайти на страницу редактирования этого блока, используя ссылку в названии блока. Для удобства таблица также выводит значение глобальной переменной $storage по каждому блоку, которое может быть использовано в шаблоне страницы для обращения к данным блоков из страницы.

Более подробная информация о кэшировании будет представлена ниже.

Краткий обзор существующих страниц

Все существующие в дизайне по умолчанию страницы можно разбить на три логические группы:

• Страницы, которые используются во внутренней зоне пользователей и недоступны посетителям извне, например, страница редактирования профиля пользователя, страница загрузки видео и т.д. Такие страницы имеют префикс [Memberzone] в названии, а также префикс member_my_ в идентификаторе страницы (например, [Memberzone] My Friends Events и member_my_friends_events).
• Страницы, которые отображают данные в контексте какого-либо пользователя и доступны всем пользователям, например, страница со списком видео, загруженного пользователем, страница со списком друзей пользователя и т.д. Такие страницы имеют префикс Member's в названии, а также префикс member_ в идентификаторе страницы (например, Member's Events и member_events).
• Другие публичные страницы не связанные с пользователями, например, список категорий, страница логина и т.д.

При создании новых страниц мы рекомендуем учитывать данные конвенции наименования.

Кэширование первого уровня (кэширование блоков)

Кэширование первого уровня (кэширование блоков) является относительно медленным кэшированием. Этот вид кэширования можно использовать практически везде, где он поддерживается блоками. Как уже было замечено выше, некоторые блоки не поддерживают кэширование (в основном это блоки, которые содержат формы для заполнения, т.е. блок логина, блок загрузки видео и д.р.). Некоторые блоки не поддерживают кэширование при определенной конфигурации параметров, например, блок списка видео не включает кэширование при отображении результатов поиска, а также в некоторых других случаях. В любом случае, даже при включенном кэшировании движок самостоятельно решит, что следует кэшировать, а что нет.

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

Кэширование второго уровня (кэширование страниц)

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

Кэширование второго уровня дополнительно поддерживает опцию сжатия кэша, которая помогает сэкономить оперативную память, но в то же время уменьшает скорость работы кэша. Данную опцию следует использовать на страницах, количество экземпляров которых в кэше относительно большое (например, для страницы просмотра видео, поскольку в кэше хранится большое количество экземпляров страницы для всех видео).

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

Важные аспекты кэширования

Существует несколько важных аспектов кэширования, которые обязательно необходимо прочитать и понять, прежде чем работать с настройкой сайта.

Кэширование не включается для администратора (если он залогинен в панели администрирования). Это сделано для того, чтобы при работе с сайтом не возникало каких-либо задержек при начальной отладке. Финальное же тестирование сайта должно быть выполнено с учетом кэширования. Этого можно добиться, если тестировать сайт в другом браузере (не в том, в котором идет работа с панелью администрирования).

Кэширование не используется, если на страницу передан параметр mode со значение async. Данный параметр используется для асинхронных запросов в различных блоках сайта (например, отправка пользовательского рейтинга на видео, либо отображение captcha).

Кэширование ограничивает возможности кастомизации сайта (особенно кэширование второго уровня). Так, нельзя, чтобы отображение какого-либо контента зависело от параметров, которые передаются на страницу. Рассмотрим простейший пример: необходимо передать идентификатор вебмастера, который затем будет подставлен в ссылку на спонсора (учет партнерского трафика). Если данный идентификатор передается в параметре wm_id, то простой вариант, который может прийти в голову - это вывести ссылку на спонсора и в ней указать значение из параметра запроса:

<a href="http://sponsor.com?wm_id={{$smarty.request.wm_id}}">

Это не будет работать при включенном кэшировании, поскольку в течение времени жизни кэша данная ссылка будет содержать одно и то же значение параметра wm_id. Для корректной работы подобных параметров следует использовать поля Динамические HTTP параметры в Настройках сайта в разделе Настройки панели администрирования. В этих полях вы можете перечислить до 5 HTTP параметров, которые будут учитываться независимо от кэширования. Кроме того, эти HTTP параметры будут также учитываться в ссылках на контент провайдеров и на рекламу.

Для использования этих параметров вам нужно вставить в шаблоне (URL-е контент провайдера, URL-е рекламы) токен вида %param_name%, т.е. для примера выше ссылка на спонсора должна выглядеть таким образом:

<a href="http://sponsor.com?wm_id=%wm_id%">

Это подразумевает, что вы указали параметр wm_id в одном из полей Динамические HTTP параметры.

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

Таким образом, в большинстве случаев вы не можете безболезненно использовать переменные типа $smarty.request, $smarty.get, $smarty.post в шаблонах сайта. Вместо них следует использовать динамические HTTP параметры.

Кэширование второго уровня автоматически отключается для залогиненных пользователей. Это позволяет не только показывать "Привет, username" в шапке сайта, но и вообще использовать любые данные из сессии пользователя в шаблоне самой страницы (но не в шаблонах блоков!)

В большинстве случаев вы не можете использовать значения из сессии пользователя ($smarty.session) в шаблонах блоков, чтобы показывать различный контент различным пользователям сайта, поскольку для всех пользователей используется один и тот же экземпляр кэша блока. Исключение на данный момент составляют блоки video_view, video_comments, album_view, album_comments, album_images, dvd_view и dvd_comments. Эти блоки сохраняют разные версии кэша для разных пользователей. Также использовать данные из сессии пользователя можно во всех блоках, которые не кэшируются.

Для проверки корректности настройки кэширования запустите проверку страниц, блоков и шаблонов сайта в плагине аудита. Если проверка не выдает ошибок - скорее всего проблем никаких не будет. Любые ошибки должны быть исправлены, т.к. скорее всего они влияют на работоспособность сайта.

При необходимости сбросить кэш первого или второго уровня вы можете воспользоваться опциями Сбросить файловый кэш и Сбросить MemCache соответственно. Эти опции находятся в боковой панели раздела UI сайта панели администрирования. Сброс кэша приведет к большому скачку нагрузки при большом трафике, поэтому эту операцию стоит выполнять только в исключительных случаях (например, при срочной необходимости обновить все страницы сайта). Сначала следует сбросить файловый кэш (кэш блоков), а через некоторое время MemCache (кэш страниц).

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

Статистика производительности

Статистика производительности позволяет оценить нагрузку на любую страницу или блок и понять, насколько корректно выбрана стратегия кэширования.

Для каждой страницы / блока на списке страниц выводятся 4 цифры:

• Количество загрузок страницы с начала процесса мониторинга.
• Среднее время срабатывания при использовании кэширования.
• Среднее время срабатывания без использования кэширования.
• Относительный процент кэширования. Наиболее важный параметр, который показывает как часто используется кэш данной страницы / блока. Чем выше это значение - тем чаще срабатывает кэш, а значит производительность выше.

Статистика производительности может быть сброшена в любой момент используя опцию Сбросить статистику производительности в боковой панели раздела UI сайта панели администрирования.

JavaScript файлы

KVS использует несколько JavaScript файлов для работы сайта. Эти скрипты находятся в директории /js в корне домена. Некоторые блоки используют функции данных JavaScript файлов, поэтому требуют их включения на странице. JavaScript файлы, которые требуются блоками на какой-либо странице будут подключены автоматически. За вывод отвечает такая строка в шаблоне header_general.tpl:

{{$js_includes|smarty:nodefaults}}

Все JavaScript файлы подключаются ссылками, в которых указана текущая версия софта и которые используют расширение jsx, вместо js. Это нужно для того, чтобы при обновлении на новую версию софта у всех пользователей не осталось закэшированных браузеров JavaScript файлов (т.к. поменяются все ссылки на них). Вот пример одной из ссылок:

http://your_domain.com/js/KernelTeamVideoSharingSystem_2.0.0.jsx

Среди всех JavaScript файлов есть системные, которые добавляются независимо от блоков: KernelTeamVideoSharingSystem.js (добавляется всегда) и KernelTeamVideoSharingMembers.js (добавляется только для залогиненных пользователей).

По умолчанию все списки видео настроены на ротацию скриншотов видео формата 240x180. JavaScript с кодом ротатора подключается в шапке и доступен на каждой странице. Если вы используете только 1 скриншот для видео, либо вам не нужна ротация скриншотов, мы рекомендуем удалить включение скрипта ротатора в шаблоне шапки. Подключение ротатора задается таким образом:

<script type="text/javascript" src="{{$config.project_url}}/js/KernelTeamImageRotator_{{$config.project_version}}.jsx"></script>
<script type="text/javascript">
    KT_rotationEngineStartup(0.2, 0.5);
</script>

Второй параметр при вызове функции KT_rotationEngineStartup устанавливает длительность показа одного скриншота в секундах до переключения на следующий. Первый параметр игнорируется.

Сама ротация скриншотов запускается при наведении (останавливается при выходе) мышки на изображение скриншота:

// второй параметр - путь к директории, где лежат скриншоты
// третий параметр - кол-во скриншотов
onmouseover="KT_rotationStart(this, '{{$config.content_url_videos_screenshots}}/{{$item.screen_url}}/240x180/', {{$item.screen_amount}})"

onmouseout="KT_rotationStop(this)"

Если вам необходима ротация скриншотов других форматов, в обработчие события наведения мышки нужно заменить размер 240x180 на другой нужный.

Следующая таблица перечисляет все JavaScript файлы, которые поставляются по умолчанию (все они находятся в директории /js в корне домена). Часть из них доступна только в полной версии KVS.

Системные email сообщения

Некоторые блоки сайта имеют функционал для отправки email сообщений различного содержания (например, отправка ссылки на сайт другу и др.). Текстовки и заголовки этих сообщений находятся в директории emails для каждого блока, который поддерживает отправку email сообщений. При необходимости эти файлы могут быть изменены вручную:

Важно! Все файлы писем сохранены в кодировке UTF8.

Информация в сессии пользователя

Ниже приведен список полей сессии залогиненного пользователя, которые доступны в шаблонах сайта. Посмотреть актуальные значения всех данных сессии можно в отладчике страниц. Данные из сессии будут видны только если вы залогинены в зону сайта.

Важно! Переменные из сессии пользователя можно использовать только в шаблонах самих страниц, а также в шаблонах некоторых блоков (video_view, video_comments, album_view, album_comments, album_images, dvd_view и dvd_comments).

Подключение кастомного функционала к движку

При необходимости подключить кастомный функционал к движку обработки сайта вы можете редактировать несколько PHP файлов, которые вызываются в цикле обработки каждой страницы. Данные скрипты не подлежат обновлениям, соответственно ваши изменения не затрутся.

Создание кастомных блоков сайта

KVS предоставляет модульный движок сайта, в который вы можете добавлять свои блоки. Каждый блок имеет свой уникальный идентификатор (скорее это идентификатор типа блока) и все файлы этого блока должны находиться в директории /blocks/%block_id%, где %block_id% - это и есть идентификатор блока.

Блок должен содержать 3 главных файла, а также файлы локализации:

• /blocks/%block_id%/%block_id%.php - PHP файл блока, который содержит всю логику блока.
• /blocks/%block_id%/%block_id%.tpl - шаблон блока по умолчанию. Этот шаблон используется только в качестве примера, поэтому вы можете создавать пустой шаблон.
• /blocks/%block_id%/%block_id%.dat - метаданные о блоке в XML формате. Вы можете использовать такой шаблон для этого файла: <block>
      <block_name>Название блока</block_name>
      <author>Автор блока</author>
      <version>Версия блока (в любом формате)</version>
  </block>
• /blocks/%block_id%/langs/english.php - файл локализации текстовок блока по умолчанию.
• /blocks/%block_id%/langs/russian.php - файл локализации текстовок блока для русского языка (этот файл необязательный).

Основным файлом блока является, конечно же, PHP файл. Этот файл должен содержать набор функций со специальными названиями, которые вызываются движком сайта по мере необходимости. Кроме функций PHP файл блока также должен содержать такую строчку кода для отклика на механизм тестирования блоков:

if ($_SERVER['argv'][1]=='test' && $_SERVER['DOCUMENT_ROOT']=='') {echo "OK";}

Каждая функция блока должна иметь название, которое начинается с идентификатора блока, т.е. %block_id%FunctionName. Например Show функция для блока list_videos должна иметь название list_videosShow.

Набор поддерживаемых функций таков:

• Show-функция (%block_id%Show, обязательна) - вызывается движком в случае GET / POST запросов на страницу, содержащую этот блок. В зависимости от типа запроса функция может либо сделать выборку данных и подготовить их к отображению, либо обработать отправленную пользователем форму в случае POST запроса. Show-функция вызывается только тогда, когда блок либо не поддерживает кэширование, либо кэш блока устарел и нужно заново выполнить полный цикл отображения блока. Функция принимает 2 параметра: $block_config - ассоциативный массив со всеми включенными параметрами конфигурации блока на этой странице и их значениями (ключом является название параметра), и $object_id - уникальный идентификатор блока на странице. Данные для отображения функция должна поместить в глобальный объект $smarty, который будет отображать шаблон этого блока. Данные, которые вы поместите в объект $smarty будут доступны только в шаблоне блока. Если вы хотите, чтобы к некоторым данным блока можно было обращаться из шаблона страницы, то их нужно поместить в глобальный объект $storage, положив в массив под ключом $object_id. Вот простой пример реализации этой функции: function my_blockShow($block_config,$object_id)
  {
      global $smarty,$storage;
  
      $show_numbers_to=intval($block_config['show_numbers_to']); // получаем из конфигурации блока настроенное там число N
      $data=array();
      for ($i=1;$i<=$show_numbers_to;$i++)
      {
          $data[]=$i; // создаем массив со всеми числами от 1 до N
      }
  
      $smarty->assign("data",$data); // помещаем массив в глобальную переменную $smarty для отображения в шаблоне блока
      $storage[$object_id]['total_count']=$show_numbers_to; // помещаем общее кол-во элементов в $storage блока для отображения в шаблоне страницы
  }
  Если ваш блок должен обрабатывать POST запросы, то делается это примерно таким образом: function my_blockShow($block_config,$object_id)
  {
      global $smarty,$storage;
  
      if ($_POST['action']=='my_post_action')
      {
          здесь выполняется логика обработки формы
          header("Location: ?action=post_processed_successfully");die; // завершаем обработку страницы и делаем редирект на эту же страницу
      }
  
      if ($_GET['action']=='post_processed_successfully')
      {
          $smarty->assign("message","Your request has been processed"); // помещаем успешное сообщение для отображения
      }
  }
  Делать редирект и завершать обработку страницы в Show-функции можно только при обработке POST запросов, поскольку во время POST запроса не используется кэширование блока. Если существует необходимость сделать редирект во время обработки GET запроса, то необходимо вернуть из Show-функции специальную строку, которая будет обработана движком с учетом всей специфики кэширования: function my_blockShow($block_config,$object_id)
  {
      global $smarty,$storage;
  
      здесь выполняется логика обработки
  
       // сообщаем движку, что нужно сделать 301 редирект по урлу
      return "status_301:http://url_to_redirect.com";
  
       // или сообщаем движку, что нужно сделать 302 редирект по урлу
      return "status_302:http://url_to_redirect.com";
  }
  Кроме этого, можно вернуть строку "status_404", если вы хотите, чтобы движок выдал 404 ошибку по странице с этим блоком.
• GetHash-функция (%block_id%GetHash, обязательна) - предназначена для кэширования блока. Функция должна возвращать одинаковое строковое значение для запросов, по которым отображается одинаковый HTML код блока, и разное для тех запросов, по которым HTML блока будет отличаться. Функция принимает 1 параметр: $block_config - ассоциативный массив со всеми включенными параметрами конфигурации блока на этой странице и их значениями (ключом является название параметра). Как правило, возвращаемая строка должна содержать список всех значений, которые передаются блоку через параметры запроса, разделенных каким-то разделителем. Самый простой пример - блок списка с пагинацией, который должен возвращать разный хэш для разных страниц списка. Это делается следующим образом: function my_blockGetHash($block_config)
  {
      $from=intval($_REQUEST[$block_config['var_from']]); // получаем из запроса переданное значение номера страницы, возможно пустое
      $category=trim($_REQUEST[$block_config['var_category_dir']]); // получаем из запроса переданное значение директории категории, возможно пустое
      return "$from|$category"; // возвращаем оба значения через разделитель, чтобы при разных переданных параметрах на выходе была разная строка
  }
  Если блок вообще не должен кэшироваться, то вы можете вернуть системное значение "nocache", которое будет означать запрет кэширования блока, а значит и запрет кэширования страницы с этим блоком.
• CacheControl-функция (%block_id%CacheControl, необязательна) - предназначена для указания типа кэширования блока, что используется в панели администрирования для поиска потенциальных ошибок кэширования. Функция должна возвращать одну из строк: "nocache" - если блок не кэшируется, "user_specific" - если блок кэшируется отдельно для каждого пользователя сайта, "status_specific" - если блок кэшируется отдельно для пользователей разных статусов, и "default" - если блок кэшируется стандартным образом. Функция принимает 1 параметр: $block_config - ассоциативный массив со всеми включенными параметрами конфигурации блока на этой странице и их значениями (ключом является название параметра). Пример функции: function my_blockCacheControl($block_config)
  {
      return "user_specific"; // указываем что блок имеет разные варианты кэша для разных пользователей
  }
  
• MetaData-функция (%block_id%MetaData, обязательна) - предназначена для указания поддерживаемых блоком параметров конфигурации. Именно эти параметры и их значения, когда включены в настройках блока на странице, передаются другим функциям блока в виде ассоциативного массива (название_параметра => значение) в параметре $block_config. Вот пример реализации данной функции со всеми типами параметров: function my_blockMetaData()
  {
      return array(
          array("name"=>"integer_parameter",      "type"=>"INT",                    "is_required"=>1, "default_value"=>"10"),
          array("name"=>"string_parameter",       "type"=>"STRING",                 "is_required"=>0, "default_value"=>""),
          array("name"=>"checkbox_parameter",     "type"=>"",                       "is_required"=>0),
          array("name"=>"integer_list_parameter", "type"=>"INT_LIST",               "is_required"=>0, "default_value"=>""),
          array("name"=>"combobox_parameter",     "type"=>"CHOICE[1,2,3]",          "is_required"=>0, "default_value"=>"1"),
          array("name"=>"sorting_parameter",      "type"=>"SORTING[field1,field2]", "is_required"=>1, "default_value"=>"field1"),
      );
  }
  
• Javascript-функция (%block_id%Javascript, необязательна) - функция предназначена для указания, какой JavaScript файл требуется для работы данного блока. Функция принимает 1 параметр: $block_config - ассоциативный массив со всеми включенными параметрами конфигурации блока на этой странице и их значениями (ключом является название параметра). Функция должна вернуть название JavaScript файла относительно директории /js/ в корне проекта, т.е. по сути просто название файла без каких-либо путей к нему. Если функция отсутствует, то считается, что блоку не требуется JavaScript. Пример реализации функции: function my_blockJavascript()
  {
      return "MyBlockJavaScript.js";
  }
  
• Async-функция (%block_id%Async, необязательна) - функция предназначена для обработки асинхронных запросов на страницу (запросы, которые сделаны с параметром ?mode=async). Функция принимает 1 параметр: $block_config - ассоциативный массив со всеми включенными параметрами конфигурации блока на этой странице и их значениями (ключом является название параметра). При получении асинхронного запроса движок не вызывает функции Show блоков страницы, а вызывает функции Async у тех блоков на странице, у которых они определены. Любой блок может обработать пришедший в функцию Async запрос и выдать результат, после чего завершить выполнение движка: function my_blockAsync($block_config)
  {
      if ($_REQUEST['action']=='my_async_action')
      {
          здесь выполняется логика обработки
          echo "processed";die; // завершаем обработку страницы и выводим результат прямо в поток
      }
  }
  
• PreProcess-функция (%block_id%PreProcess, необязательна) - функция предназначена для тех случаев, когда какой-то код в блоке должен выполняться независимо от того, закэширован ли блок или нет. В отличие от Show-функции, которая не вызывается при каждом обращении к странице с данным блоком (частота вызова Show-функции зависит от методики кэширования блока), PreProcess-функция вызывается всегда. Исходя из этого PreProcess-функция должна содержать только быстровыполняемый код и не использовать никаких подключений к базе данных. Основное назначение данной функции - запись статистики. Например, PreProcess-функция блока video_view записывает в статистику каждый свой вызов, что потом аккумулируется в качестве статистики просмотров видео. Функция принимает 2 параметра: $block_config - ассоциативный массив со всеми включенными параметрами конфигурации блока на этой странице и их значениями (ключом является название параметра), и $object_id - уникальный идентификатор блока на странице.

Файл локализации блока должен предоставлять базовые описания, а также описание всех параметров конфигурации и названия значений для параметров типа CHOICE и SORTING, которые задаются MetaData-функцией. Вот пример типового файла локализации:

$lang['%block_id%']['block_short_desc'] = "Краткое описание блока";
$lang['%block_id%']['block_desc'] = "Полное описание блока";
$lang['%block_id%']['params']['integer_parameter'] = "Описание параметра integer_parameter";
$lang['%block_id%']['params']['string_parameter'] = "Описание параметра string_parameter";
$lang['%block_id%']['params']['checkbox_parameter'] = "Описание параметра checkbox_parameter";
$lang['%block_id%']['params']['integer_list_parameter'] = "Описание параметра integer_list_parameter";
$lang['%block_id%']['params']['combobox_parameter'] = "Описание параметра combobox_parameter";
$lang['%block_id%']['params']['sorting_parameter'] = "Описание параметра sorting_parameter";
$lang['%block_id%']['values']['combobox_parameter']['1'] = "Название опции 1 параметра combobox_parameter";
$lang['%block_id%']['values']['combobox_parameter']['2'] = "Название опции 2 параметра combobox_parameter";
$lang['%block_id%']['values']['combobox_parameter']['3'] = "Название опции 3 параметра combobox_parameter";
$lang['%block_id%']['values']['sorting_parameter']['field1'] = "Название опции field1 параметра sorting_parameter";
$lang['%block_id%']['values']['sorting_parameter']['field2'] = "Название опции field2 параметра sorting_parameter";
$lang['%block_id%']['values']['sorting_parameter']['rand()'] = "Название опции rand() параметра sorting_parameter";

Отладка страниц сайта

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

Важно! Доступ к отладчику страниц доступен только если вы залогинены в панель администрирования.

Для того, чтобы открыть отладчик страницы сайта, на которой вы в данный момент находитесь, вам необходимо к адресу страницы добавить HTTP параметр debug=true, после чего KVS выведет всю отладочную информацию по текущей странице:

http://domain.com/videos/123/video/?debug=true

Отладчик отображает следующие отладочные данные по странице:

• ID страницы - идентификатор текущей страницы.
• Название - название текущей страницы и ссылка на ее редактирование.
• Отдача XML - отдает ли текущая страница данные в XML формате.
• Локаль - если текущая страница отображается в нестандартной локали, показывается локаль.
• Компоненты страниц, используемые в шаблоне страницы - список компонентов страниц, которые используются в шаблоне текущей страницы сайта, и ссылки на их редактирование.
• URI запроса - часть адреса запроса, которая находится после доменного имени (эта часть адреса участвует в правилах mod_rewrite).
• Параметры HTTP - список HTTP параметров, которые передаются на страницу (они могут передаваться как через URI запроса, так и подставляться из правил mod_rewrite).
• Значения в сессии - значения в сессии пользователя, если вы залогинены в зону пользователя на сайте.
• Динамические HTTP параметры - значения динамических параметров.

По каждому блоку, который присутствует на странице, отладчик отображает следующие данные:

• Название блока - название блока на текущей странице и ссылка на его редактирование.
• Тип блока - тип блока и ссылка на детальное описание типа блока.
• Ключ storage - ключ глобальной переменной $storage для указанного блока на текущей странице.
• Параметры конфигурации блока - перечисляются все включенные параметры конфигурации блока и их значения. Для var-параметров (параметры, которые ссылаются на HTTP параметры запроса) в скобках показываются соответствующие им значения HTTP параметров запроса, если в запросе найдено соответствие.
• Компоненты страниц, используемые в шаблоне блока - список компонентов страниц, которые используются в шаблоне указанного блока на текущей странице, и ссылки на их редактирование.
• Данные блока в хранилище storage - набор всех данных, которые содержатся в хранилище $storage блока и доступны для использования в шаблоне текущей страницы сайта (данные из $storage могут использоваться только после места вставки блока в шаблоне страницы).
• Переменные в шаблоне блока - набор всех переменных, которые доступны для использования в шаблоне указанного блока на текущей странице и их актуальные значения.

Пример использования любой переменной:

// вывод ID видео из storage блока video_view в шаблоне страницы сайта
{{$storage.video_view_video_view.video_id}}

// вывод ID видео в шаблоне блока video_view
{{$data.video_id}}

Для итерации по переменной-массиву следует использовать конструкцию {{foreach}}:

{{foreach name=data item=item from=$storage.video_view_video_view.tags}}
    {{* Обращение к элементу массива идет через переменную $item *}}
    {{$item.tag_id}}
    {{$item.tag}}
{{/foreach}}

Обратите внимание, что если у вас уже есть один цикл {{foreach}} (например, по списку видео), и внутри него вы хотите добавить еще один цикл (например, вывести категории для каждого видео в списке), то вам необходимо использовать другое название для переменных item и name:

{{foreach name=data item=item from=$data}}
    {{* Обращение к элементу основного массива идет через переменную $item *}}
    Название: {{$item.title}}
    Категории:
    {{* Внутренний цикл по категориям, список категорий доступен в переменной $item.categories *}}
    {{foreach name=data_inner item=item_inner from=$item.categories}}
        {{* Обращение к элементу внутреннего массива идет через переменную $item_inner *}}
        {{$item_inner.title}},
    {{/foreach}}
{{/foreach}}