Создание темы (смена дизайна)

Что такое тема?

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

Рассмотрим порядок работы с темой на примере темы под названием example.

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

Авторизоваться в панели управления
Перейти в режим разработчика (в правом верхнем меню пользователя)
Перейти в раздел "Дополнения / Темы" и нажать на ссылку "создать тему" в правом верхнем углу
Указать берется ли одна из существующих тем за основу (наследуемая) или это новая тема
Указать название вашей новой темы, например "Моя тема"
Указать название темы латиницей, например "example" (допустимые символы a-z, 0-9, _)
Нажать "Создать" (Create)
После чего система создаст директорию темы /themes/example/, а также файл index.php в ней
Созданная вами тема отобразится в панели управления в разделе "Дополнения / Темы".

Активация темы

Каждая тема, для ее работы в проекте, должна быть активирована.

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

Структура файлов темы

Хранение файлов в директории темы имеет следующий порядок:

Файлы php-шаблонов должны иметь схожую по вложенности структуру хранения, аналогичную оригинальному пути, например:
Путь к оригинальному файлу (изменения в который необходимо внести) - /modules/site/tpl/def/index.php
Путь к шаблону в директории темы - /themes/example/modules/site/tpl/def/index.php
Файлы статики (изображения / javascript / css) должны располагаться в директории /static/ в директории темы.
Путь к оригинальному файлу (изменения в который необходимо внести) - /public_html/js/app.js
Путь к файлу в директории темы - /themes/example/static/js/app.js
В момент установки/активации темы они будут скопированы в директорию: /public_html/themes/example/
После чего в процессе работы проекта система при попытке подключения файла проверит нет ли файла по схожему пути в директории темы и если есть подключит его

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

Доработки

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

$this->setSettings(array(
    'theme_title'   => 'Новая тема',
    'theme_parent'  => 'base',
));

В примере Новая тема наследует Стандартную тему (base). В случае если у вас будет активна Новая тема и файл шаблона не был в ней найден будет подключен файл Стандартной темы, это касается как файлов шаблонов php так и статических файлов js/css/изображений, идентично подмене исходных файлов системы темой.

Структура файла index.php

В директории темы минимально обязательно наличие файла index.php. Рассмотрим пример его содержания, на примере темы под названием 'example':

<?php

class Theme_Example extends Theme
{
    public function init()
    {
        parent::init();

        $this->setSettings(array(
            'theme_title'   => 'Моя тема',
            'theme_version' => '1.0.0',
            'extension_id'  => '1234567890123456789012345678901234567890', // уникальный идентификатор дополнения
        ));

        /**
         * Настройки заполняемые в админ. панели
         */
        $this->configSettings(array(
            // ...
        ));
    }

    /**
     * Метод вызываемы в момент старта (запуска) темы
     */
    protected function start()
    {
        // ...
    }
}

Опишем подробнее:

Название класса темы всегда начинается с префикса Theme_, а сам класс наследует базовый класс Theme.
В обязательной функции init указывается название темы, ее версия, а также объявляются дополнительные настройки.
Весь остальной код темы следует размещать уже в функции start, а также в функциях данного класса. Дополнительные php файлы с фунциями также следует подключать в функции start, либо же непосредственно перед использованием.

Для каждого из описанных выше действий предусмотрена соответствующая функция, вызываемая в момент данного действия:

install - установка
uninstall - удаление
activate - активация
deactivate - деактивация
update - обновление

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

    protected function install()
    {
        if ( ! parent::install()) return false;
        // дополнительные действия
        return true;
    }

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

Ошибки

В процессе работы темы могут возникать ошибки, которые разработчик темы может фиксировать в лог-файле ошибок. Подробнее о работе с ошибками читайте в статье "Логирование ошибок"