DOCSEARCHbyAlgolia
Submit Docs

MagicMirror² Documentation

website·Indexed 36 days ago

https://docs.magicmirror.builders

Official documentation for MagicMirror², an open-source smart mirror platform. Includes guides on installation, configuration, and core development, as well as detailed instructions for creating custom modules using the core module file, Node helpers, and the rendering component. Covers default modules such as Clock, Calendar, Weather, News Feed, and Compliments.

Tokens
28.3K
Snippets
162
Records
219
Agent score
68%

What's inside MagicMirror

  1. Overview of the MagicMirror² platform

    MagicMirror² is an open-source modular smart mirror platform designed to convert a standard mirror into a personal assistant display. It utilizes a modular plugin system and uses Electron as an application wrapper, eliminating the need for separate web server or browser installations. The software is designed to be run on a display placed behind a two-way mirror.

  2. Alternative installation methods for MagicMirror²

    While manual installation is the only officially supported method, several community-maintained alternatives exist:

  3. Understand the MagicMirror notification system

    MagicMirror uses a notification system that allows the core to send messages to modules, and allows modules to send notifications to other modules. To implement this in a custom module, use the notificationReceived handler to listen for incoming messages and the sendNotification method to broadcast messages.

  4. MagicMirror² Project Philosophy and Core Principles

    MagicMirror² is designed as an open-source platform for Raspberry Pi enthusiasts and developers, prioritizing simplicity and accessibility to encourage community contribution and learning. The project adheres to several core principles:

    • Simplicity as a Foundation: The project avoids overly complex frameworks (like Vue or SASS) to ensure that users can modify a single file and see immediate results without needing a complex build pipeline.
    • Modular and Open: The architecture is modular, allowing users and contributors to easily add or remove features.
    • Accessibility: It serves as an entry point for beginners to learn software development and open-source collaboration.
    • Collaborative Growth: The project is driven by community feedback, code contributions, and shared ideas.

  5. Trigger notifications and alerts from other modules

    Developers can trigger the alert module by sending a SHOW_ALERT notification.

    • To trigger a notification: Send SHOW_ALERT with an object containing type: "notification".
    • To trigger an alert: Send SHOW_ALERT with an empty object or alert-specific parameters.
    // Trigger a notification
self.sendNotification("SHOW_ALERT", { type: "notification", title: "Hello", message: "World" });

// Trigger an alert
self.sendNotification("SHOW_ALERT", { title: "Alert", message: "Warning!" });

  6. Render a MagicMirror component using getDom

    The getDom method is used to procedurally generate the module's UI. MagicMirror calls this method whenever the screen needs to be updated. It must return an HTML Element containing the content to be displayed. To trigger a re-render when data changes, call this.updateDom().
    getDom: function() {
	const wrapper = document.createElement("div");
	wrapper.innerHTML = 'Hello world!';
	return wrapper;
}

  7. Recompile native Node modules for Electron

    If your node_helper.js uses native Node modules, they must be recompiled for Electron using @electron/rebuild to function correctly.
    npm install --save-dev @electron/rebuild

    Add to package.json:

    "scripts": {
	"postinstall": "./node_modules/.bin/electron-rebuild"
}

  8. Sync Office 365 calendars with MagicMirror

    Office 365 calendars use date formats incompatible with MagicMirror 2. To use an Office 365 calendar, you must route it through Google Calendar:

    1. Import your existing Office 365 calendar into Google Calendar to capture past events.
    2. Use Microsoft Flow to create a trigger that automatically adds new Office 365 events to your Google Calendar (runs every 5 minutes).
    3. Use the private address generated by Google Calendar as the source URL in the MagicMirror calendar module configuration.

  9. Apply animations to MagicMirror modules

    Since version 2.25.0, MagicMirror supports animations based on the animate.css library. Animations can be applied in the following locations:

    • Global module configuration (via the animated property).
    • Within the this.hide() function in the core module file.
    • Within the this.show() function in the core module file.
    • Within the this.updateDom() function in the core module file.

    Animation names are case-sensitive. If an invalid name is provided, the system defaults to the 'fade' animation. You must use animateIn names for appearing elements and animateOut names for hiding elements; they are not interchangeable.

  10. Use the MagicMirror Logger for application logging

    MagicMirror provides a Log convenience wrapper that acts as a proxy to standard console.log methods. It is used to output information, general logs, and errors to the console. Because MagicMirror runs in an Electron front-end/browser environment, logs may appear in both the terminal and the browser's developer console.
    Log.info("info");
Log.log("log");
Log.error("error");

  11. Target specific modules in custom CSS

    Every module (including 3rd-party modules) is wrapped in a div with a CSS class named after the module. To apply styles to a specific module, use its corresponding class name. For example, the Clock module can be targeted using the .clock class.
    .clock {
  /* Your custom styles for the clock module */
}

  12. Render a MagicMirror component using Nunjucks templates

    If getDom is not overridden, MagicMirror uses the Nunjucks templating engine. To implement this, define getTemplate to return the filename of the template and getTemplateData to return an object containing the data to be injected into the template.
    // In MMM-MyModule.js
getTemplate: function() {
  return "MMM-MyModule.njk";
},

getTemplateData: function() {
  return {
    list: ["item 1", "item 2", "item 3"],
  };
}

    // In MMM-MyModule.njk

    <ul>
  {% for item in list %}
  <li>{{ item }}</li>
  {% endfor %}
</ul>