3.5.2.1.5. Calendar
ДЕМОНСТРАЦИЯ
API DOCS

Компонент Calendar предназначен для организации и отображения событий календаря.

gui calendar 1

XML-имя компонента: calendar.

Компонент реализован для блока Web Client.

Пример описания компонента в XML-дескрипторе экрана:

<calendar id="calendar"
          captionProperty="caption"
          startDate="2016-10-01"
          endDate="2016-10-31"
          height="100%"
          width="100%"/>

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

Кнопки навигации для перелистывания календаря на одну неделю вперёд/назад по умолчанию отключены. Чтобы кнопки были видны в режиме отображения недели, используйте атрибут navigationButtonsVisible:

<calendar width="100%"
          height="100%"
          navigationButtonsVisible="true"/>
gui calendar 2

Атрибуты calendar:

  • endDate - конечная дата диапазона календаря. Значение даты должно быть указано в формате "yyyy-MM-dd" или "yyyy-MM-dd HH:mm".

  • endDateProperty - имя атрибута сущности, содержащего конечную дату события.

  • datatype - datatype для атрибутов startDate, endDate и событий календаря. Используются следующие типы данных:

    • date

    • dateTime

    • localDate

    • localDateTime

    • offsetDateTime

      dateTime установлен по умолчанию. В случае, если startDateProperty и endDateProperty установлены, тогда будет использоваться datatype этих атрибутов.

  • descriptionProperty - имя атрибута сущности, содержащего описание события.

  • isAllDayProperty - имя атрибута сущности, отвечающего за отображение события в течение всего дня.

  • startDate - начальная дата диапазона календаря. Значение даты должно быть указано в формате "yyyy-MM-dd" или "yyyy-MM-dd HH:mm".

  • startDateProperty - имя атрибута сущности, содержащего начальную дату события.

  • stylenameProperty - имя атрибута сущности, содержащего имя стиля события.

  • timeFormat - формат времени: 12H or 24H.

Использование событий календаря:

Для отображения событий в ячейках календаря их можно прямо добавлять в объект Calendar при помощи метода addEvent() или использовать интерфейс CalendarEventProvider. Пример добавления события напрямую:

@Inject
private Calendar<Date> calendar;

public void generateEvent(String caption, String description, Date start, Date end, boolean isAllDay, String stylename) {
    SimpleCalendarEvent<Date> calendarEvent = new SimpleCalendarEvent<>();
    calendarEvent.setCaption(caption);
    calendarEvent.setDescription(description);
    calendarEvent.setStart(start);
    calendarEvent.setEnd(end);
    calendarEvent.setAllDay(isAllDay);
    calendarEvent.setStyleName(stylename);
    calendar.getEventProvider().addEvent(calendarEvent);
}

Метод removeEvent() интерфейса CalendarEventProvider позволяет удалить конкретное событие по его индексу:

CalendarEventProvider eventProvider = calendar.getEventProvider();
List<CalendarEvent> events = new ArrayList<>(eventProvider.getEvents());
eventProvider.removeEvent(events.get(events.size()-1));

Метод removeAllEvents, в свою очередь, удаляет все доступные события:

CalendarEventProvider eventProvider = calendar.getEventProvider();
eventProvider.removeAllEvents();

Интерфейс CalendarEventProvider имеет две готовые реализации: ListCalendarEventProvider (создаваемый по умолчанию) и ContainerCalendarEventProvider.

ListCalendarEventProvider заполняется данными с помощью метода addEvent(), принимающего объект CalendarEvent в качестве параметра:

@Inject
private Calendar<LocalDateTime> calendar;

public void addEvents() {
    ListCalendarEventProvider listCalendarEventProvider = new ListCalendarEventProvider();
    calendar.setEventProvider(listCalendarEventProvider);
    listCalendarEventProvider.addEvent(generateEvent("Training", "Student training",
            LocalDateTime.of(2016, 10, 17, 9, 0), LocalDateTime.of(2016, 10, 17, 14, 0), false, "event-blue"));
    listCalendarEventProvider.addEvent(generateEvent("Development", "Platform development",
            LocalDateTime.of(2016, 10, 17, 15, 0), LocalDateTime.of(2016, 10, 17, 18, 0), false, "event-red"));
    listCalendarEventProvider.addEvent(generateEvent("Party", "Party with friends",
            LocalDateTime.of(2016, 10, 22, 13, 0), LocalDateTime.of(2016, 10, 22, 18, 0), false, "event-yellow"));
}

private SimpleCalendarEvent<LocalDateTime> generateEvent(String caption, String description, LocalDateTime start, LocalDateTime end, Boolean isAllDay, String stylename) {
    SimpleCalendarEvent<LocalDateTime> calendarEvent = new SimpleCalendarEvent<>();
    calendarEvent.setCaption(caption);
    calendarEvent.setDescription(description);
    calendarEvent.setStart(start);
    calendarEvent.setEnd(end);
    calendarEvent.setAllDay(isAllDay);
    calendarEvent.setStyleName(stylename);
    return calendarEvent;
}

ContainerCalendarEventProvider получает данные напрямую из атрибутов сущности. Чтобы ContainerCalendarEventProvider мог использовать сущность, она должна иметь как минимум следующие атрибуты: дата начала события, дата окончания события (один из типов datatype) и заголовок события (тип String).

В следующем примере мы предположим, что сущность в источнике данных имеет все необходимые атрибуты: eventCaption, eventDescription, eventStartDate, eventEndDate, eventStylename, и укажем их имена в качестве значений атрибутов calendar:

<calendar id="calendar"
          dataContainer="calendarEventsDc"
          width="100%"
          height="100%"
          startDate="2016-10-01"
          endDate="2016-10-31"
          captionProperty="eventCaption"
          descriptionProperty="eventDescription"
          startDateProperty="eventStartDate"
          endDateProperty="eventEndDate"
          stylenameProperty="eventStylename"/>

Для пользовательского взаимодействия с элементами Calendar, такими как подписи даты и номера недель, выбор диапазона даты/времени, перетаскивание событий и изменение их размера, могут быть заданы различные слушатели. Слушатели также используются для кнопок навигации, листающих диапазон календаря вперёд и назад. Ниже приведён список слушателей по умолчанию:

  • addDateClickListener(CalendarDateClickListener listener); - добавляет слушатель кликов по дате.

    calendar.addDateClickListener(
        calendarDateClickEvent ->
                notifications.create()
                        .withCaption(String.format("Date clicked: %s", calendarDateClickEvent.getDate().toString()))
                        .show());

  • addWeekClickListener() - добавляет слушатель кликов по номеру недели.

  • addEventClickListener() - добавляет слушатель кликов по событию календаря.

  • addEventResizeListener() - добавляет слушатель изменения размеров события календаря.

  • addEventMoveListener() - добавляет слушатель перетаскивания события.

  • addForwardClickListener() - добавляет слушатель перелистывания календаря вперёд во времени.

  • addBackwardClickListener() - добавляет слушатель перелистывания календаря назад во времени.

  • addRangeSelectListener() - добавляет слушатель выбора диапазона календаря.

Событиям календаря можно задавать стили с помощью CSS. Для настройки стиля задайте имя стиля и его параметры в файле .scss. Пример настройки цвета фона события:

.v-calendar-event.event-green {
  background-color: #c8f4c9;
  color: #00e026;
}

Затем вызовите метод setStyleName для нужного события:

calendarEvent.setStyleName("event-green");

В результате, цвет фона события стал зелёным:

gui calendar 3

Для компонента Calendar можно изменить названия дней недели и месяцев по умолчанию, используя методы setDayNames() и setMonthNames():

Map<DayOfWeek, String> days = new HashMap<>(7);
days.put(DayOfWeek.MONDAY,"Heavens and earth");
days.put(DayOfWeek.TUESDAY,"Sky");
days.put(DayOfWeek.WEDNESDAY,"Dry land");
days.put(DayOfWeek.THURSDAY,"Stars");
days.put(DayOfWeek.FRIDAY,"Fish and birds");
days.put(DayOfWeek.SATURDAY,"Animals and man");
days.put(DayOfWeek.SUNDAY,"Rest");
calendar.setDayNames(days);
Атрибуты calendar

caption - captionAsHtml - captionProperty - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - datatype - description - descriptionAsHtml - descriptionProperty - endDateProperty - endDate - box.expandRatio - height - htmlSanitizerEnabled - icon - id - isAllDayProperty - rowspan - startDate - startDateProperty - stylename - stylenameProperty - timeFormat - visible - width

API

addEvent - removeAllEvents - removeEvent - setEventProvider - setDayNames

Слушатели calendar

CalendarBackwardClickListener - CalendarDateClickListener - CalendarEventClickListener - CalendarEventMoveListener - CalendarEventResizeListener - CalendarForwardClickListener - CalendarRangeSelectListener - CalendarWeekClickListener