# =========================================================================== #
# NG CMS // Плагины // Календарь                                              #
# =========================================================================== #

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

Плагин может работать в двух режимах:
* Автоматический запуск [старый вариант] - код плагина и генерация календаря
  происходит каждый раз при генерации страницы сайта
* TWIG запуск - генерация календаря происходит через вызов TWIG функции
  из шаблона сайта. В данном режиме вы можете на одной странице отобразить
  несколько независимых календарей со своей собственной информацией и включать
  его только при необходимости. Это позволит немного уменьшить нагрузку.

[[ Есть возможность "переключать" календарь без обновления страницы, см. ниже ]]


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

* currentMonth	- массив с данными о текущем выбранном месяце
  * name		- название месяца
  * link		- ссылка на страницу сайта с отображением новостей за данный месяц
* currentEntry	- данные о текущем запуске плагина
  * month		- номер месяца
  * year		- год
  * template	- используемый шаблон
  * categories	- список категорий, по которым генерируется календарь
* prevMonth		- массив с данными о "предыдущем" месяце
  * link		- ссылка на страницу сайта с отображением новостей за предыдущий месяц
* nextMonth		- массив с данными о "следующем" месяце
  * link		- ссылка на страницу сайта с отображением новостей за следующий месяц

* flags			- массив с флагами
  * havePrevMonth	- признак возможности просмотра "предыдущего" месяца
  * haveNextMonth	- признак возможности просмотра "следующего" месяца
  * ajax			- признак того, что шаблон генерируется через AJAX вызов

* weekdays		- массив с короткими именами дней недели [от 0 (воскресенье) до 6 (Пятница)]
* weeks			- основной массив с понедельным календарём.
  * 1			- первая неделя
    * 1			- первый день недели
      * dayNo		- календарный номер дня [[ если не заполнен, то по данному дню недели нет календарного дня ]]
      			  	  к примеру, если месяц начинается со среды, то за понедельник-вторник данных не будет
      * countNews	- кол-во новостей за данный день
      * className	- имя CSS класса, возможные варианты: "calendar_class_weekday", "calendar_class_weekend",
      				  "calendar_class_today_weekday", "calendar_class_today_weekend"
      * link		- ссылка на страницу сайта с отображением новостей за заданный день
      * isToday		- ФЛАГ: true, если это _сегодняшний_ день
      * isWeekDay 	- ФЛАГ: true, если это рабочий день (ПН-ПТ)
      * isWeekEnd	- ФЛАГ: true, если это выходной (СБ-ВС)

Также доступны глобальные переменные:
* tpl_url	- URL шаблонов сайта
* lang		- массив с языковыми переменными


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

Пример (для TWIG шаблона):
{{ callPlugin('calendar.show', {'cache': 60 }) }}

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

Доступные переменные (передаются в качестве мессива параметров после имени 'calendar.show':
* year		- год
* month		- месяц
* offset	- "смещение" относительно указанного года и месяца.
			  может принимать значения "prev" (показать предыдущий) и "next"
			  (показать следующий) месяц
* template	- имя шаблона
* category	- список категорий по которым генерируется календарь (если не указывать, то из всех)
* cache		- срок жизни кеша (по умолчанию = 0)


================================================================================
Переключение страниц календаря без обновления страницы сайта.
================================================================================

Данная возможность доступна благодаря наличию AJAX/RPC функции plugin.calendar.show
Функция принимает на вход следующие параметры:
* year		- год
* month		- месяц
* offset	- "смещение" относительно указанного года и месяца.
			  может принимать значения "prev" (показать предыдущий) и "next"
			  (показать следующий) месяц


Пример JScript'а для переключения между месяцами:

function ng_calendar_walk(month, year, offset) {
	// Вызов AJAX/RPC метода 'plugin.calendar.show'
	$.post('/engine/rpc.php', { json : 1, methodName : 'plugin.calendar.show', rndval: new Date().getTime(), params : json_encode({ 'year' : year, 'offset' : offset, 'month' : month }) }, function(data) {
		// В качестве результата нам передаётся JSON массив данных.
		// Ключевые поля:
		// * status - 1 (успешное выполнение), 0 - ошибка
		// * data - блок данных с сгенерированным календарём
		try {
			resTX = eval('('+data+')');
		} catch (err) { alert('Error parsing JSON output. Result: '+linkTX.response); }
		if (!resTX['status']) {
			ngNotifyWindow('Error ['+resTX['errorCode']+']: '+resTX['errorText'], 'ERROR');
		} else {
			// Заменяем содержимое DIV с ID = "ngCalendarDIV" новыми данными
			$('#ngCalendarDiv').html(resTX['data']);
		}
	}, "text").error(function() { ngHideLoading(); ngNotifyWindow('HTTP error during request', 'ERROR'); });

}