@nerdworks/event-calendar-core
v2.6.2
Published
Full-sized drag & drop event calendar with resource view
Downloads
1
Maintainers
Readme
Event Calendar
Full-sized drag & drop JavaScript event calendar with resource view:
- Lightweight (33kb br compressed)
- Zero-dependency (pre-built bundle)
- Used on over 70,000 websites with Bookly
Inspired by FullCalendar, implements similar options.
Table of contents
- allDayContent
- allDaySlot
- buttonText
- date
- dateClick
- datesAboveResources
- datesSet
- dayCellFormat
- dayHeaderAriaLabelFormat
- dayHeaderFormat
- dayMaxEvents
- dayPopoverFormat
- displayEventEnd
- dragScroll
- duration
- editable
- events
- eventAllUpdated
- eventBackgroundColor
- eventClassNames
- eventClick
- eventColor
- eventContent
- eventDidMount
- eventDragMinDistance
- eventDragStart
- eventDragStop
- eventDrop
- eventDurationEditable
- eventLongPressDelay
- eventMouseEnter
- eventMouseLeave
- eventResize
- eventResizeStart
- eventResizeStop
- eventSources
- eventStartEditable
- eventTextColor
- eventTimeFormat
- filterResourcesWithEvents
- firstDay
- flexibleSlotTimeLimits
- headerToolbar
- height
- hiddenDays
- highlightedDates
- lazyFetching
- listDayFormat
- listDaySideFormat
- loading
- locale
- longPressDelay
- moreLinkContent
- noEventsClick
- noEventsContent
- nowIndicator
- pointer
- resources
- resourceLabelContent
- resourceLabelDidMount
- select
- selectable
- selectBackgroundColor
- selectLongPressDelay
- selectMinDistance
- scrollTime
- slotDuration
- slotEventOverlap
- slotHeight
- slotLabelFormat
- slotMaxTime
- slotMinTime
- theme
- titleFormat
- unselect
- unselectAuto
- unselectCancel
- view
- viewDidMount
- views
Usage
Svelte component / ES6 module
The first step is to install the Event Calendar core
package:
npm install --save-dev @event-calendar/core
Then install any additional plugins you plan to use:
npm install --save-dev @event-calendar/time-grid
You must use at least one plugin that provides a view. The following plugins are currently available:
@event-calendar/day-grid
@event-calendar/list
@event-calendar/resource-time-grid
@event-calendar/time-grid
@event-calendar/interaction
(doesn't provide a view)
Then, in your Svelte component, use the calendar something like this:
<script>
import Calendar from '@event-calendar/core';
import TimeGrid from '@event-calendar/time-grid';
let plugins = [TimeGrid];
let options = {
view: 'timeGridWeek',
events: [
// your list of events
]
};
</script>
<Calendar {plugins} {options} />
Or in ES6 module:
import Calendar from '@event-calendar/core';
import TimeGrid from '@event-calendar/time-grid';
let ec = new Calendar({
target: document.getElementById('ec'),
props: {
plugins: [TimeGrid],
options: {
view: 'timeGridWeek',
events: [
// your list of events
]
}
}
});
The CSS is located at @event-calendar/core/index.css
. If your build tool supports CSS processing, you can import it like this:
import '@event-calendar/core/index.css';
Pre-built browser ready bundle
Include the following lines of code in the <head>
section of your page:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@event-calendar/[email protected]/event-calendar.min.css">
<script src="https://cdn.jsdelivr.net/npm/@event-calendar/[email protected]/event-calendar.min.js"></script>
Please note that the file paths contain an indication of a specific version of the library. You can remove this indication, then the latest version will be loaded:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@event-calendar/build/event-calendar.min.css"> <script src="https://cdn.jsdelivr.net/npm/@event-calendar/build/event-calendar.min.js"></script>
But it is recommended to always specify the version and explicitly update it if necessary, in order to avoid unpredictable problems when a new version of the library is released.
Then initialize the calendar with something like this:
let ec = new EventCalendar(document.getElementById('ec'), {
view: 'timeGridWeek',
events: [
// your list of events
]
});
Modifying options after initialization
You can modify the calendar options after initialization using the setOption method.
ec.setOption('slotDuration', '01:00');
In Svelte, you can simply update the original options
object.
<script>
import Calendar from '@event-calendar/core';
import TimeGrid from '@event-calendar/time-grid';
let plugins = [TimeGrid];
let options = {
view: 'timeGridWeek'
};
function updateOptions() {
options.slotDuration = '01:00';
}
</script>
<button on:click={updateOptions}>Change slot duration</button>
<Calendar {plugins} {options} />
Options
allDayContent
- Type
Content
orfunction
- Default
'all-day'
Defines the content that is displayed as a title of the all-day
slot.
This value can be either a Content or a function that returns content:
function (arg) {
// return Content
}
arg
is an object with the following properties:
text
The default text
allDaySlot
- Type
boolean
- Default
true
Determines whether the all-day
slot is displayed at the top of the calendar.
When hidden with false
, all-day events will not be displayed in timeGrid
/resourceTimeGrid
views.
buttonText
- Type
object
orfunction
- Default
{close: 'Close', dayGridMonth: 'month', listDay: 'list', listMonth: 'list', listWeek: 'list', listYear: 'list', resourceTimeGridDay: 'day', resourceTimeGridWeek: 'week', timeGridDay: 'day', timeGridWeek: 'week', today: 'today'}
Views override the default value as follows:
- dayGridMonth
text => ({...text, next: 'Next month', prev: 'Previous month'})
- listDay
text => ({...text, next: 'Next day', prev: 'Previous day'})
- listMonth
text => ({...text, next: 'Next month', prev: 'Previous month'})
- listWeek
text => ({...text, next: 'Next week', prev: 'Previous week'})
- listYear
text => ({...text, next: 'Next year', prev: 'Previous year'})
- resourceTimeGridDay
text => ({...text, next: 'Next day', prev: 'Previous day'})
- resourceTimeGridWeek
text => ({...text, next: 'Next week', prev: 'Previous week'})
- timeGridDay
text => ({...text, next: 'Next day', prev: 'Previous day'})
- timeGridWeek
text => ({...text, next: 'Next week', prev: 'Previous week'})
Text that is displayed in buttons of the header toolbar.
This value can be either a plain object with all necessary properties, or a callback function that receives default button text object and should return a new one:
function (text) {
// return new button text object
}
text
date
- Type
Date
orstring
- Default
new Date()
Date that is currently displayed on the calendar.
This value can be either a JavaScript Date object, or an ISO8601 date string like '2022-12-31'
.
dateClick
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when the user clicks on a date or a time.
function (info) {}
info
is an object with the following properties:
date
dateStr
allDay
true
or false
. Determines if the click has occurred in the all-day
slot. Month and list views are also considered as all-day slots
dayEl
jsEvent
view
The current View object
resource
If the current view is a resource view, the Resource object that owns this date
datesAboveResources
- Type
boolean
- Default
false
Determines whether the resource view should render the date headings above the resource headings.
datesSet
- Type
function
- Default
undefined
Callback function that is triggered when the date range of the calendar was originally set or changed by clicking the previous/next buttons, changing the view, manipulating the current date via the API, etc.
function (info) {}
info
is an object with the following properties:
start
end
startStr
endStr
view
The current View object
dayCellFormat
- Type
object
orfunction
- Default
{day: 'numeric'}
Defines the text that is displayed inside the day cell in the dayGrid
view.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (date) {
// return Content with the formatted date string
}
date
dayHeaderAriaLabelFormat
- Type
object
orfunction
- Default
{dateStyle: 'long'}
Views override the default value as follows:
- dayGridMonth
{weekday: 'long'}
Defines the text that is used inside the aria-label
attribute in calendar column headings.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns formatted string:
function (date) {
// return formatted date string
}
date
dayHeaderFormat
- Type
object
orfunction
- Default
{weekday: 'short', month: 'numeric', day: 'numeric'}
Views override the default value as follows:
- dayGridMonth
{weekday: 'short'}
- timeGridDay
{weekday: 'long'}
Defines the text that is displayed on the calendar’s column headings.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (date) {
// return Content with the formatted date string
}
date
dayMaxEvents
- Type
boolean
- Default
false
Determines the maximum number of stacked event levels for a given day in the dayGrid
view.
If there are too many events, a link like +2 more
is displayed.
Currently, only the value true
is supported, which limits the number of events to the height of the day cell.
dayPopoverFormat
- Type
object
orfunction
- Default
{month: 'long', day: 'numeric', year: 'numeric'}
Defines the date format of title of the popover created by the dayMaxEvents option.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (date) {
// return Content with the formatted date string
}
displayEventEnd
- Type
boolean
- Default
true
Views override the default value as follows:
- dayGridMonth
false
Determines whether to display an event’s end time.
dragScroll
- Type
boolean
- Default
true
- Requires
Interaction
plugin
Determines whether the calendar should automatically scroll during the event drag-and-drop when the mouse crosses the edge.
duration
- Type
string
,integer
orobject
- Default
{weeks: 1}
Views override the default value as follows:
- dayGridMonth
{months: 1}
- listDay
{days: 1}
- listWeek
{weeks: 1}
- listMonth
{months: 1}
- listYear
{years: 1}
- resourceTimeGridDay
{days: 1}
- resourceTimeGridWeek
{weeks: 1}
- timeGridDay
{days: 1}
- timeGridWeek
{weeks: 1}
Sets the duration of a view.
This should be a value that can be parsed into a Duration object.
editable
- Type
boolean
- Default
false
- Requires
Interaction
plugin
Determines whether the events on the calendar can be dragged and resized (both at the same time).
If you don't need both, use the more specific eventStartEditable and eventDurationEditable instead.
events
- Type
Array
- Default
[]
Array of plain objects that will be parsed into Event objects and displayed on the calendar.
This option is not used if the eventSources
option is provided.
eventAllUpdated
- Type
function
- Default
undefined
Callback function that is triggered when all events have finished updating.
This is an experimental feature and its behavior may change in the future. The function is called at the end of the cycle of rendering all events. The rendering occurs when new events are added, already displayed events are modified, or events are deleted.
function (info) { }
info
is an object with the following properties:
view
The current View object
eventBackgroundColor
- Type
string
- Default
undefined
Sets the default background color for events on the calendar.
You can use any of the CSS color formats such '#f00'
, '#ff0000'
, 'rgb(255,0,0)'
, or 'red'
.
eventClassNames
- Type
string
,array
orfunction
- Default
undefined
Sets additional CSS classes for events.
This value can be either a string containing class names 'class-1 class-2 ...'
, an array of strings ['class-1', 'class-2', ...]
or a function that returns any of the above formats:
function (info) {
// return string or array
}
info
is an object with the following properties:
event
The associated Event object
view
The current View object
eventClick
- Type
function
- Default
undefined
Callback function that is triggered when the user clicks an event.
function (info) { }
info
is an object with the following properties:
el
event
The associated Event object
jsEvent
view
The current View object
eventColor
- Type
string
- Default
undefined
This is currently an alias for the eventBackgroundColor
.
eventContent
- Type
Content
orfunction
- Default
undefined
Defines the content that is rendered inside an event’s element.
This value can be either a Content or a function that returns content:
function (info) {
// return Content
}
info
is an object with the following properties:
event
The associated Event object
timeText
view
The current View object
eventDidMount
- Type
function
- Default
undefined
Callback function that is triggered right after the element has been added to the DOM. If the event data changes, this is not called again.
function (info) { }
info
is an object with the following properties:
el
event
The associated Event object
timeText
view
The current View object
eventDragMinDistance
- Type
integer
- Default
5
- Requires
Interaction
plugin
Defines how many pixels the user’s mouse must move before the event dragging begins.
eventDragStart
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when the event dragging begins.
function (info) { }
info
is an object with the following properties:
event
The associated Event object
jsEvent
view
The current View object
eventDragStop
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when the event dragging stops.
It is triggered before the event’s information has been modified (if moved to a new date/time) and before the eventDrop callback is triggered.
function (info) { }
info
is an object with the following properties:
event
The associated Event object
jsEvent
view
The current View object
eventDrop
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when dragging stops, and the event has moved to a different day/time.
It is triggered after the event’s information has been modified and after the eventDragStop callback has been triggered.
function (info) { }
info
is an object with the following properties:
event
The associated Event object
oldEvent
An Event object that holds information about the event before the drop
oldResource
If the resource has changed, this is the Resource object the event came from. If the resource has not changed, this will be undefined
newResource
If the resource has changed, this is the Resource object the event went to. If the resource has not changed, this will be undefined
delta
A Duration object that represents the amount of time the event was moved by
revert
A function that, if called, reverts the event’s start/end date to the values before the drag
jsEvent
view
The current View object
eventDurationEditable
- Type
boolean
- Default
true
- Requires
Interaction
plugin
Determines whether calendar events can be resized.
eventLongPressDelay
- Type
integer
- Default
undefined
- Requires
Interaction
plugin
For touch devices, the amount of time (in milliseconds) the user must hold down a tap before the event becomes draggable/resizable.
If not specified, it falls back to longPressDelay.
eventMouseEnter
- Type
function
- Default
undefined
Callback function that is triggered when the user hovers over an event with the cursor (mouse pointer).
function (info) { }
info
is an object with the following properties:
el
event
The associated Event object
jsEvent
view
The current View object
eventMouseLeave
- Type
function
- Default
undefined
Callback function that is triggered when the cursor (mouse pointer) is moved out of an event.
function (info) { }
info
is an object with the following properties:
el
event
The associated Event object
jsEvent
view
The current View object
eventResize
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when resizing stops, and the duration of the event has changed.
It is triggered after the event’s information has been modified and after the eventResizeStop callback has been triggered.
function (info) { }
info
is an object with the following properties:
event
The associated Event object
oldEvent
An Event object that holds information about the event before the resize
endDelta
A Duration object that represents the amount of time the event’s end date was moved by
revert
A function that, if called, reverts the event’s end date to the values before the resize
jsEvent
view
The current View object
eventResizeStart
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when the event resizing begins.
function (info) { }
info
is an object with the following properties:
event
The associated Event object
jsEvent
view
The current View object
eventResizeStop
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when the event resizing stops.
It is triggered before the event’s information has been modified (if duration is changed) and before the eventResize callback is triggered.
function (info) { }
info
is an object with the following properties:
event
The associated Event object
jsEvent
view
The current View object
eventSources
- Type
EventSource[]
- Default
[]
Array of EventSource objects that will provide the Event Calendar with data about events.
This option is used instead of the events
option.
EventSource
should be an object with one of the following sets of properties:
1. Fetch events from a URL
url
A URL that the calendar will fetch Event objects from. HTTP requests with the following parameters will be sent to this URL whenever the calendar needs new event data
start
end
method
HTTP request method. Default 'GET'
extraParams
Other GET/POST data you want to send to the server. Can be a plain object or a function that returns an object. Default {}
2. Execute custom function
events
A custom function that is executed whenever the Event Calendar needs new event data.
function(fetchInfo, successCallback, failureCallback) { }
fetchInfo
is an object with the following properties:
start
end
startStr
endStr
The successCallback
function must be called by the custom function with an array of parsable Event objects.
If there is any failure (e.g., if an AJAX request fails), then call the failureCallback
instead. It accepts an argument with information about the failure.
Instead of calling successCallback
and failureCallback
, you may return the resulting array of events or return a Promise (or thenable) object instead.
eventStartEditable
- Type
boolean
- Default
true
- Requires
Interaction
plugin
Determines whether the events on the calendar can be dragged.
eventTimeFormat
- Type
object
orfunction
- Default
{hour: 'numeric', minute: '2-digit'}
Defines the time-text that is displayed on each event.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (start, end) {
// return Content with the formatted time string
}
start
end
eventTextColor
- Type
string
- Default
undefined
Sets the default text color for events on the calendar.
You can use any of the CSS color formats such '#f00'
, '#ff0000'
, 'rgb(255,0,0)'
, or 'red'
.
filterResourcesWithEvents
- Type
boolean
- Default
false
Determines whether resources with no events for the current range should be hidden in the resource view.
firstDay
- Type
integer
- Default
0
The day that each week begins at, where Sunday is 0
, Monday is 1
, etc. Saturday is 6
.
flexibleSlotTimeLimits
- Type
boolean
orobject
- Default
false
Determines whether slotMinTime and slotMaxTime should automatically expand when an event goes out of bounds.
If set to true
, then the decision on whether to expand the limits will be made based on the analysis of currently displayed events, but excluding background events.
If you want background events not to be ignored, then instead of true
you can pass an object with the following properties:
eventFilter
A function to determine whether a given event should be taken into account or not.
function(event) {
// return true or false
}
event
Event object to be analyzed.
The function must return true
to have this event counted, or false
to ignore it
headerToolbar
- Type
object
- Default
{start: 'title', center: '', end: 'today prev,next'}
Defines the buttons and title at the top of the calendar.
An object can be supplied with properties start
,center
,end
. These properties contain strings with comma/space separated values. Values separated by a comma will be displayed adjacently. Values separated by a space will be displayed with a small gap in between. Strings can contain any of the following values:
title
prev
next
today
a view name like dayGridMonth
height
- Type
string
- Default
undefined
Defines the height of the entire calendar.
This should be a valid CSS value like '100%'
or '600px'
.
hiddenDays
- Type
Array
- Default
[]
Exclude certain days-of-the-week from being displayed, where Sunday is 0
, Monday is 1
, etc. Saturday is 6
.
highlightedDates
- Type
Array
- Default
[]
Array of dates that need to be highlighted in the calendar.
Each date can be either an ISO8601 date string like '2022-12-31'
, or a JavaScript Date object.
lazyFetching
- Type
boolean
- Default
true
Determines when event fetching should occur.
When set to true
(the default), the calendar will only fetch events when it absolutely needs to, minimizing HTTP requests. For example, say your calendar starts out in month view, in February. The Event Calendar will fetch events for the entire month of February and store them in its internal storage. Then, say the user switches to week view and begins browsing the weeks in February. The calendar will avoid fetching events because it already has this information stored.
When set to false
, the calendar will fetch events any time the view is switched, or any time the current date changes (for example, as a result of the user clicking prev/next).
listDayFormat
- Type
object
orfunction
- Default
{weekday: 'long'}
Defines the text on the left side of the day headings in list view.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (date) {
// return Content with the formatted date string
}
date
listDaySideFormat
- Type
object
orfunction
- Default
{year: 'numeric', month: 'long', day: 'numeric'}
Defines the text on the right side of the day headings in list view.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (date) {
// return Content with the formatted date string
}
date
loading
- Type
function
- Default
undefined
Callback function that is triggered when event fetching starts/stops.
function (isLoading) { }
isLoading
true
when the calendar begins fetching events, false
when it’s done.
locale
- Type
string
- Default
undefined
Defines the locales
parameter for the native JavaScript Intl.DateTimeFormat object that the Event Calendar uses to format date and time strings in options such as dayHeaderFormat, eventTimeFormat, etc.
longPressDelay
- Type
integer
- Default
1000
For touch devices, the amount of time (in milliseconds) the user must hold down a tap before the event becomes draggable/resizable or the date becomes selectable.
For a more granular configuration, see eventLongPressDelay and selectLongPressDelay.
moreLinkContent
- Type
Content
orfunction
- Default
undefined
Defines the text that is displayed instead of the default +2 more
created by the dayMaxEvents option.
This value can be either a Content or a function that returns content:
function (arg) {
// return Content
}
arg
is an object with the following properties:
num
text
The default text like +2 more
noEventsClick
- Type
function
- Default
undefined
Callback function that is triggered when the user clicks No events area in list view.
function (info) { }
info
is an object with the following properties:
jsEvent
view
The current View object
noEventsContent
- Type
Content
orfunction
- Default
'No events'
Defines the text that is displayed in list view when there are no events to display.
This value can be either a Content or a function that returns content:
function () {
// return Content
}
nowIndicator
- Type
boolean
- Default
false
Enables a marker indicating the current time in timeGrid
/resourceTimeGrid
views.
pointer
- Type
boolean
- Default
false
- Requires
Interaction
plugin
Enables mouse cursor pointer in timeGrid
/resourceTimeGrid
views.
resources
- Type
Array
- Default
[]
Array of plain objects that will be parsed into Resource objects for displaying in the resource view.
resourceLabelContent
- Type
string
,object
orfunction
- Default
undefined
Defines the content that is rendered inside an element with a resource title.
This value can be either a Content or a function that returns content:
function (info) {
// return Content
}
info
is an object with the following properties:
resource
The associated Resource object
date
resourceLabelDidMount
- Type
function
- Default
undefined
Callback function that is triggered right after the element has been added to the DOM. If the resource data changes, this is not called again.
function (info) { }
info
is an object with the following properties:
el
resource
The associated Resource object
date
select
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when a date/time selection is made.
function (info) { }
info
is an object with the following properties:
start
end
startStr
endStr
allDay
true
or false
. Determines if the selection has occurred in the all-day
slot
jsEvent
view
The current View object
resource
If the current view is a resource view, the Resource object that was selected
selectable
- Type
boolean
- Default
false
- Requires
Interaction
plugin
Determines whether the user is allowed to highlight multiple days or time slots by clicking and moving the pointer.
selectBackgroundColor
- Type
string
- Default
undefined
- Requires
Interaction
plugin
Sets the background color for the event indicating the current selection. See selectable.
You can use any of the CSS color formats such '#f00'
, '#ff0000'
, 'rgb(255,0,0)'
, or 'red'
.
selectLongPressDelay
- Type
integer
- Default
undefined
- Requires
Interaction
plugin
For touch devices, the amount of time (in milliseconds) the user must hold down a tap before the date becomes selectable.
If not specified, it falls back to longPressDelay.
selectMinDistance
- Type
integer
- Default
5
- Requires
Interaction
plugin
Defines how many pixels the user’s mouse must move before the selection begins.
scrollTime
- Type
string
,integer
orobject
- Default
'06:00:00'
Determines how far forward the scroll pane is initially scrolled.
This should be a value that can be parsed into a Duration object.
slotDuration
- Type
string
,integer
orobject
- Default
'00:30:00'
Defines the frequency for displaying time slots.
This should be a value that can be parsed into a Duration object.
slotEventOverlap
- Type
boolean
- Default
true
Determines whether events in the timeGrid
/resourceTimeGrid
views should visually overlap when they intersect in time.
If set to false
, then intersecting events will be placed next to each other.
slotHeight
- Type
integer
- Default
24
Defines the time slot height in pixels. When changing the setting, you must additionally override the following CSS styles:
.ec-time, .ec-line {
height: 24px; /* override this value */
}
slotLabelFormat
- Type
object
orfunction
- Default
{hour: 'numeric', minute: '2-digit'}
Defines the text that will be displayed within a time slot.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (time) {
// return Content with the formatted time string
}
time
slotMaxTime
- Type
string
,integer
orobject
- Default
'24:00:00'
Defines the last time slot that will be displayed for each day.
This should be a value that can be parsed into a Duration object.
slotMinTime
- Type
string
,integer
orobject
- Default
'00:00:00'
Defines the first time slot that will be displayed for each day.
This should be a value that can be parsed into a Duration object.
theme
- Type
object
orfunction
- Default
{active: 'ec-active', allDay: 'ec-all-day', bgEvent: 'ec-bg-event', bgEvents: 'ec-bg-events', body: 'ec-body', button: 'ec-button', buttonGroup: 'ec-button-group', calendar: 'ec', compact: 'ec-compact', content: 'ec-content', day: 'ec-day', dayFoot: 'ec-day-foot', dayHead: 'ec-day-head', daySide: 'ec-day-side', days: 'ec-days', draggable: 'ec-draggable', dragging: 'ec-dragging', event: 'ec-event', eventBody: 'ec-event-body', eventTag: 'ec-event-tag', eventTime: 'ec-event-time', eventTitle: 'ec-event-title', events: 'ec-events', extra: 'ec-extra', ghost: 'ec-ghost', handle: 'ec-handle', header: 'ec-header', hiddenScroll: 'ec-hidden-scroll', highlight: 'ec-highlight', icon: 'ec-icon', line: 'ec-line', lines: 'ec-lines', noEvents: 'ec-no-events', nowIndicator: 'ec-now-indicator', otherMonth: 'ec-other-month', pointer: 'ec-pointer', popup: 'ec-popup', preview: 'ec-preview', resizer: 'ec-resizer', resizingX: 'ec-resizing-x', resizingY: 'ec-resizing-y', resource: 'ec-resource', resourceTitle: 'ec-resource-title', selecting: 'ec-selecting', sidebar: 'ec-sidebar', sidebarTitle: 'ec-sidebar-title', time: 'ec-time', title: 'ec-title', today: 'ec-today', toolbar: 'ec-toolbar', uniform: 'ec-uniform', view: '', weekdays: ['ec-sun', 'ec-mon', 'ec-tue', 'ec-wed', 'ec-thu', 'ec-fri', 'ec-sat'], withScroll: 'ec-with-scroll'}
Views override the default value as follows:
- dayGridMonth
theme => ({...theme, view: 'ec-day-grid ec-month-view'})
- listDay
theme => ({...theme, view: 'ec-list ec-day-view'})
- listMonth
theme => ({...theme, view: 'ec-list ec-month-view'})
- listWeek
theme => ({...theme, view: 'ec-list ec-week-view'})
- listYear
theme => ({...theme, view: 'ec-list ec-year-view'})
- resourceTimeGridDay
theme => ({...theme, view: 'ec-time-grid ec-resource-day-view'})
- resourceTimeGridWeek
theme => ({...theme, view: 'ec-time-grid ec-resource-week-view'})
- timeGridDay
theme => ({...theme, view: 'ec-time-grid ec-day-view'})
- timeGridWeek
theme => ({...theme, view: 'ec-time-grid ec-week-view'})
Defines the CSS classes that the Event Calendar uses to generate HTML markup.
This value can be either a plain object with all necessary properties, or a callback function that receives default theme object and should return a new one:
function (theme) {
// return actual theme object
}
theme
titleFormat
- Type
object
orfunction
- Default
{year: 'numeric', month: 'short', day: 'numeric'}
Views override the default value as follows:
- dayGridMonth
{year: 'numeric', month: 'long'}
- timeGridDay
{year: 'numeric', month: 'long', day: 'numeric'}
Defines the text that is displayed in the header toolbar’s title.
This value can be either an object with options for the native JavaScript Intl.DateTimeFormat object, or a callback function that returns a Content with the formatted string:
function (start, end) {
// return Content with the formatted date string
}
start
end
unselect
- Type
function
- Default
undefined
- Requires
Interaction
plugin
Callback function that is triggered when the current selection is cleared.
A selection can be cleared for a number of reasons:
- The user clicks away from the current selection (this does not happen when unselectAuto is
false
). - The user makes a new selection. The unselect callback will be fired before the new selection occurs.
- The user navigates forward or backward in the current view, or switches to a new view.
- The unselect method is called via the API.
function (info) { }
info
is an object with the following properties:
jsEvent
JavaScript native event object with low-level information such as click coordinates.
If unselect has been triggered via the unselect method, jsEvent will be undefined
view
The current View object
unselectAuto
- Type
boolean
- Default
true
- Requires
Interaction
plugin
Determines whether clicking elsewhere on the page will clear the current selection. See selectable.
unselectCancel
- Type
string
- Default
''
- Requires
Interaction
plugin
A CSS selector that specifies elements that will ignore the unselectAuto option.
Clicking on elements that match this CSS selector will prevent the current selection from being cleared (because of the unselectAuto option).
view
- Type
string
- Default
'resourceTimeGridWeek'
The view that is displayed in the calendar. Can be 'dayGridMonth'
, 'listDay'
, 'listWeek'
, 'listMonth'
, 'listYear'
, 'resourceTimeGridDay'
, 'resourceTimeGridWeek'
, 'timeGridDay'
or 'timeGridWeek'
.
viewDidMount
- Type
function
- Default
undefined
Callback function that is triggered right after the view has been added to the DOM.
function (info) { }
info
is an object with the following properties:
view
The mounted View object
views
- Type
object
- Default
{}
You can specify options that apply only to specific views. To do so provide separate options objects within the views
option, keyed by the name of the view.
Methods
Methods allow you to manipulate the Event Calendar after initialization. They are accessible from the calendar instance.
In Svelte, methods are available from a component instance:
<script>
import Calendar from '@event-calendar/core';
import TimeGrid from '@event-calendar/time-grid';
let ec;
let plugins = [TimeGrid];
let options = {
view: 'timeGridWeek',
eventSources: [{events: function() {
console.log('fetching...');
return [];
}}]
};
function invokeMethod() {
ec.refetchEvents();
}
</script>
<button on:click={invokeMethod}>Refetch events</button>
<Calendar bind:this={ec} {plugins} {options} />
getOption( name )
- Parameters
name
string
The option name
- Return value
mixed
orundefined
This method allows you to get the current value of any calendar option.
// E.g. Get current date
let date = ec.getOption('date');
setOption( name, value )
- Parameters
name
string
The option namevalue
mixed
The new option value
- Return value
EventCalendar
The calendar instance for chaining
This method allows you to set new value to any calendar option.
// E.g. Change the current date
ec.setOption('date', new Date());
getEvents()
- Return value
Event[]
Array of Event objects
Returns an array of events that the calendar has in memory.
getEventById( id )
- Parameters
id
string|integer
The ID of the event
- Return value Event object or
null
Returns a single event with the matching id
.
removeEventById( id )
- Parameters
id
string|integer
The ID of the event
- Return value
EventCalendar
The calendar instance for chaining
Removes a single event with the matching id
.
addEvent( event )
- Parameters
event
object
A plain object that will be parsed into an Event object
- Return value Event object or
null
Adds a new event to the calendar.
updateEvent( event )
- Parameters
event
object
A plain object or Event object
- Return value
EventCalendar
The calendar instance for chaining
Updates a single event with the matching event
.id
.
refetchEvents()
- Return value
EventCalendar
The calendar instance for chaining
Refetches events from all sources.
dateFromPoint( x, y )
- Return value
object
ornull
Returns an info
object with data as if the dateClick event had fired for that point.
info
object contains the following properties:
date
allDay
true
or false
. Determines if the point is in the all-day
slot. Month and list views are also considered as all-day slots
dayEl
resource
If the current view is a resource view, the Resource object that owns this date
Using this method, you can, for example, find out on which day a click occurred inside a multi-day event. To do this, inside eventClick, pass the jsEvent.clientX
and jsEvent.clientY
coordinates to dateFromPoint
and get the desired date.
destroy()
- Return value
undefined
Destroys the calendar, removing all DOM elements, event handlers, and internal data.
getView()
- Return value
View
Returns the View object for the current view.
unselect()
- Return value
EventCalendar
The calendar instance for chaining
Clears the current selection. See selectable.
Content
The content value can be presented in the following forms:
- a string containing text
'some text'
- an object containing the HTML string
{html: '<p>some HTML</p>'}
- an object containing an array of DOM nodes
{domNodes: [node1, node2, ...]}
Event object
This is a JavaScript object that the Event Calendar uses to store information about a calendar event.
Here are all properties that exist in Event object:
id
resourceIds
allDay
true
or false
. Determines if the event is shown in the all-day
slot
start
end
title
Content
The text appearing on the event. See Content
editable
true
, false
or undefined
. The value overriding the editable setting for this specific event
startEditable
true
, false
or undefined
. The value overriding the eventStartEditable setting for this specific event
durationEditable
true
, false
or undefined
. The value overriding the eventDurationEditable setting for this specific event
display
The rendering type of the event. Can be 'auto'
or 'background'
In addition, in your callback functions, you may get the 'ghost'
, 'preview'
and 'pointer'
for this property, which are internal values and are used, for example, to display events during drag-and-drop operations
backgroundColor
The eventBackgroundColor override for this specific event
textColor
The eventTextColor override for this specific event
extendedProps
A plain object holding miscellaneous properties specified during parsing in the explicitly given extendedProps
field
Parsing event from a plain object
When Event Calendar receives an array of plain event’s objects either from the events
option or as a result of an HTTP request to a URL of an event source, it parses the input objects into proper Event objects.
Here are all admissible fields for the event’s input object:
id
string
or integer
A unique identifier of the event. Default auto-generated value
resourceId
string
or integer
An ID of a resource that the event is associated with. This field is not used if resourceIds
is provided. Default undefined
resourceIds
Array
An array of resource IDs that the event is associated with. This field is used instead of resourceId
. Default []
allDay
boolean
Determines if the event is shown in the all-day slot. Defaults to true
if start
and end
are both passed without a time part, false
otherwise
start
string
or Date
This should be either an ISO8601 datetime string like '2022-12-31 09:00:00'
, or a JavaScript Date object holding the event’s start time
end
string
or Date
This should be either an ISO8601 datetime string like '2022-12-31 13:00:00'
, or a JavaScript Date object holding the event’s end time
title
Content
The text that will appear on the event. See Content. Default ''
editable
boolean
Overrides the master editable option for this single event. Default undefined
startEditable
boolean
Overrides the master eventStartEditable option for this single event. Default undefined
display
string
The rendering type of the event. Can be 'auto'
or 'background'
. Default 'auto'
backgroundColor
string
Sets the event’s background color just like the calendar-wide eventBackgroundColor option. Default undefined
textColor
string
Sets the event’s text color just like the calendar-wide eventTextColor option. Default undefined
color
string
This is currently an alias for the backgroundColor
field. Default undefined
extendedProps
object
A plain object with any miscellaneous properties. It will be directly transferred to the extendedProps
property of the Event object. Default {}
Duration object
This is a JavaScript object that the Event Calendar uses to store information about a period of time, like 30 minutes or 1 day and 6 hours.
Here are all properties that exist in Duration object:
years
months
days
seconds
inWeeks
Parsing duration from input values
When Event Calendar receives a value for options like duration
, scrollTime
, slotDuration
and others, it parses it into a proper Duration object.
The admissible input value can be specified in one of three formats:
- an object with any of the following keys:
year
,years
,month
,months
,day
,days
,minute
,minutes
,second
,seconds
- a string in the format
hh:mm:ss
orhh:mm
. For example,'05:00'
specifies 5 hours - an integer specifying the total number of seconds
Resource object
This is a JavaScript object that the Event Calendar uses to store information about a resource. Calendar events can be associated with resources and displayed separately using the resource view.
Here are all properties that exist in Resource object:
id
title
The title of the resource. See Content.
eventBackgroundColor
eventTextColor
Parsing resource from a plain object
When Event Calendar receives an array of plain resource’s objects for the resources
option, it parses the input objects into proper Resource objects.
Here are all admissible fields for the resource’s input object:
id
integer
or string
Uniquely identifies the resource. Event objects with a corresponding resourceIds
field will be linked to this resource. Will be coerced into a string
title
Content
Text that will be displayed on the resource when it is rendered. See Content. Default ''
eventBackgroundColor
string
Sets the default background color for this resource's events just like the calendar-wide eventBackgroundColor option. Default undefined
eventTextColor
string
Sets the default text color for this resource's events just like the calendar-wide eventTextColor option. Default undefined
View object
A View object contains information about a calendar view, such as title and date range.
Here are all properties that exist in View object:
type
title
currentStart
currentEnd
activeStart
activeEnd
Theming
The library provides a built-in dark theme. You can activate it by adding the ec-dark
CSS class to any parent element of the calendar, e.g. <body class="ec-dark">
.
If you want the dark theme to be activated automatically based on the preferred color scheme, then use the ec-auto-dark
CSS class instead.
Please note that the dark theme does not change the background and font color in the calendar. These are assumed to be set by the page styles, and the calendar inherits these styles.
If you do need to set the background or font color of the calendar, use local CSS variables for this:
.ec {
--ec-bg-color: #22272e;
--ec-text-color: #adbac7;
}
A list of all available CSS variables can be found here.
Browser support
The latest versions of Chrome, Firefox, Safari, and Edge are supported.
The library is compiled to support browsers that match the following browserslist configuration:
defaults and supports fetch
. You can see the resulting list here.