README.md

Module: Calendar

The calendar module is one of the default modules of the MagicMirror. This module displays events from a public .ical calendar. It can combine multiple calendars.

Using the module

To use this module, add it to the modules array in the config/config.js file:

modules: [
	{
		module: "calendar",
		position: "top_left",	// This can be any of the regions. Best results in left or right regions.
		config: {
			// The config property is optional.
			// If no config is set, an example calendar is shown.
			// See 'Configuration options' for more information.
		}
	}
]

Configuration options

The following properties can be configured:

Option	Description
maximumEntries	The maximum number of events shown. / Possible values: 0 - 100 Default value: 10
maximumNumberOfDays	The maximum number of days in the future. Default value: 365
displaySymbol	Display a symbol in front of an entry. Possible values: true or false Default value: true
defaultSymbol	The default symbol. Possible values: See Font Awsome website. Default value: calendar
maxTitleLength	The maximum title length. Possible values: 10 - 50 Default value: 25
wrapEvents	Wrap event titles to multiple lines. Breaks lines at the length defined by maxTitleLength. Possible values: true or false Default value: false
maxTitleLines	The maximum number of lines a title will wrap vertically before being cut (Only enabled if wrapEvents is also enabled). Possible values: 0 - 10 Default value: 3
fetchInterval	How often does the content needs to be fetched? (Milliseconds) Possible values: 1000 - 86400000 Default value: 300000 (5 minutes)
animationSpeed	Speed of the update animation. (Milliseconds) Possible values: 0 - 5000 Default value: 2000 (2 seconds)
fade	Fade the future events to black. (Gradient) Possible values: true or false Default value: true
fadePoint	Where to start fade? Possible values: 0 (top of the list) - 1 (bottom of list) Default value: 0.25
tableClass	Name of the classes issued from main.css. Possible values: xsmall, small, medium, large, xlarge. Default value: small.
calendars	The list of calendars. Possible values: An array, see calendar configuration below. Default value: An example calendar.
titleReplace	An object of textual replacements applied to the tile of the event. This allow to remove or replace certains words in the title. Example: {'Birthday of ' : '', 'foo':'bar'} Default value: { "De verjaardag van ": "", "'s birthday": "" }
displayRepeatingCountTitle	Show count title for yearly repeating events (e.g. "X. Birthday", "X. Anniversary") Possible values: true or false Default value: false
dateFormat	Format to use for the date of events (when using absolute dates) Possible values: See Moment.js formats Default value: MMM Do (e.g. Jan 18th)
dateEndFormat	Format to use for the end time of events Possible values: See Moment.js formats Default value: HH:mm (e.g. 16:30)
showEnd	Show end time of events Possible values: true or false Default value: true
fullDayEventDateFormat	Format to use for the date of full day events (when using absolute dates) Possible values: See Moment.js formats Default value: MMM Do (e.g. Jan 18th)
timeFormat	Display event times as absolute dates, or relative time, or using absolute date headers with times for each event next to it Possible values: absolute or relative or dateheaders Default value: relative
showEnd	Display the end of a date as well Possible values: true or false Default value: true
getRelative	How much time (in hours) should be left until calendar events start getting relative? Possible values: 0 (events stay absolute) - 48 (48 hours before the event starts) Default value: 6
urgency	When using a timeFormat of absolute, the urgency setting allows you to display events within a specific time frame as relative. This allows events within a certain time frame to be displayed as relative (in xx days) while others are displayed as absolute dates Possible values: a positive integer representing the number of days for which you want a relative date, for example 7 (for 7 days) Default value: 7
broadcastEvents	If this property is set to true, the calendar will broadcast all the events to all other modules with the notification message: CALENDAR_EVENTS. The event objects are stored in an array and contain the following fields: title, startDate, endDate, fullDayEvent, location and geo. Possible values: true, false Default value: true
hidePrivate	Hides private calendar events. Possible values: true or false Default value: false
hideOngoing	Hides calendar events that have already started. Possible values: true or false Default value: false
excludedEvents	An array of words / phrases from event titles that will be excluded from being shown. Additionally advanced filter objects can be passed in. Below is the configuration for the advance filtering object. Required filterBy - string used to determine if filter is applied. Optional until - Time before an event to display it Ex: ['3 days', '2 months', '1 week'] caseSensitive - By default, excludedEvents are case insensitive, set this to true to enforce case sensitivity regex - set to true if filterBy is a regex. For those not familiar with regex it is used for pattern matching, please see here for more info. Example: ['Birthday', 'Hide This Event', {filterBy: 'Payment', until: '6 days', caseSensitive: true}, {filterBy: '^[0-9]{1,}.*', regex: true}] Default value: []
sliceMultiDayEvents	If this is set to true, events exceeding at least one midnight will be sliced into separate events including a counter like (1/2). This is especially helpful in "dateheaders" mode. Events will be sliced at midnight, end time for all events but the last will be 23:59 Default value: true

Calendar configuration

The calendars property contains an array of the configured calendars. The colored property gives the option for an individual color for each calendar. The coloredSymbolOnly property will apply color to the symbol only, not the whole line. This is only applicable when colored is also enabled.

Default value:

config: {
	colored: false,
	coloredSymbolOnly: false,
	calendars: [
		{
			url: 'http://www.calendarlabs.com/templates/ical/US-Holidays.ics',
			symbol: 'calendar',
			auth: {
			    user: 'username',
			    pass: 'superstrongpassword',
			    method: 'basic'
			}
		},
	],
}

Calendar configuration options:

Option	Description
url	The url of the calendar .ical. This property is required. Possible values: Any public accessble .ical calendar.
symbol	The symbol to show in front of an event. This property is optional. Possible values: See Font Awesome website. To have multiple symbols you can define them in an array e.g. ["calendar", "plane"]
color	The font color of an event from this calendar. This property should be set if the config is set to colored: true. Possible values: HEX, RGB or RGBA values (#efefef, rgb(242,242,242), rgba(242,242,242,0.5)).
repeatingCountTitle	The count title for yearly repating events in this calendar. Example: 'Birthday'
maximumEntries	The maximum number of events shown. Overrides global setting. Possible values: 0 - 100
maximumNumberOfDays	The maximum number of days in the future. Overrides global setting
name	The name of the calendar. Included in event broadcasts as calendarName.
auth	The object containing options for authentication against the calendar.
symbolClass	Add a class to the cell of symbol.
titleClass	Add a class to the title's cell.
timeClass	Add a class to the time's cell.

Calendar authentication options:

Option	Description
user	The username for HTTP authentication.
pass	The password for HTTP authentication. (If you use Bearer authentication, this should be your BearerToken.)
method	Which authentication method should be used. HTTP Basic, Digest and Bearer authentication methods are supported. Basic authentication is used by default if this option is omitted. Possible values: digest, basic, bearer Default value: basic