Поля страниц

Общие принципы

Поле задается в виде ключ: значение. После «:» нужно указать пробел.

Поле может быть boolean «вкл/выкл».

выключить: 0, -, false
включить: 1, true, + и любой другой текст

Если в начале строки перед именем поля стоит символ «#», то эта строка игнорируется. Используйте эту возможность для создания комментариев.

# title: это строка-комментарий
title: а это реальное поле

Каждое значение поля обрезается на пробелы, поэтому если стоит задача указать начальный или конечный пробел, то используйте заменитель [NBSP]:

title: Заголовок с пробелами в конце     [NBSP]

В некоторых полях можно использовать // в качестве заменителя переноса строки \n.

announce: первая строка //вторая строка //третья строка

Если нужно, то в полях можно использовать HTML.

announce: <h1>первая строка</h1><p>вторая строка</p><p>третья строка</p>

Предопределённые замены в полях

Используйте их в значениях, чтобы упростить код:

[SITE_URL] — адрес сайта
[UPLOADS_URL] — адрес к каталогу uploads
[SERVICE_DIR] — полный путь к сервисному каталогу
[CONFIG_DIR] — полный путь к конфигурационному каталогу
[NBSP] — html-пробел
[EOL] — заменяется на «\n»

Например:

image-large: [UPLOADS_URL]default.webp

Замены полей

Поля Albireo CMS поддерживают автозамены на другие поля. Для этого используются квадратные скобки. Например:

title: Название страницы
description: [title]

В данном примере поле description примет тоже значение, что и поле title.

Пример:

title: Ихтиозавры
slug: dinosauria/[title]

Здесь адрес страницы будет совпадать с его заголовком «dinosauria/Ихтиозавры».

Также можно создавать условия замены полей:

# исходные поля
поле1: значение
поле2: что-то

# если есть поле1, то присваиваем его значение, если нет, то используем дефолт
поле3: @if [поле1] @else 'дефолтное значение'

# если есть поле1, то используем его, если нет, то поле2
поле4: @if [поле1] @else [поле2]

С помощью условных полей, можно создавать поля, подстраивающиеся под разные условия.

Автоматически создаваемые поля

Albireo CMS будет автоматически создавать некоторые поля. В большинстве случаев они используются при программировании.

page-url: полный адрес страницы на основе slug

page-url-full: полный текущий адрес (может отличаться от адреса slug, например в метках)

current-path: полный url к текущему каталогу файла страницы внутри PAGES_DIR

subdirs: подкаталоги относительно PAGES_DIR (всегда разделены символом /). Если это «.» то это корень PAGES_DIR
subdirs-basename: последний (правый) каталог из subdirs

this-file: полное имя текущего файла
this-file-stem: имя текущего файла без расширения и пути

uniqid: уникальный идентификатор страницы, привязанный к slug

date.unix: метка времени Unix создания страницы на основе поля date
date-edit.unix: метка времени Unix редактирования страницы на основе поля date-edit
date-pub.unix: метка времени Unix отложенной публикации страницы на основе поля date-pub

link-for-edit: адрес для редактирования страницы в админ-панели

user-lang: язык браузера посетителя

Просмотр данных страницы

При программировании страницы порой нужно посмотреть текущие данные страницы. Для этого используйте функцию getPageData(), которая получает данные текущей страницы. Для вывода в браузер используется отладочная функция pr().

В произвольном месте страницы пропишите:

<?php pr(getPageData()); ?>

Вы увидите массив примерно такого вида:

Array
(
   [html[lang]] => ru
   [html[prefix]] => og: https://ogp.me/ns#
   [parser] => textsimple
   [compress] => +
   [protect-pre] => 1
   [stat] => -
   [comments] => -
   [headers] =>
   [footers] =>
   [css.theme] => berry.css
   [css.fstyle] => doc.css
   [headers.title] => MAXSITE.ORG
   [headers.subtitle] => Сайт вебмастера
   ... и т.д.

Это данные (поля) текущей страницы. Если нужно получить значение какого-то поля, то его можно указать в качестве аргумента getPageData().

<?php pr(getPageData('title')); ?>

PHP в полях

В полях можно использовать обычный php-код, который возвращает данные через echo:

title: <?php echo 'Hello!'; ?>
title: <?= lang('Sitemap') ?>
pagination-format: [NBSP] - <?= lang('page') ?> %d
title: <?= CURRENT_URL['segment1'] ? lang('Tag') . ': «' . CURRENT_URL['segment1'] . '»' : lang('Tags') ?>

Если нужно оформить поле в виде сложного php-кода, то можно разместить его на несколько строк:

my: <?= 
    1+2+3
?>

Если выполнить <?php pr(getPageData('my')); ?>, то он выведет 6.

Главное, чтобы такой код не выводил перенос строки \n, поскольку это будет означать новое поле. Чтобы гарантировано избежать подобной проблемы, можно использовать кодирование в JSON:

my: <?= 
    json_encode('hello' . "\n" . 'world', JSON_UNESCAPED_UNICODE)
?>

В этом случае поле будет сохранено как "hello\nworld". Еще пример с использованием heredoc-синтаксиса:

my: <?= json_encode(<<<TXT
Звезда мне подмигнула — я ей в ответ: «Привет!»  
Она мне шлёт лучи, как будто Wi-Fi-сеть.  
На небе чат открыт, галактики в онлайне,  
А я сижу, мечтаю... в пижаме и в тайне.

© Copilot AI
TXT, JSON_UNESCAPED_UNICODE) ?>

Когда стоит задача разместить в поле сложные данные, например php-массив, то его также можно закодировать в JSON:

my-data: <?= json_encode([
    'first' => 11,
    'second' => 22,
    '3rd' => [
        'a',
        'b',
        'c' => 'Hello, Albireo!'
    ],
]) ?>

Код <?php pr(getPageData('my-data')); ?> выведет {"first":11,"second":22,"3rd":{"0":"a","1":"b","c":"Hello, Albireo!"}} — строку которую легко раскодировать через json_decode():

$myData = json_decode(getPageData('my-data'), true);

// Array
// (
//    [first] => 11
//    [second] => 22
//    [3rd] => Array
//        (
//            [0] => a
//            [1] => b
//            [c] => Hello, Albireo!
//        )
// 
// )

Множественные поля

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

css.style[]: hr.red {margin: 0 10px}
css.style[]: hr.green {margin: 0 10px}
css.style[]: hr.blue {margin: 0 10px}

Поскольку поля должны быть уникальными (по сути это ключи php-массива), то система автоматически проставит уникальные индексы, что будет эквивалентно примерно такой записи:

css.style[-19]: hr.red {margin: 0 10px}
css.style[-20]: hr.green {margin: 0 10px}
css.style[-21]: hr.blue {margin: 0 10px}

Такие поля используются для двух целей.

Первая — это создание массива одномерных элементов. Скажем в этом примере шаблон сгруппирует все поля css.style[] в единый css-код.

Вторая цель — это формирование сложного массива вида поле[ключ]: значение. Например формирование OGP (Open Graph Protocol):

ogp[og:site_name]: Website on Albireo CMS
ogp[og:type]: article
ogp[og:url]: [page-url-full]
ogp[og:title]: [title]

Для формирования итогового кода можно использовать функцию getKeysPageData(), которая по шаблону сформирует корректный html-код для каждого поля:

echo implode(getKeysPageData('ogp', '<meta property="[key]" content="[val]">'));

Загрузка данных страницы из отдельного файла

Поля страницы могут быть заданы как файл с php-массивом, аналогичному page-data.php. Файл следует разместить в каталоге config/page-data. После этого его можно указать в поле file-page-data:

file-page-data: my.php

— где my.php это config/page-data/my.php, например такого содержания:

<?php if (!defined('BASE_DIR')) exit('No direct script access allowed');

return [
    'css.fstyle' => 'design1.css',
    'headers' => 'headers/header1.php',
];

Это будет эквивалентно указанию для страницы:

css.fstyle: design1.css
headers: headers/header1.php