Ваш первый сайт

От чистой установки до собственного раздела, выводящего собственный компонент через XSLT-представление. Потребуется пустой вариант из руководства по установке и учётная запись администратора. Команды выполняются в корневой папке проекта от имени пользователя сайта.

Во время разработки держите 'debug' => 1 в htdocs/system.config.php, а после изменения этого параметра выполняйте php index.php setup linker из каталога htdocs/. На рабочем сайте верните значение 0.

1. Раздел

  1. Авторизуйтесь по адресу /login/ и откройте «Управление структурой», /admin/structure/.
  2. Выберите «Главная страница» в дереве и нажмите «Добавить» — плюс под деревом.
  3. Заполните форму:
    • «Содержимое страницы» — «Текстовая страница»;
    • «Макет страницы» — «Базовый»; оба списка открываются на других пунктах, поэтому обязательно выберите оба;
    • «Сегмент URI» — releases;
    • на вкладках «Русский» и «Українська», «Название раздела» — Releases: название обязательно на каждом языке.
  4. Нажмите «Сохранить».

Раздел откроется по адресу /releases/ с его названием в заголовке, а в главном меню появится соответствующий пункт: новый раздел получает тег menu.

2. Текст

На странице /releases/ включите «Режим редактирования» на панели инструментов страницы, кликните по текстовому блоку — пока он пуст, отображается -- — и введите текст. Текст сохраняется при уходе со страницы: выключите режим редактирования. Делайте это в Firefox: браузеры на базе Chromium (Chrome, Edge) блокируют этот запрос, и текст теряется.

3. Компонент

Создайте site/modules/main/components/ReleaseList.php:

<?php
namespace EnergineSite\main\components;

use Energine\share\components\DataSet;
use Energine\share\gears\DataDescription;
use Energine\share\gears\FieldDescription;
use Energine\share\gears\SimpleBuilder;

class ReleaseList extends DataSet {
    public function __construct($name, ?array $params = null) {
        parent::__construct($name, $params);
        $this->setType(self::COMPONENT_TYPE_LIST);
    }

    protected function createBuilder() {
        return new SimpleBuilder();
    }

    protected function createDataDescription() {
        $result = new DataDescription();
        foreach (['version', 'note'] as $fieldName) {
            $field = new FieldDescription($fieldName);
            $field->setType(FieldDescription::FIELD_TYPE_STRING);
            $result->addFieldDescription($field);
        }
        return $result;
    }

    protected function loadData() {
        return [
            ['version' => '2.12', 'note' => 'PHP 5.5+'],
            ['version' => '2.13', 'note' => 'PHP 8.4+, MariaDB 10.11+'],
        ];
    }
}

Автозагрузчик Composer начального проекта сопоставляет EnergineSite\ с site/modules/, поэтому регистрировать класс не нужно. DataSet формирует XML компонента: createDataDescription() задаёт поля, loadData() возвращает строки, а SimpleBuilder выводит их. Компонент не является активным, поэтому конфигурационный файл ему не требуется.

4. Шаблон страницы

Скопируйте шаблон текстовой страницы ядра в свой сайт:

cp core/modules/share/templates/content/textblock.content.xml site/modules/main/templates/content/releases.content.xml

В файле releases.content.xml добавьте ваш компонент после компонента textBlock_1:

<component name="releaseList" class="EnergineSite\main\components\ReleaseList"/>

Новому шаблону требуется ссылка в htdocs/:

cd htdocs
php index.php setup linker

В «Управлении структурой» выберите «Releases», нажмите «Редактировать» (карандаш), выберите CONTENT_RELEASES в поле «Содержимое страницы» и сохраните. Шаблон отображает имя своей константы, пока для неё нет перевода: добавьте CONTENT_RELEASES в «Редактор переводов», чтобы задать понятное название. Текст из шага 2 сохранится: это текстовый блок 1 данной страницы.

5. XSLT-представление

Создайте site/modules/main/transformers/releases.xslt:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

    <xsl:template match="component[@class='ReleaseList']" priority="1">
        <ul class="release_list">
            <xsl:for-each select="recordset/record">
                <li>
                    <strong><xsl:value-of select="field[@name='version']"/></strong>
                    <xsl:text>: </xsl:text>
                    <xsl:value-of select="field[@name='note']"/>
                </li>
            </xsl:for-each>
        </ul>
    </xsl:template>

</xsl:stylesheet>

и подключите его в site/modules/main/transformers/include.xslt, после energine.xslt:

<xsl:include href="releases.xslt"/>

Атрибут priority="1" даёт вашему шаблону приоритет над стандартным представлением списков. Стили XSLT считываются напрямую из файлов, поэтому запускать setup не нужно: обновите страницу /releases/, и под текстом появится список: «2.12: PHP 5.5+» и «2.13: PHP 8.4+, MariaDB 10.11+».

6. XML страницы

При включённом режиме отладки запрос /releases/?debug возвращает XML страницы. Ваш компонент присутствует там в виде <component name="releaseList" componentAction="main" class="ReleaseList" … type="list"> с набором <recordset> из элементов <record> и полем <field name="version"> в каждом из них: именно с этим узлом сопоставляется ваш XSLT-шаблон. См. Компоненты и XSLT-представления.

Что требует выполнения setup

Изменение Команда
класс PHP в site/modules/main/components/ ничего
новый файл в site/modules/main/templates/ php index.php setup linker
правка шаблона, конфига или таблицы стилей ничего
новое изображение, скрипт или стиль php index.php setup linker, и php index.php setup scriptMap для скрипта
значение debug php index.php setup linker