Компоненты

Страница Energine — это набор компонентов. Компонент — PHP-объект, выполняющий одну задачу: меню, текстовый блок, список новостей, редактор — и возвращающий результат в виде XML. Компоненты страницы образуют один XML-документ, который XSLT преобразует в HTML; см. XSLT-представления.

От адреса к странице

  1. Веб-сервер направляет каждый адрес, не являющийся файлом, в htdocs/index.php; bootstrap.php загружает автозагрузчик Composer и конфигурацию htdocs/system.config.php.
  2. DocumentController извлекает язык из адреса и создаёт Document. Документ находит страницу по адресу и правам посетителя: нет прав — 403, нет страницы — 404. Страница с адресом перенаправления отвечает редиректом (302) на него.
  3. Шаблоны макета и содержимого страницы объединяются в одну структуру, и каждый <component> в ней становится объектом; см. Шаблоны страниц.
  4. Каждый компонент запускается: читает своё действие из оставшейся части адреса и подготавливает данные.
  5. Если в адресе остались сегменты, не использованные ни страницей, ни компонентом, ответом будет 404.
  6. Документ собирается как единый XML-документ, и трансформер превращает его в ответ.

Классы

Каждый компонент расширяет Energine\share\components\Component; большинство использует один из его потомков:

Класс Что добавляет
Component имя и параметры; состояние — действие, выбранное из адреса, — с его конфигурацией и правами; build(), выводящий элемент <component>
DataSet описание данных, данные, панели инструментов, JavaScript-поведения и постраничную навигацию; типы list и form
DBDataSet таблицу базы данных (параметр tableName) и её таблицу <table>_translation для языков; столбцы становятся описанием данных
Grid редактор таблицы в административном разделе: список с фильтром, сортировкой и постраничной навигацией, формы добавления и редактирования, удаление, упорядочивание и экспорт в CSV

DataSet собирает XML в prepare(): описание данных — <fields> конфигурации, сопоставленные с тем, что возвращает loadDataDescription(), — постраничная навигация, данные из loadData(), панель инструментов и скрипты. Подкласс обычно переопределяет loadData(), возвращающий массив строк или false, либо описание данных.

Параметры

Шаблон размещает компонент вместе с его параметрами; вот главные новости домашней страницы:

<component name="topNews" class="Energine\apps\components\NewsFeed">
    <params>
        <param name="title">TXT_TOP_NEWS</param>
        <param name="limit" type="hidden">5</param>
        <param name="showAll">1</param>
        <param name="active" type="hidden">0</param>
        <param name="template">news</param>
    </params>
</component>
  • class обязателен и представляет собой полное имя класса: объект создаётся именно так, без поиска по короткому имени.
  • name задаёт имя компонента в XML страницы; без него генерируется случайное имя.
  • Каждый класс объявляет свои параметры; неизвестный параметр останавливает страницу с сообщением «Компоненту передан неизвестный параметр.»
  • a|b|c превращается в список; то же происходит с несколькими <param> с одним именем.
  • Каждый компонент знает state, rights, config и active; DataSet добавляет recordsPerPage, title и template; DBDataSet добавляет tableName, onlyCurrentLang и editable.

Состояния и конфигурация

Действия компонента — это его состояния, описанные в его конфигурации <Class>.component.xml. Фрагмент конфигурации текстового блока:

<configuration>
    <state name="main">
        <javascript>
            <behavior name="PageEditor"/>
        </javascript>
    </state>
    <state name="save" rights="3">
        <uri_patterns>
            <pattern>/save-text/</pattern>
        </uri_patterns>
    </state>
</configuration>
  • Активный компонент — параметр active; каждый Grid является таковым — требует конфигурации. Он берёт состояние, чей <pattern> соответствует оставшейся части адреса, и вызывает метод <state>State() или <state>(), передавая плейсхолдеры шаблона в качестве аргументов. Если ни один шаблон не подошёл, используется параметр state, по умолчанию main.
  • В шаблоне [name] соответствует одному сегменту адреса, а [any]/ — остатку: /get-data/[sortField]-[sortDir]/page-[pageNumber]/. Состояния, перечисленные первыми, проверяются первыми.
  • Состояние может задавать rights, собственные <params>, <fields> своего списка или формы, <toolbar> из кнопок <control>, <javascript>-поведения и <translations>, необходимые его представлению.
  • Конфигурация ищется по параметру config, затем как <Class>.component.xml в site/modules/main/config/, затем в config/ модуля, затем в конфигурациях родительских классов. Таким образом, конфигурация сайта с именем файла класса заменяет конфигурацию ядра.

Права

Уровень Константа Подпись
0 ACCESS_NONE «Права отсутствуют»
1 ACCESS_READ «Только чтение»
2 ACCESS_EDIT «Редактирование»
3 ACCESS_FULL «Полный доступ»

Права задаются для каждой страницы и группы на вкладке «Права на страницу» формы страницы; права посетителя на страницу определяются наивысшим уровнем среди его групп. Стартовый комплект содержит группы «Администратор», «Гость» и «Пользователь».

Компонент запускается только тогда, когда права посетителя на страницу достигают его уровня: атрибута rights текущего состояния или, при его отсутствии, параметра rights компонента. Если ни то ни другое не задано, уровень соответствует правам самого посетителя, и компонент работает для всех, кто может открыть страницу: задавайте собственным редакторам <param name="rights">3</param>. Компонент, требующий прав выше, чем у посетителя, исключается из XML страницы.

Режим редактирования страницы требует полного доступа.

Административные окна

<page address>/single/<component name>/<action> собирает только указанный компонент страницы. Именно так Grid открывает формы добавления и редактирования — в окне поверх списка.

Собственный компонент

Автозагрузчик Composer стартового комплекта сопоставляет EnergineSite\ с site/modules/:

  • класс EnergineSite\main\components\Hello располагается в site/modules/main/components/Hello.php;
  • шаблон размещает его по полному имени: <component name="hello" class="EnergineSite\main\components\Hello"/>;
  • его конфигурация, если она нужна, — site/modules/main/config/Hello.component.xml;
  • его представление — XSLT-шаблон для component[@class='Hello'] в таблицах стилей сайта — см. XSLT-представления.

Ваш первый сайт разбирает этот процесс шаг за шагом.