Calendar

A full-featured event calendar with month and week views, event chips, selectable dates, event-detail popovers, week numbers, and a complete JavaScript navigation API.

Full-featured Calendar with Popovers

Click any event chip to open a detail popover. Month / Week view switcher and Today navigation in the header. Events on the same day stack; overflow shows a "+N more" badge.

Click a date to see the selection…

// Full-featured with event popovers
$events = [
    ['date'        => '2025-05-05',
     'title'       => 'Audition Open',
     'type'        => 'submission',
     'color'       => '#4CAF50',
     'description' => 'Open call for new performers.',
     'url'         => '/events/1'],

    ['date'        => '2025-05-15',
     'title'       => 'Opening Night',
     'type'        => 'show',
     'color'       => '#C44900',
     'description' => 'Season opener — black tie event.'],
];

echo $m->calendar('eventsCal')
    ->events($events)
    ->view('month')
    ->selectable()
    ->highlightToday()
    ->withPopover()
    ->weekStartsMonday();

// Listen for date selection
document.getElementById('eventsCal').addEventListener('m:calendar:dateclick', function(e) {
    console.log('Selected:', e.detail.date);
    console.log('Events on day:', e.detail.events);
});

// Listen for event chip clicks
document.getElementById('eventsCal').addEventListener('m:calendar:eventclick', function(e) {
    console.log('Event clicked:', e.detail.event);
});

// Programmatic navigation
var cal = m.calendar('eventsCal');
cal.next();                          // forward one month
cal.prev();                          // back one month
cal.today();                         // jump to today
cal.goTo('2025-12-01');             // jump to specific date
cal.view('week');                    // switch to week view
cal.view('month');                   // switch back to month

// Dynamic events
cal.addEvent({
    date: '2025-05-25',
    title: 'New Event',
    color: '#9C27B0'
});
cal.clearEvents();                   // remove all events
cal.setEvents(newEventsArray);       // replace all events

Week View

The week view shows a single 7-day strip with full-day event chips. Navigates one week at a time.

// Week view with fixed cell height
echo $m->calendar('weekCal')
    ->events($events)
    ->view('week')
    ->weekStartsMonday()
    ->highlightToday()
    ->withPopover()
    ->height('200px');

With ISO Week Numbers

ISO 8601 week numbers in a narrow gutter on the left. Useful for production schedules and editorial planning.

echo $m->calendar('schedCal')
    ->events($events)
    ->weekStartsMonday()
    ->showWeekNumbers()
    ->highlightToday();

Selectable with Date Constraints

Restrict which dates can be selected with minDate() and maxDate(). Disabled dates render at reduced opacity. The selected date is reported below.

No date selected yet…

// Selectable within this calendar month only
echo $m->calendar('pickCal')
    ->selectable()
    ->highlightToday()
    ->minDate(date('Y-m-d', strtotime('first day of this month')))
    ->maxDate(date('Y-m-d', strtotime('last day of this month')));

document.getElementById('pickCal').addEventListener('m:calendar:dateclick', function(e) {
    document.getElementById('output').textContent = 'Selected: ' + e.detail.date;

    // Or get it programmatically
    var selected = m.calendar('pickCal').selected();
    console.log('Via API:', selected);
});

Read-only Display

Without selectable(), the calendar is a pure display widget — no hover cursor, no selection state. Ideal for embedding on public-facing pages.

// Pure display — no click interaction
echo $m->calendar('displayCal')
    ->events($events)
    ->highlightToday();

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->calendar($id)`	`string $id`	Create a Calendar instance.
`->events($events)`	`array`	Set all events. Each event: `date` (YYYY-MM-DD, required), `title`, `type`, `color`, `description`, `url`.
`->addEvent($event)`	`array`	Append a single event.
`->view($view)`	`string`	Initial view. Default: `'month'`. Accepted: `'month'`, `'week'`.
`->initialDate($date)`	`string YYYY-MM-DD`	Date to display on first render. Defaults to today.
`->selectable()`	`bool = true`	Allow clicking dates. Fires `m:calendar:dateclick`.
`->highlightToday()`	`bool = true`	Fill today's date number with a primary-colour circle. Default: on.
`->weekStartsMonday()`	`bool = true`	Start columns on Monday instead of Sunday.
`->showWeekNumbers()`	`bool = true`	Show ISO 8601 week numbers in the left gutter.
`->withPopover()`	`bool = true`	Show an event-detail popover when an event chip is clicked.
`->minDate($date)`	`string YYYY-MM-DD`	Earliest date that can be viewed or selected.
`->maxDate($date)`	`string YYYY-MM-DD`	Latest date that can be viewed or selected.
`->height($css)`	`string`	Fixed height for calendar rows (e.g. `'200px'`). Default: fluid.

JS JS Methods

Method / Property	Parameters	Description
`m.calendar(id)`		Get the Calendar API instance. Returns `null` if element not found.
`.view('month'\|'week')`	`string`	Switch the current view and re-render.
`.goTo(dateStr)`	`string YYYY-MM-DD`	Navigate to the period containing the given date.
`.today()`		Jump to today's month.
`.prev()`		Navigate back one month (or one week in week view).
`.next()`		Navigate forward one month (or one week in week view).
`.setEvents(events)`	`Array`	Replace all events and re-render.
`.addEvent(event)`	`Object`	Append one event and re-render.
`.clearEvents()`		Remove all events and re-render.
`.selected()`		Returns the currently selected date string (YYYY-MM-DD), or `null`.

EVENT Events

Event Name	Detail	Description
`m:calendar:dateclick`	`{ date, events }`	Fired when a selectable date cell is clicked. `date` is YYYY-MM-DD; `events` is the array of events on that day.
`m:calendar:eventclick`	`{ event, date }`	Fired when an event chip is clicked. `event` is the full event object.
`m:calendar:navigate`	`{ year, month, view }`	Fired after the calendar navigates to a new period.