К содержанию

Главное

Урок: первый компонент проекта

Когда готовых блоков не хватает, проект может завести свой компонент. За этот урок вы создадите карточку объявления с заголовком и текстом, оформите её классами SIMAI Framework и поставите на главную страницу. Урок занимает около 20 минут.

Вы сделаете шесть шагов:

  1. Объявите пространство имён компонентов проекта.
  2. Составите план заготовки.
  3. Примените план.
  4. Оформите шаблон.
  5. Вставите компонент на страницу.
  6. Соберёте сайт и проверите результат.

Понадобится проект из быстрого старта, например созданный командой php vendor/bin/docara init . --lang=ru.

1. Объявите пространство имён

Все компоненты проекта начинаются с общего имени, чтобы не путаться со встроенными. Добавьте в docara.json поле smart:

docara.json
{
  "smart": { "namespace": "project" }
}

Остальные поля файла оставьте как есть. Имена ui и docara заняты встроенными компонентами.

2. Составьте план заготовки

Bash
php vendor/bin/docara scaffold smart project.notice-card --dry-run

Команда ничего не записывает. Она показывает, какие файлы создаст, и возвращает номер плана в поле plan_id:

Code
"plan_id": "3fe97af5…"

3. Примените план

Передайте номер плана целиком:

Bash
php vendor/bin/docara scaffold --apply=<plan_id>

Появятся три файла:

Code
smart/project.notice-card/
  manifest.json          описание: параметры, назначение, доступность
  view/default.json      представление по умолчанию
  template/default.php   шаблон, который выводит HTML

В manifest.json уже объявлены два обязательных параметра — title и text. Проверьте заготовку:

Bash
php vendor/bin/docara validate smart project.notice-card

Все проверки в ответе должны быть отмечены PASS.

4. Оформите шаблон

Шаблон получает параметры в $props и печатает HTML. Замените smart/project.notice-card/template/default.php:

smart/project.notice-card/template/default.php
<?php

declare(strict_types=1);

$title = htmlspecialchars((string) ($props['title'] ?? ''), ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$text = htmlspecialchars((string) ($props['text'] ?? ''), ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
echo '<aside data-docara-smart="project.notice-card" class="flex flex-col gap-1/2 p-2 radius-surface border bg-surface-page m-bottom-1">'
    . '<strong>' . $title . '</strong>'
    . '<p class="m-0">' . $text . '</p>'
    . '</aside>';
  • htmlspecialchars экранирует текст: так в параметры нельзя подложить чужую разметку. Не убирайте его.
  • Классы flex, p-2, radius-surface, border, bg-surface-page — утилиты SIMAI Framework. Docara сама подключит их стили и подстроит цвета под светлую и тёмную тему.

5. Вставьте компонент на страницу

Допишите в конец content/ru/index.md:

Markdown
:::project.notice-card
{"title":"Новая версия","text":"Сервис обновлён: поиск стал быстрее."}
:::

Параметры пишутся в JSON между строками :::.

6. Соберите и проверьте

Bash
php vendor/bin/docara build production
php vendor/bin/docara verify-static build_production
php vendor/bin/docara serve production --host=127.0.0.1 --port=8000 --no-build

Откройте http://127.0.0.1:8000/ и прокрутите главную вниз: там рамка с заголовком «Новая версия» и текстом под ним. Остановите просмотр клавишами Ctrl+C.

Теперь проверьте, что сборка следит за параметрами. Уберите из вызова "text" и соберите сайт ещё раз — сборка остановится:

Code
[PORTABLE_SMART_PROPS_INVALID] Portable Smart [project.notice-card] has invalid [props.text.required]. Source [content/ru/index.md:38:1].

Сообщение называет параметр и строку страницы. Верните "text".

Если что-то пошло не так

Сообщение Что сделать
SCAFFOLD_NAMESPACE_FORBIDDEN Имя компонента не начинается с пространства имён из docara.json. Проверьте шаг 1 и пишите project.<имя>.
SCAFFOLD_PLAN_ID_INVALID В --apply передан не весь номер плана. Скопируйте plan_id целиком.
SCAFFOLD_TARGET_EXISTS Такой компонент уже есть. Выберите другое имя.
SMART_REGISTRY_COMPONENT_NOT_FOUND На странице опечатка в имени компонента: такого компонента нет в smart/.

Остальные коды — в справочнике «Ошибки инструментов разработчика» и «Ошибки оформления и расширения».

Что дальше