ALBIREO CMS
version: 2025.11.01
© Albireo CMS, 2020-2025

Функции рубрик Albireo CMS

categoryGetAll categoryLinks categoryList categoryTitleTriggers

Функция categoryGetAll

Функция categoryGetAll предназначена для получения полного списка всех рубрик (категорий), используемых на сайте. Она выполняет сложную агрегацию данных: сначала собирает все рубрики, упомянутые в опубликованных записях, затем обогащает эти данные информацией из конфигурационного файла (например, полными названиями или порядком сортировки) и подсчитывает количество записей в каждой рубрике. Результат кешируется для повышения производительности.

Сигнатура

function categoryGetAll(): array

Аргументы

Функция не принимает аргументов.

Результат

Возвращает индексированный массив (array), отсортированный согласно параметру order из файла конфигурации. Каждый элемент этого массива — это ассоциативный массив, описывающий одну рубрику. Структура этого внутреннего массива определяется функцией categoryList().

Примеры использования

1. Файл конфигурации CONFIG_DIR/category.php

В этом файле задаются "человеческие" имена для рубрик и их порядок.

return [
    'astronomy' => [ // site/category
        'title' => 'Астрономия',
        'caption' => 'Астрономия',
        'description' => 'Статьи по астрономии',
        'text-start' => '<div class="h2 mar20-tb">Астрономия</div>',
        'text-end' => '<hr>Текст в конце рубрики',
        'order' => 10,
        'order-pages' => 'date-desc',
        'limit' => 4,
        'path' => '',
        'my-url' => 'astronomy',
    ],

    // Рубрика 'misc' не описана, её имя будет взято из слага.
];

2. Вывод списка рубрик в сайдбаре

Это основной сценарий использования функции.

$categories = categoryGetAll();

if ($categories) {
    echo '<div class="widget categories-widget">';
    echo '<h3>Рубрики</h3>';
    echo '<ul>';

    foreach ($categories as $category) {
        echo '<li>';
        echo '<a href="' . $category['url'] . '">' . htmlspecialchars($category['title']) . '</a>';
        echo ' (' . $category['count'] . ')';
        echo '</li>';
    }

    echo '</ul></div>';
}

Примечания

  • Кеширование: Результат выполнения кешируется в статической переменной. Это означает, что при повторных вызовах в рамках одного HTTP-запроса, ресурсоемкая операция сбора и обработки данных выполняться не будет.
  • Отложенная публикация: Запрос к базе данных учитывает отложенную публикацию, исключая из подсчета рубрики из записей, которые еще не были опубликованы.

Функция categoryLinks

Функция categoryLinks является удобным хелпером для преобразования строки со слагами (идентификаторами) рубрик в готовый для отображения набор HTML-ссылок. Она использует categoryGetAll() для получения полного списка рубрик сайта, а затем выбирает из него только те, которые указаны во входной строке.

Сигнатура

function categoryLinks(string $cats, string $delimer = ', '): string

Аргументы

string $cats
Строка, содержащая один или несколько слагов рубрик, разделенных запятыми.
string $delimer (необязательный)
Строка-разделитель, которая будет вставляться между сгенерированными HTML-ссылками. По умолчанию используется запятая с пробелом (', ').

Результат

Возвращает строку (string) с HTML-кодом, содержащим ссылки на страницы рубрик. Если исходная строка $cats пуста или не содержит ни одного существующего слага, возвращается пустая строка.

Примеры использования

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

Это основной сценарий использования. В шаблоне вывода поста можно получить из его метаданных строку с рубриками и преобразовать её в ссылки.

// Предположим, в полях поста есть поле:
// category: php-news, tutorials

// Получаем это значение
$postCategories = getPageData('category'); // 'php-news, tutorials'

// Генерируем и выводим HTML-ссылки
if ($postCategories) {
    echo '<div class="post-categories">';
    echo 'Рубрики: ' . categoryLinks($postCategories);
    echo '</div>';
}

// Результат:
// <div class="post-categories">
// Рубрики: <a href=".../category/php-news">Новости PHP</a>, <a href=".../category/tutorials">Уроки и статьи</a>
// </div>

Пример 2: Использование другого разделителя

Можно легко изменить внешний вид списка, поменяв разделитель.

$cats = 'design,frontend';
$links = categoryLinks($cats, ' / ');

// $links будет:
// <a href=".../category/design">Дизайн</a> / <a href=".../category/frontend">Фронтенд</a>
echo $links;

Примечания

  • Производительность: Функция categoryGetAll(), вызываемая внутри, кеширует свой результат, поэтому многократные вызовы categoryLinks в рамках одного запроса не приведут к повторным обращениям к базе данных.
  • Готовые ссылки: Функция использует уже готовую HTML-ссылку из поля 'link', которое формируется в categoryGetAll/categoryList.

Функция categoryList

Функция categoryList является вспомогательным инструментом, который "обогащает" простой список слагов рубрик полной информацией. Она объединяет данные из трех источников: списка слагов, файла конфигурации и массива со счетчиками записей. Для каждой рубрики функция генерирует недостающие поля (такие как URL, title, description), что позволяет получить на выходе унифицированный и полный набор данных для каждой категории.

Сигнатура

function categoryList(array $cats, array $catConfig, array $catsCount = []): array

Аргументы

array $cats
Индексированный массив, содержащий слаги (идентификаторы) рубрик, которые необходимо обработать. Например, ['php-news', 'tutorials'].
array $catConfig
Ассоциативный массив с конфигурацией рубрик, загруженный из файла (например, category.php). Ключами в этом массиве должны быть слаги рубрик.
array $catsCount (необязательный)
Ассоциативный массив, где ключ — это слаг рубрики, а значение — количество записей в ней. Например, ['php-news' => 25, 'tutorials' => 40].

Результат

Возвращает отсортированный по иерархии (полю path) массив, где каждый элемент — это ассоциативный массив с полными данными одной рубрики. Типичная структура элемента:

  • slug: Идентификатор рубрики.
  • url: Полный URL-адрес страницы архива.
  • count: Количество записей.
  • title: Заголовок рубрики (из конфига или сгенерированный из слага).
  • caption: Подпись (аналогично title).
  • description: Описание.
  • text-start / text-end: Текстовые блоки для вывода до и после списка записей.
  • path: Иерархический путь (например, 'web.php.frameworks').
  • pathLevel: Уровень вложенности (количество точек в 'path').
  • link: Готовый HTML-тег <a>.
  • ... а также любые другие поля из файла конфигурации.

Примеры использования

Обычно эта функция вызывается внутри других, более высокоуровневых функций, таких как categoryGetAll(). Прямой вызов может выглядеть так:

// 1. Исходные данные
$activeSlugs = ['php', 'js', 'css'];

$configuration = [
    'php' => ['title' => 'Статьи о PHP', 'path' => 'backend.php'],
    'js'  => ['title' => 'Статьи о JavaScript', 'path' => 'frontend.js'],
    'css' => ['title' => 'CSS-трюки', 'path' => 'frontend.css', 'my-url' => 'all-about-css'],
];

$postCounts = [
    'php' => 50,
    'js'  => 75,
    'css' => 30,
];

// 2. Вызов функции
$fullCategoryData = categoryList($activeSlugs, $configuration, $postCounts);

// 3. Результат (упрощенно)
// $fullCategoryData будет содержать массив из 3-х элементов. Например, для 'css':
// [
//    'slug' => 'css',
//    'title' => 'CSS-трюки',
//    'path' => 'frontend.css',
//    'my-url' => 'all-about-css',
//    'url' => 'https://mysite.com/all-about-css', // сгенерирован из 'my-url'
//    'count' => 30,
//    'pathLevel' => 1,
//    'link' => '<a href="https://mysite.com/all-about-css">CSS-трюки</a>',
//    ...
// ]
print_r($fullCategoryData['css']);

Примечания

  • Генерация полей: Если какие-то ключевые поля (title, caption, description) не заданы в конфигурации, функция сгенерирует их на основе слага или оставит пустыми, обеспечивая унифицированную структуру для всех рубрик.
  • URL-адреса: Функция поддерживает кастомные URL через поле my-url в конфигурации. Если его нет, URL генерируется по стандартному шаблону SITE_URL/category/[slug].

Функция categoryTitleTriggers

Функция categoryTitleTriggers — это специализированная функция-триггер, предназначенная для динамического изменения мета-тегов title и description на страницах архивов рубрик. Она определяет текущую рубрику из URL, находит для неё данные в конфигурационном файле category.php и обновляет метаданные страницы. Если конфигурация для рубрики не найдена, она генерирует заголовок и описание по умолчанию.

Сигнатура

function categoryTitleTriggers(array $pageData): void

Аргументы

array $pageData
Массив с текущими данными страницы. Этот аргумент передается автоматически системой триггеров перед рендерингом страницы.

Результат

Функция ничего не возвращает (void). Её результат — это модификация данных страницы во временном хранилище с помощью setVal('pageData', ...).

Примеры использования

Эта функция не предназначена для прямого вызова. Её работа полностью управляется системой триггеров.

Активация триггера

Чтобы функция сработала для страницы архива рубрик (например, для файла pages/specific/category.php):

triggers[]: categoryTitleTriggers

Примечания

  • Назначение: Это узкоспециализированная функция, предназначенная для работы в рамках системы триггеров и страниц архивов рубрик.