# =========================================================================== #
# NG CMS // Плагин ads_pro // Управление рекламными и произвольными блоками  #
# =========================================================================== #
## 📋 Описание
Плагин ads_pro - мощное решение для управления произвольными блоками контента на вашем сайте. Позволяет создавать, настраивать и автоматизировать показ рекламных блоков, баннеров, виджетов и любого другого контента.
## ✨ Основные возможности
### 🎯 Создание и управление блоками
- **Неограниченное количество блоков** - создавайте столько блоков, сколько требуется
- **Группировка блоков** - объединяйте блоки по ID (имени) для удобного управления
- **Три типа контента**:
  - 📝 HTML - полноценный HTML-код с поддержкой стилей и скриптов
  - 🔧 PHP - динамический PHP-код для сложной логики
  - 📄 TEXT - простой текстовый контент
### ⚙️ Гибкие настройки отображения
**Режимы активации:**
- ✅ Постоянный показ - блок всегда активен
- ⏰ По расписанию - автоматический показ в заданное время
- ❌ Выключен - блок неактивен
**Условия показа:**
- 🏠 На главной странице
- 📂 В определенных категориях
- 📰 На страницах новостей
- 📄 На статических страницах
- 🔌 В плагинах
- 🌐 Везде или везде кроме указанных мест
### 🎲 Режимы отображения блоков с одинаковым ID
При наличии нескольких блоков с одинаковым именем:
1. **Последовательно** - показываются все активные блоки один за другим
2. **Первый активный** - показывается только первый подходящий блок
3. **Случайный** - каждый раз выбирается случайный блок из активных
### ⏱️ Показ по расписанию
- **Дата начала показа** - блок начнет отображаться с указанного времени
- **Дата окончания показа** - блок автоматически скроется после указанного времени
- **Гибкие настройки**:
  - Без даты начала → показ начинается немедленно
  - Без даты окончания → показ продолжается бесконечно
  - С обеими датами → точный контроль периода показа
### ⚡ Производительность
- **Автоматическое кэширование** - HTML и TEXT блоки кэшируются для быстрой загрузки
- **Умный сброс кэша** - автоматически сбрасывается при обновлении настроек
- **Синхронизация с БД** - хранение блоков в базе данных для переносимости
## 📦 Установка
1. Разместите папку плагина в `engine/plugins/ads_pro/`
2. Активируйте плагин в панели управления
3. Настройте параметры в разделе "Дополнительно" → "ads_pro"
## 🎨 Использование в шаблонах
Для вывода блока в шаблоне используйте переменную с именем блока:
```twig
{# Вывод блока с текстовым ID "sidebar_banner" #}
{{ sidebar_banner|raw }}
{# Вывод блока с числовым ID (например, 2222) - добавляется префикс block_ #}
{{ block_2222|raw }}
{# Вывод блока "top_ads" на главной странице #}
{% if isMain %}
    {{ top_ads|raw }}
{% endif %}
{# Условный вывод блока "mobile_menu" #}
{% if system_flags.check_pda %}
    {{ mobile_menu|raw }}
{% endif %}
```
**Важно:**
- Для блоков с текстовыми ID используйте их напрямую: `{{ my_block|raw }}`
- Для блоков с числовыми ID автоматически добавляется префикс `block_`: `{{ block_123|raw }}`
- Всегда используйте фильтр `|raw` для вывода HTML-контента без экранирования
## ⚙️ Настройка
### Общие настройки
- **Поддержка страниц новостей** - включить отображение блоков на полных страницах новостей
- **Сортировка новостей** - выбор порядка отображения в конфигураторе
- **Режим множественного отображения** - выбор стратегии показа блоков с одинаковым ID
### Управление блоками
1. **Создание блока**:
   - Укажите ID (имя) блока - используется в шаблонах
   - Выберите тип контента (HTML/PHP/TEXT)
   - Добавьте описание для удобства
   - Настройте условия показа
2. **Настройка расписания**:
   - Выберите режим "По расписанию"
   - Укажите дату и время начала показа
   - Укажите дату и время окончания показа
3. **Условия отображения**:
   - Добавьте правила для показа/скрытия
   - Настройте приоритеты
   - Протестируйте на сайте
## 🔧 Примеры использования
### Пример 1: Баннер в сайдбаре
```
ID: sidebar_ad
Тип: HTML
Контент:
<div class="banner">
    <a href="/promo">
        <img src="/images/banner.jpg" alt="Акция">
    </a>
</div>
Условия: Показывать везде кроме главной
```
### Пример 2: Динамический виджет
```
ID: dynamic_widget
Тип: PHP
Контент:
<?php
$count = $mysql->result("SELECT COUNT(*) FROM " . prefix . "_users");
echo "<div class='widget'>Пользователей: $count</div>";
?>
Условия: Показывать везде
```
### Пример 3: Временная акция
```
ID: promo_block
Тип: HTML
Режим: По расписанию
Начало: 01.12.2026 00:00
Окончание: 31.12.2026 23:59
Контент: <div class="promo">Новогодняя распродажа!</div>
```
## 🛠️ Технические особенности
- **Версия NGCMS**: 0.9.3+
- **PHP**: 7.0+
- **База данных**: MySQL/MariaDB
- **Хранение**: Таблица `_ads_pro` + конфигурация плагина
- **Кэш**: Файловый кэш в `engine/cache/`
## 📝 Changelog
### Версия 1.x
- ✅ Синхронизация с базой данных при переносе сайта
- ✅ Поддержка ng-helpers для улучшенной производительности
- ✅ Современный интерфейс настроек с табами
- ✅ Исправлена активация табов в настройках
## 🤝 Поддержка
При возникновении вопросов или проблем:
- Проверьте активацию плагина в админ-панели
- Убедитесь, что ID блока указан правильно в шаблоне
- Проверьте условия показа блока
- Очистите кэш плагина через настройки
## 📄 Лицензия
Плагин распространяется "как есть" для использования с NG CMS.
---
**Разработка**: NG CMS Community  
**ng-helpers интеграция**: Copilot + russsiq  
**Документация обновлена**: 29.01.2026  
**Версия**: 1.0.1

📖 **Дополнительная документация**: См. `CHANGELOG_NGHELPERS.md` для полного описания интеграции ng-helpers
