Employee Calendar Documentation

Part 1: USER GUIDE - Employee Calendar

1. Overview

The Employee Calendar is a visual representation of all your work-related events in one centralized view. It displays your shifts, attendance records, leave dates, overtime, company events, and holidays in an easy-to-read calendar format.

What is the Calendar?

Think of it as your personal work calendar that shows:

📅 Your assigned shifts (Morning, Afternoon, Night)
✅ Days you've checked in (attendance records)
🏖️ Approved leave dates
⏰ Overtime requests
🎉 Company events and holidays
📌 Shift changes and notifications

Key Features

✅ Multi-Month View - See up to 3 months at a time
✅ Color-Coded Events - Different colors for different event types
✅ Click for Details - Click any date to see detailed information
✅ Filter Events - Show/hide specific event types
✅ Print Ready - Print your calendar for offline reference
✅ Export Functionality - Download as ICS file for Google Calendar, Outlook
✅ Real-Time Updates - Calendar syncs with system changes

Calendar Components

┌──────────────────────────────────────────────────────────┐
│          EMPLOYEE CALENDAR                               │
├──────────────────────────────────────────────────────────┤
│                                                          │
│ [View Controls] [Filter] [Export] [Print]               │
│                                                          │
│ ┌─────────────────────────────────────────────────────┐ │
│ │                                                     │ │
│ │           CALENDAR GRID (Days/Weeks/Month)          │ │
│ │                                                     │ │
│ │     Date cells with color-coded indicators          │ │
│ │                                                     │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                          │
│ [Legend]                                                 │
│ 🔵 Shift | ✅ Checked-In | 🏖️ Leave | ⏰ Overtime...  │
│                                                          │
│ [Previous] [Today] [Next] Month: December 2025          │
│                                                          │
└──────────────────────────────────────────────────────────┘

2. Accessing the Calendar

2.1 Ways to Access

Option 1: From Dashboard

Dashboard → Left Menu → Calendar
    ↓
Calendar Page Opens

Option 2: From Left Navigation Menu

Main Menu → Calendar Icon 📅
    ↓
Calendar Page Opens

Option 3: Direct URL

https://dtr.company.com/employee/calendar

Option 4: From Other Pages

Any Employee Page → Calendar Link
    ↓
Opens Calendar View

2.2 Calendar Page Load

When you first open the calendar:

┌──────────────────────────────────────┐
│  Loading Calendar...                 │
│                                      │
│  ⏳ Fetching your events             │
│  ⏳ Loading attendance records        │
│  ⏳ Loading shift information         │
│  ⏳ Loading leave data                │
│                                      │
│  [Please wait]                       │
│                                      │
└──────────────────────────────────────┘

Typical load time: 1-3 seconds

Once loaded:

✅ Calendar Ready
   All your events visible
   Ready for interaction

3. Calendar Interface

3.1 Calendar Layout

The calendar displays in Month View by default:

                    DECEMBER 2025
        ┌──────────────────────────────────┐
        │ Sun Mon Tue Wed Thu Fri Sat      │
        ├──────────────────────────────────┤
        │               1   2              │
        │  3   4   5   6   7   8   9      │
        │ 10  11  12  13  14  15  16      │
        │ 17  18  19  20  21  22  23      │
        │ 24  25  26  27  28  29  30      │
        │ 31                               │
        └──────────────────────────────────┘

    [◀ Previous] [Today] [Next ▶]

3.2 Date Cell Structure

Each date cell contains multiple pieces of information:

┌──────────────────────┐
│         4            │  ← Date number
│ (Wed)                │  ← Day of week (optional)
│                      │
│ 🔵 Morning 08-17:00  │  ← Shift (if assigned)
│ ✅ Checked In        │  ← Attendance status (if today)
│ 🏖️ Leave            │  ← Special indicators
│                      │
│ [Color Bar]          │  ← Color-coded indicator
│                      │
└──────────────────────┘

Dense Display (Less detail):

┌─────────┐
│    4    │  ← Just date
│ 🔵 ✅   │  ← Icons only
│ [████]  │  ← Color bar
└─────────┘

3.3 Header Controls

Top Bar Options:

[View Mode ▼] [Filter ▼] [Export ▼] [Print]

Control	Options	Purpose
View Mode	Month / Week / Day	Change calendar display
Filter	Shifts, Leaves, OT, etc	Show/hide event types
Export	ICS, PDF, CSV	Download calendar data
Print	Print to printer	Physical copy

3.4 Navigation Bar

Bottom Bar Navigation:

[◀ Previous Month] [Today] [Next Month ▶]
Month: December 2025

Controls:

◀ Previous - Go to previous month
Today - Jump to current month
Next ▶ - Go to next month
Month Label - Click to jump to specific month

3.5 Legend (Key)

Shows what each color means:

CALENDAR LEGEND
═══════════════════════════════════════════

🔵 Blue   = Regular Shift Assigned
🟡 Yellow = Pending Approval (Shift/Leave/OT)
🔴 Red    = On Approved Leave
🟢 Green  = Checked In (Attendance)
⬜ Gray   = Off Day / Holiday
⭐ Star   = Company Event
📌 Pin    = Shift Change Notification

4. Understanding Events

4.1 Event Types Displayed

1. Shifts (🔵 Blue)

Your assigned work shifts for the day.

Dec 4 (Wed)
🔵 Morning Shift (08:00 - 17:00)

Information Shown:

✓ Shift name
✓ Start time
✓ End time
✓ Duration (typically 9 hours with break)

Click to see:

Workplace location
Workstation assignment
Break times
Special requirements

2. Attendance Records (✅ Green)

Days you've successfully checked in.

Dec 4 (Wed)
✅ Checked In - 08:30 AM
✅ Checked Out - 17:15 PM
Duration: 8h 45m
Status: APPROVED

Information Shown:

✓ Check-in time
✓ Check-out time
✓ Total duration worked
✓ Approval status
✓ Location verified

3. Leave (🏖️ Red)

Days you've taken approved leave.

Dec 10-11 (Tue-Wed)
🏖️ Sick Leave (2 days)
Approved by: Team Lead & HR

Information Shown:

✓ Leave type
✓ Date range
✓ Number of days
✓ Approval chain
✓ Leave balance impact

4. Overtime (⏰ Orange)

Overtime hours you've recorded.

Dec 5 (Fri)
⏰ Overtime: 2.5 hours
Reason: Project Deadline
Status: APPROVED

Information Shown:

✓ OT hours
✓ Reason for OT
✓ Approval status
✓ Approver name

5. Company Events (⭐ Star)

Company-wide announcements and events.

Dec 8 (Sun)
⭐ Company Foundation Day (Holiday)
All offices closed

Information Shown:

✓ Event name
✓ Event description
✓ Company-wide notice
✓ Impact on schedule

6. Holidays (⬜ Gray)

National and company holidays.

Dec 25 (Wed)
⬜ Christmas Holiday
Day off - No work required

Information Shown:

✓ Holiday name
✓ Holiday type (national/company)
✓ Whether it's a day off

7. Pending Approvals (🟡 Yellow)

Items waiting for approval.

Dec 20-27 (Fri-Fri)
🟡 Vacation Leave (5 days) - PENDING
Awaiting: Team Lead Review
Submitted: 2 days ago

Information Shown:

✓ Request type
✓ Pending status
✓ Next approver
✓ Days pending

5. Navigation & Filtering

5.1 Monthly Navigation

Move Between Months:

[◀ Previous]               [Next ▶]
   Click to go to         Click to go to
   November 2025          January 2026

[Today]
Jump directly to current month
(December 2025)

Navigation Behavior:

Click Previous → Goes back one month
Click Next → Goes forward one month
Click Today → Jumps to current date's month
Multiple clicks → Can go back/forward multiple months

Timeline Example:

Oct 2025 → Sep 2025 → Aug 2025 ← (Previous)
Dec 2025 → Jan 2026 → Feb 2026 ← (Next)

5.2 View Mode Selection

Change How Calendar Displays:

[View Mode ▼]
  ├─ Month (Default)      ← See full month
  ├─ Week                 ← See single week
  └─ Day                  ← See single day

Month View

Shows entire month (28-31 days)
Each date cell shows multiple events
Good for: Planning ahead, seeing patterns

                DECEMBER 2025
        ┌──────────────────────────────┐
        │ Sun Mon Tue Wed Thu Fri Sat  │
        │               1   2          │
        │  3   4   5   6   7   8   9  │
        │ 10  11  12  13  14  15  16  │
        │ 17  18  19  20  21  22  23  │
        │ 24  25  26  27  28  29  30  │
        │ 31                           │
        └──────────────────────────────┘

Week View

Shows single week (7 days)
More detail per day
Good for: Seeing hourly details, weekly planning

        WEEK OF DEC 1-7, 2025

Mon 1   Tue 2   Wed 3   Thu 4   Fri 5   Sat 6   Sun 7
─────────────────────────────────────────────────────
Morning Morning Morning Morning Morning OFF     OFF
08-17   08-17   08-17   08-17   08-17
✅      ✅      ✅      ✅      ⏰OT
        Checked Checked Checked Pending
        In      In      In      +2.5h

Day View

Shows single day (24 hours)
Hourly breakdown
Good for: Seeing time details, shift specifics

        DECEMBER 4, 2025 (WEDNESDAY)

Time    Status          Details
─────────────────────────────────────
08:00   Morning Shift   Starts
08:30   ✅ Checked In   System verified
12:00   Break Time      1 hour break
13:00   Break Ends      Resume work
17:00   Shift Ends      Expected end
17:15   ✅ Checked Out  Shift complete
        Duration: 8h 45m

5.3 Filter Events

Show/Hide Specific Event Types:

[Filter ▼]
  ☑ Shifts              ← Checked = visible
  ☑ Attendance
  ☑ Leave
  ☑ Overtime
  ☑ Company Events
  ☑ Holidays
  ☐ Pending Approvals   ← Unchecked = hidden

Example - Hide Pending Items:

Before Filtering (All events shown):
────────────────────────────────────
Dec 20: 🟡 PENDING Vacation Leave
Dec 21: 🏖️ Leave approved

After Filtering (Pending hidden):
────────────────────────────────────
Dec 20: [Hidden]
Dec 21: 🏖️ Leave approved

Use Cases:

Filter	When to Use
Shifts Only	Planning work schedule
Attendance Only	Reviewing work history
Leaves Only	Managing time off
OT Only	Tracking extra hours
No Pending	Seeing finalized plans

5.4 Search & Jump

Jump to Specific Date:

[Go to Date] ▼
├─ December 4 (Today)
├─ December 25 (Christmas)
├─ January 1, 2026 (New Year)
└─ [Custom Date...]

Select → Calendar jumps to that date

6. Viewing Event Details

6.1 Click a Date to See Details

Step 1: Locate Date

Find the date you want to view on the calendar.

Step 2: Click the Date

Click on date cell → Details modal opens

Step 3: Modal Opens

┌────────────────────────────────────────┐
│        DECEMBER 4, 2025 (WEDNESDAY)    │
├────────────────────────────────────────┤
│                                        │
│ SHIFT INFORMATION                      │
│ ─────────────────────────────────────  │
│ Shift:      Morning (08:00 - 17:00)   │
│ Workplace:  Main Office - 3rd Floor   │
│ Workstation: Desk 5-A                 │
│                                        │
│ ATTENDANCE RECORDS                     │
│ ─────────────────────────────────────  │
│ Check-In:    08:30 AM ✅              │
│ Check-Out:   17:15 PM ✅              │
│ Duration:    8h 45m                   │
│ Status:      APPROVED                 │
│ Location:    42.5m from office ✅     │
│                                        │
│ OTHER EVENTS FOR THIS DAY              │
│ ─────────────────────────────────────  │
│ Team Standup: 10:00 AM (Meeting)      │
│ Client Call: 2:00 PM (Conference Rm)  │
│                                        │
│ [Edit] [Export] [Print] [Close]       │
│                                        │
└────────────────────────────────────────┘

6.2 Information Displayed

Shift Details:

Shift Name:      Morning / Afternoon / Night
Start Time:      08:00 AM
End Time:        17:00 PM (5:00 PM)
Duration:        9 hours (includes 1 hour break)
Break Time:      12:00 PM - 1:00 PM
Workplace:       Office address
Workstation:     Your assigned desk

Attendance Details:

Check-In Time:   08:30 AM (timestamp)
Check-Out Time:  17:15 PM (timestamp)
Total Duration:  8 hours 45 minutes
Status:          APPROVED / REMOTE / PENDING
Location:        Distance from office (meters)
Verified By:     GPS / Manual / Admin

Leave Details:

Leave Type:      Sick / Vacation / Emergency
Date Range:      Start date - End date
Days Approved:   Number of days
Reason:          Why leave was requested
Approvers:       Team Lead name, HR name
Approval Date:   When it was approved
Balance Impact:  Days used / remaining

Overtime Details:

Date:            Which date OT was worked
Hours:           2.5 hours
Reason:          Why overtime was needed
Status:          APPROVED / PENDING / REJECTED
Approver:        Who approved it
Approval Date:   When it was approved

6.3 Actions from Details Modal

Edit (If Applicable):

[Edit] button appears if event is editable
  ├─ Pending leaves → Can edit/cancel
  ├─ Pending OT → Can withdraw
  └─ Future shifts → Can request swap

Export:

[Export] → Download as ICS file
├─ Add to Google Calendar
├─ Add to Outlook
├─ Add to Apple Calendar
└─ Add to other calendar apps

Print:

[Print] → Print event details
├─ Prints with formatting
├─ Includes timestamps
├─ Professional format
└─ Good for records

Close:

[Close] → Returns to calendar view
[X] button → Also closes modal

7. Legend & Color Coding

7.1 Color System

The calendar uses 7 main colors to represent different event types:

1. Blue (🔵) - Regular Shifts

Color:   #3B82F6 (Azure Blue)
Meaning: Your assigned work shift
Example: Morning (08:00-17:00)

Calendar Cell:
┌──────────────┐
│ 4            │
│ 🔵 MORNING   │
│ 08:00-17:00  │
│ [████████]   │  ← Blue bar
└──────────────┘

2. Green (🟢) - Checked-In

Color:   #10B981 (Emerald Green)
Meaning: Successfully checked in for work
Example: ✅ Checked In - 08:30 AM

Calendar Cell:
┌──────────────┐
│ 4            │
│ 🟢 CHECKED IN│
│ 08:30-17:15  │
│ [████████]   │  ← Green bar
└──────────────┘

3. Red (🔴) - On Leave

Color:   #EF4444 (Bright Red)
Meaning: Approved leave - no work
Example: Sick Leave (2 days)

Calendar Cell:
┌──────────────┐
│ 10-11        │
│ 🔴 LEAVE     │
│ Sick Leave   │
│ [████████]   │  ← Red bar
└──────────────┘

4. Orange (🟠) - Overtime

Color:   #F97316 (Orange)
Meaning: Extra hours worked
Example: ⏰ 2.5 hours OT

Calendar Cell:
┌──────────────┐
│ 5            │
│ 🟠 OVERTIME  │
│ +2.5 hours   │
│ [████████]   │  ← Orange bar
└──────────────┘

5. Yellow (🟡) - Pending Approval

Color:   #FBBF24 (Amber Yellow)
Meaning: Awaiting approval decision
Example: Pending Leave Request

Calendar Cell:
┌──────────────┐
│ 20           │
│ 🟡 PENDING   │
│ Leave Request│
│ [████████]   │  ← Yellow bar
└──────────────┘

6. Gray (⬜) - Off Days / Holidays

Color:   #9CA3AF (Light Gray)
Meaning: Day off, no work
Example: Weekend, Company Holiday

Calendar Cell:
┌──────────────┐
│ 7            │
│ ⬜ OFF DAY   │
│ Weekend      │
│ [████████]   │  ← Gray bar
└──────────────┘

7. Star (⭐) - Company Events

Color:   #FBBF24 (Gold Yellow)
Meaning: Important company event
Example: ⭐ Company Founding Day

Calendar Cell:
┌──────────────┐
│ 8            │
│ ⭐ EVENT     │
│ Founding Day │
│ [████████]   │  ← Gold bar
└──────────────┘

7.2 Color Meaning Quick Reference

Color	Meaning	Action
🔵 Blue	Shift assigned	Work as scheduled
🟢 Green	Checked in	Record exists
🔴 Red	On leave	Rest day, no work
🟠 Orange	Overtime worked	Extra hours logged
🟡 Yellow	Pending	Awaiting decision
⬜ Gray	Off/Holiday	No work required
⭐ Gold	Company event	Important notice

7.3 Multiple Events on Same Day

If day has multiple event types:

Date cell shows all relevant colors:

Dec 4
┌──────────────────────────┐
│ 4 (Wed)                  │
│                          │
│ 🔵 Morning Shift 08-17   │
│ 🟢 Checked In 08:30-17:15│
│ ⏰ OT Pending +1.5h      │
│                          │
│ [🟢🔵🟠] Stacked bars   │
│                          │
└──────────────────────────┘

All colors visible in cell
Multiple bars show multiple events

8. Tips & Best Practices

8.1 Using Calendar Effectively

✅ DO:

Check Calendar Regularly

Morning: Check today's shift & events
Weekly: Review upcoming week
Monthly: Plan the month ahead

Export to Personal Calendar

Export shifts to Google Calendar
Get notifications on your phone
Never miss a shift or deadline

Track Attendance

Review daily check-in records
Ensure all days are properly recorded
Report discrepancies early

Plan Leave Early

Check calendar for busy periods
Request leave well in advance
Avoid blackout dates

Monitor Pending Items

Keep eye on pending approvals
Follow up if taking too long
Resubmit if rejected

8.2 Best Practices

For Shift Management:

✅ Check assigned shift before arriving
✅ Note shift changes (yellow indicators)
✅ Plan travel time based on shift start
❌ Don't assume same shift every day

For Leave Planning:

✅ Plan ahead (submit 2+ weeks early)
✅ Check leave balance before requesting
✅ Mark calendar when approved
❌ Don't submit at last minute

For Overtime:

✅ Document reason for overtime
✅ Request approval same day if possible
✅ Keep records of extra work
❌ Don't assume OT is automatically approved

For Attendance:

✅ Check in before shift start
✅ Verify check-out at shift end
✅ Report issues to Team Lead
❌ Don't rely on memory for times

8.3 Calendar Shortcuts

Keyboard Shortcuts:

Shortcut	Action
← →	Previous/Next month
T	Jump to today
M	Switch to month view
W	Switch to week view
D	Switch to day view
P	Print calendar
E	Export calendar
?	Show help

9. Troubleshooting

Issue 1: "Calendar Not Loading"

Symptom: Blank calendar or loading spinner stuck

Solutions:

Wait 5-10 seconds for load to complete
Refresh page (F5 or Ctrl+R)
Clear browser cache
Try different browser
Check internet connection
Contact IT if persists

Issue 2: "Events Not Showing"

Symptom: Expected events don't appear on calendar

Solutions:

Check filter settings

[Filter ▼] → Make sure event type is ☑ checked

Verify date range

Are you looking in correct month?
[◀ Previous] or [Next ▶] to navigate

Refresh calendar
```
F5 or [Refresh] button
```
Check event status
```
Pending events may be filtered out
```

Issue 3: "Wrong Color for Event"

Symptom: Event shows unexpected color

Solutions:

Check event status

Click date to see full details
Status determines color

Verify event type
```
Look at legend to confirm meaning
```
Check filter
```
Event might be from different category
```

Issue 4: "Cannot Export Calendar"

Symptom: Export button doesn't work

Solutions:

Check browser

Use Chrome, Firefox, or Safari
Older IE may not support export

Check file access

Browser may need permission to download
Check popup blocker
Allow downloads

Try different format
```
If PDF fails, try ICS or CSV
```
Check disk space
```
Ensure device has storage space
```

Issue 5: "Mobile Calendar Issues"

Symptom: Calendar doesn't work well on phone

Solutions:

Rotate device to landscape
```
More readable in landscape mode
```
Use mobile-optimized view
```
Some features work better on desktop
```
Try responsive design
```
Try pinch-zoom to see details
```

Use calendar app instead

Export to Google Calendar for mobile
Get native app experience

FAQ

Q: Can I share my calendar with manager?
A: Yes, export and share the ICS file or screenshot with your Team Lead.

Q: How far back does calendar show history?
A: Shows past 1 year and future 1 year by default. Contact IT for extended history.

Q: Can I sync with Outlook or Google Calendar?
A: Yes! Export as ICS file and import into your calendar app.

Q: Why is some event data missing?
A: Old records may be archived. Contact HR for historical data.

Q: Can I print multiple months at once?
A: Yes, select month range then print. Or export to PDF first.

Q: How often does calendar update?
A: Real-time. Changes appear within seconds of approval.

Q: Can I set calendar reminders?
A: Yes, export to Google Calendar which has built-in reminders.

Q: What if shift is wrong on calendar?
A: Contact HR or Team Lead to correct the assignment.

END OF USER GUIDE - PART 1

PART 2: DEVELOPER GUIDE - Employee Calendar

1. Architecture Overview

1.1 Component Stack

CalendarController
    ├── ShiftServices
    ├── LeaveRequestServices
    ├── OvertimeServices
    ├── AttendanceRecordServices
    ├── HolidayServices
    └── CompanyEventServices
        ↓
    view('users.employee.calendar.index')
        ├── Blade Template
        ├── Alpine.js Components
        ├── Calendar Library (FullCalendar/Similar)
        └── Event Rendering
            ├── Shift Events
            ├── Attendance Events
            ├── Leave Events
            ├── Overtime Events
            ├── Holiday Events
            └── Company Event

1.2 Data Flow

User Visits: /employee/calendar
    ↓
CalendarController@index
    ├─ Get all shifts for user
    ├─ Get all attendance records
    ├─ Get all leave requests
    ├─ Get all overtime requests
    ├─ Get all holidays
    └─ Get all company events
    ↓
Process & Format Data
    └─ Convert to calendar events
        ├─ Add color coding
        ├─ Add click handlers
        ├─ Add metadata
        └─ Format dates
    ↓
Pass to Blade View
    └─ JSON-encoded events array
    ↓
Alpine.js / Calendar Library
    ├─ Render events on calendar
    ├─ Add interactivity
    ├─ Handle clicks
    └─ Manage filters
    ↓
User Interaction
    ├─ Click date → Show details modal
    ├─ Filter → Update displayed events
    ├─ Export → Generate ICS file
    └─ Print → Print calendar

2. Controller Implementation

2.1 CalendarController

File: app/Http/Controllers/Web/Employee/CalendarController.php

Method: `index()`

public function index(
    ShiftServices $shiftServices,
    AttendanceRecordServices $attendanceServices,
    LeaveRequestServices $leaveServices,
    OvertimeServices $overtimeServices,
    HolidayServices $holidayServices,
    CompanyEventServices $eventServices
) {
    $userId = auth()->user()->id;

    // Get all events
    $shifts = $shiftServices->getUserShifts($userId);
    $attendances = $attendanceServices->getRecords($userId);
    $leaves = $leaveServices->getApprovedLeaves($userId);
    $overtimes = $overtimeServices->getApprovedOvertimes($userId);
    $holidays = $holidayServices->getHolidays();
    $events = $eventServices->getCompanyEvents();

    // Format for calendar
    $calendarEvents = $this->formatCalendarEvents([
        'shifts' => $shifts,
        'attendances' => $attendances,
        'leaves' => $leaves,
        'overtimes' => $overtimes,
        'holidays' => $holidays,
        'events' => $events
    ]);

    return view('users.employee.calendar.index', [
        'events' => json_encode($calendarEvents),
        'userId' => $userId
    ]);
}

private function formatCalendarEvents($data)
{
    $events = [];

    // Format shifts as blue events
    foreach ($data['shifts'] as $shift) {
        $events[] = [
            'id' => 'shift-' . $shift->id,
            'title' => $shift->shift->name . ' (' .
                       $shift->shift->time_started . '-' .
                       $shift->shift->time_ended . ')',
            'start' => $shift->date,
            'color' => '#3B82F6', // Blue
            'type' => 'shift',
            'extendedProps' => [
                'workplace' => $shift->workplace->name,
                'workstation' => $shift->workstation->name,
                'duration' => $shift->shift->duration
            ]
        ];
    }

    // Format attendances as green events
    foreach ($data['attendances'] as $attendance) {
        $events[] = [
            'id' => 'attendance-' . $attendance->id,
            'title' => '✅ Checked In - ' .
                      $attendance->clock_in->format('H:i A'),
            'start' => $attendance->clock_in->format('Y-m-d'),
            'color' => '#10B981', // Green
            'type' => 'attendance',
            'extendedProps' => [
                'clockIn' => $attendance->clock_in,
                'clockOut' => $attendance->clock_out,
                'duration' => $attendance->duration_minutes,
                'status' => $attendance->status
            ]
        ];
    }

    // Format leaves as red events
    foreach ($data['leaves'] as $leave) {
        $events[] = [
            'id' => 'leave-' . $leave->id,
            'title' => '🏖️ ' . $leave->leave_type->name .
                      ' (' . $leave->days . ' days)',
            'start' => $leave->start_date,
            'end' => $leave->end_date->addDay(),
            'color' => '#EF4444', // Red
            'type' => 'leave',
            'extendedProps' => [
                'leaveType' => $leave->leave_type->name,
                'days' => $leave->days,
                'reason' => $leave->reason
            ]
        ];
    }

    // Format overtimes as orange events
    foreach ($data['overtimes'] as $overtime) {
        $events[] = [
            'id' => 'overtime-' . $overtime->id,
            'title' => '⏰ OT: ' . $overtime->hours . ' hours',
            'start' => $overtime->date,
            'color' => '#F97316', // Orange
            'type' => 'overtime',
            'extendedProps' => [
                'hours' => $overtime->hours,
                'reason' => $overtime->reason,
                'status' => $overtime->status
            ]
        ];
    }

    // Format holidays as gray events
    foreach ($data['holidays'] as $holiday) {
        $events[] = [
            'id' => 'holiday-' . $holiday->id,
            'title' => '⬜ ' . $holiday->name,
            'start' => $holiday->date,
            'color' => '#9CA3AF', // Gray
            'type' => 'holiday',
            'extendedProps' => [
                'description' => $holiday->description
            ]
        ];
    }

    // Format company events as gold events
    foreach ($data['events'] as $event) {
        $events[] = [
            'id' => 'event-' . $event->id,
            'title' => '⭐ ' . $event->title,
            'start' => $event->start_date,
            'end' => $event->end_date,
            'color' => '#FBBF24', // Gold
            'type' => 'event',
            'extendedProps' => [
                'description' => $event->description,
                'location' => $event->location
            ]
        ];
    }

    return $events;
}

2.2 Service Classes

class ShiftServices
{
    public function getUserShifts($userId, $startDate = null, $endDate = null)
    {
        return UserShift::where('user_id', $userId)
            ->whereBetween('date', [$startDate, $endDate])
            ->with(['shift', 'workplace', 'workstation'])
            ->get();
    }
}

class AttendanceRecordServices
{
    public function getRecords($userId, $year = null)
    {
        $year = $year ?? now()->year;

        return AttendanceRecord::where('user_id', $userId)
            ->whereYear('clock_in', $year)
            ->get();
    }
}

class LeaveRequestServices
{
    public function getApprovedLeaves($userId)
    {
        return LeaveRequest::where('user_id', $userId)
            ->where('status', 'APPROVED')
            ->with('leave_type')
            ->get();
    }
}

3. Blade Template Structure

3.1 Calendar Markup

File: resources/views/users/employee/calendar/index.blade.php

<x-employee-layout>
    <div class="container-fluid p-4">

        <!-- Header Controls -->
        <div class="flex justify-between items-center mb-4">
            <h1 class="text-3xl font-bold">My Calendar</h1>

            <div class="flex gap-2">
                <!-- View Mode -->
                <select @change="changeViewMode" class="select select-sm">
                    <option value="dayGridMonth">Month</option>
                    <option value="timeGridWeek">Week</option>
                    <option value="timeGridDay">Day</option>
                </select>

                <!-- Filter -->
                <button @click="showFilter = !showFilter" class="btn btn-sm">
                    Filter
                </button>

                <!-- Export -->
                <button @click="exportCalendar" class="btn btn-sm">
                    Export
                </button>

                <!-- Print -->
                <button @click="window.print()" class="btn btn-sm">
                    Print
                </button>
            </div>
        </div>

        <!-- Filter Panel -->
        <div x-show="showFilter" class="mb-4 p-4 bg-base-200 rounded">
            <label class="flex items-center gap-2">
                <input type="checkbox"
                    @change="toggleFilter('shift')"
                    :checked="filters.shift" />
                <span>Shifts</span>
            </label>
            <label class="flex items-center gap-2">
                <input type="checkbox"
                    @change="toggleFilter('attendance')"
                    :checked="filters.attendance" />
                <span>Attendance</span>
            </label>
            <label class="flex items-center gap-2">
                <input type="checkbox"
                    @change="toggleFilter('leave')"
                    :checked="filters.leave" />
                <span>Leaves</span>
            </label>
            <label class="flex items-center gap-2">
                <input type="checkbox"
                    @change="toggleFilter('overtime')"
                    :checked="filters.overtime" />
                <span>Overtime</span>
            </label>
            <label class="flex items-center gap-2">
                <input type="checkbox"
                    @change="toggleFilter('holiday')"
                    :checked="filters.holiday" />
                <span>Holidays</span>
            </label>
            <label class="flex items-center gap-2">
                <input type="checkbox"
                    @change="toggleFilter('event')"
                    :checked="filters.event" />
                <span>Company Events</span>
            </label>
        </div>

        <!-- Calendar Container -->
        <div id="calendar"></div>

        <!-- Legend -->
        <div class="mt-4 p-4 bg-base-200 rounded">
            <h3 class="font-bold mb-2">Legend</h3>
            <div class="grid grid-cols-3 gap-4">
                <div class="flex items-center gap-2">
                    <div class="w-4 h-4 bg-blue-500"></div>
                    <span>Shift</span>
                </div>
                <div class="flex items-center gap-2">
                    <div class="w-4 h-4 bg-green-500"></div>
                    <span>Checked In</span>
                </div>
                <div class="flex items-center gap-2">
                    <div class="w-4 h-4 bg-red-500"></div>
                    <span>Leave</span>
                </div>
                <div class="flex items-center gap-2">
                    <div class="w-4 h-4 bg-orange-500"></div>
                    <span>Overtime</span>
                </div>
                <div class="flex items-center gap-2">
                    <div class="w-4 h-4 bg-yellow-500"></div>
                    <span>Pending</span>
                </div>
                <div class="flex items-center gap-2">
                    <div class="w-4 h-4 bg-gray-500"></div>
                    <span>Holiday</span>
                </div>
            </div>
        </div>
    </div>

    <!-- Event Details Modal -->
    <div id="eventModal" class="modal">
        <div class="modal-box">
            <h3 id="eventTitle" class="font-bold text-lg"></h3>
            <div id="eventDetails" class="py-4"></div>
            <div class="modal-action">
                <button class="btn" onclick="eventModal.close()">Close</button>
                <button class="btn btn-primary" onclick="editEvent()">Edit</button>
            </div>
        </div>
    </div>

    @push('scripts')
    <script>
        const events = @json($events);

        document.addEventListener('DOMContentLoaded', function() {
            initializeCalendar(events);
        });
    </script>
    @endpush
</x-employee-layout>

4. Calendar Engine Integration

4.1 FullCalendar.js Implementation

function initializeCalendar(events) {
    const calendarEl = document.getElementById("calendar");

    const calendar = new FullCalendar.Calendar(calendarEl, {
        initialView: "dayGridMonth",
        headerToolbar: {
            left: "prev,next today",
            center: "title",
            right: "dayGridMonth,timeGridWeek,timeGridDay",
        },
        events: events,
        eventClick: handleEventClick,
        datesSet: handleDatesSet,
        eventClassNames: getEventClasses,
        height: "auto",
    });

    calendar.render();
}

function handleEventClick(info) {
    const event = info.event;
    displayEventModal(event);
}

function getEventClasses(info) {
    return ["event-" + info.event.extendedProps.type];
}

function displayEventModal(event) {
    document.getElementById("eventTitle").textContent = event.title;
    document.getElementById("eventDetails").innerHTML =
        formatEventDetails(event);
    document.getElementById("eventModal").showModal();
}

function formatEventDetails(event) {
    const props = event.extendedProps;

    switch (props.type) {
        case "shift":
            return `
                <p><strong>Workplace:</strong> ${props.workplace}</p>
                <p><strong>Workstation:</strong> ${props.workstation}</p>
                <p><strong>Duration:</strong> ${props.duration}</p>
            `;
        case "attendance":
            return `
                <p><strong>Clock In:</strong> ${props.clockIn}</p>
                <p><strong>Clock Out:</strong> ${props.clockOut}</p>
                <p><strong>Duration:</strong> ${props.duration}</p>
                <p><strong>Status:</strong> ${props.status}</p>
            `;
        // ... other types
    }
}

5. Data Models & Relationships

5.1 Key Models

// UserShift model
class UserShift extends Model
{
    protected $dates = ['date'];

    public function shift() {
        return $this->belongsTo(Shift::class);
    }

    public function workplace() {
        return $this->belongsTo(WorkPlace::class);
    }

    public function workstation() {
        return $this->belongsTo(WorkStation::class);
    }
}

// AttendanceRecord model
class AttendanceRecord extends Model
{
    protected $dates = ['clock_in', 'clock_out'];

    public function getDurationMinutesAttribute()
    {
        return $this->clock_in->diffInMinutes($this->clock_out);
    }
}

// LeaveRequest model
class LeaveRequest extends Model
{
    public function leave_type() {
        return $this->belongsTo(LeaveType::class);
    }

    public function getDaysAttribute()
    {
        return $this->start_date->diffInDays($this->end_date);
    }
}

6. API Endpoints

6.1 Get Calendar Events

Endpoint: GET /api/v1/calendar/events

Parameters:

startDate: 2025-12-01
endDate: 2025-12-31
filters: shift,attendance,leave,overtime

Response:

{
    "events": [
        {
            "id": "shift-1",
            "title": "Morning (08:00-17:00)",
            "start": "2025-12-04",
            "color": "/docs/1.0/employee/calendar#3B82F6",
            "type": "shift"
        }
    ]
}

7. Export Functionality

7.1 Export as ICS

public function exportICS()
{
    $events = $this->formatCalendarEvents([...]);

    $ics = new ICal('DTR Calendar');

    foreach ($events as $event) {
        $ics->addEvent([
            'title' => $event['title'],
            'description' => json_encode($event['extendedProps']),
            'dtstart' => $event['start'],
            'dtend' => $event['end'] ?? $event['start'],
            'categories' => $event['type']
        ]);
    }

    return response($ics->get())
        ->header('Content-Type', 'text/calendar')
        ->header('Content-Disposition', 'attachment; filename="dtr-calendar.ics"');
}

Documentation Version: 1.0
Last Updated: December 4, 2025
Status: ✅ Complete

Get Started

Admin Module

Employee Module

HR Module

TL Module

Employee Calendar Documentation

Part 1: USER GUIDE - Employee Calendar

Table of Contents

1. Overview

What is the Calendar?

Key Features

Calendar Components

2. Accessing the Calendar

2.1 Ways to Access

2.2 Calendar Page Load

3. Calendar Interface

3.1 Calendar Layout

3.2 Date Cell Structure

3.3 Header Controls

3.4 Navigation Bar

3.5 Legend (Key)

4. Understanding Events

4.1 Event Types Displayed

1. Shifts (🔵 Blue)

2. Attendance Records (✅ Green)

3. Leave (🏖️ Red)

4. Overtime (⏰ Orange)

5. Company Events (⭐ Star)

6. Holidays (⬜ Gray)

7. Pending Approvals (🟡 Yellow)

5. Navigation & Filtering

5.1 Monthly Navigation

5.2 View Mode Selection

Month View

Week View

Day View

5.3 Filter Events

5.4 Search & Jump

6. Viewing Event Details

6.1 Click a Date to See Details

6.2 Information Displayed

6.3 Actions from Details Modal

7. Legend & Color Coding

7.1 Color System

1. Blue (🔵) - Regular Shifts

2. Green (🟢) - Checked-In

3. Red (🔴) - On Leave

4. Orange (🟠) - Overtime

5. Yellow (🟡) - Pending Approval

6. Gray (⬜) - Off Days / Holidays

7. Star (⭐) - Company Events

7.2 Color Meaning Quick Reference

7.3 Multiple Events on Same Day

8. Tips & Best Practices

8.1 Using Calendar Effectively

8.2 Best Practices

8.3 Calendar Shortcuts

9. Troubleshooting

Issue 1: "Calendar Not Loading"

Issue 2: "Events Not Showing"

Issue 3: "Wrong Color for Event"

Issue 4: "Cannot Export Calendar"

Issue 5: "Mobile Calendar Issues"

FAQ

END OF USER GUIDE - PART 1

PART 2: DEVELOPER GUIDE - Employee Calendar

Table of Contents

1. Architecture Overview

1.1 Component Stack

1.2 Data Flow

2. Controller Implementation

2.1 CalendarController

Method: index()

2.2 Service Classes

3. Blade Template Structure

3.1 Calendar Markup

4. Calendar Engine Integration

4.1 FullCalendar.js Implementation

5. Data Models & Relationships

5.1 Key Models

Method: `index()`