Хелпер и свои темы

Вызов из другой темы

Хелпер приложения доступен как {$wa->code->…} и возвращает массив данных экрана. Перед использованием в теме другого приложения проверьте доступность объекта и метода:

{$_code = $wa->code}
{if $_code && method_exists($_code, 'docs')}
    {$docs = $_code->hub(['base_url' => 'https://example.com/docs/'])}
    <h1>{$docs.settings.heading|escape}</h1>
    {foreach $docs.projects as $project}
        <a href="{$project.link|escape}">{$project.name|escape}</a>
    {/foreach}
{/if}

Это хелпер приложения, поэтому проверка версии плагина для него не используется.

$project — адрес раздела, например guide, $slug — адрес статьи, например install.

Параметры options

Без base_url хелпер ищет поселение на текущем домене, предпочитая общий хаб. Если хаба нет, используется подходящее поселение раздела. При нескольких вариантах указывайте корень явно.

Неизвестные раздел и статья вызывают waException с кодом 404. Если адрес приходит от посетителя, обрабатывайте исключение в контроллере страницы.

Данные $docs

Штатные экраны получают массив $docs и алиасы $docs_<ключ>, например $docs.page и $docs_page. В index.html готовая разметка экрана доступна как $content. На странице ошибки $docs равен null.

Проект содержит id, url, name, description, intro, kind, icon, color, sort, status, SEO и даты. В дереве дополнительно доступны link, current, page_count, chapters, pages, index и tags. kind принимает theme, app, plugin; теги содержат name и url.

Глава содержит id, code_id, name, sort, pages. Статья содержит id, code_id, chapter_id, url, name, markdown, text, description, status, sort, SEO и даты; в дереве есть link и current. Значение markdown === null обозначает прежнюю HTML-страницу с текстом в text.

SEO-поля записей: meta_title, meta_description, og_title, og_description, og_image. Даты: datetime, update_datetime.

Раздел и статья

Пример для известного опубликованного раздела:

{$docs = $wa->code->project('guide')}
<h1>{$docs.project.name|escape}</h1>
<div>{$docs.html}</div>
{foreach $docs.chapters as $chapter}
    <h2>{$chapter.name|escape}</h2>
    {foreach $chapter.pages as $page}
        <a href="{$page.link|escape}">{$page.name|escape}</a>
    {/foreach}
{/foreach}

Статья с оглавлением и переходами:

{$docs = $wa->code->article('guide', 'install')}
<h1>{$docs.page.name|escape}</h1>
{foreach $docs.toc as $heading}
    <a href="#{$heading.id|escape}">{$heading.text|escape}</a>
{/foreach}
<article>{$docs.html}</article>
{if $docs.previous}
    <a href="{$docs.previous.link|escape}">{$docs.previous.name|escape}</a>
{/if}
{if $docs.next}
    <a href="{$docs.next.link|escape}">{$docs.next.name|escape}</a>
{/if}

Теги и поиск

{$docs = $wa->code->hub(['tag' => 'shop-script'])}
{foreach $docs.tags as $tag}
    <a href="{$docs.base_url|escape}?tag={$tag.url|escape:'url'}">
        {$tag.name|escape} ({$tag.count})
    </a>
{/foreach}
{foreach $docs.projects as $project}
    <a href="{$project.link|escape}">{$project.name|escape}</a>
{/foreach}

Тег фильтрует projects; menu, tags и recent остаются общими.

{$docs = $wa->code->search('установка')}
<form action="{$docs.search_url|escape}">
    <input name="query" value="{$docs.query|escape}">
    <button type="submit">Поиск</button>
</form>
{foreach $docs.results as $page}
    <a href="{$page.link|escape}">{$page.name|escape}</a>
    <p>{$page.excerpt|escape}</p>
{/foreach}

SEO и оформление HTML

При выводе в другом приложении самостоятельно примените SEO в его шаблоне страницы:

<title>{$docs.seo.title|escape}</title>
<meta name="description" content="{$docs.seo.description|escape}">
<link rel="canonical" href="{$docs.seo.canonical|escape}">
<meta name="robots" content="{$docs.seo.robots|escape}">
<meta property="og:title" content="{$docs.seo.og_title|escape}">
<meta property="og:description" content="{$docs.seo.og_description|escape}">
{foreach $docs.json_ld as $entity}
    <script type="application/ld+json">{$entity|json_encode:15}</script>
{/foreach}

Флаг 15 безопасно экранирует специальные символы JSON при вставке в script. Обычные строки выводите с |escape. Готовый $docs.html выводится без него.

HTML использует [data-code-callout], .code-markdown-code и button[data-code-copy]. Собственной теме нужно обеспечить оформление этих элементов и обработку копирования. Хелпер сам по себе не подключает стили и JavaScript штатной темы.