# =========================================================================== #
# NG CMS // Плагины // Дополнительные поля                                    #
# =========================================================================== #

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

Поддерживаемые типы дополнительных полей:
-----------------------------------------
* текстовый      - обычное в которое при добавлении/редактировании новости может
  быть добавлена любая строка.
* выбор значения - при создании поля администратор задаёт возможные варианты
  выбора, а при добавлении/редактировании новости можно выбрать один из заранее
  установленных администратором вариантом
* текстовый блок - блок текста, поддерживающий многострочный контент. при этом
  при выводе информации между строками добавляется тег HTML форматирования "<br/>"
  что позволяет корректно отображать многострочную информацию.


Коды, доступные в шаблонах:
----------------------------------------
При активации плагина в шаблонах становятся доступными следующие коды:
* [xfield_ИМЯ] ... [/xfield_ИМЯ] - специальный блок, который отображается
  только в случае, если дополнительное поле с ID "ИМЯ" заполнено
  [!!] Если поле заполнено, но его значение = "0", то оно также не будет
  отображаться.
* [xvalue_ИМЯ] - данная переменная заменяется значением поля с ID "ИМЯ"

Следующие переменные доступны в TWIG шаблонах, а также при использовании условного
блока [TWIG]..[/TWIG] в обычных шаблонах.
Обратите внимание, все переменные находятся в адресном пространстве p.xfields, т.е.
переменная ИМЯ.type доступно как p.xfields.ИМЯ.type

* ИМЯ.type - тип переменной (text, textarea, select, images)
* ИМЯ.title - название поля
* ИМЯ.value - значение переменной для всех типов кроме images
Для переменной типа images выводятся переменные:
* ИМЯ.count - кол-во изображений
* ИМЯ.value - "отрисованный" TWIG шаблон news.show.images.tpl (при его наличии)
* ИМЯ.entries - содержит список изображений, формат. см. в формател поля 'entries' шаблона news.show.images.tpl

// Для наглядности (и понимания списка доступных переменных) можно использовать TWIG функцию debugValue,
// например так: {{ debugValue(p.xfields) }} - будут выведены все доступные доп. поля и их параметры/значения


Специальные шаблоны:
----------------------------------------
Для отображения полей типа `images` (группа изображений) существует специальный TWIG шаблон
(находится в каталоге плагина) news.show.images.tpl
В шаблоне доступны следующие переменные:
* fieldName 	- ID доп. поля
* fieldTitle    - наименование доп. поля
* fieldType	- значение 'images' (заложено на будущее для возможной поддержки разных типов полей)
* entriesCount	- кол-во изображений в данном доп. поле
* entries	- массив с изображениями, каждый элемент содержит следующие поля:
	*	flags		- массив с флагами:
		*	hasPreview	- принимает значение (1) в случае, если у изображения есть уменьшенная копия
	*	url		- URL изображения
	*	width		- ширина изображения
	*	height		- высота изображения
	*	name		- имя файла (без пути) изображения
	*	origName	- оригинальное имя файла (при загрузке файла)
	*	description	- описание изображения
 	в случае наличия уменьшенной копии также будут доступы следующие переменные:
	*	pwidth		- ширина уменьшенной копии
	*	pheight		- высота уменьшенной копии
	*	purl		- URL уменьшенной копии

* execStyle	- указывает режим вызова для отображения данных. Принимаемые значения:
	//		* short		- short new display
	//		* full		- full news display
	//		* export	- export data [ for plugins or so on. No counters are updated ]
	//		* export_body	- export ONLY BODY short+full [ for plugins or so on... ]
	//		* export_short	- export ONLY BODY short      [ for plugins or so on... ]
	//		* export_full	- export ONLY BODY full       [ for plugins or so on... ]
* execPlugin	- указывает через какой плагин производится отображение данных. При вызове из ядра не заполняется (пусто).

----------------------------------------
Для работы с таблицами (в новостях) существует TWIG шаблон news.table.tpl (находится в каталоге плагина), он позволяет отображать информацию из таблиц.
Доступная переменная - массив entries, каждый элемент массива - строка табличных данных. В массиве доступны следующие переменные:
 * num		- номер записи по порядку
 * id		- ID записи в таблице БД ng_xfields
 * field_XXX (где XXX - ID поля xfields) - значение поля XXX
 * flags	- массив элементов с именем field_XXX (где XXX - ID поля xfields), значение принимает TRUE если заполнено значение для данной переменной


Пример использования плагина:
----------------------------------------
 Допустим, вы ведёте сайт, занимающийся обзорами новых видео-карт для компьютеров.
В какой-то момент Вам захотелось кроме текста новости выводить ещё и информацию о
результатах тестирования железа в вашей лаборатории.
 Тогда Вам будут полезны вот такие поля в новости:
* ID      : tested
  Описание: Проводилось тестирование
  Тип     : Выбор
  Значения: 0 => Нет
            1 => Да

* ID      : reldate
  Описание: Дата выхода на рынок
  Тип     : Текст

* ID      : vendor
  Описание: Производитель
  Тип     : Выбор
  Значение: NVidia
            ATI
            VIA
            Intel

* ID      : multi
  Описание: Поддерживает установку нескольких карт в систему
  Тип     : Выбор
  Значение: Нет
            Да
* ID      : index
  Описание: Индекс производительности
  Тип     : Текст

* ID      : result
  Описание: Мнение ред. коллегии
  Тип     : текстовый блок

В шаблон новости вы можете добавить такой блок:
[xfield_tested]
 Данный адаптер был протестирован в нашей лаборатории.<br/>
 Производитель: [xvalue_vendor]<br/>
 Установка нескольких адаптеров в систему: [xfield_multi]<br/>
 Индекс производительности: [xfield_index]<br/>
 [xfield_result]Мнение ред. коллегии:
 <div>[xvalue_result]</div>
[/xfield_tested]

В результате таких несложных действий вы получите:
1. Если вы выбрали "Да" в поле "tested", то данный блок будет отображаться.
   При выборе "Нет" - не будет.
2. Мнение ред. коллегии будет отображаться только в случае, если это
   мнение указано.

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


Полный список параметров, доступных для установки в дополнительном поле:
 *  ID - идентификатор поля
 *  Название - название, отображаемое в форме добавления/редактирования новостей
 *  Тип поля - тип поля (текстовый/текстовый блок/выбор значения)
 *  Значение по умолчанию
[*] Список значений (только для поля с типом "выбор значения")
 *  Обязательно - поле используется только для переменной с типом "выбор значения".
    При установке "Да" пользователь может выбрать только из указанных вами значений
    При установке "Нет" пользователю даётся возможность ничего не выбирать (добавляется
    пустой элемент в начало списка)


За дополнительной информацией обращайтесь на форум.
http://ngcms.ru/forum/