{
"documentation": [
{
"id": "faq",
"title": "FAQ",
"path": "FAQ.md",
"content": "Q: The Calendar is not fully recognized / I get JavaScript errors like \"setOption is not a function\" or \"addEvents is not a function\".\n\nA: This may hapen, when not including the addon packages into Vaadin's whitelisting. Please check, if your 'application.properties' contain the property \"vaadin.whitelist\" and if it does, if the whitelist includes \"org.vaadin.stefan\".\n```\nvaadin.whitelisted-packages=com.vaadin,org.vaadin.stefan,some.other.addon,etc.etc.etc\n```\n\nPlease also see [Build problems / JS (client side) errors with V14+](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Known-Issues#build-problems--js-client-side-errors-v14) for more details. If the issue still occurs, please [check](https://github.com/stefanuebe/vaadin-fullcalendar/issues/), if there might be an open issue already or create a new one.\n\nQ: The `DatesRenderedEvent` is not fired when setting an option, that changes the view.\n\nA: I deactivated the forwarding of the datesRendered event from the client side when an option is set, since\nthat would lead otherwise to a huge amount of datesRendered events. When setting options before the client side\nis fully attached, the queueing messes up the event handling here.\n\nWhen needed, you can activate or deactivate that by using the method `allowDatesRenderEventOnOptionChange(boolean)`.\nBy default this value is `false`, simply set it to true to also receive date render events on setOption.\n",
"category": "docs",
"tags": [
"faq",
"datesrenderedevent"
]
},
{
"id": "features",
"title": "Features",
"path": "Features.md",
"content": "This page shows a summary of the most important features of the FullCalendar library, that this addon provides. It is\nnot a full list of all features. If you find any library features missing, please create a [feature request](https://github.com/stefanuebe/vaadin-fullcalendar/issues/new?template=BLANK_ISSUE).\n\n## FullCalendar features\n- Adding, updating, and removing calendar entries using a data provider pattern\n- Switching between displayed intervals (next month, previous month, etc.)\n- Navigating to a specific date or today\n- Switching the calendar view (month, basic day/week, agenda day/week, list views, multi-month)\n- Setting a locale for week days, number formatting, and first-day-of-week calculation\n- Overriding the first day of the week independently of the locale\n- Limiting the maximum number of stacked entries per day (except basic views)\n- Activating day/week numbers as navigation links\n- Setting business hours with multiple time ranges per week\n- Creating recurring events (simple recurrence and RFC 5545 RRule)\n- Setting a client-side timezone\n- Optional Vaadin/Lumo theme\n- Custom native JS event handlers for entries\n- Client-side event sources (JSON feeds, Google Calendar, iCalendar)\n\n### Entry model\nThe `Entry` class supports the following properties:\n\n| Property | Method | Description |\n|---|---|---|\n| Title | `setTitle(String)` | Displayed label on the calendar |\n| Start / End | `setStart(LocalDate)` / `setStart(LocalDateTime)` / `setStart(Instant)` and equivalently `setEnd(LocalDate)` / `setEnd(LocalDateTime)` / `setEnd(Instant)` | `LocalDate`, `LocalDateTime`, or `Instant`; `LocalDate` implies all-day. `setEnd` is optional — omitting it creates a single-day (or point-in-time) entry |\n| All-day | `setAllDay(boolean)` | Force all-day rendering regardless of time part |\n| Color | `setColor(String)` | HTML color string (`\"#ff3333\"`, `\"red\"`) |\n| URL | `setUrl(String)` | FC renders the entry as an `` tag and navigates on click |\n| Interactive | `setInteractive(Boolean)` | Per-entry keyboard-focusability; `null` = inherit global `eventInteractive` |\n| Editable | `setEditable(boolean)` | Enable/disable drag and resize for this entry |\n| Display mode | `setDisplayMode(DisplayMode)` | `AUTO`, `BLOCK`, `LIST_ITEM`, `BACKGROUND`, `INVERSE_BACKGROUND`, `NONE` |\n| Overlap | `setOverlap(Boolean)` | Whether this entry may overlap others; `null` = inherit global setting |\n| Constraint | `setConstraint(String)` | Group id or `\"businessHours\"` restricting when this entry may be placed |\n| Recurring (simple) | `setRecurringDaysOfWeek` / `setRecurringStartTime` / `setRecurringEndTime` | Built-in day-of-week recurrence |\n| Recurring duration | `setRecurringDuration(String)` | ISO 8601 duration for multi-day recurring all-day events (e.g. `\"P2D\"`) |\n| RRule | `setRRule(RRule)` | RFC 5545 recurrence rule for complex patterns |\n| Exclusion dates | `rrule.excludeDates(LocalDate...)` | Dates excluded from an RRule recurrence — set on the `RRule` builder instance, transferred automatically to the entry |\n| Custom properties | `setCustomProperty(String, Object)` | Arbitrary data accessible in JS callbacks |\n\n### RRule — rich recurrence patterns\n\n`RRule` provides a fluent Java API for RFC 5545 recurrence rules, backed by the `@fullcalendar/rrule` plugin (bundled automatically).\n\n```java\n// Weekly on Monday, Wednesday, Friday\nEntry standup = new Entry();\nstandup.setTitle(\"Weekly Standup\");\nstandup.setRRule(RRule.weekly()\n .byWeekday(DayOfWeek.MONDAY, DayOfWeek.WEDNESDAY, DayOfWeek.FRIDAY)\n .dtstart(LocalDate.of(2025, 1, 1))\n .until(LocalDate.of(2025, 12, 31)));\n\n// Last Friday of each month\n// byWeekday accepts RFC 5545 BYDAY strings: \"-1fr\" = last Friday, \"1mo\" = first Monday,\n// \"-2tu\" = second-to-last Tuesday. Positive/negative numbers select the nth occurrence from\n// the start/end of the period.\nEntry endOfMonth = new Entry();\nendOfMonth.setTitle(\"Monthly Review\");\nendOfMonth.setRRule(RRule.monthly().byWeekday(\"-1fr\"));\n\n// Raw RFC 5545 string (for patterns not supported by the fluent builder)\nEntry custom = new Entry();\ncustom.setRRule(RRule.ofRaw(\"FREQ=WEEKLY;BYDAY=MO,WE;INTERVAL=2\"));\n```\n\n**When to use RRule vs. built-in recurrence:**\n- Use the built-in `recurringDaysOfWeek` / `recurringStartTime` / `recurringEndTime` for simple weekly patterns — less setup, no plugin required.\n- Use `RRule` for richer patterns: bi-weekly, monthly-by-weekday, yearly, exclusion dates, limited counts, etc.\n- The two mechanisms are mutually exclusive per entry: setting an `RRule` overrides built-in recurrence fields.\n\n### Entry URL behaviour\n\nWhen `entry.setUrl(url)` is set, FullCalendar renders the entry as an `` tag and navigates to the URL when clicked. The server-side `EntryClickedEvent` **is still fired** when the entry is clicked.\n\n### Accessibility\n\nSet `setOption(Option.ENTRY_INTERACTIVE, true)` to make all entries keyboard-focusable (`tabindex=\"0\"`), enabling keyboard-only users to Tab to entries and activate them with Enter or Space. By default, only entries with a `url` property are focusable. Enabling this globally is recommended for WCAG 2.1 AA, Success Criterion 2.1.1. For per-entry control, use `Entry.setInteractive(Boolean)` (pass `null` to inherit the global setting).\n\nAdditional accessibility options (set via `setOption`):\n- `Option.NATIVE_TOOLBAR_BUTTON_HINTS` — `Map` of `aria-label` values for toolbar buttons\n- `Option.NAV_LINK_HINT` / `Option.MORE_LINK_HINT` / `Option.NATIVE_TOOLBAR_VIEW_HINT` — screen-reader labels for navigation links, \"+N more\" overflow links, and view-switcher buttons (use `$0` as a runtime placeholder for the count or date value, e.g. `\"$0 more events\"`)\n- `Option.CLOSE_HINT` / `Option.TIME_HINT` / `Option.ENTRY_HINT` — labels for popover close buttons, time displays, and entries\n\n### Event handling\n\nServer-side events fired by the calendar:\n\n| Event | When fired |\n|---|---|\n| `TimeslotClickedEvent` | User clicks an empty time slot |\n| `TimeslotsSelectedEvent` | User selects a range of time slots |\n| `EntryClickedEvent` | User clicks an entry (including keyboard activation when `Option.ENTRY_INTERACTIVE` is true) |\n| `EntryDroppedEvent` | User drops an entry after dragging (includes new start/end) |\n| `EntryResizedEvent` | User resizes an entry (includes new start/end) |\n| `EntryDragStartEvent` | User begins dragging an entry |\n| `EntryDragStopEvent` | User releases an entry after dragging (fires regardless of whether a valid drop occurred) |\n| `EntryResizeStartEvent` | User begins resizing an entry |\n| `EntryResizeStopEvent` | User releases after resizing (fires regardless of whether a valid resize occurred) |\n| `EntryMouseEnterEvent` / `EntryMouseLeaveEvent` | Mouse enters/leaves an entry |\n| `DatesRenderedEvent` | The current view interval is rendered (use to update labels, refresh data, etc.) |\n| `MoreLinkClickedEvent` | User clicks the \"+N more\" overflow link |\n| `DayNumberClickedEvent` / `WeekNumberClickedEvent` | User clicks a day/week number (when `navLinks` is enabled) |\n| `BrowserTimezoneObtainedEvent` | The client's local timezone is detected on first load |\n| `EventSourceFailureEvent` | A client-side event source (JSON feed, Google Calendar, iCal) failed to load |\n| `ExternalEntryDroppedEvent` | An entry from a client-side event source is dropped into the calendar |\n| `ExternalEntryResizedEvent` | An entry from a client-side event source is resized |\n\n### Event sources (client-side)\n\nIn addition to the server-managed `EntryProvider`, the calendar supports client-side event sources that load data directly in the browser:\n\n```java\n// JSON feed — FC fetches from your REST endpoint with start/end query parameters\nJsonFeedEventSource jsonFeed = new JsonFeedEventSource(\"https://example.com/events\");\n// .withEditable(true) // optional: enable drag/drop for entries from this source\ncalendar.addClientSideEventSource(jsonFeed);\n\n// Google Calendar\nGoogleCalendarEventSource google = new GoogleCalendarEventSource(\"calendarId@gmail.com\");\ngoogle.withApiKey(\"YOUR_API_KEY\"); // or set globally: calendar.setOption(Option.EXTERNAL_EVENT_SOURCE_GOOGLE_CALENDAR_API_KEY, key)\ncalendar.addClientSideEventSource(google);\n\n// iCalendar (.ics) feed\nICalendarEventSource ical = new ICalendarEventSource(\"https://example.com/calendar.ics\");\ncalendar.addClientSideEventSource(ical);\n```\n\nClient-side event source entries are read-only by default (`editable = false`). To enable drag/drop and resize for a source, call `.withEditable(true)` on the source instance before adding it to the calendar. When a drag-drop occurs, an `ExternalEntryDroppedEvent` is fired; when a resize occurs, an `ExternalEntryResizedEvent` is fired (both instead of their server-managed counterparts `EntryDroppedEvent` / `EntryResizedEvent`).\n\n\n### View-specific options\n\nOverride any option for a specific view type only. The view type string is the FullCalendar view name\n(e.g. `\"dayGridMonth\"`, `\"dayGridWeek\"`, `\"timeGridWeek\"`, `\"timeGridDay\"`, `\"listWeek\"`) or a\nprefix that matches multiple views (e.g. `\"timeGrid\"` matches both `timeGridWeek` and `timeGridDay`).\nYou can also pass a `CalendarView` enum value instead of a raw string.\n\n```java\n// Limit event rows to 3 in month view, no limit in other views\ncalendar.setViewSpecificOption(\"dayGridMonth\", Option.DAY_MAX_EVENT_ROWS, 3);\n\n// Custom slot duration only in time-grid views\n// All three forms work thanks to the DurationConverter:\ncalendar.setViewSpecificOption(\"timeGrid\", Option.SLOT_DURATION, \"00:30:00\"); // string\ncalendar.setViewSpecificOption(\"timeGrid\", Option.SLOT_DURATION, Duration.ofMinutes(30)); // Duration\ncalendar.setViewSpecificOption(\"timeGrid\", Option.SLOT_DURATION, LocalTime.of(0, 30)); // LocalTime\n```\n\n### Navigation\n\n```java\ncalendar.next(); // next interval\ncalendar.previous(); // previous interval\ncalendar.today(); // jump to today\ncalendar.gotoDate(date); // jump to a specific date\n```\n\n## Scheduler features\nThe scheduler extension integrates the features of the commercial FullCalendar Scheduler plugin.\nA valid license key is required for production use (see [Scheduler license](Scheduler-license)).\n\n- Adding and removing resources (including hierarchical resource trees)\n- Linking one or multiple resources to entries (`ResourceEntry`)\n- Resource grouping by field value (`setOption(SchedulerOption.RESOURCE_GROUP_FIELD, ...)`) with customisable group headers\n- Multiple resource area columns with support for static text and interactive Vaadin components (`setResourceAreaColumns`)\n- Timeline views and vertical resource views (`SchedulerView`)\n- Filtering and ordering resources on the server side\n\nEvent handling:\n- Timeslot clicked / selected\n- Entry dropped (including the resource assignment after drop)\n\n### Component Resource Area Columns\n\nIn addition to static text columns, the resource area sidebar can display interactive Vaadin components (DatePicker, TextField, ComboBox, etc.) — one component instance per resource. This pattern mirrors Vaadin Grid's `ComponentColumn` and is useful for:\n\n- Inline editing of resource metadata (deadlines, priority, owner, notes)\n- One-way binding to entry properties (display entry start/end dates, duration)\n- Two-way binding (component change updates entry; entry change updates component)\n\nComponents are created by a callback that receives the `Resource` and returns a component instance. They are fully interactive — users can type, select, open dropdowns, etc. — and survive FullCalendar view changes and re-renders. Type-safe runtime access is provided at any time via `getComponent(resource)`.\n\n```java\n// Define a component column with a callback\nComponentResourceAreaColumn deadlineCol = new ComponentResourceAreaColumn<>(\n \"deadline\", \"Deadline\",\n resource -> {\n DatePicker picker = new DatePicker();\n picker.setWidth(\"130px\");\n return picker;\n }\n);\n\n// Mix with regular text columns\nscheduler.setResourceAreaColumns(\n new ResourceAreaColumn(\"title\", \"Name\").withWidth(\"200px\"),\n deadlineCol.withWidth(\"160px\")\n);\n\n// Update a component at any time (type-safe, no casting)\ndeadlineCol.getComponent(resource).ifPresent(picker ->\n picker.setValue(LocalDate.now())\n);\n```\n\n## Developer Tools\n\n- **[MCP Server](MCP-Server)**: Model Context Protocol server for AI assistants (Claude Code, GitHub Copilot, etc.) providing searchable documentation, Java API reference, code examples, and model schemas.\n",
"category": "docs",
"tags": [
"features",
"entry",
"localdate",
"localdatetime",
"instant",
"auto",
"block",
"background",
"none",
"rrule",
"entryclickedevent",
"timeslotclickedevent",
"timeslotsselectedevent",
"entrydroppedevent",
"entryresizedevent",
"entrydragstartevent",
"scheduler",
"resource",
"event"
]
},
{
"id": "fullcalendar-examples",
"title": "Introduction",
"path": "FullCalendar-Examples.md",
"content": "# Introduction\nThis page contains some samples to get you started with the FullCalendar addon. The samples are always based on the\nlatest version of the addon.\n\nSome samples use an in-memory entry provider when modifiying the calendar data to keep things simple. You may\nneed to adapt those parts, if you use a different entry provider.\n\nAlso we tried to keep things short. So you may see variables like `calendar`, `entry` or `entryProvider`\nwithout any declaration. In those cases these represent the basic types `FullCalendar`, `Entry` or `EntryProvider`.\n\n> **Note for 7.2.x readers:** several samples below still use the pre-7.2 API\n> (`FullCalendarBuilder.create()`, `event.createCopyBasedOnChanges()`). Both\n> remain functional in 7.2 as `@Deprecated(since = \"7.2.0\")` with no removal\n> scheduled for 7.x. For the equivalents, see\n> [Migration guide 7.1 → 7.2](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-7.1-to-7.2).\n\nIf you find an outdated sample, please create an issue for that.\n\n# Creating a basic calendar instance and add an entry\n\nThe FullCalendar is a normal Vaadin component, that can be added to your view as any other component. By default it uses\nan eager loading in memory entry provider, with which you simply can add, update or remove calendar entries.\n\n```java\n// Create a new calendar instance and attach it to our layout\nFullCalendar calendar = FullCalendarBuilder.create().build();\ncontainer.add(calendar);\ncontainer.setFlexGrow(1, calendar);\n\n// Create a initial sample entry\nEntry entry = new Entry();\nentry.setTitle(\"Some event\");\nentry.setColor(\"#ff3333\");\n\n// the given times will be interpreted as utc based - useful when the times are fetched from your database\nentry.setStart(LocalDate.now().withDayOfMonth(3).atTime(10, 0));\n entry.setEnd(entry.getStart().plusHours(2));\n\n// FC uses a data provider concept similar to the Vaadin default's one, with some differences\n// By default the FC uses a in-memory data provider, which is sufficient for most basic use cases.\n calendar.getEntryProvider().asInMemory().addEntries(entry);\n```\n\n# Add, update or remove a calendar entry\n\n```java\nInMemoryEntryProvider entryProvider = calendar.getEntryProvider().asInMemory();\n\nHorizontalLayout buttons = new HorizontalLayout();\nButton buttonSave;\nif (newInstance) {\nbuttonSave = new Button(\"Create\", e -> {\n if (binder.validate().isOk()) {\n // add the entry to the calendar instance\n entryProvider.addEntry(entry);\n entryProvider.refreshAll();\n }\n });\n } else {\nbuttonSave = new Button(\"Save\", e -> {\n if (binder.validate().isOk()) {\n // update an existing entry in the client side\n // this will only send changed data\n entryProvider.refreshItem(entry);\n }\n });\n }\n buttons.add(buttonSave);\n\nif (!newInstance) {\nButton buttonRemove = new Button(\"Remove\", e -> {\n entryProvider.removeEntry(entry);\n entryProvider.refreshAll();\n});\n buttons.add(buttonRemove);\n}\n```\n\n# Calendar event handling\nThis sample shows how to react on calendar events, that are triggered by the user or the calendar lifecycle.\n\n```java\n/*\n * The day click event listener is called when a user clicks in an empty space inside of the\n * calendar. Depending of if the clicked point was a day or time slot the event will provide the\n * time details of the clicked point. With this info you can show a dialog to create a new entry.\n */\ncalendar.addTimeslotsSelectedListener((event) -> {\n// react on the selected timeslot, for instance create a new instance and let the user edit it\nEntry entry = new Entry();\n \n entry.setStart(event.getStart()); // also event times are always utc based\n entry.setEnd(event.getEnd());\n entry.setAllDay(event.isAllDay());\n\n entry.setColor(\"dodgerblue\");\n\n// ... show an editor\n});\n\n /*\n * The entry click event listener is called when the user clicks on an existing entry.\n * The event provides the clicked event which might be then opened in a dialog.\n */\n calendar.addEntryClickedListener((event) -> {\n// react on the clicked entry, for instance let the user edit it\nEntry entry = event.getEntry();\n\n// ... show an editor\n});\n```\n\n# Entry providers\n\n> Introduced in version 4.1\n\nEntry providers allow you to minimize the memory footprint by activating lazy loading for calendar entries. The only\nexception from that is the `EagerInMemoryEntryProvider`, which simulates the old behavior of the FullCalendar.\n\nThe following examples show the different types of `EntryProvider`s and how to use them. The eager variant is the way\nto get rid of the deprecated API in the `FullCalendar`.\n\n## In memory entry provider\n\nThe `InMemoryEntryProvider` caches all registered entries on the server side, but provides only a subset of them to\nthe client (i. e. the entries of the current shown period). This way you can use the CRUD API on the server side\nwithout the need of implementing it yourself. On the other hand the client will be kept free of unnecessary information.\n\n```java\n// load items from backend\nList entryList = backend.streamEntries().collect(Collectors.toList());\n\n// init lazy loading provider based on given collection - does NOT use the collection as backend as ListDataProvider does\nLazyInMemoryEntryProvider entryProvider = EntryProvider.lazyInMemoryFromItems(entryList);\n\n// set entry provider\ncalendar.setEntryProvider(entryProvider);\n\n// CRUD operations\n// to add\nEntry entry = new Entry(); // ... plus some init\nentryProvider.addEntries(entry); // register in data provider\nentryProvider.refreshAll(); // call refresh to inform the client about the data change and trigger a refetch\n\n// after some change\nentryProvider.refreshItem(entry); // call refresh to inform the client about the data change and trigger a refetch\n\n// to remove\nentryProvider.removeEntry(entry);\nentryProvider.refreshAll(); // call refresh to inform the client about the data change and trigger a refetch\n```\n\n## Using callbacks\n\nThe callback entry provider is a base implementation of the `EntryProvider` interface. It does care about how the\nbackend creates or stores the entry data, but only fetches the entries to show from it by passing a query. The backend\nis responsible for providing the entries and handle any changes to the data (e. g. due to calendar entry events).\n\n```java\n// the callback provider uses the given callback to fetch entries when necessary\nCallbackEntryProvider entryProvider = EntryProvider.fromCallbacks(\n query -> backend.streamEntries(query),\n entryId -> backend.getEntry(entryId).orElse(null)\n);\n\n// set entry provider\ncalendar.setEntryProvider(entryProvider);\n\n// CRUD operations\n// to add\nEntry entry = new Entry(); // ... plus some init\nbackend.addEntry(entry); // register in your backend\nentryProvider.refreshAll(); // call refresh to inform the client about the data change and trigger a refetch\n\n// after some change\nbackend.updateEntry(entry); // inform your backend\nentryProvider.refreshItem(entry); // call refresh to inform the client about the data change and trigger a refetch\n\n// to remove\nbackend.removeEntry(entry); // remove from your backend\nentryProvider.refreshAll(); // call refresh to inform the client about the \n```\n\n## Custom implementation\n\nFeel free to create your own custom implementation, for instance to provide advanced internal caching on the server\nside. We recommend to extend the `AbstractEntryProvider` to start with.\n\nThe simples variant is similar to the callback variant, but with its own class:\n\n```java\nprivate static class BackendEntryProvider extends AbstractEntryProvider {\n private final EntryService service;\n\n public BackendEntryProvider(EntryService service) {\n this.service = service;\n }\n\n @Override\n public Stream fetch(@NonNull EntryQuery query) {\n return service.streamEntries(query);\n }\n\n @Override\n public Optional fetchById(@NonNull String id) {\n return service.getEntry(id);\n }\n}\n```\n\n## Activate prefetch mode (experimental)\n\nBy default the entry provider will always fetch data for the current period. Switching to an adjacent one can\nlead to flickering, since the calendar will resize itself due to the shown entries.\n\nTo prevent that flickering, the calendar can be set to \"prefetch mode\". When activated, the calendar will always\nfetch the previous and next period together with the current one. This means, that on switching to an adjacent\nperiod will initially show the previously fetched entries and update those with the latest state from the server.\nThis leads to an increased amount of data transported between server and client, but will lead to a better\nuser experience as the above mentioned flickering will be prevented.\n\nThe prefetch mode tries to obtain the necessary period based on the current view range unit. The supported units\nare \"day\", \"month\" and \"year\". If no range unit could be determined, a warning will show up. If the range unit\nis not supported, prefetch will not work (in this case the calendar behaves as if prefetch has been disabled).\n\nPlease note, that this functionality is still experimental, but should work fine in most use cases. Thus ee recommend\nto activate it to improve the user experience.\n\n```java\ncalendar.setPrefetchEnabled(true);\n```\n\n# Setting the calendar's dimensions\n\nYou may set the dimensions as with every other Vaadin component. The FC library also brings in some additional\nsettings for content height or an aspect ratio, that can be taken into account. These can be set\nvia the Options API.\n\nSee https://fullcalendar.io/docs/sizing for details.\n\n# Using timezones\n\n```java\n// FC allows to show entries in a specifc timezone. Setting a timezone only affects the client side\n// and might be interesting, when editing those entries in some kind of edit form\n\nTimezone tzBerlinGermany = new Timezone(ZoneId.of(\"Europe/Berlin\"));\ncalendar.setTimezone(tzBerlinGermany); // will rerender the client side and show all times 1-2 hours \"later\".\n\n// We can also reset the timezone to default.\ncalendar.setTimezone(Timezone.UTC);\n\n// We can also read the browsers timezone, after the component has been attached to the client side.\n// There are other ways to obtain the browser's timezone, so you are not obliged to use the listener.\ncalendar.addBrowserTimezoneObtainedListener(event -> calendar.setTimezone(event.getTimezone()));\n\n// If you want to let the calendar obtain the browser time zone automatically, you may simply use the builder.\n// In that case as soon as the client connected, it will set it's timezone in the server side instance.\n FullCalendarBuilder.create().withAutoBrowserTimezone().build();\n\n// Entries use internally utc to define times. The LocalDateTime and Instant methods setStart/End have the same effect.\nentry.setStart(Instant.now()); // UTC\n entry.setEnd(LocalDateTime.now()); // UTC\n\n// Entry provides some additional convenience methods to handle the current calendar's timezone's offset, e.g. to allow easy\n// integration into edit forms.\n calendar.setTimezone(tzBerlinGermany); // times are now 1-2 hours \"ahead\" (depending on daylight saving)\nentry.setStart(LocalDate.of(2000, 1, 1).atStartOfDay());\n\nLocalDateTime utcStart = entry.getStart(); // will be 2000-01-01, 00:00\nLocalDateTime offsetStart = entry.getStartWithOffset(); // will be 2000-01-01, 01:00\n\n// ... modify the offset start, for instance in a date picker\n// e.g. modifiedOffsetStart = offsetStart.plusHours(5);\nLocalDateTime modifiedOffsetStart = offsetStart.plusHours(5);\n\nentry.setStartWithOffset(modifiedOffsetStart); // automatically takes care of conversion back to utc\nutcStart = entry.getStart(); // will be 2000-01-01, 04:00\noffsetStart = entry.getStartWithOffset(); // will be 2000-01-01, 05:00\n```\n\n# Passing custom initial options in Java\n\nYou can fully customize the client side options in Java by passing a JsonObject when creating the FullCalendar.\nPlease be aware, that some options are always set, regardless of the values you set. Please check the\nApiDocs of the withInitialOptions method (or respective constructors) for details\n\nThe following example shows the default initial options as they are set internally by the web component.\n\n```java\nJsonObject initialOptions = Json.createObject();\ninitialOptions.put(\"height\", \"100%\");\ninitialOptions.put(\"timeZone\", \"UTC\");\ninitialOptions.put(\"header\", false);\ninitialOptions.put(\"weekNumbers\", true);\ninitialOptions.put(\"eventLimit\", false); // pass an int value to limit the entries per day\ninitialOptions.put(\"navLinks\", true); \ninitialOptions.put(\"selectable\", true);\ncalendar = FullCalendarBuilder.create().withScheduler().withInitialOptions(initialOptions).build();\n```\n\n# Style the calendar\n\n## Lumo Theme\nSince 6.1 the calendar provides a built-in Lumo theme, that changes minor parts of it to use Lumo variables, like\nsizes, colors, etc. At this point, the theme is not applied automatically, but you have to opt-in to use it.\n\nPlease also be aware, that with 6.1, it still is considered experimental, so there might be parts, that have been\nforgotten or not looking as expected. Also any additional custom stylings may override the Lumo stylings.\n\nTo activate the Lumo theme, simply add the respective theme variant, as you would do with other Vaadin components.\n\n```java\ncalendar.addThemeVariant(FullCalendarVariant.LUMO);\n```\n\n## Global styles\n\nSince 6.0 the component is part of the light dom and thus can be styles via plain css. For any details\non styling the FC please refer to the FC docs (regarding css properties, classes, etc.).\n\nThe styles can be defined as you are used to using the Vaadin theme mechanism or `@CssImport`s.\n\nSample styles.css\n\n```css\n/* change the border color of the fc in a global way*/\n.fc {\n --fc-border-color: #ddd;\n}\n\n/* change the border color of the fc for dark themes*/\n[theme~=\"dark\"] .fc {\n --fc-border-color: #333;\n}\n\n\n/* change the appearance of the week and day number to a more button like style when hovering */\n.fc a:is(.fc-daygrid-week-number, .fc-daygrid-day-number) {\n background: transparent;\n font-size: 12px;\n transition: background 200ms ;\n border-radius: 3px;\n}\n\n.fc a:is(.fc-daygrid-week-number, .fc-daygrid-day-number):hover {\n background: var(--lumo-primary-color-10pct);\n text-decoration: none;\n}\n\n.fc a.fc-daygrid-day-number {\n padding-left: 6px;\n padding-right: 6px;\n}\n```\n\n# Show the current shown time interval (e. g. month) with Vaadin components\n\n```java\nprivate void init() {\n // The element that should show the current interval.\n HasText intervalLabel = new Span();\n\n // combo box to select a view for the calendar, like \"monthly\", \"weekly\", ...\n ComboBox viewBox = new ComboBox<>(\"\", CalendarViewImpl.values());\n viewBox.addValueChangeListener(e -> {\n CalendarView value = e.getValue();\n calendar.changeView(value == null ? CalendarViewImpl.DAY_GRID_MONTH : value);\n });\n viewBox.setValue(CalendarViewImpl.DAY_GRID_MONTH);\n\n /*\n * The view rendered listener is called when the view has been rendererd on client side\n * and FC is aware of the current shown interval. Might be accessible more directly in\n * future.\n */\n calendar.addDatesRenderedListener(event -> {\n LocalDate intervalStart = event.getIntervalStart();\n CalendarView cView = viewBox.getValue();\n\n String formattedInterval = ... // format the intervalStart based on cView. See the demos for examples.\n\n intervalLabel.setText(formattedInterval);\n });\n}\n```\n\n# Creating a background entry\nA background entry is an entry, that is rendered behind all other entries. It is not clickable and\nhas no tooltip. It is useful for marking a time range, e. g. for marking a vacation.\n\n```java\nEntry entry = new Entry();\n// ... setup entry details\n \nentry.setDisplayMode(DisplayMode.BACKGROUND);\ncalendar.addEntry(entry);\n```\n\n# Adding business hours\nYou can define business hours for each day of the week. If you don't define any business hours, the calendar will\nassume, that the business hours are from 0:00 to 24:00 for each day.\n\nNon-business hours are grayed out in the calendar.\n\n```java\n// Single instance for \"normal\" business week (mo-fr)\ncalendar.setBusinessHours(new BusinessHours(LocalTime.of(9, 0), LocalTime.of(17, 0),BusinessHours.DEFAULT_BUSINESS_WEEK));\n\n// Multiple instances\n calendar.setBusinessHours(\nnew BusinessHours(LocalTime.of(9, 0), LocalTime.of(17, 0),BusinessHours.DEFAULT_BUSINESS_WEEK),\n new BusinessHours(LocalTime.of(12, 0), LocalTime.of(15, 0), DayOfWeek.SATURDAY)\n );\n\n// Single instance for \"each day from 9am to midnight\"\n calendar.setBusinessHours(new BusinessHours(LocalTime.of(9, 0)));\n```\n\n# Using tippy.js for description tooltips\nBy default the calendar does not provide tooltips for entries. However, you can easily integrate any type of\ntooltip mechanism or library, for instance by simply applying an html title or using a matured tooltip library\nlike tippy.js.\n\nThis sample shows how to easy integrate tippy.js into a custom subclass of FullCalendar to show an entry's description\nas a tooltip when hovering the entry inside the FC. Please customize the example as needed.\n\n1. Create a new TypeScript file inside the frontend folder of your project. It needs to extend either FullCalendar or\n FullCalendarScheduler. This example utilized FullCalendarScheduler. If you want to use the normal FC, simply remove\n all the -Scheduler parts. You may also have a simply JavaScript file, in that case you need to change the\n following script a bit.\n\nfull-calendar-with-tooltips.ts\n\n```typescript\nimport {FullCalendarScheduler} from '@vaadin/flow-frontend/vaadin-full-calendar/full-calendar-scheduler';\nimport tippy from 'tippy.js';\n\n\nexport class FullCalendarWithTooltip extends FullCalendarScheduler {\n initCalendar() {\n super.initCalendar();\n\n this.calendar!.setOption(\"eventDidMount\", e => {\n this.initTooltip(e);\n });\n }\n\n initTooltip(e: any) {\n if (e.event.title && !e.isMirror) {\n e.el.addEventListener(\"mouseenter\", () => {\n let tooltip = e.event.getCustomProperty(\"description\", e.event.title);\n\n e.el._tippy = tippy(e.el, {\n theme: 'light',\n content: tooltip,\n trigger: 'manual'\n });\n\n e.el._tippy.show();\n })\n\n e.el.addEventListener(\"mouseleave\", () => {\n if (e.el._tippy) {\n e.el._tippy.destroy();\n }\n })\n }\n }\n}\n\ncustomElements.define(\"full-calendar-with-tooltip\", FullCalendarWithTooltip);\n\n```\n\n2. Now create a simple JavaClass, that utilizes your js file. This Java class also imports the needed CSS files.\n\n```java\n@Tag(\"full-calendar-with-tooltip\")\n@JsModule(\"./full-calendar-with-tooltip.js\")\n@CssImport(\"tippy.js/dist/tippy.css\")\n@CssImport(\"tippy.js/themes/light.css\")\npublic class FullCalendarWithTooltip extends FullCalendarScheduler {\n\n public FullCalendarWithTooltip() {\n }\n}\n```\n\nAs shown in the subclass sample, you may also use the FullCalendarBuilder to create your custom class.\n\n# Customize the entry content\n\nFC allows you to modify the content of an entry. The given string will be interpreted as js function on client side\nand attached as `eventContent` callback. See https://fullcalendar.io/docs/content-injection (\"...a function\") for\ndetails.\n\n```java\ncalendar.setEntryDidMountCallback(\n \"function(info) {\" +\n \" info.el.style.color = 'red';\" +\n \" return info.el; \" +\n \"}\"\n);\n\n```\n\nInside the javascript callback you may access the entry's default properties or custom ones, that\nyou can set beforehand, using the custom property api (e. g.`setCustomProperty(String, Object)`).\nIn the callback you can access the custom property in a similar way, using `getCustomProperty(key)`\nor `getCustomProperty(key, defaultValue)`.\n\nPlease be aware, that the entry content callback has to be set before the client side is attached. Setting it afterwards\nhas no effect.\n\nAlso make sure, that your callback function does not contain any harmful code or allow cross side scripting.\n\n```java\n// set the custom property beforehand\nentry.setCustomProperty(Entry.EntryCustomProperties.DESCRIPTION, \"some description\");\n\n// use the custom property\ncalendar = FullCalendarBuilder.create()\n .withEntryContent(\n \"function(info) {\" +\n \" let entry = info.event;\" +\n \" console.log(entry.title);\" + // standard property\n \" console.log(entry.getCustomProperty('\" + Entry.EntryCustomProperties.DESCRIPTION+ \"'));\" + // custom property\n \" /* ... do something with the event content ...*/\" +\n \" return info.el; \" +\n \"}\"\n)\n// ... other settings\n .build();\n\n// or use the custom property in the entryDidMountCallback\n```\n\n# Use native javascript events for entries\nWith 6.2 custom native event handlers for entries have been added. These allow you to setup JavaScript events for\neach entry, e.g. a mouse over event handler. Inside these event handlers you may also access the created entry dom\nelement.\n\nCustom native event handlers are added to the FullCalender object. They will then be applied to each created\nentry object (using the entryDidMount callback).\n\nTo add an event handler, simply call the method `addEntryNativeEventListener` on the calendar. The first parameter\nis the JavaScript event name (e.g. \"mouseover\"), the second parameter is the callback, that shall be used for\nthat event. Please be aware, that we do NOT check or sanitize the given JavaScript. It is up to you to prevent\nmalicious code from being sent to your users.\n\nInside the event callback, you may access the entryDidMount argument object, that contains additional information\nabout the current entry. See the official docs (https://fullcalendar.io/docs/event-render-hooks)\nfor more details about which details it provide.\n\n```java\nFullCalendar calendar = new FullCalendar();\n\n// ... other configurations\n\n// write the js event, the current entry info and the current entry's element to the browser console.\ncalendar.addEntryNativeEventListener(\"mouseover\", \"e => console.warn(e, info.event, info.el)\");\n\nadd(calendar);\n```\n\nPlease be aware, that due to the design of the used library, these event handlers have to be setup before the\ncalendar is initialized on the client side.\n\nThis sample will change the element style, when the mouse moves over it and changes back, when leaving the element.\n\n```java\ncalendar.addEntryNativeEventListener(\"mouseover\", \"e => info.el.style.opacity = '0.5'\");\ncalendar.addEntryNativeEventListener(\"mouseout\", \"e => info.el.style.opacity = ''\");\n```\n\nYou can also access the client side dom to utilize other elements, like the parents. With this you may for instance\ncall a server side method.\n\nThe following sample shows, how a client callable method in the current view, containing the FullCalendar object, can\nbe called, when right clicking the entry. With this info you can for instance open a custom popup as a context menu.\n\n```java\n@Route(...)\npublic void MyCalendarView extends VerticalLayout {\n public MyCalendarView() {\n\n FullCalendar calender = new FullCalendar();\n // adds a contextmenu / right client event listener, that calls our openContextMenu. \n // \"this\" is the fc object, \"this.el\" is the Flow element and \"this.el.parentElement\" is our current view.\n // This hierarchy access may changed, when you nest the FC into other containers. \n\n calendar.addEntryNativeEventListener(\"contextmenu\",\n \"e => this.el.parentElement.$server.openContextMenu(info.event, e.clientX, e.clientY)\");\n\n add(calender);\n }\n\n @ClientCallable\n public void openContextMenu(JsonObject e, int pointerX, int pointerY) {\n System.out.println(e);\n System.out.println(pointerX);\n System.out.println(pointerY);\n }\n} \n```\n\nYou can combine the event handlers with a custom entryDidMount callback, if you want additional customizations\nof the entries. The FC will take care of combining the event handlers and you EDM callback\n```java\ncalendar.setEntryDidMountCallback(\"\"\"\n function(info) {\n console.warn(\"my custom callback\");\n }\"\"\");\n\ncalendar.addEntryNativeEventListener(\"mouseover\", \"e => info.el.style.opacity = '0.5'\");\ncalendar.addEntryNativeEventListener(\"mouseout\", \"e => info.el.style.opacity = ''\");\n```\n\nThe following sample shows how to utilize the entryDidMount callback, the native event handlers and the\n[Popup addon](https://vaadin.com/directory/component/popup) to show a context menu. In this sample, the context\nmenu is based on a ListBox.\n\n```java\n@Route(...)\npublic void MyCalendarView extends VerticalLayout {\n \n private Popup popup;\n \n public MyCalendarView() {\n\n FullCalendar calender = new FullCalendar();\n // adds a contextmenu / right client event listener, that calls our openContextMenu. \n // \"this\" is the fc object, \"this.el\" is the Flow element and \"this.el.parentElement\" is our current view.\n // This hierarchy access may changed, when you nest the FC into other containers. \n\n calendar.addEntryNativeEventListener(\"contextmenu\",\n \"e => {\" +\n \" e.preventDefault(); \" +\n \" this.el.parentElement.$server.openContextMenu(info.event.id);\" +\n \"}\");\n\n // by default, the entry element has no id attribute. Therefore we have to add it ourselves, using the \n // entry id, that is by default an auto generated UUID\n calendar.setEntryDidMountCallback(\"\"\"\n function(info) {\n info.el.id = \"entry-\" + info.event.id;\n }\"\"\");\n\n }\n\n @ClientCallable\n public void openContextMenu (String id){\n initPopup(); // init the popp\n\n popup.removeAll(); // remove old content\n\n\n // setup the context menu\n // (side note: the list box shows a checkmark, when selecting an item, therefore you may want to use a different \n // component for a real application or hide the checkmark with CSS)\n ListBox listBox = new ListBox<>();\n listBox.setItems(\"Option A\", \"Option B\", \"Option C\");\n listBox.addValueChangeListener(event -> {\n Notification.show(\"Selected \" + event.getValue());\n popup.hide();\n });\n\n popup.add(listBox);\n popup.setFor(\"entry-\" + id);\n\n popup.show();\n }\n\n private void initPopup () {\n if (popup == null) {\n popup = new Popup();\n popup.setFocusTrap(true);\n add(popup);\n }\n }\n} \n```\n\n# Creating a subclass of FullCalendar for custom mods\nSince version 6.0.0, the client side component is based on a simple HTMLElement and thus there is\nno framework lifecycle to hook into. The main entry points for your components are therefore:\n* connectedCallback() - called when the component is attached to the dom\n* initCalendar() - called when the calendar is initialized - only called once\n* createInitOptions(initialOptions) - called when the calendar is initialized. You can modify the initial options here.\n* createEventHandlers() - called when the calendar is initialized. You can modify the event handlers here.\n\nBe aware, that during `connectedCallback()` and before calling `initCalendar()` no internal calendar\nobject is available. Calling `this.calendar` will automatically infer `initCalendar()` and thus can lead\nto unwanted side effects. Therefore, if you want to set options, add entries or do other things with the\ncalendar object, do it after `super.initCalendar()` has been called.\n\nIf you want to modifiy options, that are passed into the calendar object, you can extend the method\n`createInitOptions(initialOptions)` and return a modified options object.\n\nIf you want to modify or extend the event handlers, you can override the method `createEventHandlers()`-\n\nWe recommend to use the `override` modifier on overridden methods to make sure, that the method is\nalways up-to-date.\n\n1. Create a custom web component\n Create a custom component, that extends FullCalendar or FullCalendarScheduler.\n\n\n```typescript\nimport {FullCalendar} from '@vaadin/flow-frontend/vaadin-full-calendar/full-calendar';\n\nexport class MyFullCalendar extends FullCalendar {\n connectedCallback() {\n super.connectedCallback();\n\n // do something with this.calendar\n // ...\n }\n\n initCalendar() {\n super.initCalendar();\n\n // do something with this.calendar\n // ...\n }\n\n createInitOptions(initialOptions) {\n // modify the initial options\n // attention: this.calendar is not available here!\n // ...\n\n return initialOptions;\n }\n\n createEventHandlers() {\n // modify the event handlers\n // attention: this.calendar is not available here!\n // ...\n\n return super.createEventHandlers();\n }\n}\n\ncustomElements.define(\"my-full-calendar\", MyFullCalendar);\n```\n\n2. Create a subclass of FullCalendar\n\n```java\nimport com.vaadin.flow.component.Tag;\nimport com.vaadin.flow.component.dependency.JsModule;\nimport org.vaadin.stefan.fullcalendar.FullCalendar;\n\n@Tag(\"my-full-calendar\")\n@JsModule(\"./my-full-calendar.js\")\npublic class MyFullCalendar extends FullCalendar {\n\n public MyFullCalendar() {\n }\n}\n```\n\n3. Use this class in your code\n\n```java\ncalendar = new MyFullCalendar();\n```\n\nYou can even use the FullCalendarBuilder to create your custom class. Be aware, that in the current version your\ncustom class needs to provide all constructors, that the extended FC class has. This will be fixed in future versions.\n\n```java\ncalendar = FullCalendarBuilder.create().withCustomType(MyFullCalendar.class).build();\n``` \n\n\n# Entry data utilities\n\n## Handling data changes in events\n\nWhen an event occurs, you may want to check or apply the event's changes against the related calendar item.\n\nYou may either do this manually or use the provided utility functions, that are part of the `EntryDataEvent` classe\n(and subclasses).\n\nIt might come in handy, that you get changes from an event in form of an `Entry` object instead of the different\nchanged values of the event itself.\n\nTo do so, you can simply call the method `createCopyBasedOnChanges()` method, that the `EntryDataEvent` provides.\nThis will create complete copy of the entry but with the changes of the event applied. This copy will not be added to\nthe calendar and is simply intended for data checks.\n\nTo apply any incoming changes to the related `Entry`, the event class provides the method `applyChangesOnEntry()`.\nThis will override the entry with the event data, but not automatically update the client side. This is up to you\nto do with an `refreshItem()` or `refreshAll()` call. Also any backend updates (except for the in memory provider)\nneeds to be handled by your logic.\n\n```java\n// directly apply the changes\ncalendar.addEntryDroppedListener(event -> {\n event.applyChangesOnEntry(); // includes now the allDay attribute if sent by client\n});\n\n// create a copy to do some business logic checks\n calendar.addEntryDroppedListener(event -> {\nEntry copy = event.createCopyBasedOnChanges();\n\n if(copy.getStartAsLocalDate().isBefore(someRequiredMinimalDate) /* do some background checks on the changed data */){\n event.applyChangesOnEntry();\n event.getSource().getEntryProvider().refreshItem(event.getEntry()); // refresh the entry to update the UI\n }\n });\n```\n\n## Create a temporary copy\n\nThe `Entry` class provides a copy API, that allows you to create a copy of an entry or from a given entry. With this you\ncan easily create temporary instances for an edit dialog without needing to write a lot of \"get-set\" calls. This is\nuseful, when your binders work with the `setBean` api\n\nPlease be aware, that this api is considered \"experimental\" and might not work in every special use case or with every\ncustom property key.\n\n```java\nEntry tmpEntry = entry.copy(); // create a temporary copy\n// you may also call copyAsType to allow the copy to be of a different type\n\nBinder binder = new Binder<>();\n\n// ... init binder\n\nbinder.setBean(tmpEntry); // you can of course also use the read/writeBean api\n\n// modify the bound fields\n\nif (binder.validate().isOk()) {\n entry.copyFrom(tmpEntry); // this will overwrite the entry with the values of the tmpEntry\n// ... update the backend as needed, e.g. by calling refreshItem on the entry provider\n}\n```\n\nAlternatively you can use the copy API in a JPA fashion, where new instances are created on changes.\n\n```java\nEntry tmpEntry = entry.copy(); // create a temporary copy\n\n// ... modify the temporary copy\n\n// return a new copy at the end without changing the initial entry\nreturn tmpEntry.copy();\n```",
"category": "docs",
"tags": [
"fullcalendar-examples",
"fullcalendar",
"entry",
"entryprovider",
"eagerinmemoryentryprovider",
"inmemoryentryprovider",
"abstractentryprovider",
"entrydataevent",
"scheduler",
"resource",
"event"
]
},
{
"id": "fullcalendar-functionality",
"title": "FullCalendar-Functionality",
"path": "FullCalendar-Functionality.md",
"content": "This addon uses a 3rd party library called FullCalendar. We try to integrate all features the library provides. Therefore\nthe following list might not include all available features, but should list the most important ones. If you find\na feature in the FC library, that this addon not yet supports, please create an feature request in the issues page.\n\nSupported features are\n- adding / updating / removing calendar entries using a data provider like mechanism,\n- switching between shown intervals (next month, previous month, etc.),\n- goto a specific date or today,\n- switch the calendar view (month, basic views for days and weeks, agenda views for days and weeks, list views for day to year),\n- setting a locale to be used for displaying week days, formatting values, calculating the first day of the week, etc. (supported locales are provided as constant list)\n- setting the first day of week to be shown (overrides the locale setting),\n- limit max shown entries per day (except basic views)\n- activating day / week numbers / names to be links\n- setting a eventRender JS function from server side\n- setting business hours information (multiple entries possible)\n- creating recurring events\n- setting a client side timezone\n- optional Lumo theme\n- custom native js event handlers for entries\n\n- Event handling for\n - clicking an empty time spot in the calendar,\n - selecting a block of empty time spots in the calendar,\n - clicking an entry,\n - moving an entry via drag and drop (event is fired on drop + changed time),\n - resizing an entry (event is fired after resize + changed time),\n - view rendered (i. e. to update a label of the shown interval)\n - clicking on limited entries link \"+ X more\"\n - clicking on a day's or week's number link (when activated)\n\n- Model supports setting\n - title,\n - start / end / all day flag,\n - color (html colors, like \"#f00\" or \"red\"),\n - description (not shown via FC),\n - editable / read only\n - rendering mode (normal, background, inversed background)\n - recurring data (day of week, start / end date and time)\n - etc.",
"category": "docs",
"tags": [
"fullcalendar-functionality",
"entry",
"event"
]
},
{
"id": "fullcalendar-migrationguides",
"title": "Index",
"path": "FullCalendar-MigrationGuides.md",
"content": "We know that migrations suck. Not only developers fear the appearance of a new major version but also every\nproduct or project manager of an application, that uses 3rd party software, knows, that it can be a stressful and time consuming horror to\nintegrate a new major version.\n\nUnfortunately this applies also for this addon. There will be breaking changes here and there, that requires you to get back\ninto your code and review everything. Nevertheless, we hope, that this migration guide helps you as good as possible\nto get a detailed insight of what has changed and what needs to be done to get you back on track.\n\nIf we missed something or anything is unclear, please ping us on GitHub. We hope, that your upgrade goes through\nas smoothly as possible.\n\n# Index\n* [4.1 > 6.0](#migrating-from-41--60)\n* [4.0 > 4.1](#migrating-from-40--41)\n* [3.x > 4.0](#migrating-from-3x--40)\n\n# Migrating from 4.1 > 6.0\nDepending on your Vaadin version you may need to update also other things, related to Vaadin core and Spring Boot.\nSteps to be taken there, will not be covered here.\n\n## Removed polymer\nSince Polymer has been removed from Vaadin 24, we decided to convert the JS elements to plain, HTML element based\nweb components. Thus, this version should work with Vaadin 23 and 24. \n\nFor most cases this should not affect your application. However, if you subclasses the javascript classes, you may need\nto adapt some of the changes. Any Polymer related feature needs to be converted to plain javascript. If you used\nproperties, you should still be able to set those via the Flow Java API, but you simply have to declare them as normal\nJS class fields. \n\nAlso please note, that the content of the component is now part of the light dom. This will most likely affect\nany custom stylings you may have defined. See the next part for details.\n\n## Styling\nSince the component is now part of the light dom, you have the advantages and disadvantages of it. \n\nAny custom styles you may have defined via overriding the JS class or via using the Java method `addCustomStyles` \ncan now be simply defined via plain css style files. So simply take your css snippets and move them to your global\ncss styles (however they are strucutred :) ).\n\nPlease be aware, that due to being part of the light dom, any other stylings may bleed into the FC now or vice versa.\nBut our experience showed, that the majority of our user base preferred the light dom variant, thus we decided to\ngo this way.\n\nAlso since we moved to a new major of the FC library, it might be, that css selectors have changed in their \nprovided styles and thus your custom styles might not work out of the box.\n\n## Folder structure and tags\nWe changed the folder structure and tag names a bit to better represent the Vaadin nature of this addon and to\nprevent potential naming conflicts. Therefore the the files will now be placed inside a folder named\n`vaadin-full-calendar`. The file names themselves have not changed.\n\nIf you subclasses one of the FC JavaScript classes, simply update the folder structure to be something like\n`@vaadin/flow-frontend/vaadin-full-calendar/full-calendar`. You may need to add the file suffix \".ts\".\n\nAdditionally we prefixed the element tag names with a `vaadin-`, so that the FC itself now has the tag \n`vaadin-full-calendar`. This is relevant, if you used the old tag names for styling or dom querying purposes.\nIn that case update the tag names.\n\n## TypeScript\nWe migrated the old JS files to TypeScript. But this process is not yet done and thus there are many things still in\nprogress (mainly the definition of custom types and some code refinement). \n\nNevertheless, for the normal use case, this has no effect. If you subclassed the JS classes, feel free to convert\nit to TypeScript, but be aware, we do not yet have any fancy TypeScript stuff. But it will come somewhere in future ;)\n\nThings to have in mind when migrating: We use protected and private modifiers of typescript now. Any underscores \nhave been removed and the methods / fields have become private or protected. For instance the `_initCalendar()` method\nis now named `initCalendar()`. This is one of the most important ones - if you have subclassed the FC, you most likely\nhave overridden this method and have to update your code. We recommend to use the `override` modifier, so that the \ncompiler marks any issues regarding such cases.\n\n### Issues with webpack\nThere is a known issue with webpack, that will most likely lead to issues, when starting the application.\n\nCheck the \"Known Issues\" page for details (> Startup issue when using webpack (Vaadin 14-23)).\n\n## No more EagerInMemoryEntryProvider\nTo make maintenance of the client side a bit easier and less error prone, we decided to remove the \n`EagerInMemoryEntryProvider` and thus have the client side always be in \"lazy loading\" mode. This means, that there is \nno official way anymore to move all entries to the client side at once.\n\nOf course you still can override this behavior by using simple JS, but we do not recommend to do\nthat as all infrastructure is built around the fetching mechanisms.\n\nThe `LazyInMemoryEntryProvider` has been renamed to `InMemoryEntryProvider`. Rename all imports and class occurrences.\nAlso the static methods inside EntryProvider have been renamed from `lazyInMemoryFromItems` to `inMemoryFrom`.\n\nReplace any usage of the eager variant with the (now) default one. You also need to call `refreshAll`/`refreshItem` \nafter you changed the data in the provider. This behavior aligns to the behavior to the normal Vaadin data provider.\n\nThe `updateMethod` of the eager variant has no replacement in the default one, as items are not pushed to the client,\nbut fetched. When the client shall be updated, call the refresh methods instead.\n\nThere are also other methods, that where some variant of `Eager`. Simply replace them with the now default one and\ncheck, if refreshs are necessary in your use cases.\n\n### Prefetch mode\nThere is now a prefetch mode, that allows fetching adjacent periods. This shall prevent flickering, when switching\nto the previous/next period. See the samples page for details.\n\n## Custom views\nUp to now custom views had to be created as a Java class but could only be registered via initial options. To\nmake life a bit easier here, the interface `CustomCalendarView` has been added plus methods to register those. \n\nIt is recommended to convert your views and use this new interface. While the old way should still work\nand lead to `AnonymousCustomCalendarView` instances, a warning will be printed onto the error console.\n\nCheck the `CustomCalendarView` docs for additional information. The relevant method is `getViewSettings()`.\n\nPlease note, that due to limitations of the FC library, views can only be set at initialization time.\n\n## Entry is \"static\" again, JsonItem is gone\nThis part describes a rare use case and should not be affecting most of the FC users.\n\nWith 4.x we tried to make the `Entry` structure more dynamic to allow easier definition of new properties and automate\nthe update mechanism a bit. Unfortunately the approach we took was not practicable in all use cases and we even had\nsome issues with proxying and mocking mechanisms.\n\nDue to that we decided to go back to the POJO approach as we had it prior to 4.x. This means, if you had extended\nthe `Entry` class to add properties using the `Key` mechanism, we are sorry, but you will have to convert your\nsubclass. \n\n### Json annotations\nNevertheless, some ideas have survived this rollback. Especially automating the conversion and update process is still\nsomething we do not want to miss. To make life a bit easier, there are now annotations to mark class fields for\nautomated conversion and allow them to be updated. Check the `Entry` source code and annotations in the `json` \nsubpackage, if you want or need to use those annotations.\n\n## Deprecated methods have been removed\n### Calendar Entry CRUD\nReplace Calendar Entry CRUD calls with `getEntryProvider().asInMemoryProvider()`, e.g. \n```java\n// before\ncalendar.addEntry(entry);\n\ncalendar.getEntryProvider().asInMemoryProvider().addEntry(entry)\n```\n\nWe know, this might be cumbersome for use cases, where you only use the in memory provider, but with having a cleaner\napi in mind this is a step we need to take. Sorry for the inconvenience.\n\n### Entry Resource API\nResource methods in `Entry` are now more aligned to other Vaadin item api, so replace for instance `assignResources`\nwith `addResources`.\n\n### Other changes\n* RenderingMode has been renamed to DisplayMode to align with the FC library and is a top class now. \n Replace it and related methods respectively.\n* Entry's method `copy(Class)` has been renamed to `copyAsType(Class)`.\n* Entry's method `getResources` now may return `null`. Use `getOrCreateResources`. We wanted to have the names here being aligned to other namings in Entry.\n* `CalendarLocale` is now an enum. This should not affect you in most use cases.\n* The option \"week numbers within days\" is no longer available, week numbers are now always display inside days by the FC library. Simply remove any calls to that setting.\n* Since we used the javax @NotNull annotation a lot for better dx, but Vaadin 24 will no longer support that due to Spring Boot 3, we decided to add our own annotation to provide additional information without potential naming conflicts. \n\n\n# Migrating from 4.0 > 4.1\n## Entry Provider and old CRUD operations\n4.1 most important change is the introduction of EntryProviders. Please see the [examples](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples#entry-providers) for details regarding the different new variants.\n\nBy default the FullCalendar uses an `EagerInMemoryEntryProvider`, which behaves the same way as the FullCalendar did before. This means, this should not be a breaking change for your application. Yet we recommend to change to either the `LazyInMemoryEntryProvider` or a callback variant to use the advantages of the new entry providers.\n\nPlease note, that the Entry CRUD API on the FullCalendar has been marked as deprecated. It is recommended to replace it with the respective API of the eager in memory provider, if you want to stay with that implementation. See the [examples page](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples#in-memory-eager-loading) for an example on how that could look like.\n\n# Migrating from 3.x > 4.0\n## Introduction\n### Timezones\nThe most breaking change when migrating from version 3.x to 4.0 will be that the server side got\nrid of any timezone inclusion regarding date times. You still may set a timezone for the calendar\nor set/get offsetted local date times, but the regular api is now always UTC based and we try to keep\nanything as clear as possible regarding whether a local date time represents a UTC time or a time with offset.\n\nPart of this change is\n* Getter and Setter of Entry start and end have changed in name and meaning\n* Timezones are not applied anymore to the server side times\n* Calendar and event time related api is also now UTC based (e.g. finding entries in a timespan)\n\n### JsonItem\nWith this version also the foundation of the `Entry` type has changed to a more dynamic, automated way of handling and converting properties, when communicating with the client. This is done in a new class `JsonItem` which `Entry` now extends.\n\nIn theory, this should not break your code, unless you have extended the Entry class. In that case please have a look into the examples page or the implementation of Entry to get an idea what has changed. We hope, that we have covered now all basic properties of the client side FullCalendar items and that subclasses are not necessary anymore.\n\nIf you still need your subclass, you may have to overhaul the conversion part. For this case it is not really possible to foresee any implementation details and give advices on those, unfortunately.\n\n## Migration steps / manual in detail\n### Timezone\nBefore heading into all UTC and timezone related changes, the first thing to mention is, that the Timezone class now\nhas some simple methods to apply or remove the offset of the timezone it represents from a local date time to create\nanother ((un)offsetted) local date time to help doing things manual. Just to keep in mind, when one of the following\nthings might seem to be a too breaking change.\n\n### Entry start / end and timezone.\nIf are using the `Instant` based start / end api only, theoretically you do not need to change your code.\nPlease notify that `getStartUTC / getEndUTC` have been deprecated. Replace them at some point with `getStartAsInstant / getEndAsInstant`.\n\nIf are using the `LocalDateTime` based versions, you will most likely need to change your code as the `LocalDateTime` based `getStart / getEnd` and\n`setStart / setEnd` methods are now always referring to UTC and never to the timezones. If you want to set or get the date time including\nthe calendar timezone's offset, please use the newly introduced `getStartWithOffset / getEndWithOffset` and `setStartWithOffset / setEndWithOffset`.\nThey take care of adding/subtracting the timezone's offset - either from the assigned calendar or as parameter.\n\nSince some methods seem to do the same as before, it might feel a bit unnecessary to have the method names changed, but we wanted to assure, that it is always clear, what \"kind\" of date time the respective method is working with. Either with the default (UTC) or some explicit offset.\n\n```java\n// Reading and writing the UTC based backend\n\nTimezone calendarTimezone = ...;\nLocalDateTime utcBasedStartDate = ...\n\n// old\nentry.setStart(utcBasedStartDate, calendarTimezone);\n\n// new\nentry.setStart(utcBasedStartDate);\n```\n\n```java\n// Editing an existing entry inside an edit form\n\nDatePicker datePicker = ...\n\n// old\ndatePicker.setValue(entry.getStart());\n\n// ...value changed by date picker\n\nentry.setStart(datePicker.getValue());\n\n\n// new\ndatePicker.setValue(entry.getStartWithOffset());\n\n// ...value changed by date picker\n\nentry.setStartWithOffset(datePicker.getValue());\n```\n\nThe offset variants with the timezone parameter are intended to be used, when working on a new entry, that\nis not yet added to a calendar. Here the entry cannot access the calendar's timezone. In this case you should use these methods. In all\nother cases we recommend to let the entry handle the timezone conversion internally by using the offset variants without timezone parameter.\n\n```java\n// Creating a new entry and let the user fill it inside an edit form\nTimezone timezone = ...;\nDatePicker datePicker = ...\n\n// old\ndatePicker.setValue(entry.getStart(timezone));\n\n// ...value changed by date picker\n\nentry.setStart(datePicker.getValue(), timezone);\n\n\n// new\ndatePicker.setValue(entry.getStartWithOffset(timezone));\n\n// ...value changed by date picker\n\nentry.setStartWithOffset(datePicker.getValue(), timezone);\n```\n\nSummarized we recommend: when working with your backend (persisting, etc), use the UTC variants. When working with some kind\nof edit form, where the user can modify his/her entry based on the calendar's timezone, use the offset variants. For new entries, that have not yet been added to the calendar, use the offset variants with timezone parameter (in the .\n\n### Entry related events date time\n#### Events and timezones\nAs with the entries also event times are now always UTC based. We tried to align the api the the entry's one in naming and behavior, so that the \"default\" date time is always UTC based, while the offset variant api provides the data with the calendar timezone's offset applied.\n\n```java\n// old\ncalendar.addTimeslotSelectedEvent(event -> {\n Entry entry = new Entry()\n entry.setStart(event.getStartDateTimeUTC());\n entry.setEnd(event.getEndDateTimeUTC());\n\n // if you need the offset variant, use for instance event.getStartDateTime();\n});\n\n// new\ncalendar.addTimeslotSelectedEvent(event -> {\n Entry entry = new Entry()\n entry.setStart(event.getStart());\n entry.setEnd(event.getEnd());\n\n // if you need the offset variant, use for instance event.getStartWithOffset();\n});\n```\n\n#### Renamed getters\nGetters in `TimeslotsSelectedEvent` have changed to be more aligned to the entry's and other events names to simplify the code to read a bit (e. g. from `getStartDateTime` to `getStart`). We added respective methods for getting the Instant and the offsetted variant.\n\n#### Removed getters in all-day related events\nSee chapter [**All-day behavior**](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#all-day-behavior) for details.\n\n### Recurrence\n`setRecurring(boolean)` is gone. There is no replacement for this method, since recurrence is now detected automatically\nbased on if you have set any relevant recurrence property in the entry. See isRecurring() for details, which properties are relevant. This behavior has been taken over from the client side library.\n\n```java\n// old\nentry.setRecurring(recurring);\n\n// new\n// entry.setRecurring(recurring); // not needed anymore, is calculated automatically\n```\n\n`setRecurringStartDate / setRecurringEndDate` has lost the timezone parameter. Remove the timezone parameter. See chapter **All-day behavior** for details.\n\n```java\n// old\nentry.setRecurringStartDate(start.toLocalDate(), timezone);\n\n// new\nentry.setRecurringStartDate(start.toLocalDate());\n```\n\n### All-day behavior\nThe displayment / interpretion of all-day entries and changing timezones has changed. In version 3.x an all-day entry was not bound to the day alone, but\nalso influenced by the timezone. This could lead to effects, that a holiday, which is on a specific day (e. g. New Year),\nspans two days, when switching the timezone. While it might somehow appear to be technically correct, it simply is not from the perspective of a calendar.\nA holiday - or in general an all-day event - is bound to the day, not the time. If you need a day spanning event, that\nis bound to the timezone and \"moves\", when changing the timezone, please create a time based event going over the whole\nday. With this change we align the server side behavior to the client side library and other big calendar providers (for instance Google Calendar).\n\nThis change also affects code at some points. You may have compilation errors for missing `Instant` or `LocalDateTime`\nbased methods, e. g. at `MoreLinkClickedEvent`. Those events provide a `LocalDate` based getter, which you\nshould use instead.\n\nOther events still may provide a date time based getter, where the returned value \"behaves\" now differently for all-day events\nas described above, e. g. all subclasses of `DateTimeEvent`, for instance the `TimeslotClickedEvent`. In 3.x when clicking\nthe 1st of March, the returned date may have been pointing to the 28th of February due to applied timezone\nconversion. Now the returned timestamp will always be the correct day at 00:00 UTC time. Simply ignore the\ntime part in this case or use the `LocalDate` getter.\n\n### Accessing custom properties in eventDidMount or eventContent\nNot a required but a recommended change. If you have customized the appearance of your entries using one of the\ncallbacks `setEntryDidMount()` or `setEntryContent()` (or the respective client side variants) and you access\ncustom properties of an entry (for instance `description`), you should change the access to the newly introduced\n`getCustomProperty()` method. This method takes the custom property key and allows to define a fallback default value\nas second parameter.\n\n```java\n// set the custom property beforehand\nEntry someEntry = ...;\nsomeEntry.setCustomProperty(EntryCustomProperties.DESCRIPTION, \"some description\");\n\ncalendar.setEntryContentCallback(\"\" +\n \"function(info) {\" +\n\n // old\n \"if(info.event.extendedProps && info.eventExtendedProps.customProperty && info.eventExtendedProps.customProperty.description) \"+\n \" console.log(info.event.extendedProps.customProperty.description);\" +\n \"else \" +\n \" console.log('no description set');\" +\n\n // new\n \" console.log(info.event.getCustomProperty('\" +EntryCustomProperties.DESCRIPTION+ \"', 'no description set'));\" + // get custom property with fallback\n\n \" /* ... do something with the event content ...*/\" +\n \" return info.el; \" +\n \"}\"\n);\n```\n\nYou can use that method also in javascript subclasses of the FullCalendar. Please note, that this method is a custom javascript, which is added\nby us as soon as the client side `eventDidMount` or `eventContent` option has been set. Beforehand the method is not present\nand using it will lead to javascript errors.\n\n\n### Deprecation\nSome methods have been deprecated due to typos or ambigious meaning. Please check any compiler warnings and apidocs\nregarding deprecated methods. They might be removed in any upcoming minor or major release without additional\nwarning.\n\n## Removed features\nIf you used a feature in your calendar, that an entry could have a different timezone for start and end:\nthis is not supported anymore out of the box. We know, that this is a step back regarding functionality,\nbut at this point we thing having a straight way of storing the times internally is a bigger and more\ncommon advantage, since this spares a lot of network overhead (entries do not need to be resend on\ntimezone change anymore). Implementing this would have taken too much time now without us knowing, if it is needed at all.\nInstead we wanted to bring you the new version as fast as possible.\n\nIf you need this feature again, please contact us and we will check how to bring it back in one or another way.",
"category": "docs",
"tags": [
"fullcalendar-migrationguides",
"eagerinmemoryentryprovider",
"lazyinmemoryentryprovider",
"inmemoryentryprovider",
"eager",
"customcalendarview",
"anonymouscustomcalendarview",
"entry",
"key",
"calendarlocale",
"jsonitem",
"instant",
"localdatetime",
"migration",
"upgrade",
"event"
]
},
{
"id": "fullcalendar-releasenotes",
"title": "Index",
"path": "FullCalendar-ReleaseNotes.md",
"content": "# Index\n* [6.2.x](#62x)\n* [6.1.x](#61x)\n* [6.0.x](#60x)\n* [4.1.x](#41x)\n* [4.0.x](#40x)\n\n\n# 6.2.x\n[Details](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-Notes-6.2.x)\n- added custom native event handlers for entries\n\n# 6.1.x\n[Details](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-Notes-6.1.x)\n- added an optional Lumo theme for the addon\n\n# 6.0.x\n- updated to FullCalendar 6.1.6\n- Migrated from Polymer 3 to simple HTML Element based web component (no Lit nor Polymer)\n- Migrated source code from JavaScript to TypeScript (ongoing process, not yet finished)\n- Folder structures changed\n- Tag names prefixed with \"vaadin-\"\n- Content is now part of the light dom, thus styling will be easier\n- Client side eager loading removed, items will now always be fetched\n- Added prefetch mode to allow smoother transition between periods\n- Breaking changes regarding methods and fields (client side and server side). Also usage of private / protected modifiers in TS.\n- Added support for FC's \"multi-month\" views.\n- Added proper API for creating and registering custom views. Also added an internal handling of \"anonymous\" custom views created by initial options.\n- Deprecated code from previous versions has been removed\n- JsonItem has been removed, Entry is a \"normal field\" class again due to issues with proxying frameworks\n- setHeight has been minimalized to be more aligned with Vaadin standards. FC internal height settings / options are not\n supported anymore. Calendar content will take only as much space as needed.\n- added type `RecurringTime` to allow setting an entry recurrence of more than 24h\n\n\nMinor changes:\n- getResources now may return null. Use getOrCreateResources.\n- CalendarLocale is now an enum. Use getLocale() to obtain the contained locale value.\n- week numbers within days is no longer available, weeknumbers are now always display inside days.\n- RenderingMode and alike namings have been named to DisplayMode / display to match the FC library naming. Also DisplayMode is now a top level class.\n- added resize observer to client side to automatically take care of resizes\n- added our own @NotNull annotation to allow support for Vaadin 23 and 24\n- Entry's method `copy(Class)` has been renamed to `copyAsType(Class)`.\n\nOther things that we may have overseen :)\n\nDue to lack of time, we have no release note details at this time. We tried to provide additional info as part of the migration page.\n\n# 4.1.x\n[Details](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-Notes-4.1.x)\n- added EntryProvider, a data provider like callback based class to allow lazy loading entries based on the actual displayed timespan\n\n# 4.0.x\n[Details](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-Notes-4.0.x)\n- introduced a new type JsonItem for creating item classes with dynamic property handling and automated conversion from and to json\n- integrated json item api into Entry types for dynamic type conversion. Due to that entries will not send all data to the client, when updating existing ones\n- changed date time handling on server side and communication to be always utc\n- entries are not resent to server anymore when changing timezone on server\n- entry data changes are now sent at once the the client\n- client side entries (\"event\") have now a getCustomProperty method inside eventDidMount or eventContent callbacks\n- removed official support of custom timezones for entries\n- renamed several methods\n- recurrence has some changes regarding enable recurrence and timezones\n",
"category": "docs",
"tags": [
"fullcalendar-releasenotes",
"recurringtime",
"migration",
"upgrade",
"entry",
"event"
]
},
{
"id": "fullcalendar-scheduler-examples",
"title": "Activating the scheduler",
"path": "FullCalendar-Scheduler-Examples.md",
"content": "# Activating the scheduler\n**using the builder**\n```java\nFullCalendar calendar = FullCalendarBuilder.create().withScheduler().build();\n```\n\n**setSchedulerLicenseKey*\n```java\n// scheduler options\n((Scheduler) calendar).setSchedulerLicenseKey(...);\n```\n\n# Adding a resource to a calendar and link it with entries\n```java\nResource resource = new Resource(null, s, color);\ncalendar.addResource(resource);\n\n// When we want to link an entry with a resource, we need to use ResourceEntry\n// (a subclass of Entry)\nResourceEntry entry = new ResourceEntry(null, title, start.atStartOfDay(), start.plusDays(days).atStartOfDay(), true, true, color, \"Some description...\");\nentry.setResource(resource);\ncalendar.addEntry(entry);\n```\n\n# Handling change of an entry's assigned resource by drag and drop\n```java\ncalendar.addEntryDroppedListener(event -> {\n event.applyChangesOnEntry();\n\n Entry entry = event.getEntry();\n\n if(entry instanceof ResourceEntry) {\n Set resources = ((ResourceEntry) entry).getResources();\n if(!resources.isEmpty()) {\n // do something with the resource info\n }\n }\n});\n```\n\n# Switching to a timeline view\n```java\ncalendar.changeView(SchedulerView.TIMELINE_DAY);\n```\n\n# Activate vertical resource view\n```java\ncalendar.setGroupEntriesBy(GroupEntriesBy.RESOURCE_DATE);\n```\n\n# Creating a resource bases background event\nResourceEntry entry = new ResourceEntry();\n// ... setup entry details, including addResource()\n\nentry.setDisplayMode(DisplayMode.BACKGROUND);\ncalendar.addEntry(entry);\n\n# Creating hierarchical resources\n```java\n// Create a parent resource. When adding the sub resources first before adding the parent to the calendar,\n// the sub resources are registered automatically on client side and server side.\n\nResource parent = new Resource();\nparent.addChildren(new Resource(), new Resource(), new Resource());\n\ncalendar.addResource(parent); // will add the resource and also it's children to server and client\n\n// add new resources to already registered parents\nResource child = new Resource()\nparent.addChild(child);\ncalendar.addResource(child); // this will update the client side\n\n// or remove them from already registered ones\ncalendar.removeResource(child); \nparent.removeChild(child); \n```\n\n# Making a resource entry draggable between resources\n```java\n// activate for the client to have an entry being draggable between resources\nresourceEntry.setResourceEditableOnClientSide(true);\n\n// update the entry on the client side, if it is already added to the calendar\ncalendar.refreshAll();\n```",
"category": "docs",
"tags": [
"fullcalendar-scheduler-examples",
"scheduler",
"resource",
"entry",
"event"
]
},
{
"id": "fullcalendar-scheduler-functionality",
"title": "FullCalendar-Scheduler-Functionality",
"path": "FullCalendar-Scheduler-Functionality.md",
"content": "This addon uses a 3rd party library called FullCalendar Scheduler. We try to integrate all features the library provides. Therefore\nthe following list might not include all available features, but should list the most important ones. If you find\na feature in the FC library, that this addon not yet supports, please create an feature request in the issues page.\n\n- adding / removing resources (hierarchies of resources are supported)\n- Link one or multiple resources with entries.\n- Activation of the Scheduler by method in the FullCalendarBuilder.\n- List of possible Scheduler based views (timeline).\n- List of possible Scheduler entries grouping.\n\n- Event handling for\n - Timeslot clicked\n - Timeslots slected\n - Entry dropped\n\n*Info:* Entries are linked to calendar internally. The calendar instance is used to resolve resources by after updating an\nentry on the client side.",
"category": "docs",
"tags": [
"fullcalendar-scheduler-functionality",
"scheduler",
"resource",
"entry",
"event"
]
},
{
"id": "fullcalendar-scheduler-license",
"title": "Activating the Scheduler - [Example](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Scheduler-Examples#activating-the-scheduler)",
"path": "FullCalendar-Scheduler-License.md",
"content": "The FullCalendar Scheduler library has a different license model then the basic FullCalendar.\n\nFor more details please visit https://fullcalendar.io/license and https://fullcalendar.io/docs/plugin-index\n\n**This addon does not provide any commercial license for the Scheduler. The license model of MIT does only affect the additional files of this addon, not the used original files.**\n\n# Activating the Scheduler - [Example](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Scheduler-Examples#activating-the-scheduler)\n\nBy default the scheduler is not active, when you use a FullCalendar instance. To have an instance with scheduler activated, use the `.withScheduler(...)` method of the `FullCalendarBuilder`.\n\nThis method will throw an exception, if the scheduler extension is not on the class path.\n\nTo link a resource with entries, use the Entry subclass `ResourceEntry`.",
"category": "docs",
"tags": [
"fullcalendar-scheduler-license",
"fullcalendarbuilder",
"resourceentry",
"scheduler",
"resource",
"entry",
"event"
]
},
{
"id": "fullcalendar-scheduler",
"title": "FullCalendar-Scheduler",
"path": "FullCalendar-Scheduler.md",
"content": "This addon extends the **FullCalendar for Flow** addon with the **FullCalendar Scheduler**, which provides\nadditional resource based views (Timeline View and Vertical Resource View) for Vaadin 23+.\n\nIt is based on the latest version of the FullCalendar Scheduler library 6.x.\n\nIt needs the [basic addon](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar) to work.\nSince this addon is not always updated when the basis gets an update, I suggest, that you add both dependencies\n(basis and extension) to always use the latest versions. This extension is compatible as long as the readme\ndoes not tells anything else.\n\n## Requirements / versions / support\nThe addon is built against Vaadin 14.x and Java 8, but is intended to be used with the latest major Vaadin version\nand thus also supports Vaadin 23 and 24 / Java 11+.\n\nAddon versions prior to the current major version are not supported anymore. If you need a fix for such a version\nfeel free to fork the project. You may create an issue, but due to limited time it is very unlikely, that we will fix\nit.\n\nPlease also have a look at the demo for some basic examples and source code of how to integrate the FC.\nFor more examples please have a look into the example section.",
"category": "docs",
"tags": [
"fullcalendar-scheduler",
"scheduler",
"resource"
]
},
{
"id": "getting-started",
"title": "Getting Started",
"path": "Getting-Started.md",
"content": "# Getting Started\n\nThis guide will help you add FullCalendar for Vaadin Flow to your project.\n\n## Requirements\n\n- **Version 7.x**: Vaadin 25+ / Java 21+\n- **Version 6.x**: Vaadin 14-24 / Java 11+\n\n## Maven Dependency\n\nAdd the Vaadin Directory repository to your `pom.xml`:\n\n```xml\n\n \n vaadin-addons\n https://maven.vaadin.com/vaadin-addons\n \n\n```\n\nAdd the core dependency:\n\n```xml\n\n org.vaadin.stefan\n fullcalendar2\n 7.1.5-SNAPSHOT\n\n```\n\n### Scheduler Extension (Optional)\n\nIf you need resource-based views (Timeline, Vertical Resource), add the Scheduler extension:\n\n```xml\n\n org.vaadin.stefan\n fullcalendar2-scheduler\n 7.1.5-SNAPSHOT\n\n```\n\n**Note**: The Scheduler extension requires a separate [commercial license](https://fullcalendar.io/pricing) from FullCalendar LLC for production use. The MIT license of this addon only covers the Java integration code.\n\n## Basic Usage\n\nCreate a simple calendar and add it to your view:\n\n```java\n// Create the calendar\nFullCalendar calendar = FullCalendarBuilder.create().build();\ncalendar.setSizeFull();\n\n// Add it to your layout\nadd(calendar);\n\n// Create and add an entry\nEntry entry = new Entry();\nentry.setTitle(\"My Event\");\nentry.setStart(LocalDate.now().atTime(10, 0));\nentry.setEnd(LocalDate.now().atTime(12, 0));\n\ncalendar.getEntryProvider().asInMemory().addEntry(entry);\n```\n\n## Next Steps\n\n- Check the [Samples](Samples) for more code examples\n- Review [Features](Features) for a full feature overview\n- See the [FAQ](FAQ) for common questions and troubleshooting\n- If you use AI tools like Claude, Cursor, or Copilot, check out our [MCP Server](MCP-Server) for enhanced assistance with the addon\n",
"category": "docs",
"tags": [
"getting-started",
"scheduler",
"resource",
"entry",
"event"
]
},
{
"id": "home",
"title": "Home",
"path": "Home.md",
"content": "Welcome to the FullCalendar for Flow documentation. Here you will find different information about\nthe Flow integration of the [FullCalendar library](https://fullcalendar.io).\n\n## Quick Links\n\n- [Getting Started](Getting-Started) - Installation and basic setup\n- [Samples](Samples) - Code examples\n- [Features](Features) - Feature overview\n- [FAQ](FAQ) - Common questions and troubleshooting\n- [Migration Guides](Migration-guides) - Upgrading between versions\n\nFor general information about the project, please check to the\n[project's readme](https://github.com/stefanuebe/vaadin-fullcalendar).",
"category": "docs",
"tags": [
"home"
]
},
{
"id": "known-issues",
"title": "Known-Issues",
"path": "Known-Issues.md",
"content": "## Known Issues\n\n### Multiline events drag & drop cause the scrollbar to lose position\nThe problem appears when you remove the events and add them back. When you remove all the events from the calendar it resizes itself. When the calendar has no events, it is much shorter which explains why the scroll position is changing.\n\nTake a look here for a workaround https://github.com/stefanuebe/vaadin-fullcalendar/issues/76\n\nAnother good way to fix it is to provide the resources/events as JSON feed and refetch the events instead of removing and adding them back.\n\n### Build problems / JS (client side) errors\nIt might be that the transitive dependencies are not resolved correctly. This mostly happens in Spring Boot due to its built-in class path scanning, which is adapted by Vaadin.\n\nPlease ensure that, if you are using the `vaadin.allowed-packages` property, it lists the addon's package `org.vaadin.stefan` (or simply `org.vaadin`).\n\nIf you are not using any allowed or blocking list in the properties and still have the issue, please check if you have added the `@EnableVaadin` annotation to your Spring application class. If that is the case, check if there are packages listed. If yes, add the package `org.vaadin.stefan` to it.\n\nIf the annotation is not added or added without any parameter and the issue occurs, please add the package `org.vaadin.stefan` plus other necessary packages that have to be scanned, as parameters.\n\nThis should enable Spring to analyze all relevant npm dependencies at runtime. Other CDI versions should work the same.\n\n### Entry cache limits\nThe calendar maintains an internal cache of entries limited to 10,000 items (LRU eviction). This is to prevent unbounded memory growth when using lazy-loaded entry providers with large datasets. If you need more entries cached, consider implementing a custom caching strategy.\n\n### Server-defined JavaScript callbacks\nThe addon uses `new Function()` to evaluate server-defined JavaScript callbacks (e.g., for entry render hooks). This is intentional and allows the server to define client-side behavior dynamically. See [FullCalendar Event Render Hooks](https://fullcalendar.io/docs/event-render-hooks) for the underlying feature.\n\n## Notes for Custom Subclasses\n\nWhen creating custom TypeScript/JavaScript subclasses of FullCalendar:\n\n1. **Prevent duplicate event handler registration**: Use a flag (e.g., `_tooltipInitialized`) to ensure event handlers are only registered once, even if `initCalendar()` is called multiple times.\n\n2. **Clean up resources**: If you add ResizeObservers or other resources, clean them up in `disconnectedCallback()` to prevent memory leaks.",
"category": "docs",
"tags": [
"known-issues",
"entry",
"event"
]
},
{
"id": "mcp-server",
"title": "FullCalendar Vaadin MCP Server",
"path": "MCP-Server.md",
"content": "# FullCalendar Vaadin MCP Server\n\nModel Context Protocol (MCP) server providing documentation, API reference, and code examples for the [FullCalendar Vaadin Flow](https://github.com/stefanuebe/vaadin-fullcalendar) addon.\n\nUse this MCP server to help AI assistants (Claude, GitHub Copilot, etc.) understand and work with FullCalendar in your Vaadin projects.\n\n## Quick Start\n\nAdd the MCP server to your AI assistant's configuration:\n\n### Claude Code / Claude Desktop\n\nAdd to your MCP configuration (`.mcp.json`, `claude_desktop_config.json`, or settings):\n\n```json\n{\n \"mcpServers\": {\n \"fullcalendar\": {\n \"type\": \"http\",\n \"url\": \"https://v-herd.eu/vaadin-fullcalendar-mcp/mcp\"\n }\n }\n}\n```\n\n### Project-Level Configuration (CLAUDE.md)\n\nAdd this to your project's `CLAUDE.md` to automatically enable the server for that project:\n\n```markdown\n## MCP Servers\n\nFullCalendar Vaadin documentation server:\n\n\\`\\`\\`json\n{\n \"mcpServers\": {\n \"fullcalendar\": {\n \"type\": \"http\",\n \"url\": \"https://v-herd.eu/vaadin-fullcalendar-mcp/mcp\"\n }\n }\n}\n\\`\\`\\`\n```\n\n### Other MCP Clients\n\nPoint your MCP client to:\n- **MCP endpoint**: `https://v-herd.eu/vaadin-fullcalendar-mcp/mcp`\n- **Health check**: `https://v-herd.eu/vaadin-fullcalendar-mcp/health`\n\n## What You Can Do\n\nOnce configured, your AI assistant can:\n\n- **Set up new projects** - Get correct Maven dependencies and repository configuration\n- **Search documentation** - Find relevant docs, examples, and API references\n- **Explore the API** - Get detailed class documentation with methods and fields\n- **Find code examples** - Get working code for common use cases\n- **Understand the data model** - Learn Entry and Resource properties\n- **Migrate between versions** - Get migration guides for version upgrades\n\n## Available Tools\n\n### `get_maven_dependency`\nGet Maven coordinates, repository config, and pom.xml snippets for project setup.\n\n```json\n{ \"name\": \"get_maven_dependency\", \"arguments\": { \"includeScheduler\": true } }\n```\n\nReturns ready-to-use configuration:\n- Artifact IDs: `org.vaadin.stefan:fullcalendar2` and `fullcalendar2-scheduler`\n- Repository: Vaadin Directory (`https://maven.vaadin.com/vaadin-addons`)\n- Version compatibility (v7 for Vaadin 25+, v6 for Vaadin 14-24)\n\n### `search_docs`\nSearch across all documentation, API reference, and code examples.\n\n```json\n{ \"name\": \"search_docs\", \"arguments\": { \"query\": \"how to add entries\", \"limit\": 10 } }\n```\n\n### `get_api_reference`\nGet detailed API reference for a Java class.\n\n```json\n{ \"name\": \"get_api_reference\", \"arguments\": { \"className\": \"FullCalendar\" } }\n```\n\n### `list_classes`\nList all available Java classes, optionally filtered.\n\n```json\n{ \"name\": \"list_classes\", \"arguments\": { \"filter\": \"Entry\", \"source\": \"addon\" } }\n```\n\n### `get_code_example`\nGet code examples for specific use cases.\n\n```json\n{ \"name\": \"get_code_example\", \"arguments\": { \"search\": \"drag and drop\", \"category\": \"events\" } }\n```\n\n### `get_entry_schema`\nGet the Entry model schema with all properties, types, and descriptions.\n\n### `get_resource_schema`\nGet the Resource model schema (Scheduler extension) with all properties.\n\n### `list_calendar_views`\nList all available calendar views (DayGrid, TimeGrid, List, Timeline, etc.).\n\n```json\n{ \"name\": \"list_calendar_views\", \"arguments\": { \"includeScheduler\": true } }\n```\n\n### `list_event_types`\nList all server-side event types that can be listened to.\n\n```json\n{ \"name\": \"list_event_types\", \"arguments\": { \"source\": \"core\" } }\n```\n\n### `get_migration_guide`\nGet migration guide for upgrading between versions.\n\n```json\n{ \"name\": \"get_migration_guide\", \"arguments\": { \"toVersion\": \"7\" } }\n```\n\n### `get_documentation`\nGet full documentation page content.\n\n```json\n{ \"name\": \"get_documentation\", \"arguments\": { \"path\": \"Getting-Started.md\" } }\n```\n\nAvailable pages: `Getting-Started.md`, `Samples.md`, `Features.md`, `FAQ.md`, `Migration-guides.md`, `Known-issues.md`, `Scheduler-license.md`\n\n## Features\n\n- **Hybrid Search**: Semantic search (OpenAI embeddings) with keyword search fallback\n- **Complete API Reference**: All Java classes with methods, fields, and constructors\n- **Code Examples**: 50+ examples extracted from documentation and demo sources\n- **Model Schemas**: Entry and Resource property definitions with types\n- **Calendar Views**: All 44 views with descriptions (including Scheduler views)\n- **Event Types**: Server-side event documentation\n- **Migration Guides**: Version upgrade instructions\n- **Maven Setup**: Dependency coordinates and pom.xml snippets\n\n---\n\n## Self-Hosting\n\nIf you need to run your own instance of the MCP server (e.g., for custom modifications or offline use), follow the instructions below.\n\n### Using Docker\n\n```bash\ncd mcp-server\ndocker build -t fullcalendar-mcp .\ndocker run -p 3000:3000 fullcalendar-mcp\n```\n\nFor semantic search (optional), pass an OpenAI API key:\n\n```bash\ndocker run -p 3000:3000 -e OPENAI_API_KEY=sk-... fullcalendar-mcp\n```\n\n### Local Development\n\n```bash\ncd mcp-server\n\n# Install dependencies\nnpm install\n\n# Extract data from source files\nnpm run extract\n\n# Start development server\nnpm run dev\n\n# Or build and start production server\nnpm run build\nnpm start\n```\n\n### Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `PORT` | Server port | `3000` |\n| `OPENAI_API_KEY` | OpenAI API key for semantic search | (keyword search only) |\n| `DATA_PATH` | Path to extracted data JSON | `./data/extracted.json` |\n| `PROJECT_ROOT` | Root of FullCalendar project (for extraction) | `../` |\n\n### Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `POST /mcp` | MCP JSON-RPC endpoint |\n| `POST /` | Alternative MCP endpoint |\n| `GET /health` | Health check |\n| `GET /info` | Server statistics |\n\n### Architecture\n\n```\nsrc/\n├── index.ts # Express HTTP server with MCP protocol\n├── types.ts # TypeScript type definitions\n├── tools/\n│ └── index.ts # Tool handler implementations\n├── search/\n│ ├── index.ts # Hybrid search orchestration\n│ ├── keyword-search.ts # FlexSearch-based keyword search\n│ └── semantic-search.ts# OpenAI embeddings search\n└── extractors/\n ├── extract-all.ts # Main extraction script\n ├── java-extractor.ts # Java source parser\n ├── docs-extractor.ts # Markdown documentation parser\n └── model-extractor.ts# Model schema extractor\n```\n\n### Updating Documentation\n\nThe server extracts documentation at build time. To update:\n\n1. Pull latest changes to the FullCalendar repository\n2. Run `npm run extract` or rebuild the Docker image\n3. Restart the server\n\n---\n\n## License\n\nMIT License - see the main project LICENSE file.\n\nThe FullCalendar Scheduler extension requires a separate [commercial license](https://fullcalendar.io/pricing) from FullCalendar LLC for production use.\n",
"category": "docs",
"tags": [
"mcp-server",
"port",
"migration",
"upgrade",
"scheduler",
"resource",
"entry",
"event"
]
},
{
"id": "migration-guide-3.x-to-4.0",
"title": "Migration-guide-3.x-to-4.0",
"path": "Migration-guide-3.x-to-4.0.md",
"content": "## Introduction\n### Timezones\nThe most breaking change when migrating from version 3.x to 4.0 will be that the server side got\nrid of any timezone inclusion regarding date times. You still may set a timezone for the calendar\nor set/get offsetted local date times, but the regular api is now always UTC based and we try to keep\nanything as clear as possible regarding whether a local date time represents a UTC time or a time with offset.\n\nPart of this change is\n* Getter and Setter of Entry start and end have changed in name and meaning\n* Timezones are not applied anymore to the server side times\n* Calendar and event time related api is also now UTC based (e.g. finding entries in a timespan)\n\n### JsonItem\nWith this version also the foundation of the `Entry` type has changed to a more dynamic, automated way of handling and converting properties, when communicating with the client. This is done in a new class `JsonItem` which `Entry` now extends.\n\nIn theory, this should not break your code, unless you have extended the Entry class. In that case please have a look into the examples page or the implementation of Entry to get an idea what has changed. We hope, that we have covered now all basic properties of the client side FullCalendar items and that subclasses are not necessary anymore.\n\nIf you still need your subclass, you may have to overhaul the conversion part. For this case it is not really possible to foresee any implementation details and give advices on those, unfortunately.\n\n## Migration steps / manual in detail\n### Timezone\nBefore heading into all UTC and timezone related changes, the first thing to mention is, that the Timezone class now\nhas some simple methods to apply or remove the offset of the timezone it represents from a local date time to create\nanother ((un)offsetted) local date time to help doing things manual. Just to keep in mind, when one of the following\nthings might seem to be a too breaking change.\n\n### Entry start / end and timezone.\nIf you are using the `Instant` based start / end api only, theoretically you do not need to change your code.\nPlease notify that `getStartUTC / getEndUTC` have been deprecated. Replace them at some point with `getStartAsInstant / getEndAsInstant`.\n\nIf you are using the `LocalDateTime` based versions, you will most likely need to change your code as the `LocalDateTime` based `getStart / getEnd` and\n`setStart / setEnd` methods are now always referring to UTC and never to the timezones. If you want to set or get the date time including\nthe calendar timezone's offset, please use the newly introduced `getStartWithOffset / getEndWithOffset` and `setStartWithOffset / setEndWithOffset`.\nThey take care of adding/subtracting the timezone's offset - either from the assigned calendar or as parameter.\n\nSince some methods seem to do the same as before, it might feel a bit unnecessary to have the method names changed, but we wanted to assure, that it is always clear, what \"kind\" of date time the respective method is working with. Either with the default (UTC) or some explicit offset.\n\n```java\n// Reading and writing the UTC based backend\n\nTimezone calendarTimezone = ...;\nLocalDateTime utcBasedStartDate = ...\n\n// old\nentry.setStart(utcBasedStartDate, calendarTimezone);\n\n// new\nentry.setStart(utcBasedStartDate);\n```\n\n```java\n// Editing an existing entry inside an edit form\n\nDatePicker datePicker = ...\n\n// old\ndatePicker.setValue(entry.getStart());\n\n// ...value changed by date picker\n\nentry.setStart(datePicker.getValue());\n\n\n// new\ndatePicker.setValue(entry.getStartWithOffset());\n\n// ...value changed by date picker\n\nentry.setStartWithOffset(datePicker.getValue());\n```\n\nThe offset variants with the timezone parameter are intended to be used, when working on a new entry, that\nis not yet added to a calendar. Here the entry cannot access the calendar's timezone. In this case you should use these methods. In all\nother cases we recommend to let the entry handle the timezone conversion internally by using the offset variants without timezone parameter.\n\n```java\n// Creating a new entry and let the user fill it inside an edit form\nTimezone timezone = ...;\nDatePicker datePicker = ...\n\n// old\ndatePicker.setValue(entry.getStart(timezone));\n\n// ...value changed by date picker\n\nentry.setStart(datePicker.getValue(), timezone);\n\n\n// new\ndatePicker.setValue(entry.getStartWithOffset(timezone));\n\n// ...value changed by date picker\n\nentry.setStartWithOffset(datePicker.getValue(), timezone);\n```\n\nSummarized we recommend: when working with your backend (persisting, etc), use the UTC variants. When working with some kind\nof edit form, where the user can modify his/her entry based on the calendar's timezone, use the offset variants. For new entries, that have not yet been added to the calendar, use the offset variants with the calendar's timezone parameter.\n\n### Entry related events date time\n#### Events and timezones\nAs with the entries also event times are now always UTC based. We tried to align the api the the entry's one in naming and behavior, so that the \"default\" date time is always UTC based, while the offset variant api provides the data with the calendar timezone's offset applied.\n\n```java\n// old\ncalendar.addTimeslotSelectedEvent(event -> {\n Entry entry = new Entry()\n entry.setStart(event.getStartDateTimeUTC());\n entry.setEnd(event.getEndDateTimeUTC());\n\n // if you need the offset variant, use for instance event.getStartDateTime();\n});\n\n// new\ncalendar.addTimeslotSelectedEvent(event -> {\n Entry entry = new Entry()\n entry.setStart(event.getStart());\n entry.setEnd(event.getEnd());\n\n // if you need the offset variant, use for instance event.getStartWithOffset();\n});\n```\n\n#### Renamed getters\nGetters in `TimeslotsSelectedEvent` have changed to be more aligned to the entry's and other events names to simplify the code to read a bit (e. g. from `getStartDateTime` to `getStart`). We added respective methods for getting the Instant and the offsetted variant.\n\n#### Removed getters in all-day related events\nSee chapter [All-day behavior](#all-day-behavior) for details.\n\n### Recurrence\n`setRecurring(boolean)` is gone. There is no replacement for this method, since recurrence is now detected automatically\nbased on if you have set any relevant recurrence property in the entry. See isRecurring() for details, which properties are relevant. This behavior has been taken over from the client side library.\n\n```java\n// old\nentry.setRecurring(recurring);\n\n// new\n// entry.setRecurring(recurring); // not needed anymore, is calculated automatically\n```\n\n`setRecurringStartDate / setRecurringEndDate` has lost the timezone parameter. Remove the timezone parameter. See chapter [All-day behavior](#all-day-behavior) for details.\n\n```java\n// old\nentry.setRecurringStartDate(start.toLocalDate(), timezone);\n\n// new\nentry.setRecurringStartDate(start.toLocalDate());\n```\n\n### All-day behavior\nThe displayment / interpretion of all-day entries and changing timezones has changed. In version 3.x an all-day entry was not bound to the day alone, but\nalso influenced by the timezone. This could lead to effects, that a holiday, which is on a specific day (e. g. New Year),\nspans two days, when switching the timezone. While it might somehow appear to be technically correct, it simply is not from the perspective of a calendar.\nA holiday - or in general an all-day event - is bound to the day, not the time. If you need a day spanning event, that\nis bound to the timezone and \"moves\", when changing the timezone, please create a time based event going over the whole\nday. With this change we align the server side behavior to the client side library and other big calendar providers (for instance Google Calendar).\n\nThis change also affects code at some points. You may have compilation errors for missing `Instant` or `LocalDateTime`\nbased methods, e. g. at `MoreLinkClickedEvent`. Those events provide a `LocalDate` based getter, which you\nshould use instead.\n\nOther events still may provide a date time based getter, where the returned value \"behaves\" now differently for all-day events\nas described above, e. g. all subclasses of `DateTimeEvent`, for instance the `TimeslotClickedEvent`. In 3.x when clicking\nthe 1st of March, the returned date may have been pointing to the 28th of February due to applied timezone\nconversion. Now the returned timestamp will always be the correct day at 00:00 UTC time. Simply ignore the\ntime part in this case or use the `LocalDate` getter.\n\n### Accessing custom properties in eventDidMount or eventContent\nNot a required but a recommended change. If you have customized the appearance of your entries using one of the\ncallbacks `setEntryDidMountCallback(...)` or `setEntryContentCallback(...)`\nand you access custom properties of an entry (for instance `description`), you should change the access to the newly\nintroduced `getCustomProperty()` method. This method takes the custom property key and allows to define a fallback\ndefault value as second parameter.\n\n> **Note (7.1):** The `setEntryContentCallback` and `setEntryDidMountCallback` methods shown below are\n> deprecated as of 7.1. Use `setOption(Option.ENTRY_CONTENT, JsCallback.of(...))` instead.\n> The `getCustomProperty()` access pattern inside the callback remains the same.\n\n```java\n// set the custom property beforehand\nEntry someEntry = ...;\nsomeEntry.setCustomProperty(EntryCustomProperties.DESCRIPTION, \"some description\");\n\ncalendar.setEntryContentCallback(\"\" +\n \"function(info) {\" +\n\n // old\n \"if(info.event.extendedProps && info.eventExtendedProps.customProperty && info.eventExtendedProps.customProperty.description) \"+\n \" console.log(info.event.extendedProps.customProperty.description);\" +\n \"else \" +\n \" console.log('no description set');\" +\n\n // new\n \" console.log(info.event.getCustomProperty('\" +EntryCustomProperties.DESCRIPTION+ \"', 'no description set'));\" + // get custom property with fallback\n\n \" /* ... do something with the event content ...*/\" +\n \" return info.el; \" +\n \"}\"\n);\n```\n\nYou can use that method also in javascript subclasses of the FullCalendar. Please note, that this method is a custom javascript, which is added\nby us as soon as the client side `eventDidMount` or `eventContent` option has been set. Beforehand the method is not present\nand using it will lead to javascript errors.\n\n\n### Deprecation\nSome methods have been deprecated due to typos or ambigious meaning. Please check any compiler warnings and apidocs\nregarding deprecated methods. They might be removed in any upcoming minor or major release without additional\nwarning.\n\n## Removed features\nIf you used a feature in your calendar, that an entry could have a different timezone for start and end:\nthis is not supported anymore out of the box. We know, that this is a step back regarding functionality,\nbut at this point we thing having a straight way of storing the times internally is a bigger and more\ncommon advantage, since this spares a lot of network overhead (entries do not need to be resend on\ntimezone change anymore). Implementing this would have taken too much time now without us knowing, if it is needed at all.\nInstead we wanted to bring you the new version as fast as possible.\n\nIf you need this feature again, please contact us and we will check how to bring it back in one or another way.\n",
"category": "docs",
"tags": [
"migration-guide-3.x-to-4.0",
"entry",
"jsonitem",
"instant",
"localdatetime",
"timeslotsselectedevent",
"morelinkclickedevent",
"localdate",
"datetimeevent",
"timeslotclickedevent",
"migration",
"upgrade",
"event"
]
},
{
"id": "migration-guide-4.0-to-4.1",
"title": "Migration-guide-4.0-to-4.1",
"path": "Migration-guide-4.0-to-4.1.md",
"content": "## Entry Provider and old CRUD operations\n\n4.1's most important change is the introduction of `EntryProvider`. The direct entry CRUD API on `FullCalendar` is deprecated; use an `EntryProvider` instead.\n\n```java\n// Old (4.0)\ncalendar.addEntry(entry);\ncalendar.removeEntry(entry);\ncalendar.getEntries();\n```\n\n```java\n// New (4.1) — eager in-memory variant (same behavior as before 4.1)\nEagerInMemoryEntryProvider provider = new EagerInMemoryEntryProvider<>();\ncalendar.setEntryProvider(provider);\n\nprovider.addEntry(entry);\nprovider.removeEntry(entry);\nprovider.getEntries();\n```\n\nBy default the `FullCalendar` still uses an `EagerInMemoryEntryProvider`, so the old behavior is preserved if you do not explicitly set a provider. The old CRUD API on `FullCalendar` keeps working but is marked `@Deprecated`.\n\n## Recommended: lazy or callback variant\n\nFor larger data sets, we recommend switching to `LazyInMemoryEntryProvider` or a callback-based provider:\n\n```java\n// Callback variant — backend fetches entries on demand per time range\nCallbackEntryProvider provider = EntryProvider.fromCallbacks(\n query -> myRepository.findByRange(query.getStart(), query.getEnd()).stream(),\n id -> myRepository.findById(id).orElse(null)\n);\ncalendar.setEntryProvider(provider);\n```\n\nSee the [FullCalendar Examples wiki page](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples#entry-providers) for complete code samples of each variant.\n\n> **Note:** `EagerInMemoryEntryProvider` was removed in v6.0. If you skip v5.x and jump to 6.x, see the [4.1 → 6.0 guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-4.1-to-6.0) for the replacement (`InMemoryEntryProvider`, now lazy-only).\n",
"category": "docs",
"tags": [
"migration-guide-4.0-to-4.1",
"entryprovider",
"fullcalendar",
"eagerinmemoryentryprovider",
"lazyinmemoryentryprovider",
"inmemoryentryprovider",
"migration",
"upgrade",
"entry",
"event"
]
},
{
"id": "migration-guide-4.1-to-6.0",
"title": "Migration-guide-4.1-to-6.0",
"path": "Migration-guide-4.1-to-6.0.md",
"content": "Depending on your Vaadin version you may need to update also other things, related to Vaadin core.\nSteps to be taken there, will not be covered here.\n\n## Removed polymer\nSince Polymer has been removed from Vaadin 24, we decided to convert the JS elements to plain, HTML element based\nweb components. Thus, this version should work with Vaadin 23 and 24. \n\nFor most cases this should not affect your application. However, if you subclasses the javascript classes, you may need\nto adapt some of the changes. Any Polymer related feature needs to be converted to plain javascript. If you used\nproperties, you should still be able to set those via the Flow Java API, but you simply have to declare them as normal\nJS class fields. \n\nAlso please note, that the content of the component is now part of the light dom. This will most likely affect\nany custom stylings you may have defined. See the next part for details.\n\n## Styling\nSince the component is now part of the light dom, you have the advantages and disadvantages of it. \n\nAny custom styles you may have defined via overriding the JS class or via using the Java method `addCustomStyles`\ncan now be simply defined via plain css style files. So simply take your css snippets and move them to your global\ncss styles (however they are structured).\n\nPlease be aware, that due to being part of the light dom, any other stylings may bleed into the FC now or vice versa.\nBut our experience showed, that the majority of our user base preferred the light dom variant, thus we decided to\ngo this way.\n\nAlso since we moved to a new major of the FC library, it might be, that css selectors have changed in their \nprovided styles and thus your custom styles might not work out of the box.\n\n## Folder structure and tags\nWe changed the folder structure and tag names a bit to better represent the Vaadin nature of this addon and to\nprevent potential naming conflicts. Therefore the the files will now be placed inside a folder named\n`vaadin-full-calendar`. The file names themselves have not changed.\n\nIf you subclasses one of the FC JavaScript classes, simply update the folder structure to be something like\n`@vaadin/flow-frontend/vaadin-full-calendar/full-calendar`. You may need to add the file suffix \".ts\".\n\nAdditionally we prefixed the element tag names with a `vaadin-`, so that the FC itself now has the tag \n`vaadin-full-calendar`. This is relevant, if you used the old tag names for styling or dom querying purposes.\nIn that case update the tag names.\n\n## TypeScript\nWe migrated the old JS files to TypeScript. But this process is not yet done and thus there are many things still in\nprogress (mainly the definition of custom types and some code refinement). \n\nNevertheless, for the normal use case, this has no effect. If you subclassed the JS classes, feel free to convert\nit to TypeScript, but be aware, we do not yet have any fancy TypeScript stuff. But it will come somewhere in future ;)\n\nThings to have in mind when migrating: We use protected and private modifiers of typescript now. Any underscores \nhave been removed and the methods / fields have become private or protected. For instance the `_initCalendar()` method\nis now named `initCalendar()`. This is one of the most important ones - if you have subclassed the FC, you most likely\nhave overridden this method and have to update your code. We recommend to use the `override` modifier, so that the \ncompiler marks any issues regarding such cases.\n\n### Issues with webpack\nThere is a known issue with webpack, that will most likely lead to issues, when starting the application.\n\nCheck the \"Known Issues\" page for details (> Startup issue when using webpack (Vaadin 14-23)).\n\n## No more EagerInMemoryEntryProvider\nTo make maintenance of the client side a bit easier and less error prone, we decided to remove the \n`EagerInMemoryEntryProvider` and thus have the client side always be in \"lazy loading\" mode. This means, that there is \nno official way anymore to move all entries to the client side at once.\n\nOf course you still can override this behavior by using simple JS, but we do not recommend to do\nthat as all infrastructure is built around the fetching mechanisms.\n\nThe `LazyInMemoryEntryProvider` has been renamed to `InMemoryEntryProvider`. Rename all imports and class occurrences.\nAlso the static methods inside EntryProvider have been renamed from `lazyInMemoryFromItems` to `inMemoryFrom`.\n\nReplace any usage of the eager variant with the (now) default one. You also need to call `refreshAll`/`refreshItem` \nafter you changed the data in the provider. This behavior aligns to the behavior to the normal Vaadin data provider.\n\nThe `updateMethod` of the eager variant has no replacement in the default one, as items are not pushed to the client,\nbut fetched. When the client shall be updated, call the refresh methods instead.\n\nThere are also other methods, that where some variant of `Eager`. Simply replace them with the now default one and\ncheck, if refreshs are necessary in your use cases.\n\n### Prefetch mode\nThere is now a prefetch mode, that allows fetching adjacent periods. This shall prevent flickering, when switching\nto the previous/next period. See the samples page for details.\n\n## Custom views\nUp to now custom views had to be created as a Java class but could only be registered via initial options. To\nmake life a bit easier here, the interface `CustomCalendarView` has been added plus methods to register those. \n\nIt is recommended to convert your views and use this new interface. While the old way should still work\nand lead to `AnonymousCustomCalendarView` instances, a warning will be printed onto the error console.\n\nCheck the `CustomCalendarView` docs for additional information. The relevant method is `getViewSettings()`.\n\nPlease note, that due to limitations of the FC library, views can only be set at initialization time.\n\n## Entry is \"static\" again, JsonItem is gone\nThis part describes a rare use case and should not be affecting most of the FC users.\n\nWith 4.x we tried to make the `Entry` structure more dynamic to allow easier definition of new properties and automate\nthe update mechanism a bit. Unfortunately the approach we took was not practicable in all use cases and we even had\nsome issues with proxying and mocking mechanisms.\n\nDue to that we decided to go back to the POJO approach as we had it prior to 4.x. This means, if you had extended\nthe `Entry` class to add properties using the `Key` mechanism, we are sorry, but you will have to convert your\nsubclass. \n\n### Json annotations\nNevertheless, some ideas have survived this rollback. Especially automating the conversion and update process is still\nsomething we do not want to miss. To make life a bit easier, there are now annotations to mark class fields for\nautomated conversion and allow them to be updated. Check the `Entry` source code and annotations in the `json` \nsubpackage, if you want or need to use those annotations.\n\n## Deprecated methods have been removed\n### Calendar Entry CRUD\nReplace Calendar Entry CRUD calls with `getEntryProvider().asInMemory()`, e.g. \n```java\n// before\ncalendar.addEntry(entry);\n\n// after\ncalendar.getEntryProvider().asInMemory().addEntry(entry);\n```\n\nWe know, this might be cumbersome for use cases, where you only use the in memory provider, but with having a cleaner\napi in mind this is a step we need to take. Sorry for the inconvenience.\n\n### Entry Resource API\nResource methods in `Entry` are now more aligned to other Vaadin item api, so replace for instance `assignResources`\nwith `addResources`.\n\n### Other changes\n* RenderingMode has been renamed to DisplayMode to align with the FC library and is a top class now. \n Replace it and related methods respectively.\n* Entry's method `copy(Class)` has been renamed to `copyAsType(Class)`.\n* Entry's method `getResources` now may return `null`. Use `getOrCreateResources`. We wanted to have the names here being aligned to other namings in Entry.\n* `CalendarLocale` is now an enum. This should not affect you in most use cases.\n* The option \"week numbers within days\" is no longer available, week numbers are now always display inside days by the FC library. Simply remove any calls to that setting.\n* Since we used the javax @NotNull annotation a lot for better dx, but Vaadin 24 will no longer support that due to Spring Boot 3, we decided to add our own annotation to provide additional information without potential naming conflicts. \n",
"category": "docs",
"tags": [
"migration-guide-4.1-to-6.0",
"eagerinmemoryentryprovider",
"lazyinmemoryentryprovider",
"inmemoryentryprovider",
"eager",
"customcalendarview",
"anonymouscustomcalendarview",
"entry",
"key",
"calendarlocale",
"migration",
"upgrade",
"event"
]
},
{
"id": "migration-guide-6.3-to-6.4",
"title": "Migrating from 6.3 to 6.4",
"path": "Migration-guide-6.3-to-6.4.md",
"content": "# Migrating from 6.3 to 6.4\n\nVersion 6.4 modernizes the addon for Vaadin 24.10 while backporting v7 features. This guide covers the upgrade path and breaking changes.\n\n> For earlier versions (6.2 or 6.1), see the [v6.0 migration guide](Migration-guides.md#migrating-from-41--60) first.\n\n## Prerequisites\n\nBefore upgrading to 6.4, ensure your project meets this requirement:\n\n| Requirement | Minimum Version |\n|-------------|-----------------|\n| **Vaadin** | 24.10.x |\n\n**Note**: Vaadin 14 is no longer supported. If you're on Vaadin 14, you must upgrade to Vaadin 24.10 first.\n\n## Step 1: Update Maven Dependencies\n\nIn your `pom.xml`, update the FullCalendar addon version:\n\n```xml\n\n org.vaadin.stefan\n fullcalendar2\n 6.4.0\n\n\n\n\n org.vaadin.stefan\n fullcalendar2-scheduler\n 6.4.0\n\n```\n\nRun Maven to fetch the new version:\n\n```bash\nmvn clean dependency:tree\n```\n\n## Step 2: Handle Breaking Changes\n\n### Overlap Field Type Change\n\nThe `Entry.overlap` field has changed from `boolean` (primitive) to `Boolean` (nullable):\n\n**Before (6.3)**:\n```java\nentry.setOverlap(true);\nboolean overlap = entry.isOverlap(); // Returns primitive boolean\n```\n\n**After (6.4)**:\n```java\nentry.setOverlap(true);\nBoolean overlap = entry.getOverlap(); // Returns nullable Boolean\n```\n\n**What changed**:\n- `isOverlap()` is deprecated in 6.4; `getOverlap()` is the non-deprecated replacement\n- `boolean` → `Boolean` (type changed to nullable)\n- `null` is now a distinct state: when null, the entry inherits the calendar-level `eventOverlap` setting; when `false`, overlap is always denied for this entry\n\n**Migration**:\n- Replace `isOverlap()` calls with `getOverlap()`. `isOverlap()` still compiles but is deprecated and coalesces `null` to `true`; `getOverlap()` gives you the raw nullable value\n- If you need a primitive, use: `Boolean overlap = entry.getOverlap(); boolean value = overlap != null && overlap;`\n- Update any comparisons: `if (overlap != null && overlap)` instead of `if (overlap)`\n\n**Recompilation against the 6.4 JAR is required.**\n\n## Step 3: Update Deprecated Method Calls (Optional)\n\nWhile deprecated methods still work, consider replacing them with the unified `setOption()` API for consistency.\n\n### Common Deprecated Methods → Replacements\n\n| Deprecated Method | Replacement |\n|-------------------|-------------|\n| `setFirstDay(DayOfWeek)` | `setOption(Option.FIRST_DAY, DayOfWeek.MONDAY)` |\n| `setWeekends(boolean)` | `setOption(Option.WEEKENDS, true)` |\n| `setEntryDidMountCallback(String)` | `setOption(Option.ENTRY_DID_MOUNT, JsCallback.of(...))` |\n\n**Example**:\n\n```java\n// Before (6.3)\ncalendar.setFirstDay(DayOfWeek.MONDAY);\ncalendar.setWeekends(false);\n\n// After (6.4) — preferred approach\ncalendar.setOption(Option.FIRST_DAY, DayOfWeek.MONDAY);\ncalendar.setOption(Option.WEEKENDS, false);\n```\n\nDeprecated methods are still functional and have `@Deprecated` annotations visible in your IDE. Replace them at your convenience — they remain supported in 6.4.\n\n## Step 4: Optional — Adopt New v7 Features\n\n### Use RRule for Recurring Entries\n\nIf you were using the legacy recurrence fields (`recurringDaysOfWeek`, `recurringStartDate`, `recurringEndDate`), consider switching to RRule:\n\n**Before (6.3 — legacy approach)**:\n```java\nEntry entry = new Entry(\"Weekly Meeting\");\nentry.setStart(LocalDateTime.of(2025, 3, 24, 10, 0));\nentry.setEnd(LocalDateTime.of(2025, 3, 24, 11, 0));\nentry.setRecurringDaysOfWeek(DayOfWeek.MONDAY, DayOfWeek.FRIDAY);\nentry.setRecurringStartDate(LocalDate.of(2025, 3, 1));\nentry.setRecurringEndDate(LocalDate.of(2025, 12, 31));\ncalendar.getEntryProvider().asInMemory().addEntry(entry);\n```\n\n**After (6.4 — RRule approach)**:\n```java\nEntry entry = new Entry(\"Weekly Meeting\");\nentry.setStart(LocalDateTime.of(2025, 3, 24, 10, 0));\nentry.setEnd(LocalDateTime.of(2025, 3, 24, 11, 0));\n\nRRule rule = RRule.weekly()\n .byWeekday(DayOfWeek.MONDAY, DayOfWeek.FRIDAY)\n .until(LocalDate.of(2025, 12, 31));\n\nentry.setRRule(rule);\ncalendar.getEntryProvider().asInMemory().addEntry(entry);\n```\n\nBoth approaches work, but RRule is more powerful (supports exclusions, complex patterns, RFC 5545 import).\n\n### Adopt New Entry Fields\n\nThe new fields (`url`, `interactive`) are optional but recommended:\n\n```java\nEntry entry = new Entry(\"Conference Talk\");\nentry.setUrl(\"https://conference.example.com/talks/opening-keynote\");\nentry.setInteractive(true); // Allows dragging and resizing\ncalendar.getEntryProvider().asInMemory().addEntry(entry);\n```\n\n## Step 5: Handle New NPM Dependencies\n\nThe following npm packages are automatically loaded:\n\n- `@fullcalendar/rrule`\n- `@fullcalendar/google-calendar`\n- `@fullcalendar/icalendar`\n- `ical.js`\n\n**You don't need to do anything** — they're bundled automatically in the addon JAR. If you have a custom npm build process, no changes are required.\n\n## Step 6: Recompile and Test\n\n```bash\nmvn clean verify\n```\n\nRestart your development server and verify.\n\nTest the following:\n\n1. Calendar renders and loads entries\n2. Drag and drop still work\n3. Entry creation/editing dialogs function\n4. Custom styling (if any) still applies\n5. Entry provider (if used) still loads data correctly\n\n## Troubleshooting\n\n### Compilation Error: \"cannot find symbol: method isOverlap()\"\n\n**Cause**: In 6.4, `isOverlap()` is deprecated but still available. This error typically means the addon dependency is not correctly resolved. If you have a subclass of `Entry` that overrides `isOverlap()` with a `boolean` return type, it now conflicts with the `Boolean` return type.\n\n**Fix**:\n```java\n// Replace:\nboolean value = entry.isOverlap();\n\n// With:\nBoolean value = entry.getOverlap();\n```\n\n### Compilation Error: \"incompatible types: Boolean cannot be converted to boolean\"\n\n**Cause**: You're assigning the result of `getOverlap()` to a primitive `boolean`.\n\n**Fix**:\n```java\n// Replace:\nboolean value = entry.getOverlap();\n\n// With:\nBoolean value = entry.getOverlap();\n// Or, to convert to primitive:\nboolean value = entry.getOverlap() != null && entry.getOverlap();\n```\n\n### Calendar Not Rendering\n\n**Cause**: Vaadin 24.10 not properly configured or stale frontend cache.\n\n**Check**:\n```bash\ngrep \"vaadin.version\" pom.xml\n```\n\nEnsure the Vaadin version is 24.10 or later, then clear your browser cache and reload:\n```bash\nmvn clean install\n```\n\n### RRule Entries Not Recurring\n\n**Cause**: RRule entries may require the `@fullcalendar/rrule` plugin, which is included but may need a page reload.\n\n**Fix**: Hard-refresh your browser (Ctrl+Shift+R / Cmd+Shift+R) to clear cached JavaScript.\n\n## Important Notes\n\n- **No automatic migration script**: Breaking changes are minimal, but review code for `isOverlap()` and deprecated method calls.\n- **Backward compatibility**: Apart from the `overlap` field type change, v6.3 code should work with minimal changes.\n- **Binary compatibility**: If you compiled v6.3 with `boolean` overlap, recompilation against v6.4 is required.\n\n## Next Steps\n\n- Review the [Release Notes](release-notes-detail/Release-notes-6.4.md) for new features\n- Check the [demo module](https://github.com/stefanuebe/vaadin-fullcalendar) for usage examples\n- File issues on [GitHub](https://github.com/stefanuebe/vaadin-fullcalendar/issues) if problems arise\n\n---\n\n*Revision: March 2026*\n",
"category": "docs",
"tags": [
"migration-guide-6.3-to-6.4",
"boolean",
"entry",
"migration",
"upgrade",
"scheduler",
"resource",
"event"
]
},
{
"id": "migration-guide-6.4-to-6.5",
"title": "Migration-guide-6.4-to-6.5",
"path": "Migration-guide-6.4-to-6.5.md",
"content": "This guide covers upgrading from v6.4.x to v6.5.0.\n\n**What 6.5 is:** a **backport of the 7.2 feature set** to the v6 line (Vaadin 24 / Java 17 / elemental JSON). If you can move to Vaadin 25 / Java 21, upgrade to 7.2 instead — that's the forward line; 6.5 is for teams that need to stay on V24. 6.5 and 7.2 ship the same feature set; the choice is about platform, not functionality.\n\n**Platform:** FullCalendar JS 6.1.20, Vaadin 24.9.x, Java 17, elemental JSON — same stack as 6.4.\n\n**Source compatibility:** 6.5 is a minor release. Existing source compiles against 6.5 unchanged; all migration steps below are **optional** and deprecated API continues to work throughout 6.x.\n\n**Binary compatibility (one caveat):** `Entry.setEditable(...)`'s JVM descriptor changed from `(Z)V` (primitive) to `(Ljava/lang/Boolean;)V` (boxed) as part of the fix for [#212](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-notes-6.5#per-entry-editable-default-no-longer-overrides-calendar-level-editable-false-212). Existing call sites that pass `true`/`false` continue to compile (Java auto-boxes at the call site). A downstream artifact that was compiled against 6.4 and runs unchanged on 6.5 would hit `NoSuchMethodError` on that single method — the normal \"rebuild your app with the new addon on the classpath\" flow avoids this. No other public method descriptors changed.\n\n**Vocabulary used below:**\n- *Start segment* — FullCalendar renders multi-day entries as one DOM element per day-cell; the \"start segment\" is the one rendered on the entry's first day.\n- *`applyChangesOnEntry()`* — method on `EntryDataEvent` subclasses (drop/resize) that copies the client-side change onto the server-side `Entry`. Skipping this call is the trigger for auto-revert.\n\n## Rolling back to 6.4 behaviour\n\nTwo new default-on behaviours landed in 6.5. The auto-revert change (#225) is the more behaviourally impactful one — see the upgrade-impact call-out under [#225](#new-auto-revert-for-unapplied-entry-changes-225) below. If you hit unexpected issues with either, switch them off in one place to get the 6.4 defaults back:\n\n```java\ncalendar.setAutoProvideEntryIdOnClient(false); // revert id propagation (#202)\ncalendar.setAutoRevertUnappliedEntryChanges(false); // revert auto-revert (#225)\n```\n\nAll other 6.5 changes are either opt-in (new API like `Option.INITIAL_VIEW`) or pure bug fixes (#212, #230, #231) — those have no runtime switch because reverting them would re-introduce the bug.\n\n## New: Client-side entry IDs provided automatically (#202)\n\nEnabled by default. Each rendered entry's start segment receives `id=\"entry-\"` on the DOM, so server-side components (e.g. `Popover`) can anchor via `document.getElementById`. See [Release notes 6.5](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-notes-6.5#client-side-entry-ids-provided-automatically-202) for details.\n\nNo code changes required to benefit. To opt out:\n\n```java\ncalendar.setAutoProvideEntryIdOnClient(false);\n```\n\n**If you already set `id` in a custom `eventDidMount` callback in 6.4:** your callback now runs AFTER the default id-assignment, so reassigning `info.el.id` inside your callback still wins. No change required. If your callback used to check `if (!info.el.id)` before assigning, that condition will now be false — remove the guard or call `setAutoProvideEntryIdOnClient(false)`.\n\n## New: Auto-revert for unapplied entry changes (#225)\n\nEnabled by default. Entries dragged or resized on the client now revert to their original position if `event.applyChangesOnEntry()` is not called on the server. See [Release notes 6.5](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-notes-6.5#auto-revert-for-unapplied-entry-changes-225) for details.\n\n**Upgrade impact — check your drop/resize listeners.** In 6.4 a listener that did *not* call `applyChangesOnEntry()` left the client showing the new position while the server kept the old `start`/`end` — visually the drop/resize appeared accepted, but server state diverged. In 6.5 that same listener will instead animate the entry back to its original position. If your 6.4 code relied on the client keeping the new position without calling `applyChangesOnEntry()`, pick one of:\n\n- add `event.applyChangesOnEntry();` in the listener so the server-side entry matches what the client shows, or\n- keep the old divergence by calling `setAutoRevertUnappliedEntryChanges(false)` (not recommended — server and client will be out of sync).\n\nNo code changes required if your 6.4 listeners already call `applyChangesOnEntry()` on every accepted drop/resize. To opt out entirely:\n\n```java\ncalendar.setAutoRevertUnappliedEntryChanges(false);\n```\n\n## Deprecated: `FullCalendarBuilder`\n\n`FullCalendarBuilder` is deprecated since 6.5.0. **No removal is scheduled for 6.x** — the class will continue to work throughout the 6.x line and is only slated for removal in a future major version. `FullCalendar` and `FullCalendarScheduler` can be constructed directly and configured through `setOption(Option, value)`; the builder no longer provides value beyond syntactic sugar.\n\n### Migration table\n\n| Builder call | Replacement |\n|---|---|\n| `FullCalendarBuilder.create().build()` | `new FullCalendar()` |\n| `.withScheduler().build()` | `new FullCalendarScheduler()` |\n| `.withScheduler(key).build()` | `new FullCalendarScheduler()` + `setOption(Option.SCHEDULER_LICENSE_KEY, key)` |\n| `.withInitialOptions(obj).build()` | `new FullCalendar(obj)` / `new FullCalendarScheduler(obj)` |\n| `.withEntryLimit(n).build()` | `new FullCalendar()` + `setOption(Option.MAX_ENTRIES_PER_DAY, n)` |\n| `.withEntryProvider(p).build()` | `new FullCalendar()` + `setEntryProvider(p)` |\n| `.withInitialEntries(entries).build()` | `FullCalendar calendar = new FullCalendar();`
`((InMemoryEntryProvider) calendar.getEntryProvider()).addEntries(entries);` — see caveat below |\n| `.withInitialView(view).build()` | `new FullCalendar()` + `setOption(Option.INITIAL_VIEW, view.getClientSideValue())` |\n| `.withLocale(l).build()` / `.withTimezone(t).build()` / `.withBusinessHours(h).build()` | `new FullCalendar()` + `setLocale(l)` / `setTimezone(t)` / `setBusinessHours(h)` |\n| `.withDirection(d).build()` | `new FullCalendar()` + `setOption(Option.DIRECTION, d.getClientSideValue())` |\n| `.withAutoBrowserTimezone().build()` | `new FullCalendar()` + `addBrowserTimezoneObtainedListener(e -> calendar.setTimezone(e.getTimezone()))` |\n| `.withAutoBrowserLocale().build()` | `new FullCalendar()` + `setLocale(UI.getCurrent().getLocale())` (after UI is available) |\n| `.withCustomCalendarViews(views).build()` | `new FullCalendar()` + `setCustomCalendarViews(views)` |\n| `.withCustomType(Cls.class).build()` | `new Cls()` — the builder previously instantiated a user-provided `FullCalendar` subclass via reflection; direct construction is simpler |\n\n**Caveats:**\n\n- *`withInitialEntries` replacement assumes the default in-memory entry provider is still in place.* A fresh `new FullCalendar()` ships with an `InMemoryEntryProvider`, so the cast is safe. Only call this before switching to a different provider — otherwise the cast will fail at runtime.\n- *`withInitialView` replacement uses the new `Option.INITIAL_VIEW` constant, added in 6.5 after verifying that FullCalendar 6.1.20 applies the `initialView` option correctly on first render (the pre-6.5 builder carried an attach-listener + `changeView()` workaround that is no longer needed). The option takes the FC view key as a String; pass `view.getClientSideValue()` on any `CalendarView` — typically a `CalendarViewImpl` enum constant like `TIME_GRID_WEEK`. Example:*\n ```java\n FullCalendar calendar = new FullCalendar();\n calendar.setOption(Option.INITIAL_VIEW, CalendarViewImpl.TIME_GRID_WEEK.getClientSideValue());\n ```\n\n### Example\n\n```java\n// Old (6.4)\nFullCalendarScheduler scheduler = (FullCalendarScheduler) FullCalendarBuilder.create()\n .withScheduler(licenseKey)\n .withEntryLimit(5)\n .withLocale(Locale.GERMAN)\n .build();\n```\n\n```java\n// New (6.5)\nFullCalendarScheduler scheduler = new FullCalendarScheduler();\nscheduler.setOption(Option.SCHEDULER_LICENSE_KEY, licenseKey);\nscheduler.setOption(Option.MAX_ENTRIES_PER_DAY, 5);\nscheduler.setLocale(Locale.GERMAN);\n```\n\nDeprecated methods still work in 6.5.x. Migration is recommended but not urgent.\n\n## Also deprecated in 6.5.0\n\n- **`FullCalendar(int entryLimit)` and `FullCalendarScheduler(int entryLimit)` constructors** — replaced by `new FullCalendar()` + `setOption(Option.MAX_ENTRIES_PER_DAY, n)`.\n- **`Delta.getYears()` and `Delta.getMonths()`** — deprecated (see #191). FullCalendar JS normalises any year/month span into `days` before emitting the delta, so both always return zero for drop/resize events. Use `delta.getDays()` plus the time components. No behaviour change.\n- **`EntryDataEvent.createCopyBasedOnChanges()`** — renamed to `getChangesAsEntry()` for clarity. The old name still works and delegates to the new method; no behaviour change.\n ```java\n // 6.4\n Entry copy = event.createCopyBasedOnChanges();\n // 6.5\n Entry copy = event.getChangesAsEntry();\n ```\n",
"category": "docs",
"tags": [
"migration-guide-6.4-to-6.5",
"nosuchmethoderror",
"entrydataevent",
"entry",
"popover",
"fullcalendarbuilder",
"fullcalendar",
"fullcalendarscheduler",
"inmemoryentryprovider",
"calendarview",
"calendarviewimpl",
"migration",
"upgrade",
"scheduler",
"resource",
"event"
]
},
{
"id": "migration-guide-6.x-to-7.x",
"title": "Migration-guide-6.x-to-7.x",
"path": "Migration-guide-6.x-to-7.x.md",
"content": "This guide covers the platform switch from the v6 line (Vaadin 24 / Java 17 / elemental JSON) to the v7 line (Vaadin 25 / Java 21 / Jackson 3). It is purely technical — no addon features are added or removed across the jump if you follow the version mapping below.\n\n**Prerequisite:** you are ready to move your application to Vaadin 25 (Java 21, Jackson 3). The Vaadin platform upgrade itself is covered by [Vaadin's own migration docs](https://vaadin.com/docs/latest/upgrading); this guide covers the addon-facing changes you will need to make on top of that.\n\n## Pick your v7 target\n\nTo avoid mixing a platform migration with a feature-delta migration, jump to the v7 release that ships the same addon feature set as your current v6:\n\n| From (v6) | Target (v7) — feature parity | Notes |\n|---|---|---|\n| 6.5 | **7.2** | same addon feature set on a different platform |\n| 6.4 | **7.1** | same addon feature set on a different platform |\n| 6.3 or older | *go via 6.4 first* | follow [6.3 → 6.4](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-6.3-to-6.4) first to absorb the 6.3→6.4 feature deltas, then continue here |\n\nWhen new 6.x releases ship, this table gains matching entries (6.6 ↔ 7.3, etc.). You can also jump to a different v7.x than your paired target, but that combines a platform migration with a feature-delta migration at once — cleaner to do the feature-delta hop inside v6 first and then use this guide for the platform switch.\n\nOnce you're on the paired v7.x, use the [within-7.x migration guides](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guides) to move further forward.\n\n## JSON framework: elemental.json → Jackson 3\n\nv7 replaces elemental.json with Jackson 3 (`com.fasterxml.jackson`). This only affects you if you use these types directly — for example, in custom converters implementing `JsonItemPropertyConverter`, or when inspecting `EntryDataEvent#getJsonObject()`.\n\n| Old (elemental.json) | New (Jackson 3) |\n|---|---|\n| `JsonObject` | `ObjectNode` |\n| `JsonArray` | `ArrayNode` |\n| `JsonValue` | `JsonNode` |\n| `json.hasKey(key)` | `json.has(key)` / `json.hasNonNull(key)` |\n| `json.put(key, value)` | `json.set(key, value)` (for `JsonNode` children) |\n| `json.keys()` | `json.propertyNames()` |\n| `array.set(array.length(), value)` | `array.add(value)` — elemental appends via `set(length(), ...)`; Jackson's `add()` appends directly. |\n| `JsonUtils.toJsonValue()` | `JsonUtils.toJsonNode()` |\n| `JsonUtils.ofJsonValue()` | `JsonUtils.ofJsonNode()` |\n\n**Note:** `CustomCalendarView.getViewSettings()` returns `ObjectNode` (Jackson) instead of `JsonObject` (elemental). Update any custom view implementations accordingly.\n\n## BusinessHours API\n\n*Introduced in 7.0; documented here for readers coming from v6.* The `BusinessHours` constructors have been replaced with a fluent static factory API:\n\n```java\n// Old (v6)\nnew BusinessHours(LocalTime.of(9, 0), LocalTime.of(17, 0), DayOfWeek.MONDAY, DayOfWeek.FRIDAY);\n\n// New (v7) — fluent builder\nBusinessHours.builder()\n .start(LocalTime.of(9, 0))\n .end(LocalTime.of(17, 0))\n .dayOfWeeks(DayOfWeek.MONDAY, DayOfWeek.FRIDAY)\n .build();\n\n// Or for a standard Mon–Fri business week:\nBusinessHours.businessWeek().start(LocalTime.of(9, 0)).end(LocalTime.of(17, 0));\n```\n\n## Theme variant rename\n\n*Introduced in 7.0; documented here for readers coming from v6.* `FullCalendarVariant.LUMO` has been renamed to `FullCalendarVariant.VAADIN`. Update any references.\n\n## CSS design tokens\n\nThe addon's built-in CSS uses these Lumo tokens internally. If you have **custom CSS** that references the addon's theme variables directly, switch to Vaadin 25's unified `--vaadin-*` tokens, which work across both the Lumo and Aura themes:\n\n| Old (Lumo) | New (Vaadin unified) |\n|---|---|\n| `--lumo-base-color` | `--vaadin-background-color` |\n| `--lumo-body-text-color` | `--vaadin-text-color` |\n| `--lumo-contrast-10pct` | `--vaadin-border-color-secondary` |\n| `--lumo-contrast-20pct` | `--vaadin-border-color` |\n| `--lumo-space-xs` | `--vaadin-padding-xs` |\n| `--lumo-border-radius-s` | `--vaadin-radius-s` |\n\nThis only applies if your own CSS references those addon theme variables. Stock usage needs no changes.\n\n## Aura theme support\n\nv7 supports the Aura theme (Vaadin 25). The addon's CSS automatically includes Aura fallbacks — no action required.\n",
"category": "docs",
"tags": [
"migration-guide-6.x-to-7.x",
"jsonitempropertyconverter",
"jsonobject",
"objectnode",
"jsonarray",
"arraynode",
"jsonvalue",
"jsonnode",
"businesshours",
"migration",
"upgrade",
"entry",
"event"
]
},
{
"id": "migration-guide-7.1-to-7.2",
"title": "Migration-guide-7.1-to-7.2",
"path": "Migration-guide-7.1-to-7.2.md",
"content": "This guide covers upgrading from v7.1.x to v7.2.0.\n\n**Platform:** 7.2 keeps the same platform baseline as 7.1 — FullCalendar JS 6.1.20, Vaadin 25.x, Java 21, Jackson 3.\n\n**Source compatibility:** 7.2 is a minor release. Existing source compiles against 7.2 unchanged; all migration steps below are **optional** and deprecated API continues to work throughout 7.x.\n\n**Binary compatibility (one caveat):** `Entry.setEditable(...)`'s JVM descriptor changed from `(Z)V` (primitive) to `(Ljava/lang/Boolean;)V` (boxed) as part of the fix for [#212](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-notes-7.2#per-entry-editable-default-no-longer-overrides-calendar-level-editable-false-212). Existing call sites that pass `true`/`false` continue to compile (Java auto-boxes at the call site). A downstream artifact that was compiled against 7.1 and runs unchanged on 7.2 would hit `NoSuchMethodError` on that single method — the normal \"rebuild your app with the new addon on the classpath\" flow avoids this. No other public method descriptors changed.\n\n**Vocabulary used below:**\n- *Start segment* — FullCalendar renders multi-day entries as one DOM element per day-cell; the \"start segment\" is the one rendered on the entry's first day.\n- *`applyChangesOnEntry()`* — method on `EntryDataEvent` subclasses (drop/resize) that copies the client-side change onto the server-side `Entry`. Skipping this call is the trigger for auto-revert.\n\n## Rolling back to 7.1 behaviour\n\nTwo new default-on behaviours landed in 7.2. The auto-revert change (#225) is the more behaviourally impactful one — see the upgrade-impact call-out under [#225](#new-auto-revert-for-unapplied-entry-changes-225) below. If you hit unexpected issues with either, switch them off in one place to get the 7.1 defaults back:\n\n```java\ncalendar.setAutoProvideEntryIdOnClient(false); // revert id propagation (#202)\ncalendar.setAutoRevertUnappliedEntryChanges(false); // revert auto-revert (#225)\n```\n\nAll other 7.2 changes are either opt-in (new API like `Option.INITIAL_VIEW`) or pure bug fixes (#212, #230, #231) — those have no runtime switch because reverting them would re-introduce the bug.\n\n## New: Client-side entry IDs provided automatically (#202)\n\nEnabled by default. Each rendered entry's start segment receives `id=\"entry-\"` on the DOM, so server-side components (e.g. `Popover`) can anchor via `document.getElementById`. See [Release notes 7.2](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-notes-7.2#client-side-entry-ids-provided-automatically-202) for details.\n\nNo code changes required to benefit. To opt out:\n\n```java\ncalendar.setAutoProvideEntryIdOnClient(false);\n```\n\n**If you already set `id` in a custom `eventDidMount` callback in 7.1:** your callback now runs AFTER the default id-assignment, so reassigning `info.el.id` inside your callback still wins. No change required. If your callback used to check `if (!info.el.id)` before assigning, that condition will now be false — remove the guard or call `setAutoProvideEntryIdOnClient(false)`.\n\n## New: Auto-revert for unapplied entry changes (#225)\n\nEnabled by default. Entries dragged or resized on the client now revert to their original position if `event.applyChangesOnEntry()` is not called on the server. See [Release notes 7.2](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-notes-7.2#auto-revert-for-unapplied-entry-changes-225) for details.\n\n**Upgrade impact — check your drop/resize listeners.** In 7.1 a listener that did *not* call `applyChangesOnEntry()` left the client showing the new position while the server kept the old `start`/`end` — visually the drop/resize appeared accepted, but server state diverged. In 7.2 that same listener will instead animate the entry back to its original position. If your 7.1 code relied on the client keeping the new position without calling `applyChangesOnEntry()`, pick one of:\n\n- add `event.applyChangesOnEntry();` in the listener so the server-side entry matches what the client shows, or\n- keep the old divergence by calling `setAutoRevertUnappliedEntryChanges(false)` (not recommended — server and client will be out of sync).\n\nNo code changes required if your 7.1 listeners already call `applyChangesOnEntry()` on every accepted drop/resize. To opt out entirely:\n\n```java\ncalendar.setAutoRevertUnappliedEntryChanges(false);\n```\n\n## Deprecated: `FullCalendarBuilder`\n\n`FullCalendarBuilder` is deprecated since 7.2.0. **No removal is scheduled for 7.x** — the class will continue to work throughout the 7.x line and is only slated for removal in a future major version. `FullCalendar` and `FullCalendarScheduler` can be constructed directly and configured through `setOption(Option, value)`; the builder no longer provides value beyond syntactic sugar.\n\n### Migration table\n\n| Builder call | Replacement |\n|---|---|\n| `FullCalendarBuilder.create().build()` | `new FullCalendar()` |\n| `.withScheduler().build()` | `new FullCalendarScheduler()` |\n| `.withScheduler(key).build()` | `new FullCalendarScheduler()` + `setOption(Option.SCHEDULER_LICENSE_KEY, key)` |\n| `.withInitialOptions(obj).build()` | `new FullCalendar(obj)` / `new FullCalendarScheduler(obj)` |\n| `.withEntryLimit(n).build()` | `new FullCalendar()` + `setOption(Option.MAX_ENTRIES_PER_DAY, n)` |\n| `.withEntryProvider(p).build()` | `new FullCalendar()` + `setEntryProvider(p)` |\n| `.withInitialEntries(entries).build()` | `new FullCalendar()` + `((InMemoryEntryProvider) calendar.getEntryProvider()).addEntries(entries)` — see caveat below |\n| `.withInitialView(view).build()` | `new FullCalendar()` + `setOption(Option.INITIAL_VIEW, view.getClientSideValue())` |\n| `.withLocale(l).build()` / `.withTimezone(t).build()` / `.withBusinessHours(h).build()` | `new FullCalendar()` + `setLocale(l)` / `setTimezone(t)` / `setBusinessHours(h)` |\n| `.withDirection(d).build()` | `new FullCalendar()` + `setOption(Option.DIRECTION, d.getClientSideValue())` |\n| `.withAutoBrowserTimezone().build()` | `new FullCalendar()` + `addBrowserTimezoneObtainedListener(e -> calendar.setTimezone(e.getTimezone()))` |\n| `.withAutoBrowserLocale().build()` | `new FullCalendar()` + `setLocale(UI.getCurrent().getLocale())` (after UI is available) |\n| `.withCustomCalendarViews(views).build()` | `new FullCalendar()` + `setCustomCalendarViews(views)` |\n| `.withCustomType(Cls.class).build()` | `new Cls()` — the builder previously instantiated a user-provided `FullCalendar` subclass via reflection; direct construction is simpler |\n\n**Caveats:**\n\n- *`withInitialEntries` replacement assumes the default in-memory entry provider is still in place.* A fresh `new FullCalendar()` ships with an `InMemoryEntryProvider`, so the cast is safe. Only call this before switching to a different provider — otherwise the cast will fail at runtime.\n- *`withInitialView` replacement uses the new `Option.INITIAL_VIEW` constant, added in 7.2 after verifying that FullCalendar 6.1.20 applies the `initialView` option correctly on first render (earlier FC versions needed an attach-listener + `changeView()` workaround, which is why the pre-7.2 builder carried it). The option takes the FC view key as a String; pass `view.getClientSideValue()` on any `CalendarView` — typically a `CalendarViewImpl` enum constant like `TIME_GRID_WEEK`. Example:*\n ```java\n FullCalendar calendar = new FullCalendar();\n calendar.setOption(Option.INITIAL_VIEW, CalendarViewImpl.TIME_GRID_WEEK.getClientSideValue());\n ```\n\n### Example\n\n```java\n// Old (7.1)\nFullCalendarScheduler scheduler = (FullCalendarScheduler) FullCalendarBuilder.create()\n .withScheduler(licenseKey)\n .withEntryLimit(5)\n .withLocale(Locale.GERMAN)\n .build();\n```\n\n```java\n// New (7.2)\nFullCalendarScheduler scheduler = new FullCalendarScheduler();\nscheduler.setOption(Option.SCHEDULER_LICENSE_KEY, licenseKey);\nscheduler.setOption(Option.MAX_ENTRIES_PER_DAY, 5);\nscheduler.setLocale(Locale.GERMAN);\n```\n\nDeprecated methods still work in 7.2.x. Migration is recommended but not urgent.\n\n## Also deprecated in 7.2.0\n\n- **`FullCalendar(int entryLimit)` and `FullCalendarScheduler(int entryLimit)` constructors** — replaced by `new FullCalendar()` + `setOption(Option.MAX_ENTRIES_PER_DAY, n)`.\n- **`Delta.getYears()` and `Delta.getMonths()`** — deprecated (see #191). FullCalendar JS normalises any year/month span into `days` before emitting the delta, so both always return zero for drop/resize events. Use `delta.getDays()` plus the time components. No behaviour change.\n- **`EntryDataEvent.createCopyBasedOnChanges()`** — renamed to `getChangesAsEntry()` for clarity. The old name still works and delegates to the new method; no behaviour change.\n ```java\n // 7.1\n Entry copy = event.createCopyBasedOnChanges();\n // 7.2\n Entry copy = event.getChangesAsEntry();\n ```\n",
"category": "docs",
"tags": [
"migration-guide-7.1-to-7.2",
"nosuchmethoderror",
"entrydataevent",
"entry",
"popover",
"fullcalendarbuilder",
"fullcalendar",
"fullcalendarscheduler",
"inmemoryentryprovider",
"calendarview",
"calendarviewimpl",
"migration",
"upgrade",
"scheduler",
"resource",
"event"
]
},
{
"id": "migration-guides",
"title": "Migration-guides",
"path": "Migration-guides.md",
"content": "We know that migrations suck. Not only developers fear the appearance of a new major version but also every\nproduct or project manager of an application, that uses 3rd party software, knows, that it can be a stressful and time consuming horror to\nintegrate a new major version.\n\nUnfortunately this applies also for this addon. There will be breaking changes here and there, that requires you to get back\ninto your code and review everything. Nevertheless, we hope, that this migration guide helps you as good as possible\nto get a detailed insight of what has changed and what needs to be done to get you back on track.\n\nIf we missed something or anything is unclear, please ping us on GitHub. We hope, that your upgrade goes through\nas smoothly as possible.\n\n## Upgrading within 7.x\n\n- [7.1 → 7.2](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-7.1-to-7.2) — client-side entry IDs (#202), auto-revert (#225), `FullCalendarBuilder` deprecation (#232), `Entry.setEditable` binary-compat caveat (#212), `Delta.getYears/getMonths` deprecation (#191), `createCopyBasedOnChanges` → `getChangesAsEntry` rename\n\n\n## Upgrading to v7 / Vaadin 25\n\n- [v6.x → v7.x](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-6.x-to-7.x) — Vaadin 24 to 25. Includes a 6 ↔ 7 version mapping table so you can jump to the v7 release with the same feature set you have today.\n\n## Upgrading within 6.x\n\n- [6.4 → 6.5](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-6.4-to-6.5) — backport of the 7.2 feature set (auto-revert, client-side entry IDs, `FullCalendarBuilder` deprecation, `setEditable` binary-compat caveat, Delta / `createCopyBasedOnChanges` deprecations) to Vaadin 24 / Java 17 / elemental JSON\n- [6.3 → 6.4](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-6.3-to-6.4) — Vaadin 14 to 24.10 plus v7 feature backports. If your target is v7, do this hop first and then continue via the [v6.x → v7.x](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-6.x-to-7.x) guide.\n\n## Older upgrades\n\n- [4.1 → 6.0](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-4.1-to-6.0) — Polymer removal, light DOM, TypeScript\n- [4.0 → 4.1](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-4.0-to-4.1) — introduction of `EntryProvider`\n- [3.x → 4.0](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-3.x-to-4.0) — UTC-based times, `JsonItem`, timezone handling\n",
"category": "docs",
"tags": [
"migration-guides",
"fullcalendarbuilder",
"entryprovider",
"jsonitem",
"migration",
"upgrade",
"entry",
"event"
]
},
{
"id": "release-notes-4.0.x",
"title": "Release notes for 4.0",
"path": "Release-Notes-4.0.x.md",
"content": "# Release notes for 4.0\nThis page gives you an overview of the major changes, that came with the release of [FullCalendar for Flow, version 4.0](https://vaadin.com/directory/component/full-calendar-flow).\n\nIf you are going to update from 3.x, please also have a look into the [migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#migrating-from-3x--40).\n\nIf you are new to the FullCalendar or want to see, what might have changed in code, please visit our [examples](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples).\n\n# New base type JsonItem for calendar items\nWith this major version we introduced a new based type for calendar items (e.g. `Entry`). JsonItem provides a dynamic property approach, that allows defining properties via keys. Those keys provide details and rules for the automatic conversion of items from and to json.\n\nCurrently the Entry and it's subclasses implement JsonItem. Other implementations will follow in future.\n\nSee the [examples page](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples#use-the-low-level-jsonitem-api-to-modify-a-calendar-item) for some details.\n\n# Date Time communication changed to UTC based \n\nWhile internally entries stored time values as UTC already beforehand, the communication was always based on the calendar's timezone. This led to the issue, that on a timezone change, the entries had to be resent. While this might be no problem for some use cases, other scenarios could lead to a freezing UI, when having many entries and switching the timezone.\n\nTo improve the performance here and unify the transport of times, we decided to introduce this breaking change and let the communication always be UTC based.\n\nThis means also, that custom timezones for Entries are not supported anymore as they have been before. If you used that feature, you may need to catch that missing feature in your edit forms and displayment. We apologize for that inconvenience.\n\nAlso the behavior of all day entries regarding timezones has changed. All day entries are now no longer affected by timezones.\n\nPlease see the [migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#migrating-from-3x--40) for more details.\n\n# Changed entry data is now sent at once\nIn 3.x the server instance did not check, if you already sent some data to the client. Instead, it fired a java script call for every entry CRUD call. This means, that for instance calling `addEntry()` 20 times, the server called the respective client side api 20 times and also the calendar hat to rerender 20 times. \n\nStarting with 4.0.x those server side data changes are collected internally and sent at once. This means, you can call the CRUD api as often as you want in a request - there will only be one call on the client side (or to be more concrete maximal 3 one for add, update and remove respectively - this may be also change in future for a more optimal handling).\n\n# Custom properties on the client side\n\nWhen you customize the entry content via setEntryContent or setEntryDidMount, you may now access custom properties via a dedicated getter instead of traversing through multiple properties.\n\nSee the [example page](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples#customize-the-entry-content) for details.\n\n# Recurrence\nThere are minor changes to recurrence, that most likely will need your attention regarding compiler issues. See [this chapter](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#recurrence) for details.\n\n- renamed several methods\n- recurrence has some changes regarding enable recurrence and timezones\n\n# Other\nSome methods have become deprecated. Please check the compiler warnings and try to replace them soon.",
"category": "docs",
"tags": [
"release-notes-4.0.x",
"entry",
"migration",
"upgrade",
"event"
]
},
{
"id": "release-notes-4.1.x",
"title": "Release notes for 4.1",
"path": "Release-Notes-4.1.x.md",
"content": "# Release notes for 4.1\nThis page gives you an overview of the major changes, that came with the release of [FullCalendar for Flow, version 4.1](https://vaadin.com/directory/component/full-calendar-flow).\n\nPlease also have a look on our [migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#migrating-from-40--41) and our [examples](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples).\n\n## Entry Provider\nWith 4.1 we introduced a new way of providing calendar items. Up to now the official supported way was to register all known entries to the server side, which itself would push it then to the client. This means that both, the server and the client, needed to keep all the data in memory. \n\nWith the newly introduces `EntryProvider` we provide a way of providing entries similar to the common Vaadin `DataProvider`. When using an `EntryProvider`, the client will control via parameters, which entries are to be fetched to the client. The server on the otherside only needs to create and provide the entries, that are requested. \n\n### In memory variants\nOf course, it is up to the server side, how and when the entries are created. Beside the base interface we also introduced the sub interface `InMemoryEntryProvider`, which comes in two pre-implemented variants\n* EagerInMemoryEntryProvider\n* LazyInMemoryEntryProvider\n\nThe eager variant is an exception to the above described behavior of the `EntryProvider`. While it implements the `EntryProvider` interface, it behaves like the old way the FullCalendar transported entries to the client: it pushes them itself. So if you still want to have all entries on the client available at any time (e. g. when your application operats in a scope with a slow network access), you can use this instance. \n\nThe lazy variant is a mixture between the old and the new way. It acts a bit like the common `ListDataProvider`, where all known entries are cached on the server side, but only the necessary ones are fetched from the client. \n\n### Initial EntryProvider on FullCalendar\nWith this update the FullCalendar itself does not cache any entries directly, but uses an `EntryProvider` for all cases. A new FullCalendar is initialized with an instance of the `EagerInMemoryEntryProvider`. This shall prevent any breaking changes for updating applications. Yet we recommend to change to a different `EntryProvider` due to the advantages of fetching only the necessary entries.\n\n### Entry CRUD operations on FullCalendar\nAll entry CRUD operations (e. g. `addEntries()`) are therefore delegated to the calendar's provider, when that provider supports those methods. For that, the provider has to be at least an `InMemoryEntryProvider`. If you want to use the `update` api, it needs to be the `EagerInMemoryEntryProvider`, since for the lazy variant the update api is not necessary any more as updating the client side is handled by the `refresh` api.\n\nBe aware, that any calls to the CRUD operations will lead to an exception, if you don't use the correct data provider. \n\n### Callback Entry Provider\nFor easy integration of using a callback based variant we introduced the `CallbackEntryProvider`. You can simply create an instance by calling `EntryProvider.fromCallbacks()`.\n\n### Custom implemenation\nIf none of the predefined variants fits your needs, you are of course free to implement your own version. In that case we recommend to extend the `AbstractEntryProvider` as a starting point.\n\n## Info on missing offset api for recurrence\nWith 4.0.x the date time api for entries has changed. You might have seen, that the recurring start / end time variants do not provide an offset variant. This is due to an [issue in the native FullCalendar library](https://github.com/fullcalendar/fullcalendar/issues/5273). As soon as the issue has been fixed, we try to add the respective api.\n\n## Deprecation\nSome methods have become deprecated, especially the CRUD operations in the `FullCalendar`. We recommend to replace them with the respective replacements, since they might be removed with the next major release.\n\n\n ",
"category": "docs",
"tags": [
"release-notes-4.1.x",
"entryprovider",
"dataprovider",
"inmemoryentryprovider",
"listdataprovider",
"eagerinmemoryentryprovider",
"callbackentryprovider",
"abstractentryprovider",
"fullcalendar",
"migration",
"upgrade",
"entry",
"event"
]
},
{
"id": "release-notes-6.1.x",
"title": "Release notes for 6.1",
"path": "Release-Notes-6.1.x.md",
"content": "# Release notes for 6.1\n\nWith 6.1, the (for now experimental) Lumo theme has been added to the addon. This theme slightly changes\nthe appearance of the calendar to align more with other Vaadin components' Lumo styles.\n\nTo use it, simply apply the respective theme variant to your calendar instance. It also works with custom\nsubclasses of the calendar. Please be aware, that changing Lumo variables or overriding FC styles also affect\nthis theme.\n\n```java\ncalendar.addThemeVariant(FullCalendarVariant.LUMO);\n```\n\nMajor changes:\n* the today marker is now shown as a badge instead of having a background color\n* header font sizes reduced\n* selection colors aligned with Grid selection\n* using the lumo prime color as the default color for events (that have no own color); the default color of background events is not changed at the moment\n* applying several other lumo colors, sizes and spaces to different parts of the calendar\n ",
"category": "docs",
"tags": [
"release-notes-6.1.x"
]
},
{
"id": "release-notes-6.2.x",
"title": "Release notes for 6.2",
"path": "Release-Notes-6.2.x.md",
"content": "# Release notes for 6.2\n\nWith 6.2 custom native event handlers for entries have been added. These allow you to setup JavaScript events for\neach entry, e.g. a mouse over event handler. Inside these event handlers you may also access the created entry dom\nelement.\n\nCustom native event handlers are added to the FullCalender object. They will then be applied to each created\nentry object (using the entryDidMount callback).\n\nTo add an event handler, simply call the method `addEntryNativeEventListener` on the calendar. The first parameter\nis the JavaScript event name (e.g. \"mouseover\"), the second parameter is the callback, that shall be used for\nthat event. Please be aware, that we do NOT check or sanitize the given JavaScript. It is up to you to prevent\nmalicious code from being sent to your users.\n\nInside the event callback, you may access the entryDidMount argument object, that contains additional information\nabout the current entry. See the official docs (https://fullcalendar.io/docs/event-render-hooks) \nfor more details about which details it provide.\n\n```java\nFullCalendar calendar = new FullCalendar();\n\n// ... other configurations\n\n// write the js event, the current entry info and the current entry's element to the browser console.\ncalendar.addEntryNativeEventListener(\"mouseover\", \"e => console.warn(e, info.event, info.el)\");\n\nadd(calendar);\n```\n\nPlease be aware, that due to the design of the used library, these event handlers have to be setup before the\ncalendar is initialized on the client side.\n\nYou can combine the event handlers with a custom entryDidMount callback, if you want additional customizations\nof the entries. The FC will take care of combining the event handlers and you EDM callback",
"category": "docs",
"tags": [
"release-notes-6.2.x",
"entry",
"event"
]
},
{
"id": "release-notes-4.0",
"title": "New base type JsonItem for calendar items",
"path": "Release-notes-4.0.md",
"content": "This page gives you an overview of the major changes, that came with the release of [FullCalendar for Flow, version 4.0](https://vaadin.com/directory/component/full-calendar-flow).\n\nIf you are going to update from 3.x, please also have a look into the [migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#migrating-from-3x--40).\n\nIf you are new to the FullCalendar or want to see, what might have changed in code, please visit our [examples](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples).\n\n# New base type JsonItem for calendar items\nWith this major version we introduced a new based type for calendar items (e.g. `Entry`). JsonItem provides a dynamic property approach, that allows defining properties via keys. Those keys provide details and rules for the automatic conversion of items from and to json.\n\nCurrently the Entry and it's subclasses implement JsonItem. Other implementations will follow in future.\n\nSee the [examples page](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples#use-the-low-level-jsonitem-api-to-modify-a-calendar-item) for some details.\n\n# Date Time communication changed to UTC based\n\nWhile internally entries stored time values as UTC already beforehand, the communication was always based on the calendar's timezone. This led to the issue, that on a timezone change, the entries had to be resent. While this might be no problem for some use cases, other scenarios could lead to a freezing UI, when having many entries and switching the timezone.\n\nTo improve the performance here and unify the transport of times, we decided to introduce this breaking change and let the communication always be UTC based.\n\nThis means also, that custom timezones for Entries are not supported anymore as they have been before. If you used that feature, you may need to catch that missing feature in your edit forms and displayment. We apologize for that inconvenience.\n\nAlso the behavior of all day entries regarding timezones has changed. All day entries are now no longer affected by timezones.\n\nPlease see the [migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#migrating-from-3x--40) for more details.\n\n# Changed entry data is now sent at once\nIn 3.x the server instance did not check, if you already sent some data to the client. Instead, it fired a java script call for every entry CRUD call. This means, that for instance calling `addEntry()` 20 times, the server called the respective client side api 20 times and also the calendar hat to rerender 20 times.\n\nStarting with 4.0.x those server side data changes are collected internally and sent at once. This means, you can call the CRUD api as often as you want in a request - there will only be one call on the client side (or to be more concrete maximal 3 one for add, update and remove respectively - this may be also change in future for a more optimal handling).\n\n# Custom properties on the client side\n\nWhen you customize the entry content via setEntryContent or setEntryDidMount, you may now access custom properties via a dedicated getter instead of traversing through multiple properties.\n\nSee the [example page](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples#customize-the-entry-content) for details.\n\n# Recurrence\nThere are minor changes to recurrence, that most likely will need your attention regarding compiler issues. See [this chapter](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#recurrence) for details.\n\n- renamed several methods\n- recurrence has some changes regarding enable recurrence and timezones\n\n# Other\nSome methods have become deprecated. Please check the compiler warnings and try to replace them soon.",
"category": "docs",
"tags": [
"release-notes-4.0",
"entry",
"migration",
"upgrade",
"event"
]
},
{
"id": "release-notes-4.1",
"title": "Release-notes-4.1",
"path": "Release-notes-4.1.md",
"content": "This page gives you an overview of the major changes, that came with the release of [FullCalendar for Flow, version 4.1](https://vaadin.com/directory/component/full-calendar-flow).\n\nPlease also have a look on our [migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-MigrationGuides#migrating-from-40--41) and our [examples](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/FullCalendar-Examples).\n\n## Entry Provider\nWith 4.1 we introduced a new way of providing calendar items. Up to now the official supported way was to register all known entries to the server side, which itself would push it then to the client. This means that both, the server and the client, needed to keep all the data in memory.\n\nWith the newly introduces `EntryProvider` we provide a way of providing entries similar to the common Vaadin `DataProvider`. When using an `EntryProvider`, the client will control via parameters, which entries are to be fetched to the client. The server on the otherside only needs to create and provide the entries, that are requested.\n\n### In memory variants\nOf course, it is up to the server side, how and when the entries are created. Beside the base interface we also introduced the sub interface `InMemoryEntryProvider`, which comes in two pre-implemented variants\n* EagerInMemoryEntryProvider\n* LazyInMemoryEntryProvider\n\nThe eager variant is an exception to the above described behavior of the `EntryProvider`. While it implements the `EntryProvider` interface, it behaves like the old way the FullCalendar transported entries to the client: it pushes them itself. So if you still want to have all entries on the client available at any time (e. g. when your application operats in a scope with a slow network access), you can use this instance.\n\nThe lazy variant is a mixture between the old and the new way. It acts a bit like the common `ListDataProvider`, where all known entries are cached on the server side, but only the necessary ones are fetched from the client.\n\n### Initial EntryProvider on FullCalendar\nWith this update the FullCalendar itself does not cache any entries directly, but uses an `EntryProvider` for all cases. A new FullCalendar is initialized with an instance of the `EagerInMemoryEntryProvider`. This shall prevent any breaking changes for updating applications. Yet we recommend to change to a different `EntryProvider` due to the advantages of fetching only the necessary entries.\n\n### Entry CRUD operations on FullCalendar\nAll entry CRUD operations (e. g. `addEntries()`) are therefore delegated to the calendar's provider, when that provider supports those methods. For that, the provider has to be at least an `InMemoryEntryProvider`. If you want to use the `update` api, it needs to be the `EagerInMemoryEntryProvider`, since for the lazy variant the update api is not necessary any more as updating the client side is handled by the `refresh` api.\n\nBe aware, that any calls to the CRUD operations will lead to an exception, if you don't use the correct data provider.\n\n### Callback Entry Provider\nFor easy integration of using a callback based variant we introduced the `CallbackEntryProvider`. You can simply create an instance by calling `EntryProvider.fromCallbacks()`.\n\n### Custom implemenation\nIf none of the predefined variants fits your needs, you are of course free to implement your own version. In that case we recommend to extend the `AbstractEntryProvider` as a starting point.\n\n## Info on missing offset api for recurrence\nWith 4.0.x the date time api for entries has changed. You might have seen, that the recurring start / end time variants do not provide an offset variant. This is due to an [issue in the native FullCalendar library](https://github.com/fullcalendar/fullcalendar/issues/5273). As soon as the issue has been fixed, we try to add the respective api.\n\n## Deprecation\nSome methods have become deprecated, especially the CRUD operations in the `FullCalendar`. We recommend to replace them with the respective replacements, since they might be removed with the next major release.\n\n\n ",
"category": "docs",
"tags": [
"release-notes-4.1",
"entryprovider",
"dataprovider",
"inmemoryentryprovider",
"listdataprovider",
"eagerinmemoryentryprovider",
"callbackentryprovider",
"abstractentryprovider",
"fullcalendar",
"migration",
"upgrade",
"entry",
"event"
]
},
{
"id": "release-notes-6.0",
"title": "Release-notes-6.0",
"path": "Release-notes-6.0.md",
"content": "Nothing to see here, check migration page for 6.0.",
"category": "docs",
"tags": [
"release-notes-6.0",
"migration",
"upgrade"
]
},
{
"id": "release-notes-6.1",
"title": "Release-notes-6.1",
"path": "Release-notes-6.1.md",
"content": "With 6.1, the (for now experimental) Lumo theme has been added to the addon. This theme slightly changes\nthe appearance of the calendar to align more with other Vaadin components' Lumo styles.\n\nTo use it, simply apply the respective theme variant to your calendar instance. It also works with custom\nsubclasses of the calendar. Please be aware, that changing Lumo variables or overriding FC styles also affect\nthis theme.\n\n```java\ncalendar.addThemeVariant(FullCalendarVariant.LUMO);\n```\n\nMajor changes:\n* the today marker is now shown as a badge instead of having a background color\n* header font sizes reduced\n* selection colors aligned with Grid selection\n* using the lumo prime color as the default color for events (that have no own color); the default color of background events is not changed at the moment\n* applying several other lumo colors, sizes and spaces to different parts of the calendar",
"category": "docs",
"tags": [
"release-notes-6.1"
]
},
{
"id": "release-notes-6.2",
"title": "Release-notes-6.2",
"path": "Release-notes-6.2.md",
"content": "With 6.2 custom native event handlers for entries have been added. These allow you to setup JavaScript events for\neach entry, e.g. a mouse over event handler. Inside these event handlers you may also access the created entry dom\nelement.\n\nCustom native event handlers are added to the FullCalender object. They will then be applied to each created\nentry object (using the entryDidMount callback).\n\nTo add an event handler, simply call the method `addEntryNativeEventListener` on the calendar. The first parameter\nis the JavaScript event name (e.g. \"mouseover\"), the second parameter is the callback, that shall be used for\nthat event. Please be aware, that we do NOT check or sanitize the given JavaScript. It is up to you to prevent\nmalicious code from being sent to your users.\n\nInside the event callback, you may access the entryDidMount argument object, that contains additional information\nabout the current entry. See the official docs (https://fullcalendar.io/docs/event-render-hooks) \nfor more details about which details it provide.\n\n```java\nFullCalendar calendar = new FullCalendar();\n\n// ... other configurations\n\n// write the js event, the current entry info and the current entry's element to the browser console.\ncalendar.addEntryNativeEventListener(\"mouseover\", \"e => console.warn(e, info.event, info.el)\");\n\nadd(calendar);\n```\n\nPlease be aware, that due to the design of the used library, these event handlers have to be setup before the\ncalendar is initialized on the client side.\n\nYou can combine the event handlers with a custom entryDidMount callback, if you want additional customizations\nof the entries. The FC will take care of combining the event handlers and your EDM callback",
"category": "docs",
"tags": [
"release-notes-6.2",
"entry",
"event"
]
},
{
"id": "release-notes-6.4",
"title": "FullCalendar Addon 6.4.0 Release Notes",
"path": "Release-notes-6.4.md",
"content": "# FullCalendar Addon 6.4.0 Release Notes\n\nVersion 6.4.0 represents a significant platform modernization and feature expansion of the FullCalendar addon. This release bridges the gap for Vaadin 24 users who cannot yet migrate to Vaadin 25, while bringing a comprehensive set of v7 features to the v6 codebase.\n\n## Platform Upgrade\n\n### Vaadin 14 → Vaadin 24.10\n\nThe addon has been upgraded from Vaadin 14 (LTS) to Vaadin 24.10.x. This is a major platform shift that modernizes the underlying component framework.\n\n- **Java version**: Requires Java 17+ (upgraded from Java 8)\n- **Polymer removal**: Vaadin 14's Polymer 3 has been replaced with plain HTML Element-based web components (already completed in v6.0)\n- **Vaadin Flow**: Updated to Vaadin Flow 24.10.x with all associated ecosystem updates\n\n> **Breaking Change**: This version requires **Vaadin 24.10**. Vaadin 14 LTS is no longer supported.\n\n## Entry Model Enhancements\n\n### New Entry Fields\n\nThe `Entry` class now includes several new properties backported from v7:\n\n| Field | Type | Purpose |\n|-------|------|---------|\n| `url` | String | Hyperlink for the entry; integrated into entry rendering |\n| `interactive` | Boolean | Controls whether the entry is interactive (draggable, resizable) |\n| `overlap` | Boolean | **Breaking change** — now `Boolean` (nullable) instead of `boolean` primitive; use getters carefully |\n| `recurringDuration` | String | For recurring entries, controls the duration of recurrence windows independently of event duration |\n\n### Recurrence Rule Support (RFC 5545 — RRULE)\n\nVersion 6.4 introduces full RFC 5545 recurrence rule support via the new `RRule` class:\n\n```java\nEntry event = new Entry(\"Team Meeting\");\nevent.setStart(LocalDateTime.of(2025, 3, 24, 10, 0));\nevent.setEnd(LocalDateTime.of(2025, 3, 24, 11, 0));\n\n// Weekly meetings, Monday and Friday, until end of April\nRRule rule = RRule.weekly()\n .byWeekday(DayOfWeek.MONDAY, DayOfWeek.FRIDAY)\n .until(LocalDate.of(2025, 4, 30));\n\nevent.setRRule(rule);\ncalendar.getEntryProvider().asInMemory().addEntry(event);\n```\n\n**Key Features**:\n- Structured form (recommended): Set frequency and properties like `byWeekday`, `until`, `count`, etc.\n- Raw RRULE string: For importing from external sources (e.g., iCalendar exports): `RRule.ofRaw(\"FREQ=WEEKLY;BYDAY=MO,FR\")`\n- Exclusions: Use `excludeDates()` or `excludeRules()` to define exception dates or patterns\n- Mutually exclusive with legacy recurrence fields (`recurringDaysOfWeek`, `recurringStartDate`, etc.)\n\nThe `@fullcalendar/rrule` npm package is automatically bundled and loaded.\n\n### Nullable Overlap Property\n\nThe `overlap` field's type has changed from `boolean` to `Boolean`:\n\n```java\nentry.setOverlap(true); // supported\nentry.setOverlap(null); // now allowed\nBoolean val = entry.getOverlap(); // returns null if not set\n```\n\nRecompilation is required. Be careful when reading the value — `null` is now a distinct state from `false`.\n\n## JsCallback System (Type-Safe Client-Side Callbacks)\n\nVersion 6.4 introduces the `JsCallback` wrapper for client-side event handlers, replacing raw string-based callback injection:\n\n```java\n// New (6.4+): type-safe wrapper\ncalendar.setOption(Option.ENTRY_DID_MOUNT,\n JsCallback.of(\"function(info) { info.el.title = info.event.title; }\"));\n\n// Clear a callback\ncalendar.setOption(Option.ENTRY_DID_MOUNT, JsCallback.clearCallback());\n```\n\nThis replaces the previous `setEntryDidMountCallback(String)` pattern. The `JsCallback.of()` factory method wraps a JavaScript function string for safe transport to the client, where it is evaluated via `new Function()`.\n\n## FullCalendar JavaScript Library Updates\n\nThe bundled FullCalendar JavaScript library has been upgraded from **6.1.9 to 6.1.20**, bringing:\n- Bug fixes and performance improvements\n- Enhanced compatibility with modern browser APIs\n- Better internationalization support\n\n## Event Classes and DOM Event Integration\n\nEleven new event classes have been added to support additional user interactions:\n\n| Event Class | Purpose |\n|-------------|---------|\n| `EntryDragStartEvent` | Fired when user begins dragging an entry |\n| `EntryDragStopEvent` | Fired when user completes or cancels a drag operation |\n| `EntryResizeStartEvent` | Fired when user begins resizing an entry |\n| `EntryResizeStopEvent` | Fired when user completes or cancels a resize operation |\n| `DropEvent` | Fired when content is dropped from outside the calendar |\n| `EntryReceiveEvent` | Fired when an entry is received from an external source |\n| `ExternalEntryDroppedEvent` | Fired when an external entry is dropped on the calendar |\n| `ExternalEntryResizedEvent` | Fired when an external entry is resized |\n| `ExternalEntryEvent` | Base class for external entry events |\n| `TimeslotsUnselectEvent` | Fired when a selection is cleared |\n| `EntryTimeChangedEvent` | Fired when an entry's time is changed |\n\nThese events integrate native browser DOM events with the FullCalendar backend, allowing precise control over drag, resize, and drop behaviors.\n\n## New Option Enum Constants\n\nA large number of new `Option` enum constants have been added for advanced customization. See the `Option` enum Javadoc for the complete list.\n\n- **Render hooks**: `ENTRY_CONTENT`, `ENTRY_DID_MOUNT`, `DAY_CELL_CONTENT`, `SLOT_LABEL_CONTENT`, etc.\n- **Interaction handlers**: `SELECT_CONSTRAINT`, `SELECT_ALLOW`, `SELECT_OVERLAP`, etc.\n- **Display configuration**: `SLOT_LABEL_FORMAT`, `ENTRY_TIME_FORMAT`, `BUSINESS_HOURS`, etc.\n\nThese options map directly to FullCalendar's JavaScript API and allow fine-grained control over rendering and behavior without requiring custom JavaScript.\n\n## Client-Side Event Sources\n\nThree new event source types enable fetching calendar entries from external systems:\n\n| Source Type | Purpose |\n|-------------|---------|\n| **Google Calendar** | Load events directly from Google Calendar feeds |\n| **iCalendar (ICS)** | Import .ics files and feed URLs |\n| **JSON Feed** | Load custom event feeds from URLs or APIs |\n\nThese are automatically integrated with the `@fullcalendar/google-calendar`, `@fullcalendar/icalendar`, and `@fullcalendar/core` packages.\n\n```java\n// Set a global API key (applies to all Google Calendar sources)\ncalendar.setOption(Option.EXTERNAL_EVENT_SOURCE_GOOGLE_CALENDAR_API_KEY, \"AIzaSy...\");\n\n// Add a Google Calendar event source\ncalendar.addClientSideEventSource(new GoogleCalendarEventSource(\"holidays@group.calendar.google.com\")\n .withId(\"holidays\")\n .withColor(\"green\"));\n```\n\n## Scheduler Extensions\n\n### ComponentResourceAreaColumn\n\nThe scheduler component now supports Vaadin components directly in resource area columns:\n\n```java\nFullCalendarScheduler scheduler = new FullCalendarScheduler();\nComponentResourceAreaColumn column = new ComponentResourceAreaColumn(\n resource -> new Button(\"Edit \" + resource.getTitle(),\n e -> editResource(resource))\n);\nscheduler.setResourceAreaColumns(List.of(column));\n```\n\n### ResourceAreaColumn Configuration\n\nA new `ResourceAreaColumn` configuration class provides declarative control over scheduler resource area styling and layout.\n\n## Draggable API\n\nNew server-side `Draggable` class for making external Vaadin components draggable onto the calendar,\nreplacing the previous manual JS initialization approach.\n\n- `new Draggable(component)` — wrap any Vaadin component to make it draggable\n- `new Draggable(component, entry)` — include entry data that FC uses to create a calendar entry on drop\n- `withItemSelector(String)` — container mode: only children matching the CSS selector are draggable\n- `withEventDataCallback(JsCallback)` — dynamically create entry data from the dragged element via JS\n- `calendar.addDraggable(draggable)` — register on a calendar; returns `Registration` for cleanup\n- `EntryReceiveEvent.getDraggable()` — access the original Draggable from the entry receive listener\n- `DropEvent.getDraggable()` — access the Draggable from the drop listener\n\nThe `Draggable` lifecycle is fully managed: re-initialization on reattach, cleanup of JS listeners\non deregistration and disconnect.\n\n## Performance Improvements\n\n### Bounded Entry Cache\n\nThe in-memory entry provider now applies an internal size bound to prevent unbounded memory growth. This is handled automatically and requires no configuration change. No new API was added.\n\n### Thread-Safe Refresh Operations\n\nEntry provider refresh operations are now fully thread-safe, allowing background processes to update the calendar without synchronization overhead.\n\n### BeanProperties Converter Caching\n\nConversion overhead for Entry serialization has been reduced via reflection-based caching of property accessors, improving responsiveness during calendar interaction.\n\n## Dependencies\n\n### New NPM Packages (Automatic)\n\nThe following npm packages are now automatically bundled and loaded:\n\n- `@fullcalendar/rrule` — RFC 5545 recurrence rules\n- `@fullcalendar/google-calendar` — Google Calendar integration\n- `@fullcalendar/icalendar` — iCalendar (ICS) support\n- `ical.js` — ICS file parsing\n\nThese are included in the build automatically; **no manual npm installation required**.\n\n## Deprecated Functionality\n\nApproximately 30 convenience methods have been deprecated in favor of the unified `setOption()` API. Examples:\n\n```java\n// Deprecated (still works)\ncalendar.setFirstDay(DayOfWeek.MONDAY);\n\n// Preferred (v6.4+)\ncalendar.setOption(Option.FIRST_DAY, DayOfWeek.MONDAY);\n```\n\nDeprecated methods remain functional but log warnings if invoked. They will be removed in a future major version.\n\nSee the Migration Guide for a complete list of deprecated methods and their replacements.\n\n## What's NOT Included\n\nThe following v7 features are **not** backported to v6.4:\n\n- **Aura Theme variant** — The Aura theme (introduced in Vaadin 25) is not available. The Lumo-based `full-calendar-theme-vaadin.css` is included and works with Vaadin 24.\n- **Jackson JSON** — The addon continues to use `elemental.json` (Vaadin's built-in JSON library) for compatibility\n- **Java 21+ Language Features** — Code remains Java 17-compatible; no records, pattern matching, or sealed classes\n\n## Upgrade Path\n\n| Current Version | Recommended Action |\n|-----------------|-------------------|\n| v6.3.x | Review Migration Guide, update Maven dependency, recompile |\n| v6.2.x or earlier | Review full v6.0 migration guide first, then v6.3→6.4 |\n| v5.x or earlier | Not recommended; consider v7.x instead |\n\n## Support\n\n- Documentation: See Migration Guide for step-by-step instructions\n- Issues: [GitHub Issues](https://github.com/stefanuebe/vaadin-fullcalendar/issues)\n- Demo: Clone the repository and run the demo app with Vaadin 24.10\n\n---\n\n*Release date: March 2026*\n*FullCalendar JS Library: 6.1.20*\n*Vaadin: 24.10.x*\n*Java: 17+*\n",
"category": "docs",
"tags": [
"release-notes-6.4",
"entry",
"boolean",
"rrule",
"jscallback",
"entrydragstartevent",
"entrydragstopevent",
"entryresizestartevent",
"entryresizestopevent",
"dropevent",
"entryreceiveevent",
"externalentrydroppedevent",
"externalentryresizedevent",
"externalentryevent",
"timeslotsunselectevent",
"entrytimechangedevent",
"option",
"resourceareacolumn",
"draggable",
"migration",
"upgrade",
"scheduler",
"resource",
"event"
]
},
{
"id": "release-notes-6.5",
"title": "Release-notes-6.5",
"path": "Release-notes-6.5.md",
"content": "This page gives you an overview of the major changes that came with the release of\n[FullCalendar for Flow, version 6.5](https://vaadin.com/directory/component/full-calendar-flow).\n\n**Platform:** FullCalendar JS 6.1.20, Vaadin 24.9.x, Java 17, elemental JSON. 6.5 is a source-compatible minor release **backporting the 7.2 feature set** to the v6 line — designed for teams that want the 7.2 features without the Vaadin 25 / Java 21 upgrade. See the [migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-6.4-to-6.5) for the single binary-compat caveat and migration notes, or the [7.2 release notes](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Release-notes-7.2) for the original v7-line release.\n\n## 6.5 or 7.x?\n\n- **Stay on 6.5** if you need to keep running on Vaadin 24 / Java 17 (e.g. your Vaadin licence, CI infrastructure, or dependent modules aren't ready to jump). 6.5 gives you the complete 7.2 feature set on that stack.\n- **Upgrade to 7.1/7.2** if you can move to Vaadin 25 / Java 21. That's the forward line; 6.x is maintenance-track.\n- 6.5 and 7.2 share the same feature set; the choice is about platform, not functionality.\n\n## Highlights\n\n- **[Client-side entry IDs](#client-side-entry-ids-provided-automatically-202)** — default on, no configuration needed.\n- **[Auto-revert for unapplied entry changes](#auto-revert-for-unapplied-entry-changes-225)** — default on; prevents server/client drift when a drop/resize listener rejects the change.\n- **[`FullCalendarBuilder` deprecated](#deprecated-fullcalendarbuilder-232)** — direct construction + `setOption(...)` is the forward path. No removal scheduled for 6.x.\n- Bug fixes for scheduler extended-prop updates ([#230](#schedulerupdateresource-now-propagates-extended-props-230)), scheduler timeline sizing ([#231](#scheduler-timeline-sizing-in-dense-resource-layouts-231)) and per-entry editable ([#212](#per-entry-editable-default-no-longer-overrides-calendar-level-editable-false-212)).\n\n## Client-Side Entry IDs Provided Automatically (#202)\n\nServer-side components such as `Popover` anchor to target elements via `document.getElementById`. Before 6.5, rendered calendar entries had no DOM `id`, so anchoring required a custom `eventDidMount` callback with JavaScript-side id generation.\n\nStarting with 6.5, `FullCalendar` assigns `id=\"entry-\"` to the **start segment** of each rendered entry by default. The feature is controlled by `setAutoProvideEntryIdOnClient(boolean)`, which defaults to `true`.\n\n### Usage\n\n```java\n// Default on — nothing to configure.\nEntry meeting = new Entry(\"m-1\");\nmeeting.setTitle(\"Quarterly review\");\n// ...\n\n// Anchor a Popover to the rendered entry:\nPopover popover = new Popover();\npopover.setFor(\"entry-m-1\");\n```\n\nOpt-out:\n\n```java\ncalendar.setAutoProvideEntryIdOnClient(false);\n```\n\n### ID schema and uniqueness\n\n- **Single-day entry**, any view → `id=\"entry-\"` on the single segment.\n- **Multi-day entry** (month/week view) → `id=\"entry-\"` on the **start segment only**; continuation segments stay id-free so HTML id uniqueness is preserved.\n- **Scheduler, entry assigned to multiple resources** → to keep ids unique across the resource rows, the id is suffixed with the row's resource id: `id=\"entry--\"`. Entries that live in a single resource row get the plain `entry-` schema.\n- **Drag-preview (\"mirror\") elements** during an ongoing drag are not tagged — the id stays on the real element.\n\n### Overriding the default\n\nIf you set your own `eventDidMount` callback via `setOption(Option.ENTRY_DID_MOUNT, JsCallback.of(...))`, the default snippet runs first and your callback runs afterwards, so reassigning `info.el.id` in your callback wins.\n\n```java\ncalendar.setOption(Option.ENTRY_DID_MOUNT, JsCallback.of(\n \"function(info) { info.el.id = 'my-' + info.event.id; }\"));\n// Result: id='my-' (your value, the default was overwritten)\n```\n\n### Notes\n\n- For anchoring to the exact segment a user clicked, prefer the element from the click event rather than `getElementById` — the click element always points at the clicked segment, even for multi-day entries whose id lives only on the start.\n- The feature relies on the `eventDidMount` render hook. If you replace that hook with a brace-less arrow expression (e.g. `\"info => info.el.title = info.event.title\"`), the default snippet is skipped to keep the output syntactically valid. Use a braced function body to keep the default id-assignment alongside your callback.\n\n## Auto-Revert for Unapplied Entry Changes (#225)\n\nWhen a user drags or resizes an entry, FullCalendar JS immediately moves the entry to its new position on the client. The server receives an `EntryDroppedEvent` or `EntryResizedEvent`. Previously, if the developer chose not to call `event.applyChangesOnEntry()` (e.g., after a validation failure), the client would keep showing the entry at the new position while the server still had the old data — an inconsistent state.\n\nStarting with 6.5, the calendar **automatically reverts** the client-side entry to its original position when `applyChangesOnEntry()` is not called. This is controlled by `setAutoRevertUnappliedEntryChanges(boolean)`, which defaults to `true`.\n\n### Usage\n\n```java\n// Auto-revert is enabled by default — no configuration needed.\n// Entries revert automatically when applyChangesOnEntry() is not called.\n\ncalendar.addEntryDroppedListener(event -> {\n if (isDropAllowed(event)) {\n event.applyChangesOnEntry(); // entry stays at new position\n entryProvider.refreshItem(event.getEntry());\n }\n // If not called: entry reverts to original position on the client\n});\n```\n\nTo restore the previous behavior (client keeps the new position regardless):\n\n```java\ncalendar.setAutoRevertUnappliedEntryChanges(false);\n```\n\n### How It Works\n\n1. When a drop or resize occurs, the FullCalendar JS `revert()` function is captured on the client side.\n2. On the server, after all event listeners have been executed, a `beforeClientResponse` callback checks whether `applyChangesOnEntry()` was called.\n3. If not called (and auto-revert is enabled), the server sends a `revertEntry` command to the client, which triggers FullCalendar's native revert animation.\n4. If `applyChangesOnEntry()` was called, the pending revert is cleared — the entry stays at the new position.\n\n### Notes\n\n- Auto-revert works for `EntryDroppedEvent`, `EntryResizedEvent`, and `EntryDroppedSchedulerEvent`.\n- `ExternalEntryDroppedEvent` / `ExternalEntryResizedEvent` (from client-side event sources or draggable external DOM) do **not** participate in auto-revert — those flows create new entries on drop, so the server-side handler typically owns the accept/reject decision explicitly.\n- The revert uses FullCalendar's native revert mechanism, which provides a smooth animation back to the original position.\n- If you need to inspect the state from another listener or a downstream component, `EntryDataEvent#isChangesApplied()` returns whether `applyChangesOnEntry()` was called on this event — useful when multiple listeners are chained and a later one needs to know whether the earlier ones already accepted the change.\n\n## Deprecated: `FullCalendarBuilder` (#232)\n\n`FullCalendarBuilder` and all its `with...` methods are now `@Deprecated`. `FullCalendar` and `FullCalendarScheduler` can be constructed directly and configured through `setOption(Option, value)`; the builder no longer provides value beyond syntactic sugar. No removal is scheduled for 6.x — the class is slated for removal in a future major version.\n\n### Example\n\n```java\n// 6.4 — builder\nFullCalendarScheduler scheduler = (FullCalendarScheduler) FullCalendarBuilder.create()\n .withScheduler(licenseKey)\n .withEntryLimit(5)\n .build();\n```\n\n```java\n// 6.5 — direct construction\nFullCalendarScheduler scheduler = new FullCalendarScheduler();\nscheduler.setOption(Option.SCHEDULER_LICENSE_KEY, licenseKey);\nscheduler.setOption(Option.MAX_ENTRIES_PER_DAY, 5);\n```\n\nSee the [6.4 → 6.5 migration guide](https://github.com/stefanuebe/vaadin-fullcalendar/wiki/Migration-guide-6.4-to-6.5#deprecated-fullcalendarbuilder) for the full mapping table.\n\n**New `Option.INITIAL_VIEW`:** verified that FullCalendar 6.1.20 applies the `initialView` option correctly on first render, so the `withInitialView(view)` replacement is a clean `setOption(Option.INITIAL_VIEW, view.getClientSideValue())` rather than the attach-listener + `changeView()` workaround the builder used to carry. The builder's `build()` method now uses the option directly as well.\n\nAlso deprecated: the single-argument constructors `FullCalendar(int entryLimit)` and `FullCalendarScheduler(int entryLimit)`. Replace with the no-arg constructor plus `setOption(Option.MAX_ENTRIES_PER_DAY, n)`.\n\n## Demo: DemoDialog now supports resource assignment (#164)\n\nThe bundled `DemoDialog` (used by the full demo and entry-provider demos) now shows a \"Resources\" multi-select field when the edited entry is a `ResourceEntry` on a Scheduler-capable calendar. Available resources are read from `Scheduler.getResources()`. When creating an entry via timeslot selection in a resource view, the resource the user clicked on is pre-selected.\n\nDemo-only change — no addon API surface.\n\n## Deprecated: `Delta.getYears()` and `Delta.getMonths()` (#191)\n\nFullCalendar JS normalises year/month portions of a drop/resize delta into `days` before sending it to the server — dragging an entry from e.g. 31 March to 29 February produces `days: -31`, not `months: -1`. The `Delta.years` and `Delta.months` fields therefore stay zero for every FC-originated drag/drop event.\n\nThe two getters are now `@Deprecated` to document this. Handlers that react to drag/drop should read `Delta.getDays()` and the time components; the year/month fields remain only for manually-constructed `Delta` instances.\n\nNo removal scheduled; deprecated methods continue to work throughout 6.x.\n\n## Renamed: `EntryDataEvent.createCopyBasedOnChanges()` → `getChangesAsEntry()`\n\nThe old name was verbose and did not describe what the method actually returns. From 6.5 the method is called `getChangesAsEntry()`. The old name remains as a `@Deprecated` delegate — existing code keeps working.\n\n## Bug Fixes\n\n### `Scheduler.updateResource` now propagates extended props (#230)\n\nPreviously, calling `scheduler.updateResource(resource)` only applied changes to known built-in properties (title, color, eventOverlap, …) on the client side. Any changes to extended props were silently dropped.\n\n```java\nResource room = new Resource(\"room-1\", \"Room 1\", null);\nroom.addExtendedProps(\"department\", \"Engineering\");\nscheduler.addResource(room);\n\n// Later — update the extended prop\nroom.addExtendedProps(\"department\", \"Marketing\");\nscheduler.updateResource(room);\n// Before 6.5: client still shows \"Engineering\"\n// From 6.5: client reflects \"Marketing\"\n```\n\nResource properties that are not part of FC's built-in resource object (anything except `title`, `eventColor`, `eventBackgroundColor`, `eventBorderColor`, `eventTextColor`, `eventConstraint`, `eventOverlap`, `eventAllow`, `eventClassNames`) now route through FC's `Resource.setExtendedProp(name, value)` on update, matching the initial-creation behavior.\n\n### Scheduler timeline sizing in dense resource layouts (#231)\n\nPreviously, code that registered many resources one at a time — e.g. a `for`-loop calling `scheduler.addResource(...)` per entry — could leave the scrollgrid chunk tables stuck at `style=\"width: 0px; min-width: 930px\"`, rendering at min-width instead of filling the container. Users saw a large empty dead-zone to the right of the timeline.\n\n**Root cause:** every `addResource` / `removeResource` / `updateResource` call on the server fired an immediate `callJsFunction`. N calls → N JS round-trips → N inner FC updates, which pushed FC's internal Preact tree past its double-rAF settling window; `computeScrollerDims()` then wrote `width: 0` and nothing re-measured afterwards.\n\n**Fix:** resource writes on the scheduler now accumulate in a per-request pending state and flush once in a `beforeClientResponse` callback. A request that calls `addResource` 100 times fires exactly one `callJsFunction(\"addResources\", [...100], ...)` at the end of the request. FC sees one inner update and settles correctly.\n\nCollapse rules within a single request:\n- `addResource(R)` followed by `removeResource(R)` → no client op (R was never sent).\n- `removeResource(R)` followed by `addResource(R')` (same id) → remove + re-add, in that order.\n- `updateResource(R)` after `addResource(R)` → collapses into the add (the add payload carries the latest state).\n- `removeAllResources()` → supersedes any earlier piecewise ops in the same request.\n\nNo API change: `addResource`, `addResources(Iterable)`, `removeResource`, `removeResources(Iterable)`, `updateResource`, and `removeAllResources` keep their existing signatures. The difference is purely in _when_ the client is notified — at the end of the current request, not immediately.\n\n### Per-entry `editable` default no longer overrides calendar-level `editable: false` (#212)\n\nCalling `calendar.setOption(Option.EDITABLE, false)` to disable drag'n'drop globally used to have no effect — entries still responded to drag. Reason: each `Entry` carried an implicit `editable: true` default that was serialized to the client, overriding the calendar-level setting.\n\nStarting with 6.5, `Entry.editable` defaults to \"not set\" (internally `null`). An unset value is no longer sent to the client, so the calendar-level option takes effect. Explicit `entry.setEditable(true)` or `setEditable(false)` continue to work as before — they remain per-entry overrides.\n\n```java\n// 6.5 — actually works\ncalendar.setOption(Option.EDITABLE, false);\ncalendar.setEntryProvider(EntryProvider.inMemoryFrom(someEntries));\n// None of the entries are draggable.\n```\n\n**Source-level compatibility:** `entry.isEditable()` still returns `boolean` with the same default (true), and `entry.setEditable(true/false)` still works (auto-boxing). `setEditable(null)` is newly allowed — it clears the explicit override and lets the entry inherit the calendar-level setting again.\n\n**Addon-default change:** FullCalendar JS itself defaults the calendar-level `editable` option to `false`. With the per-entry override gone, that would have flipped the out-of-the-box UX to \"nothing draggable or resizable\". To preserve the pre-6.5 experience (entries are draggable by default unless the dev opts out), the addon now sets `editable: true` as a calendar-level default in every `FullCalendar` constructor. An explicit `setOption(Option.EDITABLE, false)` or a user-supplied `initialOptions` with `editable: false` continues to win.\n\n**Binary compatibility note:** the `setEditable` method descriptor changed from `(Z)V` (primitive boolean) to `(Ljava/lang/Boolean;)V` (boxed). Pre-compiled dependents calling `setEditable(...)` must be recompiled against 6.5 before use. Source recompilation is the normal path when upgrading the addon, so this rarely matters in practice.\n",
"category": "docs",
"tags": [
"release-notes-6.5",
"fullcalendarbuilder",
"popover",
"fullcalendar",
"entrydroppedevent",
"entryresizedevent",
"entrydroppedschedulerevent",
"externalentrydroppedevent",
"externalentryresizedevent",
"fullcalendarscheduler",
"demodialog",
"resourceentry",
"delta",
"entry",
"migration",
"upgrade",
"scheduler",
"resource",
"event"
]
},
{
"id": "release-notes-7.0",
"title": "Release-notes-7.0",
"path": "Release-notes-7.0.md",
"content": "This page gives you an overview of the major changes, that came with the release of \n[FullCalendar for Flow, version 7.0](https://vaadin.com/directory/component/full-calendar-flow).\n\nThe main change in version 7.0 is the Vaadin 25 support, which includes the new requirement\nfor at least Java 21 and, if used, Spring Boot 4. \n\nAlso the used FullCalendar version has been increased to 6.1.20.\n\n## Major code changes\nSince element Json is gone and Jackson 3 is the new player on the field, json related things have been\nreworked to use Jackson types instead of elemental Json ones. Some method names have changed to align better with \nthe handled types.\n\n## Theming\nThe FullCalendar theme variant `LUMO` has been renamed to `VAADIN` to cover all themes at once. This should\naffect you only, when you have explicitly removed the theme variant.\n\nThe Vaadin theming now covers Lumo and Aura and applies the respective styles to the calendar. As before,\nthere might be variables or cases, where the styling is not applied correctly or missing - in this case\nplease open a github issue.\n\n## Other\nThe class `BusinessHours` has been reworked. The constructors have been removed and instead\nthere are now static methods to define new instance. The api also has been changed to allow a fluent definition\nstyle of business hours.\n\nDeprecated APIs are subject to change or removal in future versions.",
"category": "docs",
"tags": [
"release-notes-7.0",
"lumo",
"vaadin",
"businesshours"
]
},
{
"id": "release-notes-7.1",
"title": "Release-notes-7.1",
"path": "Release-notes-7.1.md",
"content": "This page gives you an overview of the major changes that came with the release of\n[FullCalendar for Flow, version 7.1](https://vaadin.com/directory/component/full-calendar-flow).\n\nVersion 7.1 is driven by the following goals:\n\n1. **Close the feature gap** — bring the Java API up to parity with FullCalendar v6 so that options which\n previously required raw `setOption` calls now have proper typed support.\n2. **Keep the API lean** — rather than growing a sprawling set of individual setter methods, new functionality\n is surfaced through the generic `setOption` API, backed by typed enums, automatic value converters, and\n `JsCallback` for function values. Dedicated one-off setters that duplicate what `setOption` can already\n express are deprecated.\n3. New event types to allow more fine-grain control over what happens on the client side\n\nNo APIs have been removed in this release. Deprecated methods continue to work and will be removed in a future\nmajor version. See the [migration guide](Migration-guides#migration-notes-70--71) for the one behaviour change\ninvolving `Entry.overlap` and the full list of deprecated methods.\n\n## Entry model enhancements\n\nSeveral new properties have been added to `Entry`:\n\n- `setUrl(String)` — entries with a URL are rendered as `` tags; FC navigates to the URL on click\n- `setInteractive(Boolean)` — per-entry keyboard-focusability override (`null` inherits the global `eventInteractive` setting)\n- `setRecurringDuration(String)` — ISO 8601 duration for multi-day all-day recurring events (e.g. `\"P2D\"`)\n- `setRRule(RRule)` — RFC 5545 recurrence rules via the `RRule` fluent builder, including `RRule.excludeDates(LocalDate...)` to exclude specific dates\n- `setOverlap(Boolean)` — changed from primitive `boolean` to `Boolean`; `null` means \"inherit global overlap setting\"\n\n## Unified callback API: `JsCallback` and `setOption`\n\nJavaScript callbacks and static option values now share a single API path: `setOption(Option, value)`.\n`JsCallback` is a lightweight wrapper that marks a string as a JavaScript function — the client\nevaluates it via `new Function()` before passing it to FullCalendar.\n\nThe `Option` enum now includes all callback-related constants (render hooks, interaction guards,\ndata transforms, etc.). Scheduler-specific callback constants are in `SchedulerOption`:\n\n```java\n// Static value — unchanged\ncalendar.setOption(Option.ENTRY_OVERLAP, false);\n\n// Function — wrap in JsCallback\ncalendar.setOption(Option.ENTRY_OVERLAP,\n JsCallback.of(\"function(stillEvent, movingEvent) { return stillEvent.display === 'background'; }\"));\n\n// Render hook\ncalendar.setOption(Option.ENTRY_DID_MOUNT,\n JsCallback.of(\"function(info) { info.el.title = info.event.title; }\"));\n\n// Scheduler resource hook\nscheduler.setOption(SchedulerOption.RESOURCE_LABEL_CLASS_NAMES,\n JsCallback.of(\"function(arg) { return arg.resource.extendedProps.isSpecial ? ['special'] : []; }\"));\n```\n\n`JsCallback.of(null)` returns `null`, enabling clean \"clear callback\" patterns:\n\n```java\ncalendar.setOption(Option.ENTRY_CONTENT, JsCallback.of(userProvidedFunction)); // safe when null\n```\n\nThe individual callback setter methods from 7.0 (`setEntryClassNamesCallback`, `setEntryDidMountCallback`,\netc.) are deprecated. See the [migration guide](Migration-guides#deprecated-individual-callback-methods-use-setoption--jscallback-instead) for\nthe complete replacement table.\n\n## Draggable API\n\nNew server-side `Draggable` class for making external Vaadin components draggable onto the calendar,\nreplacing the previous manual JS initialization approach.\n\n- `new Draggable(component)` — wrap any Vaadin component to make it draggable\n- `new Draggable(component, entry)` — include entry data that FC uses to create a calendar entry on drop\n- `withItemSelector(String)` — container mode: only children matching the CSS selector are draggable\n- `withEventDataCallback(JsCallback)` — dynamically create entry data from the dragged element via JS\n- `calendar.addDraggable(draggable)` — register on a calendar; returns `Registration` for cleanup\n- `EntryReceiveEvent.getDraggable()` — access the original Draggable from the entry receive listener\n- `DropEvent.getDraggable()` — access the Draggable from the drop listener\n\nThe `Draggable` lifecycle is fully managed: re-initialization on reattach, cleanup of JS listeners\non deregistration and disconnect.\n\n## Interaction events\n\nNew server-side events cover the full drag/resize lifecycle:\n`EntryDragStartEvent`, `EntryDragStopEvent`, `EntryResizeStartEvent`, `EntryResizeStopEvent`.\n\nPlease note, that these should be mainly used for visual feedback. `EntryDroppedEvent` and `EntryResizedEvent` are still\nthe main events for reacting on calendar modification by the user.\n\nExternal entry support has been added via `ExternalEntryDroppedEvent` and `ExternalEntryResizedEvent`, fired when\nentries from a client-side event source are dropped into or resized within the calendar.\n\nAdditional interaction options are available via the `Option` enum:\n- `Option.DROP_ACCEPT` — CSS selector or JS function to filter accepted draggable elements\n- `Option.UNSELECT_CANCEL` — CSS selector for elements that should not cancel an active selection\n\n## Event sources\n\nTyped Java wrappers have been added for three common FC event source types:\n\n- `JsonFeedEventSource` — FC's JSON feed event source\n- `GoogleCalendarEventSource` — Google Calendar integration\n- `ICalendarEventSource` — iCalendar (.ics) feeds\n\nThe `JsonFeedEventSource` builder supports per-source parameter name overrides via `withStartParam(String)`,\n`withEndParam(String)`, and `withTimeZoneParam(String)`. For global overrides, use the corresponding\n`Option.EXTERNAL_EVENT_SOURCE_START_PARAM`, `EXTERNAL_EVENT_SOURCE_END_PARAM`, and\n`EXTERNAL_EVENT_SOURCE_TIME_ZONE_PARAM` option keys via `setOption`.\n\n`EventSourceFailureEvent` is fired server-side when an event source fails to load.\n\n## Scheduler resource features\n\nThe resource area can now be configured with typed column definitions via\n`setResourceAreaColumns(ResourceAreaColumn...)`. Resources can be grouped by a shared field using\n`setOption(SchedulerOption.RESOURCE_GROUP_FIELD, \"fieldName\")`,\nwith customizable render hooks for group headers and lanes via callback options.\nUse `setOption(SchedulerOption.REFETCH_RESOURCES_ON_NAVIGATE, true)` to re-fetch resources on each navigation.\nResource lifecycle events (`resourceAdd`, `resourceChange`, `resourceRemove`, `resourcesSet`) are\navailable as callback options for custom logic on resource data changes.\n\nIn addition to static text columns, the resource area sidebar can display interactive Vaadin components (DatePicker, TextField, ComboBox, etc.) \n— one component instance per resource. This pattern mirrors Vaadin Grid's `ComponentColumn` and is useful for:\n\n- Inline editing of resource metadata (deadlines, priority, owner, notes)\n- One-way binding to entry properties (display entry start/end dates, duration)\n- Two-way binding (component change updates entry; entry change updates component)\n\nComponents are created by a callback that receives the `Resource` and returns a component instance. They are fully interactive \n— users can type, select, open dropdowns, etc. — and survive FullCalendar view changes and re-renders. Type-safe runtime access is provided at any time via `getComponent(resource)`.\n\n\n## Accessibility\n\nA set of new options improves keyboard accessibility and screen reader support:\n\n- `Option.ENTRY_INTERACTIVE` — make all entries keyboard-focusable (WCAG 2.1 AA) via `setOption`\n- `Option.NATIVE_TOOLBAR_BUTTON_HINTS` — accessible labels for toolbar buttons\n- `Option.NATIVE_TOOLBAR_VIEW_HINT` / `Option.NAV_LINK_HINT` / `Option.MORE_LINK_HINT` — labels for view switchers, nav links, and \"+N more\" links\n- `Option.CLOSE_HINT` / `Option.TIME_HINT` / `Option.ENTRY_HINT` — labels for popover close buttons, time displays, and entries\n\n## Other new options and methods\n\nA number of smaller additions round out the release:\n\n- `Option.PROGRESSIVE_EVENT_RENDERING` — render events in batches as they arrive (via `setOption`)\n- `Option.DATE_INCREMENT` / `Option.DATE_ALIGNMENT` — navigation increment and alignment for custom views (via `setOption`)\n- `Entry.setConstraint(BusinessHours)` — constrain drag/resize to specific time slots\n- `Option.CONTENT_SECURITY_POLICY` — CSP nonce for dynamically generated `