MagicMirror module for calendar view.

My previous module, MMM-CalendarExt2, was always notorious for its difficulty to use. I need a more easy and light one. So I rewrite this from scratch newly.

• Only focusing on how it shows; Parsing is delegated to original MagicMirror module calendar. (It means the calendar module is REQUIRED to use this module.)
• Only week and month views. I found that people are rarely interested in other views on CX2. So I drop out different views.
• Respect to original MM's hide/show mechanism. Now you can hide/show this module easily with other scheduler or control modules. (By the way, Look at this module also. - MMM-Scenes)
• No dependency on the 3rd party modules (e.g. momentJS or Luxon, etc.). This is built with pure JS and CSS only.

• week view or month view
• locale-aware calendar
• customizing events: filtering, sorting, transforming
• multi-instance available. You don't need to copy and rename the module. Just add one more configuration in your config.js.

cd ~/MagicMirror/modules
git clone https://github.com/MMRIZE/MMM-CalendarExt3

Anyway, even this simplest will work.

{
  module: "MMM-CalendarExt3",
  position: "bottom_center",
},

More conventional;

{
  module: "MMM-CalendarExt3",
  position: "bottom_center",
  title: "",
  config: {
    mode: "month",
    instanceId: "basicCalendar",
    locale: 'de-DE',
    maxEventLines: 5,
    firstDayOfWeek: 1,
    calendarSet: ['us_holiday', 'abfall', 'mytest'],
    ...
  }
},

You need setup default calendar configuration also.

/* default/calendar module configuration */
{
  module: "calendar",
  position: "top_left",
  config: {
    broadcastPastEvents: true, // <= IMPORTANT to see past events
    calendars: [
      {
        url: "webcal://www.calendarlabs.com/ical-calendar/ics/76/US_Holidays.ics",
        name: "us_holiday", // <= RECOMMENDED to assign name
        color: "red" // <= RECOMMENDED to assign color
      },
      ...

All the properties are omittable, and if omitted, a default value will be applied.

Jump calendar view to another moment. It will return after glanceTime from last notification command.

• instanceId : If you have more than 1 instance of this module, you can specify the instance to manipulate. If omitted or null, all instances would obey this notification order.
• step : How many leaps of the current view. In mode:'week' 1 step will be a week. In mode:'month' 1 step will be a month. Negative value is allowed.

Set the date of specific view.

• instanceId : See the above
• date : Specific date to move. e.g) In mode:'month', date: "2022-12-25" would display calendar view of 2022 Decemeber. Be aware of weekIndex of mode:'week'. The view range will be calculated with weekIndex, weeksInView and this value.

Any module which can emit this notification could become the source of this module. Generally, the default calendar module would be.

Any module which can emit this notification could become the source of weather forecasting. Generally, the default weather module would be.

Nothing yet. (Does it need?)

You can handle almost all of the visual things with CSS. See the module.css and override your needs into your custom.css.

• CX3, CX3_{instanceId}, mode_week or mode_month : The root selector. Each instance of this module will have CX3_{instanceId} as another root selector. With this CSS selector, you can assign individual look to each instance.

.CX3 {
  /* you CAN modify these values; but SHOULD NOT to remove */
  --celllinecolor: #333;
  --cellbgcolor: rgba(0, 0, 0, 0.2);
  --cellheaderheight: 25px;
  --cellfooterheight: 2px;
  --defaultcolor: #FFF;
  --eventheight: calc(var(--fontsize) + 4px);
  --totalheight: calc(var(--eventheight) * var(--maxeventlines));
  font-size: var(--fontsize);
  color: var(--defaultcolor);
  line-height: calc(var(--eventheight))
}

Most commonly used values would be defined in .CX3 selector as variables.

--fontsize, --maxeventlines, --eventheight would be imported from configuration for your setup convenience.

• .cell : Every day cell has this selector. Each cell could have these class name together by its condition.

  • .today, .thisMonth, .thisYear
  • .year_2022, .month_12, .date_25, .weekday_0

• .cellHeader, .cellFooter : Parts of day cell. .cellHeader would have .cw(count of week) and .cellDate as children.

  • .cellHeader .cellDate : Displaying date of the cell. The date would have many parts of date/hour information from cellDateOptions of config.

• .event : Every event has this selector. Each event could have these class name together by its condition.

  • .continueFromPreviousWeek, .continueToNextWeek
  • .calendar_{calendarName}, {class} : Orginal calendar
  • .passed, .future, .current,
  • .multiday, .singleday, .fullday

And event also has dataSet (data-*) as its attributes. (e.g. data-title="...", data-start-date="...") You can use these attributes also.

• .weekGrid, .weekGridRow : Definition of calendar grid. You can adjust the grid itself. (e.g. Shrink the width of weekends cells)

Each event object has this structure.

{
  "title": "Leeds United - Chelsea",
  "startDate": 1650193200000,
  "endDate": 1650199500000,
  "fullDayEvent": false,
  "class": "PUBLIC",
  "location": false,
  "geo": false,
  "description": "...",
  "today": false,
  "symbol": ["calendar-alt"],
  "calendarName": "tottenham",
  "color": "gold",
  "calendarSeq": 1, // This would be the order from `calendarSet` of configuration
  "isPassed": true,
  "isCurrent": false,
  "isFuture": false,
  "isFullday": false,
  "isMultiday": false
}

You can use these values to handle events.

You can filter each event by its condition.

eventFilter: (ev) => {
  if (ev.isFullday) return false
  return true
}

This example shows how you can filter out 'fullday' events.

You can sort each event by its condition. However, this module arranges events masonry with density. So displaying would not fit with your sorting intention. Anyway, try if you need it.

eventSorter: (a, b) => {
  return a.calendarSeq - b.calendarSeq
}

This example tries to sort events by calendar order in calendarSet.

You can manipulate or change the properties of the event.

eventTransformer: (ev) => {
  if (ev.title.search('John') > -1) ev.color = 'blue'
  return ev
}

This example shows how you can transform the color of events when the event title has specific text.

When you are using MM's default weather forecasting, weather icon will be displayed on the day cell.

useWeather: true,
weatherLocationName: 'New York',
// Original weather module might have its location name with more details. (e.g. 'New York City, US'), but the partial text included would be acceptable for this attribute.
// When the location name would not match, warning messgage will be shown on dev console. Check it.

You can set brands icons like this; (However, default calendar module cannot accept FA brands icons AFAIK.)

/* In your default calendar config */
symbol: ['fa-brands fa-canadian-maple-leaf'],
/* or */
symbol: ['brands canadian-maple-leaf'],
/* of course below are also allowed */
symbol: 'brands canadian-maple-leaf',
/* But if you want multi-icons, use array */
symbol: ['brands google-drive', 'solid calendar'],

eventTransformer: (e) => {
  e.startDate = new Date(e.start?.date || e.start?.dateTime).valueOf()
  e.endDate = new Date(e.end?.date || e.end?.dateTime).valueOf()
  e.title = e.summary
  e.fulldayEvent = (e.start?.date) ? true : false
  return e
}

• The default calendar module cannot emit the exact starting time of multidays-fullday-event which is passing current moment. Always it starts from today despite of original event starting time. So this module displays these kinds of multidays-fullday-event weirdly.
• I am not considering 5-weekdays-view at this moment. Only-Weekdays-view might be useful, but in some cultures/locales, Locale-aware Weekdays are not easy to normalize. Friday and Sunday are weekends in Brunei. Iran adopts Friday only. I cannot calculate any convenient way to normalize this kind of grid view.
• I'll add TimeLine and TimeTable views/extended modules in future.

• Added useWeather option. (true/false)
• Added weatherLocationName option (some partial text to distinguish location)

• Added Display legend of the calendar (displayLegend: true and when you set the calendar name on calendar module)
• Fixed Some CSS fixture

• Fixed Urgent fix for useSymbol issue since #1.2.2
• Fixed symbol:null issue resolved

• Fixed Move eventFormatter to prior to get compatibility with other calendar module (e.g GoogleCalendar module)

• Added Multi icons
• Added Font-awesome 'brands' icons

• Added Magic opposite color for the full-day event (This feature could solve the issue of no-color assigned.)
• Fixed CSS file renamed (module.css => MMM-CalendarExt3.css)

• Support multi notifications from multi-calendar providers. (It will prevent events reset.)

• MMRIZE#4

• Released.

• Seongnoh Yi ([email protected])