# =========================================================================== #
# NG CMS // Плагины // Генератор форм обратной связи (ng-helpers v0.2.2)     #
# =========================================================================== #

МОДЕРНИЗАЦИЯ С NG-HELPERS v0.2.2 [31 января 2026]
--------------------------------------------------------------------
✅ array_get() - безопасный доступ к $_REQUEST/$_POST (50+ замен)
✅ logger(message, level, file) - структурированное логирование
✅ CSRF защита через validate_csrf() и csrf_field()
✅ Валидация email через validate_email()
✅ Санитизация данных через sanitize()
✅ Защита от "Undefined index" предупреждений
✅ Улучшенная безопасность и стабильность

О ПЛАГИНЕ
--------------------------------------------------------------------
 Плагин feedback позволяет администратору создавать различные типы форм
обратной связи, которые будет заполнять посетитель.

Плагином поддерживается неограниченное кол-во форм, внутри формы может быть
любое кол-во полей.
Поле может быть следующего типа:
1. Текстовое - одна строка, которую вводит пользователь
2. Текстовый блок - многострочный блок (textarea)
3. Поле выбора - выпадающий список, варианты со значениями прописываются
   администратором при создании/настройке формы обратной связи
4. Дата - отображается 3 выпадающих списка для выбора дня/месяца/года
5. Email - поле для ввода email адреса, оно позволяет отправлять пользователю сообщение
   (выбирается шаблон)

Результаты заполнения форм отправляются на заранее заданный список e-mail
адресов (список задаётся для каждой формы отдельно).
При наличии полей типа email (с выбранным шаблоном) сообщение отправляется и на него.

Настройка плагина
=====================

[x] Создание формы.
------------------------
При нажатии на ссылку "создать новую форму" создаётся пустая форма с
id "newform". При использовании настоятельно рекомендуется заменить
идентификатор формы на другое.

[x] Использование формы.
------------------------
Для того, чтобы форму можно было использовать, необходимо выставить
флаг "активна" при её редактировании.


[x] Собственные шаблоны.
------------------------
При желании, вы можете создать свой собственный шаблон для любой формы обратной связи.
Шаблон плагина может храниться как в шаблоне сайта, так и в самом плагине.
Пути расположения шаблонов:
  /templates/<имя шаблона сайта>/plugins/feedback/custom/<имя шаблона плагина>/
  /engine/plugins/feedback/tpl/custom/<имя шаблона>/
Администратор сайта в настройках плагина может выбрать используемый шаблон.


Шаблоны:
===========[ site.form.tpl ]===========
Форма вывода шаблона

------------------------
В шаблонах доступны следующие TWIG переменные:

< TODO >


===========[ mail.html.tpl / mail.text.tpl ]===========
Форма отправки email сообщения

------------------------
В шаблонах доступны следующие TWIG переменные:
  * form		- массив с параметрами формы
  * form.id		- ID формы
  * form.title		- название формы
  * form.description	- описание формы
  * flags		- массив с наборами флагов
  * flags.link_news	- признак наличие прикрепленной новости

Для отображения полей формы доступны следующие переменные:
  * entries		- массив, содержит данные о переменных, отсортирован в соответствии с порядком
			  отображения переменных в настройках формы
  * entries[x].id	- ID переменной
  * entries[x].title	- заголовок переменной
  * entries[x].value	- заполненное пользователем значение переменной

  * values		- массив со значениями переменных
			ключ - ID переменной
			значение - заполненное пользователем значение переменной

В случае наличия прикрепленной новости доступны также переменные:
  * news.id		- ID прикрепленной новости
  * news.title		- заголовок новости
  * news.url		- URL прикрепленной новости


[x] Привязка формы к новостям
------------------------
Форма может работать в 3х режимах:
- Без привязки
- Привязка возможна
- Привязка обязательна

Для привязки формы к новости необходимо к URL'у новости дополнительно передавать GET параметр linked_id={тут_id_новости}
При размещении ссылки в шаблонах новостей (news.short.tpl / news.full.tpl) доп. параметр будет выглядеть как
linked_id={news-id}

Полностью URL формы в установке по умолчанию будет выглядеть как: /plugin/feedback/?id=9&linked_id={news-id}



Использование плагина
=====================
При заходе в режим редактирования формы обратной связи вы увидите URL, по которому данная форма будет доступна.



