You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

components-calendar.asciidoc 41KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185
  1. ---
  2. title: Calendar
  3. order: 30
  4. layout: page
  5. ---
  6. [[components.calendar]]
  7. = [classname]#Calendar#
  8. ifdef::web[]
  9. [.sampler]
  10. image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/dates/dates-calendar"]
  11. endif::web[]
  12. The [classname]#Calendar# component allows organizing and displaying calendar
  13. events. The main features of the calendar include:
  14. * Monthly, weekly, and daily views
  15. * Two types of events: all-day events and events with a time range
  16. * Add events directly or with an event provider
  17. * Control the range of the visible dates
  18. * Selecting and editing date or time range by dragging
  19. * Drag and drop events to calendar
  20. * Support for localization and timezones
  21. User interaction with the calendar elements, such as date and week captions as
  22. well as events, is handled with event listeners. Also date/time range
  23. selections, event dragging, and event resizing can be listened by the server.
  24. The weekly view has navigation buttons to navigate forward and backward in time.
  25. These actions are also listened by the server. Custom navigation can be
  26. implemented using event
  27. ifdef::web[handlers, as described in <<components.calendar.customizing>>.]
  28. ifndef::web[handlers.]
  29. The data source of a calendar can be practically anything, as its events are
  30. queried dynamically by the component. You can bind the calendar to any data source by implementing an __event provider__.
  31. The [classname]#Calendar# has undefined size by default and you usually want to
  32. give it a fixed or relative size, for example as follows.
  33. [source, java]
  34. ----
  35. Calendar cal = new Calendar("My Calendar");
  36. cal.setWidth("600px");
  37. cal.setHeight("300px");
  38. ----
  39. After creating the calendar, you need to set a time range for it, which also
  40. controls the view mode, and set up the data source for calendar events.
  41. [[components.calendar.daterange]]
  42. == Date Range and View Mode
  43. The Vaadin Calendar has two types of views that are shown depending on the date
  44. range of the calendar. The __weekly view__ displays a week by default. It can
  45. show anything between one to seven days a week, and is also used as a single-day
  46. view. The view mode is determined from the __date range__ of the calendar,
  47. defined by a start and an end date. Calendar will be shown in a __monthly view__
  48. when the date range is over than one week (seven days) long. The date range is
  49. always calculated in an accuracy of one millisecond.
  50. [[figure.components.calendar.daterange.monthly]]
  51. .Monthly view with All-Day and Normal Events
  52. image::img/calendar-monthly.png[width=60%, scaledwidth=100%]
  53. The monthly view, shown in <<figure.components.calendar.daterange.monthly>>, can
  54. easily be used to control all types of events, but it is best suited for events
  55. that last for one or more days. You can drag the events to move them. In the
  56. figure, you can see two longer events that are highlighted with a blue and green
  57. background color. Other markings are shorter day events that last less than a 24
  58. hours. These events can not be moved by dragging in the monthly view.
  59. [[figure.components.calendar.daterange.weekly]]
  60. .Weekly View
  61. image::img/calendar-weekly.png[width=60%, scaledwidth=100%]
  62. In <<figure.components.calendar.daterange.weekly>>, you can see four normal day
  63. events and also all-day events at the top of the time line grid.
  64. In the following, we set the calendar to show only one day, which is the current
  65. day.
  66. [source, java]
  67. ----
  68. cal.setStartDate(new Date());
  69. cal.setEndDate(new Date());
  70. ----
  71. Notice that although the range we set above is actually zero time long, the
  72. calendar still renders the time from 00:00 to 23:59. This is normal, as the
  73. Vaadin Calendar is guaranteed to render at least the date range provided, but
  74. may expand it. This behaviour is important to notice when we implement our own
  75. event providers.
  76. [[components.calendar.events]]
  77. == Calendar Events
  78. All occurrences in a calendar are represented as __events__. You have three ways
  79. to manage the calendar events:
  80. * Add events directly to the [classname]#Calendar# object using the [methodname]#addEvent()#
  81. * Use the __event provider__ mechanism
  82. You can add events with [methodname]#addEvent()# and remove them with the
  83. [methodname]#removeEvent()#. These methods will use the underlying event
  84. provider to write the modifications to the data source.
  85. [[components.calendar.events.types]]
  86. === Event Interfaces and Providers
  87. Events are handled though the [interfacename]#CalendarEvent# interface. The
  88. concrete class of the event depends on the specific
  89. [classname]#CalendarEventProvider# used in the calendar.
  90. By default, [classname]#Calendar# uses a [classname]#BasicEventProvider# to
  91. provide events, which uses [classname]#BasicEvent# instances.
  92. Calendar does not depend on any particular data source implementation. Events
  93. are queried by the [classname]#Calendar# from the provider that just has to
  94. implement the [interfacename]#CalendarEventProvider# interface. It is up to the
  95. event provider that [classname]#Calendar# gets the correct events.
  96. ifdef::vaadin7[]
  97. You can bind any Vaadin [classname]#Container# to a calendar, in which case a
  98. [classname]#ContainerEventProvider# is used transparently. The container must be
  99. ordered by start date and time of the events. See
  100. <<dummy/../../../framework/datamodel/datamodel-container#datamodel.container,"Collecting
  101. Items in Containers">> for basic information about containers.
  102. endif::vaadin7[]
  103. [[components.calendar.events.details]]
  104. === Event Types
  105. A calendar event requires a start time and an end time. These are the only
  106. mandatory properties. In addition, an event can also be set as an all-day event
  107. by setting the [literal]#++all-day++# property of the event. You can also set
  108. the [literal]#++description++# of an event, which is displayed as a tooltip in
  109. the user interface.
  110. If the [literal]#++all-day++# field of the event is [literal]#++true++#, then
  111. the event is always rendered as an all-day event. In the monthly view, this
  112. means that no start time is displayed in the user interface and the event has an
  113. colored background. In the weekly view, all-day events are displayed in the
  114. upper part of the screen, and rendered similarly to the monthly view. In
  115. addition, when the time range of an event is 24 hours or longer, it is rendered
  116. as an all-day event in the monthly view.
  117. When the time range of an event is equal or less than 24 hours, with the
  118. accuracy of one millisecond, the event is considered as a normal day event.
  119. Normal event has a start and end times that may be on different days.
  120. [[components.calendar.events.basic]]
  121. === Basic Events
  122. The easiest way to add and manage events in a calendar is to use the __basic
  123. event__ management API. Calendar uses by default a
  124. [classname]#BasicEventProvider#, which keeps the events in memory in an internal
  125. reprensetation.
  126. For example, the following adds a two-hour event starting from the current time.
  127. The standard Java [classname]#GregorianCalendar# provides various ways to
  128. manipulate date and time.
  129. [source, java]
  130. ----
  131. // Add a two-hour event
  132. GregorianCalendar start = new GregorianCalendar();
  133. GregorianCalendar end = new GregorianCalendar();
  134. end.add(java.util.Calendar.HOUR, 2);
  135. calendar.addEvent(new BasicEvent("Calendar study",
  136. "Learning how to use Vaadin Calendar",
  137. start.getTime(), end.getTime()));
  138. ----
  139. See the http://demo.vaadin.com/book-examples-vaadin7/book#calendar.monthlyview[on-line example, window="_blank"].
  140. This adds a new event that lasts for 3 hours. As the BasicEventProvider and
  141. BasicEvent implement some optional event interfaces provided by the calendar
  142. package, there is no need to refresh the calendar. Just create events, set their
  143. properties and add them to the Event Provider.
  144. ifdef::vaadin7[]
  145. [[components.calendar.container]]
  146. == Getting Events from a Container
  147. You can use any Vaadin [interfacename]#Container# that implements the
  148. [interfacename]#Indexed# interface as the data source for calendar events. The
  149. [classname]#Calendar# will listen to change events from the container as well as
  150. write changes to the container. You can attach a container to a
  151. [classname]#Calendar# with [methodname]#setContainerDataSource()#.
  152. In the following example, we bind a [classname]#BeanItemContainer# that contains
  153. built-in [classname]#BasicEvent# events to a calendar.
  154. [source, java]
  155. ----
  156. // Create the calendar
  157. Calendar calendar = new Calendar("Bound Calendar");
  158. // Use a container of built-in BasicEvents
  159. final BeanItemContainer<BasicEvent> container =
  160. new BeanItemContainer<BasicEvent>(BasicEvent.class);
  161. // Create a meeting in the container
  162. container.addBean(new BasicEvent("The Event", "Single Event",
  163. new GregorianCalendar(2012,1,14,12,00).getTime(),
  164. new GregorianCalendar(2012,1,14,14,00).getTime()));
  165. // The container must be ordered by the start time. You
  166. // have to sort the BIC every time after you have added
  167. // or modified events.
  168. container.sort(new Object[]{"start"}, new boolean[]{true});
  169. calendar.setContainerDataSource(container, "caption",
  170. "description", "start", "end", "styleName");
  171. ----
  172. See the http://demo.vaadin.com/book-examples-vaadin7/book#calendar.beanitemcontainer[on-line example, window="_blank"].
  173. The container must either use the default property IDs for event data, as
  174. defined in the [interfacename]#CalendarEvent# interface, or provide them as
  175. parameters for the [methodname]#setContainerDataSource()# method, as we did in
  176. the example above.
  177. [[components.calendar.container.sorting]]
  178. === Keeping the Container Ordered
  179. The events in the container __must__ be kept ordered by their start date/time.
  180. Failing to do so may and will result in the events not showing in the calendar
  181. properly.
  182. Ordering depends on the container. With some containers, such as
  183. [classname]#BeanItemContainer#, you have to sort the container explicitly every
  184. time after you have added or modified events, usually with the
  185. [methodname]#sort()# method, as we did in the example above. Some container,
  186. such as [classname]#JPAContainer#, keep the in container automatically order if
  187. you provide a sorting rule.
  188. For example, you could order a [classname]#JPAContainer# by the following rule,
  189. assuming that the start date/time is held in the [literal]#++startDate++#
  190. property:
  191. [source, java]
  192. ----
  193. // The container must be ordered by start date. For JPAContainer
  194. // we can just set up sorting once and it will stay ordered.
  195. container.sort(new String[]{"startDate"}, new boolean[]{true});
  196. ----
  197. See the http://demo.vaadin.com/book-examples-vaadin7/book#calendar.jpacontainer[on-line example, window="_blank"].
  198. ifdef::web[]
  199. [[components.calendar.container.customization]]
  200. === Delegation of Event Management
  201. Setting a container as the calendar data source with
  202. [methodname]#setContainerDataSource()# automatically switches to
  203. [classname]#ContainerEventProvider#. You can manipulate the event data through
  204. the API in [classname]#Calendar# and the user can move and resize event through
  205. the user interface. The event provider delegates all such calendar operations to
  206. the container.
  207. If you add events through the [classname]#Calendar# API, notice that you may be
  208. unable to create events of the type held in the container or adding them
  209. requires some container-specific operations. In such case, you may need to
  210. customize the [methodname]#addEvent()# method.
  211. For example, [classname]#JPAContainer# requires adding new items with
  212. [methodname]#addEntity()#. You could first add the entity to the container or
  213. entity manager directly and then pass it to the [methodname]#addEvent()#. That
  214. does not, however, work if the entity class does not implement
  215. [interfacename]#CalendarEvent#. This is actually the case always if the property
  216. names differ from the ones defined in the interface. You could handle creating
  217. the underlying entity objects in the [methodname]#addEvent()# as follows:
  218. [source, java]
  219. ----
  220. // Create a JPAContainer
  221. final JPAContainer<MyCalendarEvent> container =
  222. JPAContainerFactory.make(MyCalendarEvent.class,
  223. "book-examples");
  224. // Customize the event provider for adding events
  225. // as entities
  226. ContainerEventProvider cep =
  227. new ContainerEventProvider(container) {
  228. @Override
  229. public void addEvent(CalendarEvent event) {
  230. MyCalendarEvent entity = new MyCalendarEvent(
  231. event.getCaption(), event.getDescription(),
  232. event.getStart(), event.getEnd(),
  233. event.getStyleName());
  234. container.addEntity(entity);
  235. }
  236. }
  237. // Set the container as the data source
  238. calendar.setEventProvider(cep);
  239. // Now we can add events to the database through the calendar
  240. BasicEvent event = new BasicEvent("The Event", "Single Event",
  241. new GregorianCalendar(2012,1,15,12,00).getTime(),
  242. new GregorianCalendar(2012,1,15,14,00).getTime());
  243. calendar.addEvent(event);
  244. ----
  245. endif::web[]
  246. endif::vaadin7[]
  247. ifdef::web[]
  248. [[components.calendar.eventprovider]]
  249. == Implementing an Event Provider
  250. If the two simple ways of storing and managing events for a calendar are not
  251. enough, you may need to implement a custom event provider. It is the most
  252. flexible way of providing events. You need to attach the event provider to the
  253. [classname]#Calendar# using the [methodname]#setEventProvider()# method.
  254. Event queries are done by asking the event provider for all the events between
  255. two given dates. The range of these dates is guaranteed to be at least as long
  256. as the start and end dates set for the component. The component can, however,
  257. ask for a longer range to ensure correct rendering. In particular, all start
  258. dates are expanded to the start of the day, and all end dates are expanded to
  259. the end of the day.
  260. [[components.calendar.eventprovider.customevents]]
  261. === Custom Events
  262. An event provider could use the built-in [classname]#BasicEvent#, but it is
  263. usually more proper to define a custom event type that is bound directly to the
  264. data source. Custom events may be useful for some other purposes as well, such
  265. as when you need to add extra information to an event or customize how it is
  266. acquired.
  267. Custom events must implement the [interfacename]#CalendarEvent# interface or
  268. extend an existing event class. The built-in [classname]#BasicEvent# class
  269. should serve as a good example of implementing simple events. It keeps the data
  270. in member variables.
  271. [source, java]
  272. ----
  273. public class BasicEvent
  274. implements CalendarEventEditor, EventChangeNotifier {
  275. ...
  276. public String getCaption() {
  277. return caption;
  278. }
  279. public String getDescription() {
  280. return description;
  281. }
  282. public Date getEnd() {
  283. return end;
  284. }
  285. public Date getStart() {
  286. return start;
  287. }
  288. public String getStyleName() {
  289. return styleName;
  290. }
  291. public boolean isAllDay() {
  292. return isAllDay;
  293. }
  294. public void setCaption(String caption) {
  295. this.caption = caption;
  296. fireEventChange();
  297. }
  298. public void setDescription(String description) {
  299. this.description = description;
  300. fireEventChange();
  301. }
  302. public void setEnd(Date end) {
  303. this.end = end;
  304. fireEventChange();
  305. }
  306. public void setStart(Date start) {
  307. this.start = start;
  308. fireEventChange();
  309. }
  310. public void setStyleName(String styleName) {
  311. this.styleName = styleName;
  312. fireEventChange();
  313. }
  314. public void setAllDay(boolean isAllDay) {
  315. this.isAllDay = isAllDay;
  316. fireEventChange();
  317. }
  318. public void addEventChangeListener(
  319. EventChangeListener listener) {
  320. ...
  321. }
  322. public void removeListener(EventChangeListener listener) {
  323. ...
  324. }
  325. protected void fireEventChange() {...}
  326. }
  327. ----
  328. You may have noticed that there was some additional code in the
  329. [classname]#BasicEvent# that was not in the [interfacename]#CalendarEvent#
  330. interface. Namely [classname]#BasicEvent# also implements two additional
  331. interfaces:
  332. [interfacename]#CalendarEditor#:: This interface defines setters for all the fields, and is required for some of
  333. the default handlers to work.
  334. [interfacename]#EventChangeNotifier#:: This interface adds the possibility to listen for changes in the event, and
  335. enables the [classname]#Calendar# to render the changes immediately.
  336. The start time and end time are mandatory, but caption, description, and style
  337. name are not. The style name is used as a part of the CSS class name for the
  338. HTML DOM element of the event.
  339. In addition to the basic event interfaces, you can enhance the functionality of
  340. your event and event provider classes by using the [classname]#EventChange# and
  341. [classname]#EventSetChange# events. They let the [classname]#Calendar# component
  342. to know about changes in events and update itself accordingly. The
  343. [classname]#BasicEvent# and [classname]#BasicEventProvider# examples given
  344. earlier include a simple implementation of these interfaces.
  345. [[components.calendar.eventprovider.eventprovider]]
  346. === Implementing the Event Provider
  347. An event provider needs to implement the [interfacename]#CalendarEventProvider#
  348. interface. It has only one method to be implemented. Whenever the calendar is
  349. painted, [methodname]#getEvents(Date, Date)# method is called and it must return
  350. a list of events between the given start and end time.
  351. The following example implementation returns only one example event. The event
  352. starts from the current time and is five hours long.
  353. [source, java]
  354. ----
  355. public class MyEventProvider implements CalendarEventProvider{
  356. public List<Event> getEvents(Date startDate, Date endDate){
  357. List<Event> events = new ArrayList<Event>();
  358. GregorianCalendar cal = new GregorianCalendar();
  359. cal.setTime(new Date());
  360. Date start = cal.getTime();
  361. cal.add(GregorianCalendar.HOUR, 5);
  362. Date end = cal.getTime();
  363. BasicEvent event = new BasicEvent();
  364. event.setCaption("My Event");
  365. event.setDescription("My Event Description");
  366. event.setStart(start);
  367. event.setEnd(end);
  368. events.add(event);
  369. return events;
  370. }
  371. }
  372. ----
  373. It is important to notice that the [classname]#Calendar# may query for dates
  374. beyond the range defined by start date and end date. Particularly, it may expand
  375. the date range to make sure the user interface is rendered correctly.
  376. endif::web[]
  377. ifdef::web[]
  378. [[components.calendar.appearance]]
  379. == Styling a Calendar
  380. Configuring the appearance of the Vaadin Calendar component is one of the basic
  381. tasks. At the least, you need to consider its sizing in your user interface. You
  382. also quite probably want to use some color or colors for events.
  383. [[components.calendar.appearance.sizing]]
  384. === Sizing
  385. The Calendar supports component sizing as usual for defined (fixed or relative)
  386. sizes. When using an undefined size for the calendar, all the sizes come from
  387. CSS. In addition, when the height is undefined, a scrollbar is displayed in the
  388. weekly view to better fit the cells to the user interface.
  389. Below is a list of style rules that define the size of a Calendar with undefined
  390. size (these are the defaults):
  391. [source, css]
  392. ----
  393. .v-calendar-month-sizedheight .v-calendar-month-day {
  394. height: 100px;
  395. }
  396. .v-calendar-month-sizedwidth .v-calendar-month-day {
  397. width: 100px;
  398. }
  399. .v-calendar-header-month-Hsized .v-calendar-header-day {
  400. width: 101px;
  401. }
  402. /* for IE */
  403. .v-ie6 .v-calendar-header-month-Hsized .v-calendar-header-day {
  404. width: 104px;
  405. }
  406. /* for others */
  407. .v-calendar-header-month-Hsized td:first-child {
  408. padding-left: 21px;
  409. }
  410. .v-calendar-header-day-Hsized {
  411. width: 200px;
  412. }
  413. .v-calendar-week-numbers-Vsized .v-calendar-week-number {
  414. height: 100px;
  415. line-height: 100px;
  416. }
  417. .v-calendar-week-wrapper-Vsized {
  418. height: 400px;
  419. overflow-x: hidden !important;
  420. }
  421. .v-calendar-times-Vsized .v-calendar-time {
  422. height: 38px;
  423. }
  424. .v-calendar-times-Hsized .v-calendar-time {
  425. width: 42px;
  426. }
  427. .v-calendar-day-times-Vsized .v-slot,.v-calendar-day-times-Vsized .v-slot-even {
  428. height: 18px;
  429. }
  430. .v-calendar-day-times-Hsized, .v-calendar-day-times-Hsized .v-slot,.v-calendar-day-times-Hsized .v-slot-even {
  431. width: 200px;
  432. }
  433. ----
  434. [[components.calendar.appearance.event-style]]
  435. === Event Style
  436. Events can be styled with CSS by setting them a __style name suffix__. The
  437. suffix is retrieved with the [methodname]#getStyleName()# method in
  438. [interfacename]#CalendarEvent#. If you use [classname]#BasicEvent# events, you
  439. can set the suffix with [methodname]#setStyleName()#.
  440. [source, java]
  441. ----
  442. BasicEvent event = new BasicEvent("Wednesday Wonder", ... );
  443. event.setStyleName("mycolor");
  444. calendar.addEvent(event);
  445. ----
  446. Suffix [literal]#++mycolor++# would create
  447. [literal]#++v-calendar-event-mycolor++# class for regular events and
  448. [literal]#++v-calendar-event-mycolor-add-day++# for all-day events. You could
  449. style the events with the following rules:
  450. [source, css]
  451. ----
  452. .v-calendar .v-calendar-event-mycolor {}
  453. .v-calendar .v-calendar-event-mycolor-all-day {}
  454. .v-calendar .v-calendar-event-mycolor .v-calendar-event-caption {}
  455. .v-calendar .v-calendar-event-mycolor .v-calendar-event-content {}
  456. ----
  457. endif::web[]
  458. ifdef::web[]
  459. [[components.calendar.visible-hours-days]]
  460. == Visible Hours and Days
  461. As we saw in <<components.calendar.daterange>>, you can set the range of dates
  462. that are shown by the Calendar. But what if you wanted to show the entire month
  463. but hide the weekends? Or show only hours from 8 to 16 in the weekly view? The
  464. [methodname]#setVisibleDays()# and [methodname]#setVisibleHours()# methods allow
  465. you to do that.
  466. [source, java]
  467. ----
  468. calendar.setVisibleDays(1,5); // Monday to Friday
  469. calendar.setVisibleHours(0,15); // Midnight until 4 pm
  470. ----
  471. After the above settings, only weekdays from Monday to Friday would be shown.
  472. And when the calendar is in the weekly view, only the time range from 00:00 to
  473. 16:00 would be shown.
  474. Note that the excluded times are never shown so you should take care when
  475. setting the date range. If the date range contains only dates / times that are
  476. excluded, nothing will be displayed. Also note that even if a date is not
  477. rendered because these settings, the event provider may still be queried for
  478. events for that date.
  479. endif::web[]
  480. ifdef::web[]
  481. [[components.calendar.drag-and-drop]]
  482. == Drag and Drop
  483. Vaadin Calendar can act as a drop target for drag and drop, described in
  484. <<dummy/../../../framework/advanced/advanced-dragndrop#advanced.dragndrop,"Drag
  485. and Drop">>. With the functionality, the user could drag events, for example,
  486. from a table to a calendar.
  487. To support dropping, a [classname]#Calendar# must have a drop handler. When the
  488. drop handler is set, the days in the monthly view and the time slots in the
  489. weekly view can receive drops. Other locations, such as day names in the weekly
  490. view, can not currently receive drops.
  491. Calendar uses its own implementation of [interfacename]#TargetDetails#:
  492. [classname]#CalendarTargetdetails#. It holds information about the the drop
  493. location, which in the context of [classname]#Calendar# means the date and time.
  494. The drop target location can be retrieved via the [methodname]#getDropTime()#
  495. method. If the drop is done in the monthly view, the returned date does not have
  496. exact time information. If the drop happened in the weekly view, the returned
  497. date also contains the start time of the slot.
  498. Below is a short example of creating a drop handler and using the drop
  499. information to create a new event:
  500. [source, java]
  501. ----
  502. private Calendar createDDCalendar() {
  503. Calendar calendar = new Calendar();
  504. calendar.setDropHandler(new DropHandler() {
  505. public void drop(DragAndDropEvent event) {
  506. CalendarTargetDetails details =
  507. (CalendarTargetDetails) event.getTargetDetails();
  508. TableTransferable transferable =
  509. (TableTransferable) event.getTransferable();
  510. createEvent(details, transferable);
  511. removeTableRow(transferable);
  512. }
  513. public AcceptCriterion getAcceptCriterion() {
  514. return AcceptAll.get();
  515. }
  516. });
  517. return calendar;
  518. }
  519. protected void createEvent(CalendarTargetDetails details,
  520. TableTransferable transferable) {
  521. Date dropTime = details.getDropTime();
  522. java.util.Calendar timeCalendar = details.getTargetCalendar()
  523. .getInternalCalendar();
  524. timeCalendar.setTime(dropTime);
  525. timeCalendar.add(java.util.Calendar.MINUTE, 120);
  526. Date endTime = timeCalendar.getTime();
  527. Item draggedItem = transferable.getSourceComponent().
  528. getItem(transferable.getItemId());
  529. String eventType = (String)draggedItem.
  530. getItemProperty("type").getValue();
  531. String eventDescription = "Attending: "
  532. + getParticipantString(
  533. (String[]) draggedItem.
  534. getItemProperty("participants").getValue());
  535. BasicEvent newEvent = new BasicEvent();
  536. newEvent.setAllDay(!details.hasDropTime());
  537. newEvent.setCaption(eventType);
  538. newEvent.setDescription(eventDescription);
  539. newEvent.setStart(dropTime);
  540. newEvent.setEnd(endTime);
  541. BasicEventProvider ep = (BasicEventProvider) details
  542. .getTargetCalendar().getEventProvider();
  543. ep.addEvent(newEvent);
  544. }
  545. ----
  546. endif::web[]
  547. ifdef::web[]
  548. [[components.calendar.contextmenu]]
  549. == Using the Context Menu
  550. Vaadin Calendar allows the use of context menu (mouse right-click) to manage
  551. events. As in other context menus in Vaadin, the menu items are handled in
  552. Vaadin as __actions__ by an __action handler__. To enable a context menu, you
  553. have to implement a Vaadin [interfacename]#Action.Handler# and add it to the
  554. calendar with [methodname]#addActionHandler()#.
  555. An action handler must implement two methods: [methodname]#getActions()# and
  556. [methodname]#handleAction()#. The [methodname]#getActions()# is called for each
  557. day displayed in the calendar view. It should return a list of allowed actions
  558. for that day, that is, the items of the context menu. The [parameter]#target#
  559. parameter is the context of the click - a [classname]#CalendarDateRange# that
  560. spans over the day. The [parameter]#sender# is the [classname]#Calendar# object.
  561. The [methodname]#handleActions()# receives the target context in the
  562. [parameter]#target#. If the context menu was opened on an event, the target is
  563. the [interfacename]#Event# object, otherwise it is a
  564. [classname]#CalendarDateRange#.
  565. endif::web[]
  566. ifdef::web[]
  567. [[components.calendar.localization]]
  568. == Localization and Formatting
  569. [[components.calendar.localization.locale]]
  570. === Setting the Locale and Time Zone
  571. Month and weekday names are shown in the language of the locale setting of the
  572. [classname]#Calendar#. The translations are acquired from the standard Java
  573. locale data. By default, [classname]#Calendar# uses the system default locale
  574. for its internal calendar, but you can change it with
  575. [methodname]#setLocale(Locale locale)#. Setting the locale will update also
  576. other location specific date and time settings, such as the first day of the
  577. week, time zone, and time format. However, time zone and time format can be
  578. overridden by settings in the [classname]#Calendar#.
  579. For example, the following would set the language to US English:
  580. [source, java]
  581. ----
  582. cal.setLocale(Locale.US);
  583. ----
  584. The locale defines the default time zone. You can change it with the
  585. [methodname]#setTimeZone()# method, which takes a
  586. [classname]#java.util.TimeZone# object as its parameter. Setting timezone to
  587. null will reset timezone to the locale default.
  588. For example, the following would set the Finnish time zone, which is EET
  589. [source, java]
  590. ----
  591. cal.setTimeZone(TimeZone.getTimeZone("Europe/Helsinki"));
  592. ----
  593. [[components.calendar.localization.datecaption]]
  594. === Time and Date Caption Format
  595. The time may be shown either in 24 or 12 hour format. The default format is
  596. defined by the locale, but you can change it with the
  597. [methodname]#setTimeFormat()# method. Giving a [literal]#++null++# setting will
  598. reset the time format to the locale default.
  599. [source, java]
  600. ----
  601. cal.setTimeFormat(TimeFormat.Format12H);
  602. ----
  603. You can change the format of the date captions in the week view with the
  604. [methodname]#setWeeklyCaptionFormat(String dateFormatPattern)# method. The date
  605. format pattern should follow the format of the standard Java
  606. [classname]#java.text.SimpleDateFormat# class.
  607. For example:
  608. [source, java]
  609. ----
  610. cal.setWeeklyCaptionFormat("dd-MM-yyyy");
  611. ----
  612. endif::web[]
  613. ifdef::web[]
  614. [[components.calendar.customizing]]
  615. == Customizing the Calendar
  616. In this section, we give a tutorial for how to make various basic customizations
  617. of the Vaadin Calendar. The event provider and styling was described earlier, so
  618. now we concentrate on other features of the Calendar API.
  619. [[components.calendar.customizing.overview]]
  620. === Overview of Handlers
  621. Most of the handlers related to calendar events have sensible default handlers.
  622. These are found in the [package]#com.vaadin.ui.handler# package. The default
  623. handlers and their functionalities are described below.
  624. * [classname]#BasicBackwardHandler#. Handles clicking the back-button of the weekly view so that the viewed month is changed to the previous one.
  625. * [classname]#BasicForwardHandler#. Handles clicking the forward-button of the weekly view so that the viewed month is changed to the next one.
  626. * [classname]#BasicWeekClickHandler#. Handles clicking the week numbers int the monthly view so that the viewable date range is changed to the clicked week.
  627. * [classname]#BasicDateClickHandler#. Handles clicking the dates on both the monthly view and the weekly view. Changes the viewable date range so that only the clicked day is visible.
  628. * [classname]#BasicEventMoveHandler#. Handles moving the events in both monthly view and the weekly view. Events can be moved and their start and end dates are changed correctly, but only if the event implements [classname]#CalendarEventEditor# (implemented by [classname]#BasicEvent#).
  629. * [classname]#BasicEventResizeHandler#. Handles resizing the events in the weekly view. Events can be resized and their start and end dates are changed correctly, but only if the event implements [classname]#CalendarEventEditor# (implemented by the [classname]#BasicEvent#).
  630. All of these handlers are automatically set when creating a new
  631. [classname]#Calendar#. If you wish to disable some of the default functionality,
  632. you can simply set the corresponding handler to [literal]#++null++#. This will
  633. prevent the functionality from ever appearing on the user interface. For
  634. example, if you set the [classname]#EventMoveHandler# to [literal]#++null++#,
  635. the user will be unable to move events in the browser.
  636. [[components.calendar.customizing.creating]]
  637. === Creating a Calendar
  638. Let us first create a new [classname]#Calendar# instance. Here we use our own
  639. event provider, the [classname]#MyEventProvider# described in
  640. <<components.calendar.eventprovider.eventprovider>>.
  641. [source, java]
  642. ----
  643. Calendar cal = new Calendar(new MyEventProvider());
  644. ----
  645. This initializes the Calendar. To customize the viewable date range, we must set
  646. a start and end date to it.
  647. There is only one visible event in the timeline, starting from the current time.
  648. That is what our event provider passes to the client.//TODO See the figure
  649. 3.
  650. It would be nice to also be able to control the navigation forward and backward.
  651. The default navigation is provided by the default handlers, but perhaps we want
  652. to restrict the users so they can only navigate dates in the current year. Maybe
  653. we also want to pose some other restrictions to the clicking week numbers and
  654. dates.
  655. These restrictions and other custom logic can be defined with custom handlers.
  656. You can find the handlers in the [package]#com.vaadin.addon.calendar.ui.handler#
  657. package and they can be easily extended. Note that if you don not want to extend
  658. the default handlers, you are free to implement your own. The interfaces are
  659. described in [interfacename]#CalendarComponentEvents#.
  660. endif::web[]
  661. [[components.calendar.navigation]]
  662. == Backward and Forward Navigation
  663. Vaadin Calendar has only limited built-in navigation support. The weekly view
  664. has navigation buttons in the top left and top right
  665. corners.
  666. // TODO See the figure 4.
  667. You can handle backward and forward navigation with a
  668. [interfacename]#BackwardListener# and [interfacename]#ForwardListener#.
  669. [source, java]
  670. ----
  671. cal.setHandler(new BasicBackwardHandler() {
  672. protected void setDates(BackwardEvent event,
  673. Date start, Date end) {
  674. java.util.Calendar calendar = event.getComponent()
  675. .getInternalCalendar();
  676. if (isThisYear(calendar, end)
  677. && isThisYear(calendar, start)) {
  678. super.setDates(event, start, end);
  679. }
  680. }});
  681. ----
  682. The forward navigation handler can be implemented in the same way. The example
  683. handler restricts the dates to the current year.
  684. ifdef::web[]
  685. [[components.calendar.dateclick]]
  686. == Date Click Handling
  687. By default, clicking a date either in month or week view switches to single-day
  688. view, while clicking on the date header in the day view has no effect. The date
  689. click event is handled by a [interfacename]#DateClickHandler#.
  690. The following example handles click events on the date header in the day view to
  691. zoom out to the week view. For other clicks it applies the default behavior; in
  692. the week view clicking on a day switches to the day view.
  693. [source, java]
  694. ----
  695. calendar.setHandler(new BasicDateClickHandler() {
  696. public void dateClick(DateClickEvent event) {
  697. Calendar cal = event.getComponent();
  698. // Check if the current range is already one day long
  699. long currentCalDateRange = cal.getEndDate().getTime() -
  700. cal.getStartDate().getTime();
  701. // From one-day view, zoom out to week view
  702. if (currentCalDateRange <= DateConstants.DAYINMILLIS) {
  703. // Change the date range to the current week
  704. GregorianCalendar weekstart = new GregorianCalendar();
  705. GregorianCalendar weekend = new GregorianCalendar();
  706. weekstart.setTime(event.getDate());
  707. weekend.setTime(event.getDate());
  708. weekstart.setFirstDayOfWeek(java.util.Calendar.SUNDAY);
  709. weekstart.set(java.util.Calendar.HOUR_OF_DAY, 0);
  710. weekstart.set(java.util.Calendar.DAY_OF_WEEK,
  711. java.util.Calendar.SUNDAY);
  712. weekend.set(java.util.Calendar.HOUR_OF_DAY, 23);
  713. weekend.set(java.util.Calendar.DAY_OF_WEEK,
  714. java.util.Calendar.SATURDAY);
  715. cal.setStartDate(weekstart.getTime());
  716. cal.setEndDate(weekend.getTime());
  717. Notification.show("Custom zoom to week");
  718. } else {
  719. // Default behavior, change date range to one day
  720. super.dateClick(event);
  721. }
  722. }
  723. });
  724. ----
  725. endif::web[]
  726. ifdef::web[]
  727. [[components.calendar.weekclick]]
  728. == Handling Week Clicks
  729. The monthly view displays week numbers for each week row on the left side of the
  730. date grid. The week number are clickable and you can handle the click events by
  731. setting a [interfacename]#WeekClickHandler# for the [classname]#Calendar#
  732. object. The default handler changes the date range to be the clicked week.
  733. In the following example, we add a week click handler that changes the date
  734. range of the calendar to one week only if the start and end dates of the week
  735. are in the current month.
  736. [source, java]
  737. ----
  738. cal.setHandler(new BasicWeekClickHandler() {
  739. protected void setDates(WeekClick event,
  740. Date start, Date end) {
  741. java.util.Calendar calendar = event.getComponent()
  742. .getInternalCalendar();
  743. if (isThisMonth(calendar, start)
  744. && isThisMonth(calendar, end)) {
  745. super.setDates(event, start, end);
  746. }
  747. }
  748. });
  749. ----
  750. endif::web[]
  751. ifdef::web[]
  752. [[components.calendar.eventclick]]
  753. == Handling Event Clicks
  754. The calendar events in all views are are clickable. There is no default handler.
  755. Just like the date and week click handlers, event click handling is enabled by
  756. setting an [interfacename]#EventClickHandler# for the [classname]#Calendar#
  757. object.
  758. You can get hold of the clicked event by the [methodname]#getCalendarEvent()#
  759. method in the [classname]#EventClick# object passed to the handler, as shown in
  760. the following example.
  761. [source, java]
  762. ----
  763. cal.setHandler(new EventClickHandler() {
  764. public void eventClick(EventClick event) {
  765. BasicEvent e = (BasicEvent) event.getCalendarEvent();
  766. // Do something with it
  767. new Notification("Event clicked: " + e.getCaption(),
  768. e.getDescription()).show(Page.getCurrent());
  769. }
  770. });
  771. ----
  772. endif::web[]
  773. ifdef::web[]
  774. [[components.calendar.eventdrag]]
  775. == Event Dragging
  776. The user can drag an event to change its position in time. The default handler
  777. sets the start and end time of the event accordingly. You can do many things
  778. with a custom move handler, such as restrict moving events.
  779. In the following example, we add a [interfacename]#EventMoveHandler# to a
  780. [classname]#Calendar#. The event handler updates the new position to the
  781. datasource, but only if the new dates are in the current month. This requires
  782. making some changes to the event provider class.
  783. [source, java]
  784. ----
  785. cal.setHandler(new BasicEventMoveHandler() {
  786. private java.util.Calendar javaCalendar;
  787. public void eventMove(MoveEvent event) {
  788. javaCalendar = event.getComponent().getInternalCalendar();
  789. super.eventMove(event);
  790. }
  791. protected void setDates(CalendarEventEditor event,
  792. Date start, Date end) {
  793. if (isThisMonth(javaCalendar, start)
  794. && isThisMonth(javaCalendar, end)) {
  795. super.setDates(event, start, end);
  796. }
  797. }
  798. });
  799. ----
  800. For the above example to work, the example event provider presented earlier
  801. needs to be changed slightly so that it doesn't always create a new event when
  802. [methodname]#getEvents()# is called.
  803. [source, java]
  804. ----
  805. public static class MyEventProvider
  806. implements CalendarEventProvider {
  807. private List<CalendarEvent> events =
  808. new ArrayList<CalendarEvent>();
  809. public MyEventProvider() {
  810. events = new ArrayList<CalendarEvent>();
  811. GregorianCalendar cal = new GregorianCalendar();
  812. cal.setTime(new Date());
  813. Date start = cal.getTime();
  814. cal.add(GregorianCalendar.HOUR, 5);
  815. Date end = cal.getTime();
  816. BasicEvent event = new BasicEvent();
  817. event.setCaption("My Event");
  818. event.setDescription("My Event Description");
  819. event.setStart(start);
  820. event.setEnd(end);
  821. events.add(event);
  822. }
  823. public void addEvent(CalendarEvent BasicEvent) {
  824. events.add(BasicEvent);
  825. }
  826. public List<CalendarEvent> getEvents(Date startDate,
  827. Date endDate) {
  828. return events;
  829. }
  830. }
  831. ----
  832. After these changes, the user can move events around as earlier, but dropping an
  833. event, the start and end dates are checked by the server. Note that as the
  834. server-side must move the event in order for it to render to the place it was
  835. dropped. The server can also reject moves by not doing anything when the event
  836. is received.
  837. endif::web[]
  838. ifdef::web[]
  839. [[components.calendar.dragselection]]
  840. == Handling Drag Selection
  841. Drag selection works both in the monthly and weekly views. To listen for drag
  842. selection, you can add a [interfacename]#RangeSelectListener# to the
  843. [classname]#Calendar#. There is no default handler for range select.
  844. In the code example below, we create an new event when any date range is
  845. selected. Drag selection opens a window where the user is asked for a caption
  846. for the new event. After confirming, the new event is be passed to the event
  847. provider and calendar is updated. Note that as our example event provider and
  848. event classes do not implement the event change interface, we must refresh the
  849. [classname]#Calendar# manually after changing the events.
  850. [source, java]
  851. ----
  852. cal.setHandler(new RangeSelectHandler() {
  853. public void rangeSelect(RangeSelectEvent event) {
  854. BasicEvent calendarEvent = new BasicEvent();
  855. calendarEvent.setStart(event.getStart());
  856. calendarEvent.setEnd(event.getEnd());
  857. // Create popup window and add a form in it.
  858. VerticalLayout layout = new VerticalLayout();
  859. layout.setMargin(true);
  860. layout.setSpacing(true);
  861. final Window w = new Window(null, layout);
  862. ...
  863. // Wrap the calendar event to a BeanItem
  864. // and pass it to the form
  865. final BeanItem<CalendarEvent> item =
  866. new BeanItem<CalendarEvent>(myEvent);
  867. final Form form = new Form();
  868. form.setItemDataSource(item);
  869. ...
  870. layout.addComponent(form);
  871. HorizontalLayout buttons = new HorizontalLayout();
  872. buttons.setSpacing(true);
  873. buttons.addComponent(new Button("OK", new ClickListener() {
  874. public void buttonClick(ClickEvent event) {
  875. form.commit();
  876. // Update event provider's data source
  877. provider.addEvent(item.getBean());
  878. UI.getCurrent().removeWindow(w);
  879. }
  880. }));
  881. ...
  882. }
  883. });
  884. ----
  885. endif::web[]
  886. ifdef::web[]
  887. [[components.calendar.eventresizing]]
  888. == Resizing Events
  889. The user can resize an event by dragging from both ends to change its start or
  890. end time. This offers a convenient way to change event times without the need to
  891. type anything. The default resize handler sets the start and end time of the
  892. event according to the resize.
  893. In the example below, we set a custom handler for resize events. The handler
  894. prevents any event to be resized over 12 hours in length. Note that this does
  895. not prevent the user from resizing an event over 12 hours in the client. The
  896. resize will just be corrected by the server.
  897. [source, java]
  898. ----
  899. cal.setHandler(new BasicEventResizeHandler() {
  900. private static final long twelveHoursInMs = 12*60*60*1000;
  901. protected void setDates(CalendarEventEditor event,
  902. Date start, Date end) {
  903. long eventLength = end.getTime() - start.getTime();
  904. if (eventLength <= twelveHoursInMs) {
  905. super.setDates(event, start, end);
  906. }
  907. }
  908. });
  909. ----
  910. endif::web[]