# =========================================================================== #
# NG CMS // Плагины // Архив сайта                                            #
# =========================================================================== #

Плагин позволяет на сайте отображать информационный блок-архив новостей.
В блоке показывается список месяцев в которые на сайте создавались новости.

[!] Версия 0.10: Интегрирована ng-helpers v0.2.2 для улучшения производительности и безопасности

Для работы плагина используется единый TWIG шаблон (по умолчанию archive.tpl).

Требования:
- NGCMS >= 0.9.3
- PHP >= 7.0
- ng-helpers >= 0.2.2 (для улучшенного кеширования и валидации)

--------------------------------------------------------------------
Поддерживаемые переменные:
  . {{tpl_url}} - путь к текущему активному шаблону сайта

* Цикл {% for entry in entries %}{% endfor %} - шаблон содержимого (строки) информационного блока
  Поддерживаемые переменные:
  . {{entry.link}}   - ссылка на новости по указанному месяцу
  . {{entry.title}}   - название месяца и год
  . {{entry.cnt}}     - кол-во новостей в указанном месяце [включается в настройках]
  . {{entry.ctext}}   - текстовое описание кол-ва, конкретное слово указано в языковом
                файле main.ini (переменная counter.case) [включается в настройках]
  . {% if (entry.counter) %} .. {% endif %} - информационный блок, всё что в нём лежит либо
    (не)показывается в зависимости от установки флага "отображать счетчик новостей"
    в настройках плагина


================================================================================
Варианты использования плагина в шаблонах
================================================================================
1. Автоматический запуск.
В шаблоне main.tpl будет доступна переменная {plugin_archive} с выводом блока календаря
2. TWIG
В любом шаблоне можно запустить генерацию календаря при помощи  TWIG функции callPlugin()

Пример (для TWIG шаблона):
{{ callPlugin('archive.show', {'maxnum' : 12, 'counter' : 1, 'tcounter' : 1, 'template': 'archive_twig'}) }}

Пример (для любого не-TWIG шаблона, к примеру, для main.tpl):
{{ callPlugin('archive.show', {'cacheExpire': 60 }) }}

Доступные переменные (передаются в качестве мессива параметров после имени 'archive.show':
* maxnum		- кол-во отображаемых месяцев
* counter		- отображать счетчик новостей
* tcounter	- отображать текстовое описание количества
* template	- имя шаблона
* cacheExpire		- срок жизни кеша (по умолчанию = 0)

__________________________________________
  Поддерживаемые функции
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Генерацию блока при помощи TWIG функции callPlugin()
+ Кеширование с автоматическим управлением TTL (ng-helpers v0.2.2)
+ Валидация параметров: maxnum (1-50), cacheExpire (0-86400 сек)
+ Санитизация имени шаблона для защиты от XSS
+ Расширенное логирование (engine/logs/archive.log)

Интеграция ng-helpers (v0.10):
- ✅ cache_get/cache_put - современное кеширование (HIT/MISS мониторинг)
- ✅ clamp() - валидация maxnum (1-50) и TTL (0-86400 сек)
- ✅ sanitize() - защита от XSS через параметр template
- ✅ logger() - расширенное логирование операций

Подробная документация: engine/plugins/archive/CHANGELOG_NGHELPERS.md
+ Шаблоны плагина внутри шаблона сайта
