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

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

Под темой понимается возможность выполнить полную перезагрузку / подмену шаблонов страниц сайта без вмешательства в код исходных файлов шаблонов проекта. В рамках темы доступна как подмена существующих 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 - при наличии ошибок возникших в процессе
  • идентичные правила действуют и для остальных упомянутых функций.

Ошибки

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