Table of Contents Page plugin for Cotonti

Руководство и документация по плагина toc_page для Cotonti

Код плагина: toc_page
Версия: 1.0.1
Автор: webitproff
Лицензия: BSD
Исходный код: github.com/webitproff/toc_page-cotonti

Оглавление

Техническая часть

1. Общая информация
2. Требования
3. Установка и удаление
4. Структура файлов
5. База данных
6. Функции плагина
7. Административный интерфейс
8. Шаблоны
9. Локализация
10. Настройки
11. Примеры использования
12. Примечания

Руководство пользователя

1. Сразу после установки
2. Первый взгляд на страницу плагина
3. Знакомство с вкладками
4. Создание первого дерева
5. Что такое дерево и зачем оно нужно
6. Открытие дерева для наполнения
7. Форма добавления элемента
8. Добавление элемента типа «Категория»
9. Добавление элемента типа «Страница»
10. Добавление элемента типа «Произвольная ссылка»
11. Управление элементами после добавления
12. Сохранение изменений
13. Заключение

Общая информация

Плагин toc_page предназначен для создания и управления произвольными деревьями оглавления на сайте Cotonti. Он хранит деревья и их элементы в собственных таблицах базы данных и не зависит от структуры категорий модуля Pages.

Плагин предоставляет административный интерфейс для создания деревьев, добавления в них элементов трёх типов (категория, страница, произвольная ссылка), настройки иерархии, порядка и видимости. Для вывода дерева на сайте используется PHP-функция cot_toc_page_render().

Плагин поддерживает мультиязычность через плагин i18n: если он активен, заголовки категорий и страниц автоматически берутся из локализованных данных.

Требования

• Cotonti 1.0+ или совместимая версия
• Модуль Pages (page)
• PHP 8.5+
• MySQL 8.0+ (или совместимый драйвер PDO)
• Рекомендуется плагин i18n для мультиязычности

Установка и удаление

Установка

1. Скопируйте папку toc_page в каталог plugins/ сайта Cotonti.
2. Перейдите в административную панель → Расширения.
3. Найдите плагин Table of Contents Page и нажмите Установить.
4. При необходимости настройте параметр default_tree в настройках плагина.

При установке Cotonti автоматически выполнит SQL-файл setup/toc_page.install.sql, который создаст таблицы cot_toc_page_trees и cot_toc_page_items с префиксом вашего сайта.

Удаление

При удалении плагина Cotonti выполнит SQL-файл setup/toc_page.uninstall.sql, который удалит обе таблицы. Все данные плагина будут безвозвратно удалены.

Структура файлов

plugins/toc_page/
├── toc_page.setup.php          // Метаданные и конфигурация плагина
├── toc_page.global.php         // Глобальная инициализация
├── toc_page.functions.php      // Основные функции плагина
├── toc_page.admin.php          // Административный интерфейс
├── setup/
│   ├── toc_page.install.sql    // SQL для установки
│   └── toc_page.uninstall.sql  // SQL для удаления
├── tpl/
│   ├── toc_page.admin.tpl      // Шаблон админки
│   └── toc_page.tpl            // Шаблон вывода дерева
└── lang/
    └── toc_page.ru.lang.php    // Русский языковой файл

Назначение файлов

• toc_page.setup.php — содержит метаданные плагина (код, название, описание, версию, автора, лицензию, требования) и конфигурационный параметр default_tree.
• toc_page.global.php — подключает файл функций плагина через cot_incfile('toc_page', 'plug').
• toc_page.functions.php — регистрирует таблицы плагина в Cotonti и объявляет публичные функции для работы с деревьями.
• toc_page.admin.php — обрабатывает действия в админ-панели, формирует данные для шаблона, выполняет CRUD-операции с деревьями и элементами.
• toc_page.install.sql — SQL-запросы для создания таблиц плагина.
• toc_page.uninstall.sql — SQL-запросы для удаления таблиц плагина.
• toc_page.admin.tpl — шаблон административной части на XTemplate.
• toc_page.tpl — шаблон вывода дерева на фронтенде.
• toc_page.ru.lang.php — русские языковые строки интерфейса.

База данных

Таблица cot_toc_page_trees

Хранит деревья оглавления.

Таблица cot_toc_page_items

Хранит элементы деревьев.

Функции плагина

Все функции объявлены в файле toc_page.functions.php.

toc_page_get_tree($treeId)

Возвращает вложенный массив элементов указанного дерева. Выполняет SQL-запрос к таблице cot_toc_page_items с условием tree_id = ? AND item_enabled = 1, сортирует по item_sort ASC, затем рекурсивно группирует элементы по parent_id.

Параметры:

• $treeId (int) — ID дерева.

Возвращает: массив элементов с ключом children для вложенных элементов.

cot_toc_page_render($treeId, $tpl = 'toc_page')

Получает дерево через toc_page_get_tree() и передаёт его в toc_page_display() для рендеринга.

Параметры:

• $treeId (int) — ID дерева.
• $tpl (string) — имя шаблона без расширения .tpl; по умолчанию toc_page.

Возвращает: HTML-код отрендеренного дерева.

toc_page_display($items, $level, $tpl)

Рекурсивно обходит элементы и формирует HTML с помощью XTemplate. Для каждого элемента определяются URL и заголовок:

• category — используется $item['item_ref'] как код категории. URL строится через cot_url('page', ['c' => $code]). Заголовок берётся из локализованных данных, если они доступны, иначе из структуры страниц Cotonti.
• page — $item['item_ref'] преобразуется в целое число и используется как ID страницы. URL и заголовок берутся из таблицы страниц с учётом локализации.
• custom — URL берётся из $item['item_url'], заголовок из $item['item_title'] или из URL.

Если заголовок пуст, элемент пропускается. Если URL пуст, но заголовок есть, элемент выводится как обычный текст (разделитель), а вложенные элементы обрабатываются.

Параметры:

• $items (array) — массив элементов дерева.
• $level (int) — текущий уровень вложенности.
• $tpl (string) — имя шаблона.

Возвращает: HTML-код списка.

toc_page_i18n_cat_title($catCode)

Возвращает локализованное название категории, если активен плагин i18n и для текущей локали есть перевод. Иначе возвращает null.

toc_page_i18n_page_title($pageId)

Возвращает локализованное название страницы из таблицы i18n, если активен плагин i18n и запись существует. Иначе возвращает null.

Административный интерфейс

Админка плагина реализована в файле toc_page.admin.php. Доступ к ней осуществляется через раздел Администрирование → Table of Contents Page.

Вкладки

• Деревья — список деревьев, создание, переименование, удаление.
• Редактирование дерева — управление элементами выбранного дерева.

Действия на вкладке «Деревья»

• add — создание нового дерева. Поля: tree_title, tree_desc.
• edit_tree — отображение формы редактирования названия и описания дерева.
• update_tree — обновление названия и описания дерева.
• delete — удаление дерева и всех его элементов.

Действия на вкладке «Редактирование дерева»

• save — сохранение изменений элементов из таблицы (заголовки, родители, порядок, видимость).
• add_item — добавление нового элемента. Поля: item_type, item_ref_cat (для категории), item_ref_page (для страницы), item_url (для ссылки), item_title, parent_id.
• delete_item — удаление элемента и всех его потомков.

Формирование списка родителей

При выводе каждого элемента в таблице строится выпадающий список всех элементов дерева, кроме самого себя. Это позволяет изменить родителя непосредственно в таблице.

Шаблоны

Шаблон админки: tpl/toc_page.admin.tpl

Содержит разметку обеих вкладок, форму фильтров и таблицы элементов. Использует XTemplate-блоки:

• MAIN.TREES_ROW — строка таблицы деревьев.
• MAIN.EDIT_TREE_FORM — форма редактирования названия и описания дерева (показывается при действии edit_tree).
• MAIN.EDIT_ITEM — строка таблицы элементов.

Шаблон вывода: tpl/toc_page.tpl

Используется функцией cot_toc_page_render() для отображения дерева на сайте. Основные блоки:

• LIST — список уровня.
• LIST.ROW — элемент списка. Содержит условие: если {ROW_URL} не пуст, выводится ссылка, иначе — текст.

Локализация

Языковые строки интерфейса находятся в файле lang/toc_page.ru.lang.php. Основные ключи:

• toc_page_title — название плагина
• toc_page_tab_trees — вкладка «Деревья»
• toc_page_tab_edit — вкладка «Редактирование дерева»
• toc_page_tree_items — кнопка «Элементы»
• toc_page_edit_tree_meta — кнопка «Изменить»
• toc_page_msg_tree_updated — сообщение «Дерево обновлено»
• и другие строки для полей, действий и сообщений.

Настройки

В файле toc_page.setup.php определён один конфигурационный параметр:

• default_tree (тип string) — ID дерева по умолчанию. Используется, если функция вызывается без аргумента.

По умолчанию значение равно 0, что означает отсутствие дерева.

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

Вывод дерева в шаблоне сайта

{PHP|cot_toc_page_render(1)}

Здесь 1 — ID дерева. Функция вернёт HTML-код дерева.

Вывод с кастомным шаблоном

{PHP|cot_toc_page_render(1, 'my_custom_toc')}

В этом случае будет использоваться файл tpl/my_custom_toc.tpl.

Примечания

• Плагин не изменяет структуру таблиц Cotonti.
• Все данные плагина хранятся в собственных таблицах и при удалении плагина уничтожаются.
• Для корректной работы с категориями в поле item_ref хранится код категории, а не её ID.
• При пустом URL у элемента с типом custom и наличии вложенных элементов, он работает как разделитель и не отображается как ссылка.
• Плагин поддерживает неограниченное количество деревьев и элементов.

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

Это руководство написано для тех, кто только что установил плагин и впервые открыл его в административной панели Cotonti. Мы пройдём весь путь: от первого знакомства с интерфейсом до создания полноценного дерева с элементами трёх типов. Каждый шаг описан максимально подробно.

Сразу после установки

После того как плагин установлен, в административной панели Cotonti появляется новый пункт меню. Он находится в разделе «Администрирование» и называется «Table of Contents Page». Нажмите на этот пункт.

Откроется страница плагина. Сейчас она почти пустая, потому что вы ещё не создали ни одного дерева. Не пугайтесь: именно с этого экрана начинается вся работа.

Первый взгляд на страницу плагина

На странице вы увидите заголовок «Table of Contents Page». Под ним расположены две вкладки: «Деревья» и «Редактирование дерева». Сейчас активна вкладка «Деревья».

Внутри вкладки «Деревья» находятся два основных блока:

• Список деревьев — таблица, в которой будут отображаться все созданные вами деревья. Сейчас она пустая.
• Добавить дерево — форма, с помощью которой вы создадите первое дерево.

Знакомство с вкладками

Плагин имеет две вкладки, и каждая отвечает за свою часть работы.

Вкладка «Деревья»

Эта вкладка предназначена для управления самими деревьями. Здесь вы можете:

• создавать новые деревья;
• просматривать список уже созданных деревьев;
• изменять название и описание дерева;
• удалять дерево целиком.

Вкладка «Редактирование дерева»

Эта вкладка служит для наполнения дерева элементами. Здесь вы:

• выбираете, с каким деревом работаете;
• добавляете элементы разных типов;
• настраиваете порядок, вложенность и видимость элементов;
• сохраняете изменения.

Проще говоря: сначала на вкладке «Деревья» вы создаёте контейнер, а затем на вкладке «Редактирование дерева» наполняете его содержимым.

Создание первого дерева

Теперь создадим первое дерево. Выполните следующие действия.

1. Убедитесь, что вы находитесь на вкладке «Деревья». Если нет — нажмите на неё.
2. Найдите блок «Добавить дерево».
3. В поле «Название дерева» введите название. Например, Документация по продукту или Помощь по сайту. Это название будет видно вам в списке деревьев, чтобы не путаться.
4. В поле «Описание» можно ввести короткое пояснение. Это необязательно, но полезно, если деревьев будет несколько. Например, Руководство пользователя для модуля фильтра товаров.
5. Нажмите кнопку «Создать».

После нажатия кнопки дерево появится в таблице «Список деревьев». Вы увидите:

• ID — номер дерева, который присваивается автоматически. Он понадобится позже, чтобы вывести дерево на сайте.
• Название дерева — то, что вы ввели.
• Описание — ваше пояснение.
• Действия — кнопки для работы с деревом: «Элементы», «Изменить», «Удалить».

Запомните ID вашего дерева. Например, если это первое дерево, его ID будет 1.

Что такое дерево и зачем оно нужно

Дерево — это структура, в которую вы будете добавлять пункты меню или оглавления. Представьте, что дерево — это каркас, а элементы — отдельные ветви. Благодаря дереву вы можете объединить в одном месте страницы из разных категорий, добавить внешние ссылки и выстроить их в удобном порядке.

Вы можете создать несколько деревьев. Например, одно для документации, другое для раздела «Помощь», третье для ссылок на внешние ресурсы. Каждое дерево будет отдельным списком на сайте.

Открытие дерева для наполнения

После создания дерева нужно перейти к его наполнению. Для этого выполните одно из действий:

• Перейдите на вкладку «Редактирование дерева». Если дерево только что создано, оно будет выбрано автоматически.
• Или на вкладке «Деревья» нажмите кнопку «Элементы» рядом с нужным деревом.

Теперь вы на вкладке «Редактирование дерева». В верхней части экрана будет написано, какое дерево вы редактируете, например: «Редактирование дерева: Документация по продукту».

Ниже вы увидите таблицу элементов. Сейчас она пустая. Под таблицей находится форма «Добавить элемент» — именно с её помощью мы будем добавлять пункты.

Форма добавления элемента

Форма «Добавить элемент» содержит несколько полей:

• Тип — выпадающий список, где нужно выбрать, что вы добавляете: «Категория», «Страница» или «Произвольная ссылка».
• Категория — появляется только при выборе типа «Категория»; это выпадающий список всех категорий страниц сайта.
• Страница — появляется только при выборе типа «Страница»; это выпадающий список всех опубликованных страниц.
• URL — появляется только при выборе типа «Произвольная ссылка»; сюда вводится адрес.
• Заголовок — текстовое поле, куда можно ввести свой текст для пункта меню. Если оставить пустым, для категорий и страниц будет использовано их собственное название.
• Родитель — выпадающий список всех уже добавленных элементов, чтобы выбрать, в какой из них вложить новый пункт. По умолчанию стоит «Верхний уровень», то есть пункт будет на первом уровне дерева.

Теперь рассмотрим добавление каждого типа элемента отдельно.

Добавление элемента типа «Категория»

Категория — это раздел сайта, в котором уже могут находиться страницы. Добавляя категорию в дерево, вы создаёте пункт, который ведёт на эту категорию.

Предположим, у вас есть категория с названием «Статьи». Мы хотим добавить её в дерево как первый пункт.

1. В форме «Добавить элемент» найдите поле «Тип» и выберите из списка «Категория».
2. После этого под полем «Тип» появится новое поле — «Категория». Нажмите на него, чтобы открыть список всех категорий вашего сайта.
3. Выберите нужную категорию, например «Статьи».
4. В поле «Заголовок» можно ввести свой текст, если вы хотите, чтобы пункт меню назывался иначе, чем категория. Например, введите Полезные статьи. Если оставить пустым, будет показано название категории «Статьи».
5. В поле «Родитель» оставьте «Верхний уровень», так как это первый пункт и он должен быть на первом уровне.
6. Нажмите кнопку «Добавить».

После этого элемент появится в таблице выше. Вы увидите строку с ID, типом «Категория», названием выбранной категории, заголовком, родителем «Верхний уровень», порядком (например, 1) и флажком «Включено» (по умолчанию включено).

Добавление элемента типа «Страница»

Страница — это отдельная статья или материал сайта. Вы можете добавить любую опубликованную страницу в дерево, даже если она находится в другой категории.

Допустим, у вас есть страница с заголовком «Как установить модуль». Добавим её как вложенный пункт в категорию «Статьи».

1. В форме «Добавить элемент» выберите тип «Страница».
2. Появится поле «Страница». Нажмите на него, чтобы открыть список всех опубликованных страниц.
3. Найдите и выберите страницу «Как установить модуль».
4. В поле «Заголовок» можно ввести свой текст, например Установка модуля. Если оставить пустым, будет показано название страницы.
5. В поле «Родитель» выберите ранее добавленный элемент «Полезные статьи» (или «Статьи», если вы оставили заголовок по умолчанию). Для этого нажмите на список и выберите нужный пункт.
6. Нажмите кнопку «Добавить».

Теперь в таблице появится новая строка. В колонке «Родитель» будет указан выбранный элемент. Это означает, что страница будет вложена в него и на сайте отобразится с отступом.

Добавление элемента типа «Произвольная ссылка»

Произвольная ссылка — это любой адрес в интернете: другая страница вашего сайта, внешний сайт, документ, файл. Этот тип подходит, если нужно добавить в дерево что-то, чего нет среди страниц или категорий Cotonti.

Добавим ссылку на внешний ресурс, например на форум поддержки.

1. В форме «Добавить элемент» выберите тип «Произвольная ссылка».
2. Появится поле «URL». Введите полный адрес, например https://forum.example.com.
3. В поле «Заголовок» обязательно введите текст, который будет отображаться в меню. Например, Форум поддержки. Если не ввести, заголовком станет сам URL, что некрасиво.
4. В поле «Родитель» при необходимости выберите, в какой элемент вложить ссылку. Если оставить «Верхний уровень», ссылка будет отдельным пунктом на первом уровне.
5. Нажмите «Добавить».

Ссылка появится в таблице. В колонке «Ссылка на объект» будет показан URL, а в колонке «Тип» — «Произвольная ссылка».

Управление элементами после добавления

После добавления нескольких элементов вы можете изменить их порядок, вложенность и видимость прямо в таблице.

В таблице элементов есть такие колонки:

• ID — номер элемента, изменить нельзя.
• Тип — показывает, что это: категория, страница или ссылка.
• Ссылка на объект — название категории или страницы либо URL.
• Заголовок — текстовое поле, можно изменить.
• Родитель — выпадающий список. Выберите другого родителя, чтобы переместить элемент в другую ветку.
• Порядок — число. Чем меньше число, тем выше элемент среди соседей с тем же родителем.
• Включено — флажок. Если он установлен, элемент виден на сайте. Снимите, чтобы временно скрыть.
• Действия — кнопка «Удалить».

Чтобы изменить порядок, просто введите новые числа в колонке «Порядок». Например, у вас есть три пункта на верхнем уровне. Поставьте им 1, 2, 3. Если хотите, чтобы какой-то пункт был первым, поставьте ему 1, остальным — 2 и 3.

Чтобы изменить вложенность, в колонке «Родитель» выберите другой элемент. Если выбрать «Верхний уровень», элемент станет самостоятельным.

Чтобы скрыть элемент, снимите галочку в колонке «Включено». Позже её можно вернуть.

Сохранение изменений

После любых правок в таблице элементов обязательно нажмите кнопку «Сохранить изменения», которая находится под таблицей. Только после этого ваши изменения вступят в силу.

Заключение

Теперь вы умеете:

• создавать деревья;
• добавлять в них категории, страницы и произвольные ссылки;
• настраивать порядок, вложенность и видимость элементов;
• сохранять изменения.

Созданное дерево можно вывести на сайте с помощью ID дерева. Если вы сами работаете с шаблонами, используйте вызов {PHP|cot_toc_page_render(1)}, где 1 — ID вашего дерева. Если шаблонами занимается разработчик, просто передайте ему этот ID.

Плагин готов к работе. Удачи в создании удобных и понятных оглавлений!