# =========================================================================== #
# NG CMS // Плагины // Облако тегов v0.30                                     #
# =========================================================================== #
# Обновлено для PHP 8.3 с современными шаблонами и Twig синтаксисом          #
# =========================================================================== #
Плагин позволяет запустить на вашем сайте функцию "облако тегов".
Что такое "облако тегов"? Вот описание из википедии:
----
Облако тегов или Туча ярлыков или Облако меток (англ. tag cloud) - визуальное
представление списка ярлыков (или категорий). Частота упоминаний, поисков, ссылок
в интернете с определенного сайта неких слов, терминов, имен, отображается на
специальной странице в виде изображения этих слов в формате гиперссылок.
Размер изображения тем больше, чем выше релевантность данного слова (термина, имени).
----
После установки и активизации плагина у вас появляется возможность для каждой новости
указать (через запятую) список тегов/ключевых слов актуальных для данной новости.
ВАЖНЫЕ ИЗМЕНЕНИЯ В ВЕРСИИ 0.30:
* Полная совместимость с PHP 8.3
* Модернизированные шаблоны с div/CSS структурой вместо таблиц
* Переход на синтаксис переменных Twig: {{ variable }} вместе {variable}
* Улучшенная доступность и семантическая разметка HTML
* Поддержка современных CSS3 свойств и респонсивного дизайна
* НОВАЯ ВОЗМОЖНОСТЬ: Вызов через callPlugin() в шаблонах Twig
* АВТОМАТИЧЕСКОЕ ОБНОВЛЕНИЕ: При пересборке индексов обновляется структура БД
* НОВАЯ ФУНКЦИЯ: Автоматическое добавление категорий в теги с настраиваемым включением/выключением
Отображение плагина:
--------------------------------------------------------------------
* Внутри новости:
  При активации плагина становятся доступны:
  1. Блок [tags] ... [/tags], который будет видим в случае, если в новости
     есть хотябы один тег
  2. Переменная {{ tags }}, содержащая список тегов
  TWIG переменные:
  * p.tags.flags.haveTags - флаг: true если есть теги, иначе - false
  * p.tags.value	- блок со списком тегов (выводит тоже самое, что и переменная {{ tags }})
  * p.tags.count	- кол-во тегов в новости
  * p.tags.list		- массив со списком тегов, каждый элемент содержит:
	* name		- название тега
	* link		- URL тега
	* value		- ссылка на тег
* На боковой панели:
  СПОСОБ 1 (классический): Добавьте в шаблон сайта main.tpl переменную {{ plugin_tags }}
  СПОСОБ 2 (новый в v0.30): Используйте функцию callPlugin() в любом месте шаблона:
  {% if pluginIsActive('tags') %}
    {{ callPlugin('tags.show', {'maxnum': 12, 'counter': 1, 'template': 'sidebar', 'cacheExpire': 60}) }}
  {% endif %}
* На собственной страничке плагина:
  Страница плагина доступна по следующему адресу на Вашем сайте:
  /plugin/tags/ (при заданных по умолчанию настройках ЧПУ)
Возможности режима отображения: внутри новости
--------------------------------------------------------------------
Для формирования переменной {{ tags }} используется конфигурационный файл
params.ini, находящийся в одном каталоге вместе с шаблоном плагина
(в зависимости от настроек плагина, шаблон может располагаться либо
в каталоге плагина, либо - в каталоге общего шаблона сайта).
Из файла params.ini используются следующие переменные:
tag_news 	   - оформление отображения тега
	Доступные переменные:
		{{ url }} - URL страницы тега
		{{ tag }} - тег
tag_news_delimiter - разделитель тегов в списке
Возможности режима отображения: на боковой панели
--------------------------------------------------------------------
Для отображения используются следующие файлы:
* sidebar.tpl - "оболочка" вокруг облака тегов на боковой панели
  Доступные переменные:
  {{ tpl_url }} - URL шаблона сайта
  {{ entries }} - список тегов. как формируется - указано ниже
  {{ cloud3d }} - специальная переменная для вывода 3D облака тегов, активируется
              параметром конфигурации `Выводить переменную для 3D облака тегов`
              (пример работы с 3D облаком тегов можно найти в скине 3d)
  ** стиль отображения списка берётся из params.ini
* cloud.tpl - "оболочка" вокруг облака тегов (на странице плагина)
  Доступные переменные:
  {{ tpl_url }} - URL шаблона сайта
  {{ entries }} - список тегов. как формируется - указано ниже
  {{ tag }}     - название отображаемого тега
  {{ pages }}   - отображение блока постраничной навигации
  ** стили для отображения тегов в списке тегов берётся из params.ini
  ** стиль для отображения новостей по конкретному тегу берётся из cloud.tag.entry.tpl
  Блоки:
  [paginator]..[/paginator] - отображается в случае, если есть постраничная навигация (т.е.
   если навигация разрешена и должно отображаться более одной страницы)
* cloud.tag.tpl - "оболочка" вокруг облака тегов (на странице плагина) при отображении
  конкретного тега.
  ## Это опциональный шаблон, его наличие - не обязательно.
  ## Если данного шаблона нет, то вместо него используется шаблон cloud.tpl
* cloud.tag.entry.tpl - стиль отображения новостей по конкретному тегу
  Доступные переменные:
  {{ news_link }} - ссылка на новость
  {{ title }}     - название новости
  {{ date }}      - дата создания новости
  ** ВНИМАНИЕ !! **
  ** [ для данного шаблона указан неполный список поддерживаемых переменных    ] **
  ** [ описание полного списка смотрите в описании шаблона сайта news.full.tpl ] **

ВАЖНО: В версии 0.30 отдельный шаблон pages.tpl удален для упрощения.
Пагинация теперь встроена непосредственно в cloud.tpl и sidebar.tpl через переменную {{ pages }}.
Параметры отображения постраничной навигации берутся из текущего шаблона из файла
конфигурации variables.ini (блок [navigation])

* params.ini - конфиг, из которого используются параметры:
* pages.tpl - отображение постраничной навигации
  Доступные переменные:
  {{ pages }}     - страницы для постраничной навигации (сгенерированные стандартной функцией NextGen CMS)
  ВНИМАНИЕ: В версии 0.30 блоки [prev_link] и [next_link] удалены для унификации с другими плагинами.
  Теперь используется стандартная пагинация NextGen CMS через переменную {{ pages }}.
  ** Параметры отображения постраничной навигации берутся из текущего шаблона из файла
     конфигурации variables.ini (блок [navigation])
* params.ini - конфиг, из которого используются параметры:
  news.tag              - стиль отображения тега в списке тегов в новости
       Доступные переменные:
       {{ url }}    - ссылка на страницу тега
       {{ tag }}    - название тега
  news.tag.delimiter    - разделитель между тегами
  news.notags	- текст для отображения при включении функции "Всегда выводить в новости блок с тегами"
  sidebar.tag           - стиль отображения тега на боковой панели
       Доступные переменные:
       {{ url }}    - ссылка на страницу тега
       {{ tag }}    - название тега
       {{ posts }}  - кол-во новостей в которых встречается этот тег
       {{ params }} - HTML стиль/класс отображения тега
  sidebar.tag.delimiter - разделитель между тегами
  cloud.tag             - стиль отображения тега на странице плагина (список тегов)
       Доступные переменные:
       {{ url }}    - ссылка на страницу тега
       {{ tag }}    - название тега
       {{ posts }}  - кол-во новостей в которых встречается этот тег
       {{ params }} - HTML стиль/класс отображения тега
  cloud.tag.delimiter   - разделитель между тегами
  ; Переменные, доступные при использовании 3D облака тегов
  size3d.min    - минимальный размер шрифта для облака тегов (в pt, по умолчанию - 10)
  size3d.max    - максимальная размер шрифта для облака тегов (в pt, по умолчанию - 18)
Возможности режима отображения: на странице плагина (общая страница)
--------------------------------------------------------------------
На общей странице отображается просто список тегов.
Все возможности дублируются с возможностями режима "на боковой панели".
Отличительные черты:
1. Использование шаблона "sidebar.tpl" вместо шаблона "cloud.tpl"
2. В шаблоне "plugin.tpl" доступна переменная {{ tag }} в которой для данного
   режима отображается строка "список тегов"
Смысл данного режима - возможность отобразить заметно бОльший список тегов
(вплоть до нескольких сотен).
Возможности режима отображения: на странице плагина (страница тега)
--------------------------------------------------------------------
На странице конкретного тега отображается список новостей, в которых
встречается данный тег.
Для отображения используются следующие файлы:
* plugin.tpl - "оболочка" для отображения списка новостей по тегу.
  Доступные переменные для данного шаблона описаны ниже.
  Переменная {{ tag }} в данном режиме принимает иное значение - в неё
  записывается выбранный пользователем тег.
* entry.tpl - строка-описание новости
  Доступные переменные:
  {{ news_link }} - URL новости
  {{ title }}     - Название новости
  {{ date }}      - Дата создания новости
Настройка отображения плагина при добавлении/редактировании новостей
--------------------------------------------------------------------
Для отображения элементов плагина используются следующие файлы:
* tags_addnews.tpl  - добавление новости
* tags_editnews.tpl - редактирование новости
  Доступные переменные:
  {{ tags }} - список тегов новости
ТЕХНИЧЕСКИЕ ИЗМЕНЕНИЯ В ВЕРСИИ 0.30:
--------------------------------------------------------------------
* Все шаблоны переведены на современную div/CSS структуру
* HTML5 семантические элементы и улучшенная доступность
* Адаптивная верстка с поддержкой мобильных устройств
* Синтаксис переменных обновлен с {variable} на {{ variable }}
* Добавлены CSS классы для гибкой стилизации:
  - .tags-container для основных контейнеров
  - .tags-cloud для облака тегов
  - .tags-list для списков тегов
  - .tag-item для отдельных тегов
  - .tags-form для форм ввода
  - .tags-navigation для пагинации
* Полная совместимость с PHP 8.3
* Улучшенная производительность и оптимизация кода
* НОВАЯ ФУНКЦИЯ: callPlugin() для вызова из Twig шаблонов
* АВТООБНОВЛЕНИЕ БД: При пересборке индексов автоматически обновляется структура БД
* АВТОКАТЕГОРИИ: Функция автоматического добавления категорий в теги

НОВАЯ ФУНКЦИЯ - АВТОМАТИЧЕСКИЕ КАТЕГОРИИ:
--------------------------------------------------------------------
В версии 0.30 добавлена возможность автоматически добавлять названия категорий
в список тегов при сохранении новости.

Настройка функции:
* В разделе конфигурации плагина добавлена опция "Автоматически добавлять категории в теги"
* По умолчанию функция отключена (можно включить в настройках плагина)
* Работает как для новых новостей, так и при редактировании существующих

Принцип работы:
* При сохранении новости плагин проверяет, включена ли функция в настройках
* Если включена, извлекает название категории из глобального массива $catmap
* Автоматически добавляет название категории к существующим тегам новости
* Предотвращает дублирование - если категория уже есть в тегах, повторно не добавляется
* Работает независимо от того, указал ли пользователь теги вручную или нет

Преимущества:
* Улучшает SEO - категории автоматически становятся тегами
* Увеличивает связность контента на сайте
* Экономит время авторов - не нужно дублировать категорию в тегах вручную
* Можно легко включить/выключить в настройках без изменения кода

Пример работы:
* Новость размещена в категории "Технологии"
* Автор указал теги: "php, программирование, веб"
* При сохранении автоматически добавится: "php, программирование, веб, Технологии"
* При повторном сохранении дублирования не произойдет
ОБНОВЛЕНИЕ С ПРЕДЫДУЩИХ ВЕРСИЙ:
--------------------------------------------------------------------
Для обновления с версии 0.25 и ранее:
1. Загрузите новые файлы плагина
2. Перейдите в настройки плагина в админке
3. Выберите "Пересобрать индексы тегов" = "Да"
4. Сохраните настройки
При пересборке индексов автоматически произойдет:
- Обновление структуры таблиц БД для PHP 8.3
- Оптимизация индексов и связей
- Проверка целостности данных
- Очистка неиспользуемых тегов
--------------------------------------------------------------------
В версии 0.30 добавлена возможность вызова плагина Tags через функцию callPlugin(),
что позволяет более гибко управлять выводом тегов в любом месте шаблона.
Синтаксис:
{{ callPlugin('tags.show', параметры) }}
Доступные параметры:
* maxnum (число) - максимальное количество тегов для вывода (по умолчанию: 20)
* orderby (строка) - сортировка: 'name', 'count', 'random' (по умолчанию: 'name')
* orderdir (строка) - направление сортировки: 'asc', 'desc' (по умолчанию: 'asc')
* template (строка) - имя шаблона для вывода (по умолчанию: 'sidebar')
* counter (число) - включить счетчик использований (по умолчанию: 1)
* cache (булево) - использовать кэширование (по умолчанию: true)
* cacheExpire (число) - время кэширования в секундах (по умолчанию: 3600)
* newsfilter (число) - фильтровать по текущей категории (1 - да, 0 - нет)
ВАРИАНТЫ СОРТИРОВКИ:
===================
1. В СЛУЧАЙНОМ ПОРЯДКЕ:
   {{ callPlugin('tags.show', {'orderby': 'random'}) }}
2. НАЗВАНИЕ (ВОЗРАСТАНИЕ) - по умолчанию:
   {{ callPlugin('tags.show', {'orderby': 'name', 'orderdir': 'asc'}) }}
   или просто:
   {{ callPlugin('tags.show', {}) }}
3. НАЗВАНИЕ (УБЫВАНИЕ):
   {{ callPlugin('tags.show', {'orderby': 'name', 'orderdir': 'desc'}) }}
4. ПОПУЛЯРНОСТЬ (ВОЗРАСТАНИЕ):
   {{ callPlugin('tags.show', {'orderby': 'count', 'orderdir': 'asc'}) }}
5. ПОПУЛЯРНОСТЬ (УБЫВАНИЕ):
   {{ callPlugin('tags.show', {'orderby': 'count', 'orderdir': 'desc'}) }}
ПРАКТИЧЕСКИЕ ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ:
==================================
1. Простое облако тегов (по умолчанию):
   {{ callPlugin('tags.show') }}
2. Топ-10 популярных тегов:
   {{ callPlugin('tags.show', {'maxnum': 10, 'orderby': 'count', 'orderdir': 'desc'}) }}
3. Случайные теги с кэшированием на 5 минут:
   {{ callPlugin('tags.show', {'maxnum': 15, 'orderby': 'random', 'cacheExpire': 300}) }}
4. Кастомный шаблон облака:
   {{ callPlugin('tags.show', {'template': 'cloud', 'maxnum': 25}) }}
5. Теги по алфавиту без счетчиков:
   {{ callPlugin('tags.show', {'orderby': 'name', 'orderdir': 'asc', 'counter': 0}) }}
6. Популярные теги с длительным кэшем:
   {{ callPlugin('tags.show', {'maxnum': 20, 'orderby': 'count', 'orderdir': 'desc', 'cacheExpire': 7200}) }}
РЕКОМЕНДУЕМЫЕ КОНФИГУРАЦИИ:
==========================
Для боковой панели (популярные теги):
{{ callPlugin('tags.show', {
    'maxnum': 15,
    'template': 'sidebar',
    'orderby': 'count',
    'orderdir': 'desc',
    'counter': 1,
    'cacheExpire': 1800
}) }}
Для страницы облака тегов (все по алфавиту):
{{ callPlugin('tags.show', {
    'template': 'cloud',
    'orderby': 'name',
    'orderdir': 'asc',
    'counter': 1
}) }}
Случайная подборка для разнообразия:
{{ callPlugin('tags.show', {
    'maxnum': 10,
    'template': 'sidebar',
    'orderby': 'random',
    'counter': 0,
    'cacheExpire': 300
}) }}
Компактный список без счетчиков:
{{ callPlugin('tags.show', {
    'maxnum': 30,
    'template': 'sidebar',
    'orderby': 'name',
    'counter': 0
}) }}
СООТВЕТСТВИЕ С HTML SELECT:
===========================
Если используете HTML форму для выбора сортировки:
<select name="orderby">
    <option value="0">В случайном порядке</option>        → 'orderby': 'random'
    <option value="1">Название (возрастание)</option>     → 'orderby': 'name', 'orderdir': 'asc'
    <option value="2">Название (убывание)</option>        → 'orderby': 'name', 'orderdir': 'desc'
    <option value="3">Популярность (возрастание)</option> → 'orderby': 'count', 'orderdir': 'asc'
    <option value="4">Популярность (убывание)</option>    → 'orderby': 'count', 'orderdir': 'desc'
</select>
ИНТЕГРАЦИЯ С УСЛОВИЯМИ:
======================
Проверка активности плагина:
{% if pluginIsActive('tags') %}
    {{ callPlugin('tags.show', {'maxnum': 12, 'orderby': 'count', 'orderdir': 'desc'}) }}
{% endif %}
Разные настройки для разных страниц:
{% if isHandler('news:main') %}
    {{ callPlugin('tags.show', {'maxnum': 10, 'orderby': 'random'}) }}
{% else %}
    {{ callPlugin('tags.show', {'maxnum': 15, 'orderby': 'count', 'orderdir': 'desc'}) }}
{% endif %}
ОТОБРАЖЕНИЕ ТЕГОВ В НОВОСТЯХ:
============================
В шаблонах новостей используйте переменные p.tags.*:
{% if p.tags.flags.haveTags %}
    <div class="post-tags">
        {{ lang.tags }} ({{ p.tags.count }}):
        {% for tag in p.tags.list %}
            <a href="{{ tag.link }}" class="tag-link">{{ tag.name }}</a>{% if not loop.last %}, {% endif %}
        {% endfor %}
    </div>
{% endif %}
ВАЖНЫЕ ЗАМЕЧАНИЯ:
================
* Все параметры callPlugin() опциональны
* Кэширование помогает снизить нагрузку на БД
* Для отображения в новостях используйте p.tags.*, а НЕ callPlugin()
* Параметр newsfilter работает только в контексте категорий новостей
Преимущества callPlugin():
* Можно использовать в любом месте шаблона, не только в боковой панели
* Гибкие параметры для каждого конкретного использования
* Независимое кэширование для разных вызовов
* Условная проверка активности плагина
