# =========================================================================== #
# NG CMS // Плагины // Блоки новостей                                         #
# =========================================================================== #

Плагин отображает на сайте информационные блоки по заданным критериям.
Функционально он заменяет плагины: lastnews, top_news

Работа с шаблонами
--------------------------------------------------------------------
Для своей работы плагин использует 2 файла-шаблона: entries.tpl и xnews.tpl
При настройках каждого профиля необходимо указать каталог в котором плагин
будет искать шаблон.

Алгоритм поиска:
1. Сначала плагин проверяет наличие каталога шаблона в templates/ВАШ_ШАБЛОН/plugins/xnews/КАТАЛОГ/ и наличие
   в нём файлов entries.tpl и xnews.tpl - если нашел, то использует их
2. Если в п. 1 файлы не были найдены, то плагин ищет шаблон в engine/plugins/xnews/tpl/КАТАЛОГ/ и проверяет
   наличие файлов entries.tpl и xnews.tpl - если нашел, то использует их
3. Если файлы не найдены, то выводится сообщение об ошибке о потеряном шаблоне

[[ !! Если шаблон не задан, то плагин пытается использовать шаблон в engine/plugins/xnews/tpl/example/ !! ]]


Используемые шаблоны [ шаблоны в формате шаблонизатора TWIG ]:
--------------------------------------------------------------------
* entries.tpl	- шаблон для отображения данных из новости.
  Обладает всеми возможностями шаблона news.short.tpl, но есть и дополнительные
  возможности.
  Переменные в шаблоне выводятся в виде {{ variable }}
  . news.author.name	- имя автора
  . news.author.url	- ссылка на профиль автора
  . news.author.id	- ID автора
  . news.title		- заголовок новости
  . news.short		- короткая новость
  . news.full		- полная новость
  . news.categories.masterText	- HTML ссылка для главной категории новости
  . news.categories.text	- HTML список категорий новости с ссылками на эти категории
  . news.categories.count	- кол-во категорий в которых находится новость
  . news.categories.list	- массив категорий в которых находится новость, каждый элемент содержит:
	. id		- ID категории
	. alt		- альт. имя категории
	. name		- имя категории
	. icon		- иконка категории
	. url		- URL категории
	. text		- HTML ссылка для категории
  . news.url.full		- ссылка на текущую новость
  . news.url.print		- ссылка на "версию для печати" текущей новости
  . news.flags.isUpdated	- Флаг: была ли новость отредактирована
  . news.update		- дата/время обновления (формат по умолчанию)
  . news.updateStamp		- дата/время обновления в unixtime, можно преобразовать в собственный формат
			  средствами TWIG'а
  . news.date		- дата/время публикации (формат по умолчанию)
  . news.dateStamp		- дата/время публикации в unixtime
  . news.views		- кол-во просмотров
  . news.flags.canEdit	- Флаг: может ли посетитель редактировать эту новость
  . news.flags.canDelete - Флаг: может ли посетитель удалить эту новость
  . news.url.edit	- URL для редактирования новости
  . news.url.delete	- URL для удаления новости
  . _files		- массив с приложенными к новости файлами
  . _images		- массив с приложенными к новости картинками

При включении опции "Извлекать URL'ы изображений из текста новости" (extractEmbeddedItems) доступны также переменные:
  . news.embed.imgCount	- кол-во извлеченных изображений
  . news.embed.images	- список URL'ов изображений

* xnews.tpl - основной шаблон
  . entriesCount	- кол-во найденных новостей
  . entries		- массив с отрисованными шаблонами entries.tpl по найденным новостям



Использование плагина при выводе в main.tpl
--------------------------------------------------------------------
Данные плагина можно использовать только при помощи TWIG функции callPlugin.
Формат вызова: callPlugin('xnews.show', параметры)

Функция xnews.show принимает на вход следующие параметры [детальное описание см. в админке плагина]:
  . id			- ID блока. Если заполнить это поле, то будет генерировать блок в соответствии 
			  с настройками в админке плагина
  . categoryMode	- Из каких категорий генерируется лента новостей
			  0: только из списка категорий, прописанного в categories
			  1: только из текущей категории
			  2: из списка категорий из categories + из текущей категории
  . categories		- Список категорий для генерации ленты
			  список через запятую из ID категорий
  . visibilityMode	- Область видимости
			  0: везде
			  1: на странице категорий
			  2: на странице новостей
			  3: страница категорий + новостей
  . visibilityCList	- Список категорий на которых отображается блок
			  список через запятую из ID категорий, на которых будет отображаться блок (если visibilityMode > 0)
  . mainMode		- Отображение новостей с главной страницы
			  0: Все новости
			  1: Только новости с главной
			  2: Только новости не с главной
  , pinMode		- Отображение прикрепленных новостей
			  0: Все новости
			  1: Только прикрепленные новости
			  2: Только неприкрепленные новости
  , favMode		- Отображение новостей из закладок администратора
			  0: Все новости
			  1: Только новости из закладок администратора
			  2: Только новости, не находящиеся в закладках администратора
  . count		- Количество новостей для отображения
  . skip		- Номер (по порядку) с которого начинать показ
  . maxAge		- Новости на последние N дней
  . order		- Порядок вывода новостей
			  'viewed' - по кол-ву просмотров (обратный порядок)
			  'commented' - по кол-ву комментариев (обратный порядок)
			  'random' - случайный порядок
			  'last' - по дате публикации
  . showNoNews		- Выводить блок если в нём нет новостей
			  true - выводить
			  false - не выводить
  . maxAge		- Вывод новостей только за последние N дней
  . skipCurrent		- Не отображать в блоке текущую новость (внимание, данный режим не позволяет кешировать новости!)
  . cacheAge		- Если указано значение > 0, то определяет срок кеширования блока (в секундах)
  . template	[!!]	- Каталог, в котором хранится необходимый шаблон (файлы entries.tpl и xnews.tpl)
где [!!] означает, что это обязательный параметр (кроме случая работы через ID плагина)


Пример вызова плагина в main.tpl:
1. Вывести блок с ID 'main'
[TWIG]{{ callPlugin('xnews.show', { 'id': 'main'}) }}[/TWIG]


2. Вывести новости из категории с ID = 15
[TWIG]{{ callPlugin('xnews.show', { 'categoryMode' : 0, 'categories' : '15', 'template' : 'xnews1'}) }}[/TWIG]


Примеры заполнения шаблонов:
--------------------------------------------------------------------
entries.tpl:
<li>
<a href="{{ link }}">
 {% if (title|length > 15) %}{{ title|slice(0,15) }}..{% else %}{{ title }}{% endif %}<br/> 
 {{ dateStamp|date("m/d/Y G:i") }}</a>
 {% if (pluginIsActive('uprofile')) %}<a href="{{ author_link }}">{{ author_name }}</a>{% endif %}
 {{ category }}
 {% if (flags.canEditNews) %}<img src="{{ skins_url }}/images/rewrite.gif">{% endif %}<br />
</li>
<br />

---- В данном примере мы:
1. Обрезаем заголовок новости (title) по длине (15 символов)
2. Форматируем дату (параметр dateStamp)
3. Выводим профиль автора новости если плагин uprofile включен на сайте
4. Выводим изображение (rewrite.gif) если посетитель может редактировать данную новость

xnews.tpl
<div>
<ul>
{% for entry in entries %}
{{ entry }}
{% endfor %}
</ul>
</div>

---- В данном примере мы просто выводим все новости