Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/omnia-digital/livewire-calendar
Laravel Livewire component to show Events in a good looking monthly calendar
https://github.com/omnia-digital/livewire-calendar
calendar laravel livewire omnia
Last synced: 25 days ago
JSON representation
Laravel Livewire component to show Events in a good looking monthly calendar
- Host: GitHub
- URL: https://github.com/omnia-digital/livewire-calendar
- Owner: omnia-digital
- License: mit
- Created: 2023-03-30T02:58:42.000Z (over 1 year ago)
- Default Branch: dev
- Last Pushed: 2024-09-16T17:17:14.000Z (about 2 months ago)
- Last Synced: 2024-10-01T09:22:55.118Z (about 1 month ago)
- Topics: calendar, laravel, livewire, omnia
- Language: PHP
- Homepage:
- Size: 1.11 MB
- Stars: 74
- Watchers: 1
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Livewire Calendar
This package allows you to build a Livewire monthly calendar grid to show events for each day. Events can be loaded
from within the component and will be presented on each day depending on the date of the event.
Special thanks to asantibanez/livewire-calendar as this originally was a fork of that package. We are using this new package in one of our large projects so we will be actively maintaining.
## Preview
## Installation
You can install the package via composer:
```bash
composer require omnia-digital/livewire-calendar
```
## Requirements
This package uses `livewire/livewire` (https://laravel-livewire.com/) under the hood.
It also uses TailwindCSS (https://tailwindcss.com/) for base styling.
Please make sure you include both of this dependencies before using this component.
## Usage
In order to use this component, you must create a new Livewire component that extends from
`LivewireCalendar`
You can use `make:livewire` to create a new component. For example.
``` bash
php artisan make:livewire AppointmentsCalendar
```
- In the `AppointmentsCalendar` class, instead of extending from the base `Component` Livewire class,
extend from `LivewireCalendar`.
- **Remove the `render` method or you will override the parent and the calendar will not display.**
- You'll have a class similar to this snippet.
``` php
class AppointmentsCalendar extends LivewireCalendar
{
//
}
```
In this class, you must override the following method
```php
public function events() : Collection
{
// must return a Laravel collection
}
```
In the `events()` method, return a collection holding the events that will be displayed on
the calendar. Events must be keyed arrays holding at least the following keys:
`id`, `title`, `description`, `date` (`date` must be a `Carbon\Carbon` instance).
Example
```php
public function events() : Collection
{
return collect([
[
'id' => 1,
'title' => 'Breakfast',
'description' => 'Pancakes! 🥞',
'date' => Carbon::today(),
],
[
'id' => 2,
'title' => 'Meeting with Pamela',
'description' => 'Work stuff',
'date' => Carbon::tomorrow(),
],
]);
}
```
The `date` value will be used to determine to what day the event belongs to. To
load values in the `events()` method, you can use the following component properties
to filter your events.
- `startsAt`: starting date of month
- `endsAt`: ending date of month
- `gridStartsAt`: starting date of calendar grid. Can be a date from the previous month.
- `endingStartsAt`: ending date of calendar grid. Can be a date from the next month.
Example
```php
public function events(): Collection
{
return Model::query()
->whereDate('scheduled_at', '>=', $this->gridStartsAt)
->whereDate('scheduled_at', '<=', $this->gridEndsAt)
->get()
->map(function (Model $model) {
return [
'id' => $model->id,
'title' => $model->title,
'description' => $model->notes,
'date' => $model->scheduled_at,
];
});
}
```
Now, we can include our component in any view.
Example
```blade
```
This will render a calendar grid.
By default, the component will render the current month. If you want to change the
starting month, you can set the `initialYear` and `initialMonth` props.
Example
```blade
```
If you use it as a nested component, you can use variables and make it dynamic (:key prop will force livewire to re-render calendar).
Example
```blade
```
You should include scripts with `@livewireCalendarScripts` to enable drag and drop which is turned on by default.
You must include them after `@livewireScripts`
```blade
@livewireScripts
@livewireCalendarScripts
```
The component has 3 public methods that can help navigate forward and backward through months:
- `goToPreviousMonth`
- `goToNextMonth`
- `goToCurrentMonth`
You can use these methods on extra views using `before-calendar-view` or `after-calendar-view` explained below.
### Advanced usage
### Ui customization
You can customize the behavior of the component with the following properties when rendering on a view:
- `week-starts-at` which can be a number from 0 to 6 according to Carbon days of week to indicate
with which day of week the calendar should render first.
- `event-view` which can be any `blade.php` view that will be used to render the event card.
This view will be injected with a `$event` variable holding its data.
- `before-calendar-view` and `after-calendar-view` can be any `blade.php` views that can be rendered before or after
the calendar itself. These can be used to add extra features to your component using Livewire.
- `drag-and-drop-classes` can be any css class used to render the hover effect when dragging an event over each day
in the calendar. By default, this value is `border border-blue-400 border-4`
- `day-of-week-view` which can be any `blade.php` view that will be used to render the header of each calendar day.
This view will be injected the `day` property which is a Carbon instance of the day of the week.
```blade
```
### Advanced ui customization
(This options should be used using blade views based on the component default views)
To use these options, it is recommended to publish the base blade views used by the component and extend their
behavior and styling to your liking. To do this, run `php artisan vendor:publish` and export the `livewire-calendar` tag.
- `calendar-view` which can be any `blade.php` view that renders the whole component. It's advised to override this
view with an altered copy of the base `calendar-view` eg adding a view next to the component.
- `day-view` which can be any `blade.php` view that will be used to render each day of the month. This view will be
injected with the following properties: `componentId` (id of the Livewire component)
, `day` (day of the month as a Carbon instance)
, `dayInMonth` (if the day is part of the month or not)
, `isToday` (if the day is today's date)
, `events` (events collection that correspond to this day)
Example
```blade
```
### Interaction customization
You can override the following methods to add interactivity to your component
```php
public function onDayClick($year, $month, $day)
{
// This event is triggered when a day is clicked
// You will be given the $year, $month and $day for that day
}
public function onEventClick($eventId)
{
// This event is triggered when an event card is clicked
// You will be given the event id that was clicked
}
public function onEventDropped($eventId, $year, $month, $day)
{
// This event will fire when an event is dragged and dropped into another calendar day
// You will get the event id, year, month and day where it was dragged to
}
```
### Automatic polling
You can also add automatic polling if needed using `pollMillis` parameters. You can combo with `pollAction` in
order to call a specific action in your component at the desired polling interval.
### Disabling interactions
By default click and drag/drop events are enabled. To disable them you can use the following parameters when
rendering the component
```blade
```
### Testing
``` bash
composer test
```
### Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
### Security
If you discover any security related issues, please email us at [email protected] instead of using the issue tracker.
## Credits
- [Osei Quashie](https://github.com/Osimba)
- [Josh Torres](https://github.com/joshtorres)
- [Andrés Santibáñez](https://github.com/asantibanez)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.