Adds support for vkurko/calendar to Filament PHP.

This package adds support for vkurko/calendar (free, open-source alternative to FullCalendar) to your FilamentPHP panels.

Although the package is ready for production-use, it is still in active development. Please be cautious and double-check the documentation before updating the package, as new releases might introduce breaking changes due to refactoring and improvements to the DX. We do our best to keep these changes to a minimum.

Showcase

Screen.Recording.2024-07-15.at.9.31.47.mp4

Support us

Your support is key to the continual advancement of our plugin. We appreciate every user who has contributed to our journey so far.

While our plugin is available for all to use, if you are utilizing it for commercial purposes and believe it adds significant value to your business, we kindly ask you to consider supporting us through GitHub Sponsors. This sponsorship will assist us in continuous development and maintenance to keep our plugin robust and up-to-date. Any amount you contribute will greatly help towards reaching our goals. Join us in making this plugin even better and driving further innovation.

Installation

You can install the package via composer:

composer require guava/calendar

Make sure to publish the package assets using:

php artisan filament:assets

Make sure you have a custom filament theme (read here how to create one) and add the following to the content property of your theme's tailwind.config.js:

{
    content: [
        //...

        './vendor/guava/calendar/resources/**/*.blade.php',
    ]
}

This ensures that the CSS is properly built.

Usage

Creating the calendar Widget

First you need to create a custom widget and extend the CalendarWidget class. Make sure to remove the view property from the generated widget class!

Either use the artisan command or simply create an empty class and extend CalendarWidget:

php artisan make:filament-widget

The widget class should look like this:

use \Guava\Calendar\Widgets\CalendarWidget;

class MyCalendarWidget extends CalendarWidget
{
}

Add the widget like a regular widget to any filament page you like, such as your Dashboard.

Customizing the calendar view

By default, we show the dayGridMonth view. You can customize the view by overriding the calendarView property on the widget class:

protected string $calendarView = 'resourceTimeGridWeek';

All available views are listed in the calendar documentation.

Adding events

By default, the calendar will be empty. To add events, simply override the getEvents method:

public function getEvents(array $fetchInfo = []): Collection | array
    {
        return [
            // Chainable object-oriented variant
            Event::make()
                ->title('My first event')
                ->start(today())
                ->end(today()),
                
            // Array variant
            ['title' => 'My second event', 'start' => today()->addDays(3), 'end' => today()->addDays(3)],
            
            // Eloquent model implementing the `Eventable` interface
            MyEvent::find(1),
        ];
    }

Creating events

As shown in the example, there are multiple ways to create events. At the very least, an array object with a title, start and end properties is required.

To help you with creating events, we provide an Event ValueObject which contains methods with all available properties an event can have.

This is possible because the Event clas implements the Eventable interface, which returns the array object. You can add this interface to any class you want which should be treated as an event, such as your eloquent models.

Here is an example:

using an Eloquent model as Events

class Foo extends Model implements Eventable
{
    // ...
    
    public function toEvent(): Event|array {
        return Event::make($this)
            ->title($this->name)
            ->start($this->starts_at)
            ->end($this->ends_at);
    }
}

Notice that the model is passed to the Event constructor in the make method. This sets the key and model properties to the event object, so it can be used to trigger actions.

Event object

The event object takes all available options like the underlying calendar package, for more info read here.

Below is a list of available methods on the event object:

Setting the tile

Sets the title of the event that is rendered in the calendar.

Event::make()->title('My event');

Customizing the start/end date

Sets the start or end date (and time) of the event in the calendar.

Event::make()
    ->start(today())
    ->end(today()->addDays(3));

Making the event all-day

Sets whether the event is an all-day event or not.

Event::make()->allDay();

Customizing the background / text color

Sets the background color of the event (by default it is the primary color of the panel).

Event::make()
->backgroundColor('#ff0000')
->textColor('#ffffff');

Customizing the display

By default, events are rendered as blocks. This is when the display is set to auto, which it is by default. You can also change the event to be rendered as a background event, which then fills the whole date cell. To do so, you can set display to background on the event:

This doesn't work always though, it only works on all day events and in specific views. If the background event is unsupported, the event will not be rendered at all.

Event::make()
->display('background') // or 'auto'
->displayAuto() // short-hand for ->display('auto')
->displayBackground(); // short-hand for ->display('background')

Setting the action on click

This sets the action that should be mounted when the event is clicked. It can be any name of a filament action you defined in your widget, such as edit or view.

By default, all CalendarWidget classes already include a view and edit action.

Event::make()->action('edit');

Set the model and record key

To mount the action with the correct record, we need to pass the model type and primary key of the record.

The model is also required if you want to display multiple types of events and have each be rendered differently (see customizing event content).

$record = MyModel::find(1);
// 1. variant
Event::make($record);

// 2. variant
Event::make()
    ->model($record::class)
    ->key($record->getKey());

Passing custom data

You can pass any custom data to the event that you wish:

Event::make()
->extendedProp('foo', 'bar')
// or
->extendedProps(['baz' => 'qux', 'quux' => 'corge']);

Custom Event Content

By default, we use the default view from the calendar package. However, you are able to use your own by overriding the getEventContent method on your calendar widget class.

In order to keep things performant, the blade view is rendered once on the server and then re-used for every event. Thus, you cannot access the event data from the server side via Blade or Laravel, or do any server-side operations.

However, each event is wrapped in an alpine component, which exposes the event data that you can freely use using AlpineJS.

If you only have one type of events or events that render the same way, you can simply return a view or a HtmlString from the getEventContent method:

public function getEventContent(): null|string|array
{
    // return a blade view
    return view('calendar.event');
    
    // return a HtmlString
    return new HtmlString('<div>My event</div>');
}

Example of the calendar.event view blade file:

<div class="flex flex-col items-start">
    <span x-text="event.title"></span>
    <template x-for="user in event.extendedProps.users">
        <span x-text="user.name"></span>
    </template>
</div>

If you want to render events differently based on their model type, you can return an array like so:

public function getEventContent(): null|string|array
{
    return [
        MyModel::class => view('calendar.my-model-event'),
        AnotherModel::class => view('calendar.another-model-event'),
    ];
}

Customize the form schema

When an event triggers an action (such as view or edit actions), a modal with a form is mounted.

You can customize the form schema by overriding the getSchema method in your widget class:

public function getSchema(?string $model = null): ?array
{
    // If you only work with one model type, you can ignore the $model parameter and simply return a schema
    return [
        TextInput::make('title')
    ];
    
    // If you have multiple model types on your calendar, you can return different schemas based on the $model property
    return match($model) {
        Foo::class => [
            TextInput::make('name'),
        ],
        Bar::class => [
            TextInput::make('title'),
            TextArea::make('description'),
        ],
    }
}

Resources

Resource views (their names start with resource) allow you to group events into resources (such as rooms, projects, etc.).

To use resource views, you need to create resources and assign your events to these resources.

Creating resources

To create resources, you need to override the getResources method on your calendar widget class. Just like events, there are three options you can choose from to create resources:

public function getResources(): Collection|array
{
    return [
        // Chainable object-oriented variant
        Resource::make('foo')
            ->title('Room 1'),
            
        // Array variant
        ['id' => 'bar', 'title' => 'Room 2'],
        
        // Eloquent model implementing the `Resourceable` interface
        MyRoom::find(1),
    ];
}

Handling events

By default, the calendar is a view-only collection of events. You can enable more functionalities by configuring various events as described below.

Event-click event

An event click event is triggered when an event in the calendar is clicked. By default, a click event mounts the view action.

To listen to click events, simply override the eventClickEnabled property:

protected bool $eventClickEnabled = true;

You can set the default click action by overriding the defaultEventClickAction property of the widget. This simply needs to be the name of an action that you can freely define in your widget, like regular Filament actions:

protected ?string $defaultEventClickAction = 'edit';

And that's it! As long as pass your model policy checks, an edit modal will be mounted when you click on an event.

If you want to handle the event click logic completely by yourself, you may override the onEventClick method:

    public function onEventClick(array $info = []): void
{
    // do something on click
    // $info contains the event data:
    // $info['event'] - the event object
    // $info['view'] - the view object
}

Resize event

A resize event is triggered when an event is resized at the ending edge of the event. This allows you to quickly modify the duration of an event.

To listen to resize events, simply override the eventResizeEnabled property:

protected bool $eventResizeEnabled = true;

Except for resolving the record the event is related to, there is no default action and it's up to you to implement the logic. To do that, override the onEventResize method:

public function onEventResize(array $info = []): bool
{
    // Don't forget to call the parent method to resolve the record
    parent::onEventResize($info);
     
    // Validate the data
    // Update the record ($this->getRecord())
    // $info contains the event data:
    // $info['event'] - the event object
    // $info['oldEvent'] - the event object before resizing
    // $info['endDelta'] - the difference in time between the old and new event
    
    // Return true if the event was resized successfully
    // Return false if the event was not resized and should be reverted on the client-side   
}

Drag & Drop event

A drop event is triggered when an event is dragged and dropped to a different slot in the calendar. This allows you to quicky move the start (and end) date of an event.

To listen to drag and drop events, simply override the eventDragEnabled property:

protected bool $eventDragEnabled = true;

Except for resolving the record the event is related to, there is no default action and it's up to you to implement the logic. To do that, override the onEventDrop method:

public function onEventDrop(array $info = []): bool
{
    // Don't forget to call the parent method to resolve the record
    parent::onEventDrop($info); 
    
    // Validate the data
    // Update the record ($this->getRecord())
    // $info contains the event data:
    // $info['event'] - the event object
    // $info['oldEvent'] - the event object before resizing
    // $info['oldResource'] - the old resource object
    // $info['newResource'] - the new resource object
    // $info['delta'] - the duration object representing the amount of time the event was moved by
    // $info['view'] - the view object
    
    // Return true if the event was moved successfully
    // Return false if the event was not moved and should be reverted on the client-side
}

No-events-click event

A no-events-click event is applicable only on list views and is triggered when a user clicks on the no events cell. By default, this event does nothing and it's up to you to implement the logic.

To listen to no-events-click events, simply override the noEventsClickEnabled property:

protected bool $noEventsClickEnabled = true;

To handle the no-events-click logic, override the onNoEventsClick method:

public function onNoEventsClick(array $info = []): void
{
    // do something on click
    // $info contains the event data:
    // $info['view'] - the view object
}

Context menu

Optionally you can add a context menu to your calendar, which allows you to create events by clicking on a date cell or by selecting a date/time range by dragging.

There are multiple places where you can use context menus at.

context_menu_preview.mp4

context_menu_preview_2.mp4

Date click context menu

This context menu is triggered when a user clicks on a date cell in the calendar.

To enable the context menu, all you need to do is implement the getDateClickContextMenuActions method:

For example:

public function getDateClickContextMenuActions(): array
{
    CreateAction::make('foo')
        ->model(Foo::class)
        ->mountUsing(fn ($arguments, $form) => $form->fill([
            'starts_at' => data_get($arguments, 'dateStr'),
            'ends_at' => data_get($arguments, 'dateStr'),
        ])),
}

The mount using function is used to fill the form with the arguments from the calendar. It contains all information that vkurko/calendar provides in the select and dateClick events, but most importantly:

startStr and endStr for range selection
dateStr for date clicks

Date select context menu

This context menu is triggered when a user selects on a date range in the calendar.

To enable the context menu, all you need to do is implement the getDateSelectContextMenuActions method:

For example:

public function getDateSelectContextMenuActions(): array
{
    CreateAction::make('foo')
        ->model(Foo::class)
        ->mountUsing(fn ($arguments, $form) => $form->fill([
            'starts_at' => data_get($arguments, 'startStr'),
            'ends_at' => data_get($arguments, 'endStr'),
        ])),
}

Event click context menu

This context menu is triggered when a user clicks on an event in the calendar.

To enable the context menu, all you need to do is implement the getEventClickContextMenuActions method:

For example:

public function getEventClickContextMenuActions(): array
{
    return [
        $this->viewAction(),
        $this->editAction(),
        $this->deleteAction(),
    ];
}

No events click context menu

This context menu is only rendered on list views and is triggered when a user clicks on the no events cell when there are no events.

To enable the context menu, all you need to do is implement the getNoEventsClickContextMenuActions method. Also, make sure that the noEventsClickEnabled property is set to true.

public function getNoEventsClickContextMenuActions(): array
{
    return [
        CreateAction::make('foo')
            ->model(Foo::class)
    ];
}

no_events_context_menu.mp4

Customization

Locale

By default, the calendar will use the app's locale.

The underlying calendar package doesn't support locales as a combination of language and region/country code, so locales such as fr_CA or en_US become invalid.

We attempt to resolve this by only using the first language part of the locale. If you still run into any issues with the localization, you can override the calendar's locale manually using the locale property:

protected ?string $locale = 'en';

Troubleshooting

Context menu actions don't work

If you encounter issues with the context menu, either that the actions don't mount correctly or that the arguments array is empty, make sure that the name of the action is unique across the whole widget. If there is another action with the same name, it might be mounted instead of the one you want.

Authorization

Due to security reasons, actions use Laravel's default authorization mechanism to check if user is allowed to perform actions.

This means that most likely your actions might not work when you add them (such as view or edit actions on event click). If that's the case, please create a policy for your model and add the necessary checks to the policy.

You can also overide the authorize method on your widget class and handle all authorization logic on your own.

// $ability will contain the name of the action
public function authorize($ability, $arguments = []);

Security measures

Keep in mind that a lot of the data in this package comes from the client side JavaScript and could be tampered with. Always validate the data on the server side and never trust the data from the client side.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Lukas Frey
All Contributors
Spatie - Our package skeleton is a modified version of Spatie's Package Skeleton
vkurko/calendar - free, open-source alternative to FullCalendar
saade/filament-fullcalendar - heavy inspiration for this package

License

The MIT License (MIT). Please see License File for more information.

Adds support for vkurko/calendar to Filament PHP.

Showcase

Support us

Installation

Usage

Creating the calendar Widget

Customizing the calendar view

Adding events

Creating events

using an Eloquent model as Events

Event object

Setting the tile

Customizing the start/end date

Making the event all-day

Customizing the background / text color

Customizing the display

Setting the action on click

Set the model and record key

Passing custom data

Custom Event Content

Customize the form schema

Resources

Creating resources

Handling events

Event-click event

Resize event

Drag & Drop event

No-events-click event

Context menu

Date click context menu

Date select context menu

Event click context menu

No events click context menu

Customization

Locale

Troubleshooting

Context menu actions don't work

Authorization

Security measures

Testing

Changelog

Contributing

Security Vulnerabilities

Credits

License

About

Languages