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

Темы - это то, что определяет внешний вид вашего видео веб-сайта. Темы - ничто иное как набор CSS, JavaScript и файлы шаблона, хранимые в директории тем. Это руководство проведёт вас через структуру темы, а также создавать их и устанавливать.

Введение

Все темы в CumulusClips хранятся в каталоге тем: /cc-content/themes. Каждая тема сидит в своём собственном каталоге в этом месте. У вас может быть столько тем, сколько вы пожелаете, но включенными быть могут только две: одна для основного сайта, другая для мобильного. Чтобы увидеть какие темы доступны в CumulusClips посетите раздел тем в административной панели: Admin Panel -> Appearance -> Themes.

Создание темы

Лучший способ создать тему для CumulusClips - это скопировать тему по умолчанию cumulus и дать ей новое уникальное название. Затем откройте текстовым редактором файл theme.xml и обновите название темы, автора, и любые другие желаемые поля.

Если вы готовы принять вызов и желаете построить целиком и полностью свою тему с нуля, то ниже вы найдёте список необходимых файлов для темы. Просто создайте каталог внутри /cc-content/themes. Название каталога должно быть уникально и состоять только из букв нижнего ригистра, без пробелов или специальных символов. Затем, добавьте все требуемые файлы в созданный вами каталог темы.

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

Необходимые файлы

Для постоения темы CumulusClips необходимы несколько каталогов и файлов, вот они:

  • theme.xml
  • screenshot.png
  • layouts/
    • default.header.tpl
    • default.footer.tpl
  • index.tpl
  • videos.tpl
  • members.tpl
  • profile.tpl
  • play.tpl
  • comments.tpl
  • member_videos.tpl
  • contact.tpl
  • register.tpl
  • login.tpl
  • server_404.tpl
  • activate.tpl
  • opt-out.tpl
  • myaccount/
    • myaccount.tpl
    • upload.tpl
    • upload_video.tpl
    • upload_complete.tpl
    • myvideos.tpl
    • edit_video.tpl
    • myfavorites.tpl
    • update_profile.tpl
    • privacy.tpl
    • change_password.tpl
    • mysubscriptions.tpl
    • mysubscribers.tpl
    • message_inbox.tpl
    • message_send.tpl
    • message_read.tpl

Переменные

Изнутри объекта view, блоков и разметок, у вас есть доступ к системному объекту $config, всем системным константам и любым переменным объекта View.

Нормальные переменные, которые предназначены для доступа из файлов темы, должны быть назначены объекту View, или controller-у, или плагину.

View::$vars->my_variable = 'Это будет доступно из view-шки';

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

<h1><?=$my_variable?></h1>

Метаданные

Основные метаданные, которые состоят из заголовка страницы, ключевых слов и тегов описания берутся из текущего языкового файла. Эти значения хранятся в cвойстве meta объекта View, разумеется, если определена (некоторые страницы могут намеренно опускать эти теги). Для доступа к метаданным страницы ссылайтесь на свойство View::$meta, т.е.:

<head>
<title><?=View::$meta->title?></title>
<meta name="description" content="<?=View::$meta->description?>" />
</head>

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

Системный объект $config

Системный объект $config содержит некоторые системные настройки, которые используются как в ваших темах, так и во всём приложении. Большинство значений $config назначены файлом начальной загрузки (/cc-core/config/bootstrap.php). Вы можете просмотреть этот файл и увидеть некоторые доступные вам значения. Имейте ввиду, что содержимое объекта $config может измениться с момента определения в начале загрузки, до момента вызова вашей темы.

Объект $config - глобальный, поэтому напрямую доступен в файлах фаших тем. Одно из наиболее используемых значений $config - это видео URL-ы, такие как H.264 видео URL т.е.:

<video width="640" height="480">
    <source src="<?=$config->h264_url?>/video.mp4" type="video/mp4" />
</video>

Константа THEME

Все системные константы доступны вашей теме, однако константа THEME особенно полезна. Это URL который даёт доступ к корневому каталогу вашей темы. Она содержит URL наподобие этого:

http://{your_domain}/cc-content/themes/{your_theme}

Это удобно для определения прямых URL к различным файлам, таким как CSS, JavaScript, изображениям и прочим файлам вашей темы. Вот пример ссылки на CSS внутри вашей темы, используя константу THEME:

<link rel="stylesheet" type="text/css" href="<?=THEME?>/css/main.css" />

Константа THEME_PATH

THEME_PATH похожа на вышеобозначенную константу THEME только она даёт путь по файловой системе к корневому каталогу вашей темы вместо URL. Она выводит что-то наподобие:

/path/to/your/site/cc-content/themes/{your_theme}

Это удобно при программировании внутри темы, например для подключения скриптов через PHP. Вот пример включения скрипта PHP в вашей теме, используя константу THEME_PATH:

include_once (THEME_PATH . '/scripts/random.php');

Составляющие темы

Скриншот

Скриншот - это значок вашей темы шириной в 200px в формате png. Этот файл отображается вместе с ижнформацией о вашей теме в разделе Themes в административной панели. Он должен называться просто 'screenshot.png' и находиться в корневом каталоге вашей темы.

XML-файл темы

XML-файл определяет вашу тему в CumulusClips. В него необходимо добавить описательную информацию о вашей теме, такую как название, описание, автор и т.д. Ниже приведен пример XML-файла темы:

<?xml version="1.0" encoding="UTF-8"?>
<theme>
    <author>Мигель А. Хуртадо</author>
    <name>Cumulus</name>
    <mobile>false</mobile>
    <description>Тема для CumulusClips по умолчанию</description>
</theme>

Эта информация видима администраторам в пределах раздела тем панели администратора. Следующие XML-элементы темы необходимы:

  • author - Персона / организация, создавшая тему
  • name - Название темы
  • mobile - Является или нет эта тема мобильной. (true если для мобильных платформ, false если нет)
  • description - Краткое описание для темы

Вы свободно можете добавлять собственную информацию на своё усмотрение. XML-файл темы должен быть назван 'theme.xml' и находиться в корневом каталоге темы.

Представления

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

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

Из представления вы можете отдать распоряжения системе загрузить верхний/нижний колонтитул в любом месте, где вы пожелаете посредством вызова методов View::Header и View::Footer. Пример представления может выглядеть следующим образом:

<?php View::Header(); ?>

<h1>Заголовок</h1>
<p>Содержимое страницы</p>

<?php View::Footer(); ?>

Разметки

Структура вашей темы состоит из разметок. Разметка - это пара файлов, верхний и нижний колонтитул, в каталоге разметок. Они должны быть названы в соответствии со следующим соглашением:

{ваша_разметка}.header.tpl
{ваша_разметка}.footer.tpl

Вы можете переопределить это поведение и использовать другую разметку, вызвав метод View::SetLayout из представления и передавая нужное имя разметки, например

View::SetLayout('my_custom_layout');

CumulusClips будет использовать разметку 'my_custom_layout'.

Блоки

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

Блок может быть вставлен вызовом метода View::Block. Вы должны передать имя блока который вы хотите подключить, т.е.

View::Block('ad_300.tpl');

В результате блок 'ad_300' будет включен. Метод View::Block поддерживает как имя файла блока, так и и полный путь файловой системы. По умолчанию этот метод перым делом смотрит в каталог blocks/. Если каталог или файл не существует, то полученное имя будет трактовано как путь файловой системы. Блоки могут быть использованы во всех представлениях, разметках и даже в других блоках.

Повторяющиеся блоки

Повторяющиеся блоки идентичны обычным блокам. Однако, что следует отметить при использовании повторяющихся блоков является то, что они предназначены для вывода много раз подряд. Чтобы вывести последовательность повторяющихся блоков, используйте метод View::RepeatingBlock, передайте ему имя блока, который вы хотите повторять и список, который надо перебрать, например:

View::RepeatingBlock('block.tpl', $list_of_records);

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

<?php $list_of_videos = array (43, 59, 81, 92, 101, 166); ?>

<!-- Недавнее видео -->
<div id="recent-videos">
    <?php View::RepeatingBlock ('recent_video_block.tpl', $list_of_videos); ?>
</div>

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

<!-- recent_video_block.tpl -->
<?php $video = new Video ($_id); ?>

<div>
    <p><a href="<?=$video->url?>/"><?=$video->title?></a></p>
    <p><?=$video->description?></p>
</div>

Очереди

Шаблонизатор CumulusClips использует очереди для того, чтобы позволить разработчикам плагинов, ставить в очередь свои элементы, которые позднее будут выведены все вместе. В шаблонизаторе есть четыре очереди. Вот они:

  • Очередь CSS
  • Очередь JavaScript
  • Очередь метаданных
  • Очередь блока боковой колонки

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

Использавание очередей - это двухступенчатый процесс. Сначала вы должны добавить элемент в очередь используя метод Add. Затем вы должны отдать распоряжение шаблонизатору перечислить все эти элементы используя метод Write. Все вышеперечисленные очереди работают одинаково.

Очередь CSS

Для того, чтобы добавить элемент в очередь CSS вы должны использовать метод View::AddCss. Вы должны указать файл, который желаете поставить в очередь. Этот метод принимает как имя файла, так и URL. Этот метод первым делом ищет принятый файл в каталоге css/ вашей темы. Если файла или каталога не существует, он будет воспринимать представленный аргумент как прямой URL и использовать его как есть. Вот пример обоих методов:

View::AddCss('http://random-site.com/styles/reset.css');
View::AddCss('test.css');
View::AddCss('main.css');

Позднее, в секции HEAD вашей темы, вы можете вывести всю очередь CSS, используя метод View::WriteCss, т.е.:

<head>
<title>Моя страница</title>
<?php View::WriteCss(); ?>
</head>

Метод View::WriteCss автоматически сформирует HTML, необходимый для правильного подключения файла CSS. Приведенный выше вывод будет выглядеть так:

<head>
    <title>Моя страница</title>
    <link rel="stylesheet" type="text/css" href="http://random-site.com/styles/reset.css" />
    <link rel="stylesheet" type="text/css" href="http://example.com/cc-content/themes/example/css/test.css" />
    <link rel="stylesheet" type="text/css" href="http://example.com/cc-content/themes/example/css/main.css" />
</head>

Очередь JavaScript

Для того, чтобы добавить элемент в очередь JavaScript вы должны использовать метод View::AddJs. Вы должны указать файл, который желаете поставить в очередь. Этот метод принимает как имя файла, так и URL. Этот метод первым делом ищет принятый файл в каталоге js/ вашей темы. Если файла или каталога не существует, он будет воспринимать представленный аргумент как прямой URL и использовать его как есть. Вот пример обоих методов:

View::AddJs('https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.js');
View::AddJs('plugin.js');

По умолчанию, очередь выводится в нижней части HTML, перед закрывающим тегом BODY. Вы можете вывести всю очередь JavaScript используя метод View::WriteJs, т.е.:

</div>
    <!-- END Wrapper -->

    <?php View::WriteJs(); ?>

</body>
</html>

Метод View::WriteJs автоматически сформирует HTML, необходимый для правильного подключения файла JavaScript. Приведенный выше вывод будет выглядеть так:

</div>
    <!-- END Wrapper -->

    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.js"></script>
    <script type="text/javascript" src="http://example.com/cc-content/themes/example/js/plugin.js"></script>

</body>
</html>

Очередь метаданных

Для того чтобы добавить элемент в очередь метаданных, используйте метод View::AddMeta. Этот метод принимает пары ключ-значение, по-сути имя мета-тега и его содержимое. Очередь метаданных может форимровать только мета-теги, другие, такие как http-equiv не могут быть сгенерированы посредством очереди метаданных. Вот пример добавления к очереди метаданных:

View::AddMeta('robots', 'noindex,nofollow');
View::AddMeta('author', 'Billy Joe Bob');

Позднее, в секции HEAD вашей темы, вы можете вывести всю очередь метаданных, используя метод View::WriteMeta, т.е.:

<head>
<title>Моя страница</title>
<?php View::WriteMeta(); ?>
</head>

Метод View::WriteMeta автоматически сформирует HTML, необходимый для правильного вывода метаданных. Приведенный выше вывод будет выглядеть так:

<head>
    <title>Моя страница</title>
    <meta name="robots" content="noindex,nofollow" />
    <meta name="author" content="Billy Joe Bob" />
</head>

Очередь блока боковой колонки

Для того чтобы добавить элемент в очередь боковой колонки, используйте метод View::AddSidebarBlock. Этот метод принимает файл блока, который вы желаете добавить в очередь. Этот метод принимает как имя файла, так и полный путь файловой системы. Этот метод первым делом ищет принятый файл в каталоге blocks/ вашей темы. Если файла или каталога не существует, он будет воспринимать представленный аргумент как полный путь файловой системы и использовать его как есть. Вот пример обоих методов:

View::AddSidebarBlock('/var/www/html/cc-content/plugins/sample/custom-block.tpl');
View::AddSidebarBlock('login-box.tpl');

Обычное месторасположение блоков боковой колонки, разумеется в боковой колонке, которая распологается в файле нижнего колонтитула разметки. Однако, вы можете использовать этот метод в любом месте вашей темы. Для того чтобы вывести очередь блоков боковой колонки, вы должны использовать метод View::WriteSidebarBlocks, т.е.:

<!-- НАЧАЛО боковой колонки -->
<div id="sidebar">

    <?php View::WriteSidebarBlocks(); ?>

</div>
<!-- КОНЕЦ боковой колонки -->

Результатом вышеуказанного примера будет включение всех блоков в нужное место вашей темы.