Главная Документация Разработка Темы

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

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

WS 0.971
Тема CMS WebSource определяет HTML-структуру сайта, шаблоны страниц и записей, стили, JavaScript и локализацию.

В этом руководстве создадим минимальную рабочую тему и подключим её через административную панель.

Структура темы

Темы хранятся в папке:

text
resource/themes

Создайте отдельную папку темы:

text
resource/themes/example

Рекомендуемая начальная структура:

text
example/
  assets/
    css/
      style.css
    js/
      script.js
  includes/
    header.php
    footer.php
  template/
    page/
      default.php
    post/
    404.php
  index.php
  theme-info.json

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

  • theme-info.json
  • index.php

Остальные файлы добавляются в зависимости от устройства сайта.

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

Описание темы

Создайте файл theme-info.json в корне темы:

json
{
    "theme-name": "Example",
    "theme-author": "Author",
    "theme-version": "1.0.0"
}

Все три поля обязательны:

Поле Описание
theme-name Отображаемое название темы.
theme-author Автор темы.
theme-version Версия темы.

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

Общий header

Создайте файл includes/header.php:

php
<!DOCTYPE html>
<html lang="<?php echo CurrentLanguage::htmlLang(); ?>">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <?php
    echo PageData::getSeoHead();
    echo PageData::getFaviconHead();
    echo CurrentTheme::getCSS();
    ?>
</head>
<body>
    <header>
        <a href="<?php echo CurrentLanguage::url('/'); ?>">Главная</a>
    </header>

CurrentTheme::getCSS() автоматически сформирует подключения существующих файлов стилей темы.

Создайте файл includes/footer.php:

php
    <footer>
        <p>Example</p>
    </footer>
    <?php echo CurrentTheme::getJS(); ?>
</body>
</html>

CurrentTheme::getJS() подключает JavaScript темы и создаёт объект window.wsSite с данными текущей страницы и окружения сайта.

Главная страница

Корневой файл index.php используется для главной страницы сайта:

php
<?php include CurrentTheme::header(); ?>

<main>
    <h1><?php echo PageData::getTitle(); ?></h1>
    <div><?php echo PageData::getContent(); ?></div>
</main>

<?php include CurrentTheme::footer(); ?>

CMS самостоятельно выбирает этот файл для главной страницы.

Шаблон обычной страницы

Создайте файл template/page/default.php:

php
<?php include CurrentTheme::header(); ?>

<main>
    <h1><?php echo PageData::getTitle(); ?></h1>
    <div><?php echo PageData::getContent(); ?></div>
</main>

<?php include CurrentTheme::footer(); ?>

После активации темы шаблон default появится в списке шаблонов страницы в административной панели.

Имя файла становится именем шаблона:

text
template/page/default.php -> default

Шаблоны записей

Шаблоны записей хранятся отдельно:

text
template/post/{template}.php

Например:

text
template/post/news.php

Такой файл можно назначить типу записей через административную панель.

Внутри шаблона доступны данные текущей записи:

php
<?php include CurrentTheme::header(); ?>

<main>
    <article>
        <h1><?php echo PageData::getTitle(); ?></h1>
        <div><?php echo PageData::getContent(); ?></div>
    </article>
</main>

<?php include CurrentTheme::footer(); ?>

Страница ошибки

Для собственной страницы ошибки создайте template/404.php:

php
<?php include CurrentTheme::header(); ?>

<main>
    <h1>404</h1>
    <p>Страница не найдена.</p>
</main>

<?php include CurrentTheme::footer(); ?>

Если файл отсутствует, CMS использует системную страницу ошибки.

Стили

Основные стили разместите в файле:

text
assets/css/style.css

Он автоматически подключается при вызове:

php
echo CurrentTheme::getCSS();

Дополнительно CMS подключает файл, совпадающий с текущим шаблоном:

text
assets/css/index.css
assets/css/default.css
assets/css/news.css

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

Отсутствующие файлы просто пропускаются.

JavaScript

Основной JavaScript разместите в файле:

text
assets/js/script.js

Он автоматически подключается при вызове:

php
echo CurrentTheme::getJS();

Для ES-модулей можно использовать:

text
assets/js/modules/script.js

Также поддерживаются файлы текущего шаблона:

text
assets/js/default.js
assets/js/modules/default.js

Файлы из папки modules подключаются с атрибутом type="module".

Изображения и другие ресурсы

Получайте URL ресурсов через CurrentTheme::assetUrl():

php
$logo = CurrentTheme::assetUrl(
    'images',
    'logo.svg'
);

Использование в HTML:

php
<img src="<?php echo CurrentTheme::assetUrl('images', 'logo.svg'); ?>" alt="Логотип">

Метод проверяет существование файла и добавляет версию темы к URL.

Папку assets передавать не нужно.

Локализация

Переводы темы хранятся в папке lang:

text
lang/
  ru/
    common.php
  en/
    common.php

Пример lang/ru/common.php:

php
<?php
return [
    'main' => 'Главная',
    'contacts' => 'Контакты',
];

Получение перевода:

php
echo SiteLang::html('main', 'Главная');

Для каждого языка используется его URL-префикс.

Настройки темы

Файл theme-settings.json является необязательным.

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

Значения настроек доступны через:

php
$logo = CurrentTheme::data('logo');

Настройки темы лучше вынести в отдельное руководство, поскольку их структура зависит от типов полей административной панели.

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

После создания файлов:

  1. Откройте раздел тем в административной панели.
  2. Выберите тему Example.
  3. Сохраните настройки.
  4. Откройте главную страницу сайта.

CMS покажет тему в списке только как непосредственную папку внутри resource/themes.

Тема не будет активирована, если:

  • отсутствует theme-info.json
  • manifest содержит некорректный JSON
  • отсутствует одно из обязательных полей manifest
  • отсутствует или недоступен index.php
  • папка темы находится вне resource/themes

Проверка результата

После активации проверьте:

  • открывается ли главная страница
  • выводятся ли header и footer
  • подключился ли assets/css/style.css
  • подключился ли assets/js/script.js
  • появился ли шаблон default при редактировании страницы
  • открывается ли страница с назначенным шаблоном
  • отображается ли собственная страница 404
  • изменяется ли параметр ?v= у ресурсов после обновления версии темы