vuelcalendar v1.0.25

VuelCalendar

Since 19.03.2024 All new features, issues, fixes, updates and DOCS will be available at below link

• Component preview
• Docs

https://vuelcomponents.github.io/

UPCOMING

• v0.8.0 - Mobile support, Treshold Event Drag(eg. 15 min)
• v0.9.0 - ListView, MonthView, DayView
• v0.9.5 - Plugins: Toolbars,
• v1.0.0 - Fully stable version + VanillaJS support
• v1.1.0 - Angular support

Important UPDATE 26.03.2024 -> v0.7

Today's update on March 26, 2024 introduces the Performance Mode, which enables smooth handling of large volumes of events in the calendar. This mode operates on two main pillars: virtual scrolling and event caching in two-dimensional arrays. By combining these solutions, it allows for loading unlimited events at once, ensuring smooth operations on them. Despite using Performance Mode, users still have access to the full list of events for the day through specific events.

*Fully supports backend integration.

This Vue Calendar is a versatile calendar search tool akin to V-Calendar, designed for efficient schedule management and event allocation along a horizontal timeline. It offers a range of features facilitating the manipulation, deletion, modification, and addition of events, along with configurations for timeline styling and date ranges.

This calendar tool serves as a robust platform for organizing events and managing time efficiently. Users can seamlessly navigate through dates, allocate events with precision, and customize the display to suit their specific needs. Whether it's for personal scheduling, project management, or team coordination, VuelCalendar provides a user-friendly interface coupled with powerful functionalities.

Key features of VuelCalendar include:

• Event Management: Users can effortlessly add, edit, move, and delete events directly on the timeline, streamlining the process of organizing schedules.

• Customizable Timeline: The timeline display can be configured to accommodate different date ranges, time intervals, and styles, ensuring flexibility in visualizing schedules.

• Date Range Selection: Users can specify date ranges to focus on specific periods, making it easier to manage schedules within desired timeframes.

• Configurable Event Properties: Users can define various properties for events, such as title, description, duration, and color coding, for enhanced organization and clarity.

• Integration Capabilities: VuelCalendar can be integrated with other applications and platforms, allowing for seamless data exchange and collaboration.

Updated 22.03.2024 | 15:41 | Read about new features at the end of the document -> v.0.2

How to Use

:point_down:

npm install vuelcalendar

:point_up_2:

Vue

<section class="w-[800px]">
   <VuelCalendar :vuelCalendarOptions="vuelCalendarOptions" :colors="colors" ></VuelCalendar>
</section>
/* These settings will cause the calendar to extend the document downward when expanding the timeline downwards. */

<section class="w-[800px] max-h[600px] overflow-auto">
   <VuelCalendar :vuelCalendarOptions="vuelCalendarOptions" :colors="colors"></VuelCalendar>
</section>
/* 
If you enforce height through styling, you must also set overflow!!.
This prevents your document from expanding, allowing the calendar to be extendable downwards. 
However, remember!
You must set the maximum height equal to the height parameter for the calendarOptions object. 
This is crucial for the correct functioning of the calendar. 
*/

TS/JS Object

COMPOSITION API

const calendarApi = ref<IVuelCalendarApi | undefined>(undefined);

const vuelCalendarOptions = ref<IVuelCalendarOptions>({
    height:600, /* The initial height of the calendar*/
    theme:'dark', /* 'dark' and 'light' theme available */
    startDate:new Date(), /* Define the first day being displayed on the calendar */
    daysForward:5, /* Minimum 1, this parameter defines how many days after the start day should be displayed */
    startHour:17, /* Minimum 0, Max 23, define time from 'startHour' to 23:59 */
    endHour:24, /* Minimum 1, Max 24, Must be greater than startHour */
    renderer:'ExampleRender', /* example vue component to use as renderer for event container (read about Renderers below)*/,
    draggableEvents:true, /* set if you want to implement draggable events -> onEventDropped(drop:VuelCalendarDrop) -< then implement this method to catch dropped events on timeline */
    /* set if you want to implement resizable events -> onEventStartResized(resized:VuelCalendarResize); onEventEndResized(resized:VuelCalendarResize); -< then implement these methods to operate on resized events on timeline */
    resizableEvents:true,
    onVuelCalendarApiReady: (api: IVuelCalendarApi) => {
        calendarApi.value = api;
        api.setEvents([
            {
                id: 1,
                label: 'Event #1',
                data: {},
                start: new Date(new Date().setHours(8, 0)),
                end: new Date(new Date().setHours(23, 0)),
            },
        ]); /* after API is ready you can set new Events to the calendar */
    },
    onDayClicked:(day:VuelCalendarDay)=>
    {
        /* The function returns the day that was clicked, along with the time and date on the timeline, as well as the events that belong to this day.*/
    },
    onDayDblClicked:(day:VuelCalendarDay)=>
    {
        /* The function returns the day that was double clicked, along with the time and date on the timeline, as well as the events that belong to this day.*/
    },
    onEventClicked:(event:VuelCalendarEvent)=>
    {
        /* The function returns the event that was clicked, along with the time and date of start and end, as well as the data:any that belong to this event.*/
    },
    onEventDropped:(event:VuelCalendarDrop)=>
    {
        /* property draggableEvents must be set to true in VuelCalendarOptions */
        /* The function returns the drop object(VuelCalendarEvent&VuelCalendarDay&MousEvent) that was being dragged, along with the time and date on timeline.*/
    },
});

OPTIONS API

import VuelCalendar from 'vuelcalendar';
import type {IVuelCalendarApi, VuelCalendarOptions, VuelCalendarEvent, VuelCalendarDay} from 'vuelcalendar';

calendarApi: {} as any, /* options api fix for this type will be available in the futue, now its recommended to use it as any */
calendarOptions:{
        height:600, /* The initial height of the calendar*/
        theme:'dark', /* 'dark' and 'light' theme available */
        startDate:new Date(), /* Define the first day being displayed on the calendar */
        daysForward:5, /* Minimum 1, this parameter defines how many days after the start day should be displayed */
        startHour:17, /* Minimum 0, Max 23, define time from 'startHour' to 23:59 */
        endHour:24, /* Minimum 1, Max 24, Must be greater than startHour */
        renderer:'ExampleRender', /* example vue component to use as renderer for event container (read about Renderers below)*/
        draggableEvents:true, /* set if you want to implement draggable events -> onEventDropped(drop:VuelCalendarDrop) -< then implement this method to catch dropped events on timeline */
        /* set if you want to implement resizable events -> onEventStartResized(resized:VuelCalendarResize); onEventEndResized(resized:VuelCalendarResize); -< then implement these methods to operate on resized events on timeline */
        resizableEvents:true,
        onVuelCalendarApiReady:(api:any)=>{
          this.calendarApi = api;
          api.setEvents( [
            {
              id:1,
              label:'Event #1',
              data:{},
              start:new Date(new Date().setHours(8, 0)),
              end:new Date(new Date().setHours(23, 0)),
            }
          ]) /* after API is ready you can set new Events to the calendar */
        },
        onDayClicked:(day:VuelCalendarDay)=>
        { 
            /* The function returns the day that was clicked, along with the time and date on the timeline, as well as the events that belong to this day.*/
        },
        onDayDblClicked:(day:VuelCalendarDay)=>
        {
            /* The function returns the day that was double clicked, along with the time and date on the timeline, as well as the events that belong to this day.*/
        },
        onEventClicked:(event:VuelCalendarEvent)=>
        {
           /* The function returns the event that was clicked, along with the time and date of start and end, as well as the data:any that belong to this event.*/
        },
        onEventDropped:(event:VuelCalendarDrop)=>
        {
            /* property draggableEvents must be set to true in VuelCalendarOptions */
            /* The function returns the drop object(VuelCalendarEvent&VuelCalendarDay&MousEvent) that was being dragged, along with the time and date on timeline.*/
        },

API functions

Change timeline start date

calendarApi!.setDate(date);

• date: Type of Date

This function is responsible for changing the startDate to a new date. If you change this date, your timeline will set the initial date to this date.

Change timeline start hour

calendarApi!.setStartHour(hour);

• hour: Type of Number min:0, max: 23

This function is responsible for changing the startHour to a new hour. If you change this hour, your timeline will set the initial hour to this hour.

Change timeline end hour

calendarApi!.setEndHour(hour);

• hour: Type of Number min:0, max: 24

This function is responsible for changing the endHour to a new hour. If you change this hour, your timeline will set the end hour of timeline to this hour.

Set date range

calendarApi!.setDateRange(startDate:Date, endDate:Date);

This function is responsible for setting a specific date range on calendar

Set time range

calendarApi!.setDateRange(startHour:number, endHour:number);
/* set the start and hour on timeline */

startHour: min0, max 24 endHour: min:0, max24 This function is responsible for setting a specific time range on calendar

Set days forward

calendarApi!.setDaysForward(days:Number);

days: Type of Number min:1 = 1 means a one day on timeline This function is responsible for setting a days forward on time line

Switch view mode ( days <=> month )

calendarApi.switchViewMode();

This function is responsible for switching the calendar view mode from daily to monthly and vice versa.

Set new events

calendarApi.setEvents(events);

• events: Type of VuelCalendarEvent

This function is responsible for deleting old events and replacing them with new ones.

Pushing events

calendarApi.addEvents(events);

• events: Type of VuelCalendarEvent

This function is responsible for adding new events to the current ones.

Remove events by param

calendarApi.removeEventsByParam(param, value);

• param: Type of String
• value: Type of any

This function is responsible for removing the selected event. For example, by sending the parameter string 'id' with the value 5, we will remove the event with id === 5

calendarApi.removeEventsByParam('id', 5);
/* event with id 5 has been removed */

Edit events by param

calendarApi.configureEventsByParam(param, value, object);

• param: Type of String
• value: Type of any
• object: Type of VuelCalendarEvent

This function is responsible for finding the event with the specified parameter and value, and then replacing the values for that parameter. For example, if we insert 'id' in the parameter, 5 in the value, and {start: todaysDate, end: todaysDatePlus2Hours, data: {employees: listOfEmployees}} in the object, then in the event with id 5, the start and end dates will be changed, and the object data of any type will be assigned a list of employees.

calendarApi.configureEventsByParam(
    'id', 5, 
        {
           start:startDate, 
           end:endDate, 
           data:{
             employees:[]
           }
        })
/* params has been changed to event id === 5 */

Features and updates

22.03.2024 | 17:01

• Great performance update

• Calendar is ready to work on thousands of events

• A lot of features has appeared. Visit the site to look at changes.

20.03.2024 | 15:41

1. From now on, you can resize events on timeline in end and start time and date.

to use pass 'resizableEvents = true' to vuelCalendarOptions and implement methods:

onEventStartResized:(resized:VuelCalendarResize)=>{}
onEventEndResized:(resized:VuelCalendarResize)=>{}

details: https://vuelcomponents.github.io/

18.03.2024 | 15:41

1. From now on, you can set events spanning over multiple days. The issue with random errors in 'endDateCorrection' for onEventDropped has also been resolved. Wow :)

16.03.2024 | 19:40

1. Function onDayDoubleClicked(similiar to onDayClicked) has been included

16.03.2024 | 19:10

1. Corrected functionality of drag & drop. parameter 'endDateCorrection' has been included to VuelCalendarDrop object passed to onEventDrop() function.

• The 'endDateCorrection' parameter is responsible for providing the end time after the shift. When your event is being moved, for example, 2.5 hours forward or backward, this parameter gives you the end date of the event after the shift, in order to provide you with the correct duration of the item in case you want to use it in onDrop to utilize configureEventsByParam and change the start and end as if you were moving it along the timeline.

16.03.2024 | 11:30

1. Added a new function to the API: setTimeRange -> from now on, you can set the time range on the timeline (from 00 to 24).

calendarApi.setTimeRange(6, 13) /* startHour has been set to 6:00 and endHour to 13:00 */

2. Added a new function to the API: setDateRange -> from now on, you can set the date range on the timeline (e.g., from 15.04.2022 to 20.04.2022).

calendarApi.setDateRange(new Date(2024-12-03), new Date(2024-12-19))

3. Added a new function to the API: setEndHour -> from now on, you can set the end hour (e.g., set the end hour to 23:00).

calendarApi.setEndHour(14) /* timeline will end on 14:00 */

15.03.2024 | 19:45

• Tiny borders style modification + calendarApi.setViewMode() method included, ugly bar removed.

13.03.2024 | 21:15

1. Drag & Drop Functionality

• Example usage:

vuelCalendarOptions: {
...
draggableEvents:true
}

onEventDropped:(event:VuelCalendarDrop)=>
{
    /* property draggableEvents must be set to true in VuelCalendarOptions */
    /* The function returns the drop object(VuelCalendarEvent&VuelCalendarDay&MousEvent) that was being dragged, along with the time and date on timeline.*/
}

13.03.2024 | 16:00

1. A parameter 'Renderer' has been added to the VuelCalendarOptions object.

• This is a component that allows using a custom component inside an event container.
• Example usage:

/* main.ts */
app.component('ExampleRenderer', ExampleRenderer)

vuelCalendarOptions: {
...
renderer:'ExampleRenderer'
}

/* ExampleRenderer.vue */
export default defineComponent({
  name:"ExampleRenderer",
  props:{
    event:{
      type:Object as PropType<VuelCalendarEvent>,
    } /* this the full Event<VuelCalendarEvent> object passed to your rendering component */
  }
})
</script>

<template>
<div :style="`min-height:50px; background:${event.data.color}; display:flex; padding-inline:3px; align-items:center`">
 <div>
   <img :src="event.data.img" style="width:25px; border-radius:30px; margin-right:20px;"/>
 </div> 
 <p>
   {{event.label}}
 </p>
</div>
</template>

12.03.2024 | 20:40

1. Performance improvements were achieved by decomposing into multiple components and relieving the DOM tree through standardizing functions and incorporating them into computed properties.

2. Classes for DOM elements to make theme more customizable has been added

3. Added the Colors prop, which defines colors for theme styles as parent entities.

export type Colors = {
    surface?:string;
    primary?:string
    event?:string
    highlight?:string
    textPrimary?:string
    menuBg?:string,
    dragging?:string,
}

4. Types included

Upcoming features

1. Lazy loading for events within the container.

2. Calendar rotation for choosing between two modes: Horizontal (current) and Vertical.

3. More performance improvement

4. Drag & Drop <- 13.03.2024

5. Time bar following the mouse