fullCalendar - календарь с большими возможностями

• Основные возможности
• Управление календарями
• Уведомления
• Создание и изменение событий
• Личные события
• Уведомление
• Повторяющиеся события
• Удаление событий
• Перетаскиваемые события
• Список событий
• Права на операции с событиями
• События javascript
• Серверные события MODX
• Системные настройки
• Ссылки

Этот календарь основан на той же javascript-библиотеке, что и myCalendar, но имеет более широкие возможности.

Основные возможности

• Неограниченное количество календарей. Настройка и управление календарями находится в меню "Приложения".
• Настраиваемое уведомление о наступающем событии на почту и на сайте.
• Повторяющиеся события.
• Личные события, просмотр которых другим пользователям можно отключить.
• Пользовательские события.

Управление календарями

Для того, чтобы вывести события на сайте, нужно сначала создать календарь. Делается это в админке в меню Приложения->fullCalendar.
Тут же можно указать ряд настроек: цвет текста, цвет события, класс календаря.

Для Google календаря отмечаем соответствующий чекбокс и вводим название календаря, которое нужно получить в кабинете разработчиков Google. Как это сделать описано тут. Не забываем при этом про системную настройку, в которой указываем ключ Google Calendar API Key.

После того как календарь создан, можно вызывать сниппет. В параметре calendars через запятую указываем id календарей, события которых нужно вывести в календаре на сайте

// Выводить события календаря с id = 1 
[[!fullCalendar? &calendars=`1`]]

В календаре можно показывать события как одного календаря-объекта, так и нескольких. Для этого в параметре calendars через запятую нужно указать id необходимых календарей-объектов, как обычных так и гугл календарей. Соответственно, при создании события в диалоге можно выбрать календарь-объект, для которого создаётся данное событие.

Также возможно вообще не указывать календарь-объект при вызове сниппета, а использовать для подгрузки событий плагин, в котором определять свои события, не привязанные к календарю-объекту. Например, в нём можно формировать события из ресурсов. Правда в этом режиме будет не доступно редактирование событий.

На странице сниппет fullCalendar можно вызывать несколько раз. В этом случае каждому такому вызову нужно давать уникальное название, которое указывается в параметре instance. Для одного календаря instance можно не указывать.

[[!fullCalendar? &instance=`calendar1` &calendars=`1`]]
[[!fullCalendar? &instance=`calendar2` &calendars=`2,3`]]

Уведомления

Функционал уведомлений состоит из 2 частей: онлайн уведомления и уведомления по почте. За онлайн уведомления отвечает плагин. Поэтому, на какой бы страничке сайта вы не находились, плагин сообщит о наступлении события всплывающим окошком, а также продублирует уведомление на почту по следующей логике:

• — если у события есть автор, то уведомляем его,
• — если автора нет (аноним), то уведомляем текущего авторизованного пользователя,
• — если текущий пользователь не авторизован, то отбой.

Для управления уведомлениями есть 2 системные настройки:

• Онлайн-уведомления — включает/отключает уведомление на сайте.
• Уведомления по почте — включает/отключает уведомление по почте.

Такие события имеют css-класс notified-event для дополнительной настройки. В календаре они помечаются иконкой будильника (см. картинку ниже).

Есть еще скрипт для cron'а, который можно запускать по расписанию. Находится он в папке core/components/fullcalendar/cron/notify.php. Сейчас он работает, чтобы оповещать о событиях, которые произойдут в текущий день. Запускать его можно в полночь. Алгоритм можно прописать любой. Думаю, программисту это не составит труда.

Создание и изменение событий

Создать событие можно 5-ю способами:

• кликнуть на ячейке календаря;
• выделить диапазон ячеек;
• кликнуть на кнопку + в шапке календаря (если выведена);
• кликнуть на кнопку создания события, выведенную сниппетом fcCreateEvent.
• перетащить HTML элемент события в календарь (если используются внешние события).

Откроется диалог создания события.

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

Если у текущего календаря указано несколько календарей-объектов в параметре calendars, то в диалоге можно выбрать, к какому календарю-объекту будет относится создаваемое событие. Если нужно выделить событие другим цветом, то выбрать его можно кликнув на квадрат справа от заголовка. Если цвет не указать, то событие будет окрашено в цвет, указанный у календаря-объекта.

Личные события

Если пользователь авторизован, то он может пометить данное событие как личное. Такие события при вызове календаря с параметром showPrivate=`0` посторонним пользователям отображаться не будут. Но даже если разрешить выводить в календаре личные сообщения (showPrivate=`1`), то редактировать их сможет только сам автор и админ, авторизованный в бэкэнде. Для неавторизованных пользователей чекбокс "Личное" недоступен. Таким образом, для разных пользователей в одном и том же календаре будут отображаться разные события.

Таким событиям добавляется класс private-event.

Уведомление

При необходимости можно включить режим уведомления и указать за сколько нужно это уведомление выполнить. Тут надо отметить, что уведомление сработает, если пользователь находится на сайте вне зависимости от того, на какой странице он находится (при условии, что уведомления включены). Чтобы уведомления работали и для пользователей вне сайта, нужно самостоятельно настроить скрипт для cron, описанный выше.

Повторяющиеся события

Если событие должно повторяться с определённой периодичностью, то нужно отметить соответствующий чекбокс и выбрать нужный период повторения. Доступные варианты — повтор каждый день, каждую неделю, каждый месяц, каждый год. Также можно указать предел, после которого событие повторяться не будет. Отличить повторяющиеся события от обычных можно по значку цикла.

Повторяющиеся события также имеют свой класс repeated-event, который можно менять в своем файле стилей.

Удаление событий

Удалить событие можно двумя способами. Первый способ - это нажать крестик в верхнем правом углу события. Удаляется оно после подтверждения. Второй способ - нажать кнопку "Удалить" в диалоге редактирования события.

Перетаскиваемые события

Перетаскиваемые (drag-n-drop) события представляют собой HTML блоки, которые можно перетаскивать в календарь. При этом в календаре создаются соответствующие события. Подробное описание можно найти тут.

Список событий

События можно выводить отдельным списком. Выводить события можно или на конкретную дату, или ограничить периодом. За это отвечает отдельный сниппет fcGetEvents. Списков на странице можно выводить сколько угодно. Если редактирование в списке разрешено (readOnly=`0`), то события можно изменять и удалять. Сами списки обновляемые. Т.е. если событие добавлено кнопкой "Добавить событие" или в календаре, который находится на этой же странице, то оно появится и в списке. Подробнее можно прочитать в документации.

Права на операции с событиями

Чтобы иметь возможность создавать, изменять и удалять события, календарь должен быть в режиме редактирования. Для этого параметр readOnly должен быть выставлен в 0. Также можно запретить незарегистрированным пользователям любые операции с событиями кроме просмотра. Для этого нужно указать параметр allowGuestEdit=`0`.

События javascript

В дополнении fullCalandar есть 8 яваскрипт событий, которые отвечают за интерактив:

• fc_event_saved
• fc_event_removed
• fc_event_click
• fc_event_resize
• fc_event_receive_error
• fc_event_receive_success
• fc_event_notify
• fc_event_render
• fc_event_after_render
• fc_calendar_after_render

$(document).on('fc_event_saved', function(event, object) {
    # object - это объект события календаря
    alert('Событие ' + object.title + ' сохранено.');
});

Событие fc_event_click срабатывает при клике на событие календаря. В обработчике этого яваскрипт события можно переопределить поведение календаря. Например, заменить стандартный диалог редактирования на свой или вообще его отменить.

$(document).on('fc_event_click', function(e, event, view) {
    # event - это объект события календаря
    console.log(event);
    // Отмена стандартного диалога
    event.preventClick = true;
    // api для собственной реализации редактирования события
});

Событие fc_event_resize срабатывает при ресайзе события. В обработчике можно отменить это действие.

$(document).on('fc_event_resize', function(e, event, delta) {
    # event - это объект события календаря, delta - объект 
    // Отмена стандартного поведения
    event.preventResize = true;
});

События fc_event_receive_error и fc_event_receive_success относятся к перетаскиваемым событиям. Первое срабатывает в случае ошибки при перетаскивании. Второе — в случае успешного результата. Кстати, добавление можно отменить:

$(document).on('fc_event_receive_success', function (e, event) {
    # e - javascript event, event - это объект события календаря
    $('#'+event.instance).fullCalendar('removeEvents', event._id); // Удаляем событие только из разметки (его ещё нет в базе)
    e.stopImmediatePropagation(); // Отменяем выполнение других javascript событий
    alert('По вторникам добавлять события нельзя.');
});

А вот пример, как можно вывести диалог при дропе события на календарь:

<script>
    $(document).on('fc_event_receive_success', function (e, event) {
        // e - javascript event, event - это объект события календаря
        fullCalendar.openDialog(event).done(function(event){ console.log(event); }).fail(function(error){ alert(error); });
    });
</script>

Диалог вызывается методом opeDialog() объекта fullCalendar. Причём возвращает он промис (promise). Поэтому у него доступны 2 метода:

• done() — регистрирует функцию, которая выполнится в случае успеха. В нём доступен javascript объект события.
• fail() — регистрирует функцию, которая будет выполнена в случае ошибки от сервера или при нажатии кнопки "Закрыть" диалога события.

Событие fc_event_notify срабатывает, когда есть уведомление. В обработчике можно изменить полученное уведомление или вообще отменить его вывод.

Событие fc_event_render пригодится, если нужно изменить процесс отображения через jQuery метод css(). В обработчик передаются 3 агрумента - event, element и view. Event — это объект событие календаря. Element — это jQuery объект, который используется для отображения события в календаре. View — это объект текущего вида.

Событие fc_event_after_render срабатывает сразу после того, как событие отображено в календаре. Это событие можно использовать для управления всплывающей подсказкой qTip2. Можно переинициализировать подсказки со своими настройками.

<script>
    $(document).on('fc_event_after_render', function (jsEvent, event, element, view) {
        // Переопределение подсказки
        element.qtip({
            overwrite: true,
            content: {
                title: event.calendarName,
                text: event.description
            },
            position: {
                my: 'bottom center',
                at: 'top center',
                target: element
            },
            show: {
                delay:200,
                target: element,
                solo: true
            },
            style: {
                classes: 'qtip-bootstrap'
            }
        });
</script>

Можно переопределить только определённые свойства подсказки

<script>
    $(document).on('fc_event_after_render', function (jsEvent, event, element, view) {
        // Переопределение заголовка подсказки    
        element.qtip('option', 'content.title', 'Новый заголовок');
        // Переопределение текста подсказки    
        element.qtip('option', 'content.text', 'Новый текст');
    });
</script>

Событие fc_calendar_after_render срабатывает, когда все события отрендерены. В обработчике доступны агрументы instance и view.

Использовать эти методы не обязательно. Они пригодятся, если нужно выполнить дополнительные действия.

Серверные события MODX

fullCalendar добавляет события для плагинов MODX, благодаря которым открываются большие возможности по управлению событиями календаря:

• fcOnGetEvent — срабатывает при открытии диалога при клике на событие. Можно переопределить значения полей события.
• fcOnGetEventList — срабатывает после формирования списка событий. Даёт возможность отредактировать текущий список событый или сформировать новый список пользовательских событий перед выводом в календарь.
• fcOnGetNotifications — срабатывает при проверке событий, о который нужно уведомить. Позволяет изменить или заново сформировать уведомления.
• fcOnSaveEvent — срабатывает непосредственно перед сохранением события календаря. Позволяет отменить сохранение.
• fcOnRemoveEvent — срабатывает перед удалением события календаря. Возможно отменить удаление.

Примеры этих событий в плагинах можно посмотреть в описании событий.

Системные настройки

Ссылки

• Демо.
• Сниппет fullCalendar.
• Сниппет fcGetEvents.
• Сниппет fcCreateEvent.
• Перетаскиваемые события.
• Списки событий.
• События MODX.