)`
175 |
176 | Sample:
177 |
178 | - You have created a `` named "myDivSample"
179 | - You want to remove a `flipInX` type animation created with `addAnimateCSS()`
180 | function
181 |
182 | ```javascript
183 | removeAnimateCSS("myDivSample", "flipInX");
184 | ```
185 |
186 | ::: tip Tip
187 |
188 | You have to update only one element of your module.
189 |
190 | So, why not add an animation!?
191 |
192 | :::
193 |
194 | ```javascript
195 | ...
196 | // select element ("myDivSample")
197 | let test = document.getElementById("myDivSample")
198 | // apply pretty update of this element
199 | test.textContent = "Hello AnimateCSS!"
200 | // add an "flipInX" animation type to "myDivSample" with 1 sec duration
201 | addAnimateCSS("myDivSample", "flipInX", 1)
202 | setTimeout(() => {
203 | // remove animation after 1sec
204 | removeAnimateCSS("myDivSample", "flipInX")
205 | }, 1000)
206 | ...
207 | ```
208 |
--------------------------------------------------------------------------------
/modules/clock.md:
--------------------------------------------------------------------------------
1 | # Clock
2 |
3 | The `clock` module is one of the default modules of the MagicMirror. This module
4 | displays the current date and time. The information will be updated realtime.
5 |
6 | ## Screenshot
7 |
8 | 
9 |
10 | ## Using the module
11 |
12 | To use this module, add it to the modules array in the `config/config.js` file:
13 |
14 | ```javascript
15 | modules: [
16 | {
17 | module: "clock",
18 | position: "top_left", // This can be any of the regions.
19 | config: {
20 | // The config property is optional.
21 | // See 'Configuration options' for more information.
22 | },
23 | },
24 | ];
25 | ```
26 |
27 | ## Configuration options
28 |
29 | The following properties can be configured:
30 |
31 | | Option | Description |
32 | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
33 | | `timeFormat` | Use 12 or 24 hour format.
**Possible values:** `12` or `24`
**Default value:** uses value of _config.timeFormat_ |
34 | | `timezone` | Specific a timezone to show clock.
**Possible examples values:** `America/New_York`, `America/Santiago`, `Etc/GMT+10`
**Default value:** `none`. See more information about configuration value [here](https://momentjs.com/timezone/docs/#/data-formats/packed-format/) |
35 | | `displaySeconds` | Display seconds.
**Possible values:** `true` or `false`
**Default value:** `true` |
36 | | `showPeriod` | Show the period (am/pm) with 12 hour format.
**Possible values:** `true` or `false`
**Default value:** `true` |
37 | | `showPeriodUpper` | Show the period (AM/PM) with 12 hour format as uppercase.
**Possible values:** `true` or `false`
**Default value:** `false` |
38 | | `clockBold` | Remove the colon and bold the minutes to make a more modern look.
**Possible values:** `true` or `false`
**Default value:** `false` |
39 | | `showTime` | Turn off or on the Time section.
**Possible values:** `true` or `false`
**Default value:** `true` |
40 | | `showDate` | Turn off or on the Date section.
**Possible values:** `true` or `false`
**Default value:** `true` |
41 | | `showWeek` | Turn off or on the Week section.
**Possible values:** `true` or `false`
**Default value:** `false` |
42 | | `showSunTimes` | Turn off or on the section showing sunrise and sunset times (digital clock only).
**Possible values:** `true` or `false`
**Default value:** `false` |
43 | | `showMoonTimes` | Turn off or on the section showing moonrise and moonset times (digital clock only). Optionally display an image of lunar phase and lit percentage of the moon
**Possible values:** `times`, `percent`, `phase`, `both` or `false` (disable)
**Default value:** `false` |
44 | | `lat` | Latitude for sun/moon calculations.
**Default value:** `47.630539` |
45 | | `lon` | Longitude for sun/moon calculations.
**Default value:** `-122.344147` |
46 | | `dateFormat` | Configure the date format as you like.
**Possible values:** [Docs](https://momentjs.com/docs/#/displaying/format/)
**Default value:** `"dddd, LL"` |
47 | | `displayType` | Display a digital clock, analog clock, or both together.
**Possible values:** `digital`, `analog`, or `both`
**Default value:** `digital` |
48 | | `analogSize` | **Specific to the analog clock.** Defines how large the analog display is.
**Possible values:** `A positive number of pixels`
**Default value:** `200px` |
49 | | `analogFace` | **Specific to the analog clock.** Specifies which clock face to use.
**Possible values:** `simple` for a simple border, `none` for no face or border, or `face-###` (where ### is currently a value between 001 and 012, inclusive)
**Default value:** `simple` |
50 | | `secondsColor` | **Specific to the analog clock.** Specifies what color to make the 'seconds' hand.
**Possible values:** `any HTML RGB Color`
**Default value:** `#888888`
// starting in version 2.31.0 this property is DEPRECATED, and WILL be removed in some future version. Use CSS instead. Class "clock-second-digital" for digital clock, "clock-second" for analog clock. |
51 | | `analogPlacement` | **Specific to the analog clock. _(requires displayType set to `'both'`)_** Specifies where the analog clock is in relation to the digital clock
**Possible values:** `top`, `right`, `bottom`, or `left`
**Default value:** `bottom` |
52 | | `analogShowDate` | **Obsolete**, can be replaced with analogPlacement and showTime.
**Specific to the analog clock.** If the clock is used as a separate module and set to analog only, this configures whether a date is also displayed with the clock.
**Possible values:** `false`, `top`, or `bottom`
**Default value:** `top` |
53 | | `sendNotifications` | Enable notifications for elapsed time. Used to be always done send prio to v2.23
**Possible values:** `true`, or `false`
**Default value:** `false` |
54 |
55 | ## Notifications
56 |
57 | The clock makes use of the built-in
58 | [Notification Mechanism](https://github.com/magicmirrororg/magicmirror/wiki/notifications)
59 | to relay notifications to all modules.
60 |
61 | Current notifications are:
62 |
63 | | Notification | Description |
64 | | -------------- | ---------------------------------------------------- |
65 | | `CLOCK_SECOND` | A second has elapsed.
_Parameter_: second value |
66 | | `CLOCK_MINUTE` | A minute has elapsed
_Parameter_: minute value |
67 |
68 | ## styles for clock hands (analog) and text (digital) can be found in clock_style.css, use css/custom.css to override
69 |
--------------------------------------------------------------------------------
/modules/compliments.md:
--------------------------------------------------------------------------------
1 | # Compliments
2 |
3 | The `compliments` module is one of the default modules of the MagicMirror. This
4 | module displays a random compliment.
5 |
6 | ## Screenshot
7 |
8 | 
9 |
10 | ## Using the module
11 |
12 | To use this module, add it to the modules array in the `config/config.js` file:
13 |
14 | ```javascript
15 | modules: [
16 | {
17 | module: "compliments",
18 | position: "lower_third", // This can be any of the regions.
19 | // Best results in one of the middle regions like: lower_third
20 | config: {
21 | // The config property is optional.
22 | // If no config is set, the default compliments are shown.
23 | // See 'Configuration options' for more information.
24 | },
25 | },
26 | ];
27 | ```
28 |
29 | ## Configuration options
30 |
31 | The following properties can be configured:
32 |
33 | | Option | Description |
34 | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35 | | `updateInterval` | How often does the compliment have to change? (Milliseconds)
**Possible values:** `1000` - `86400000`
**Default value:** `30000` (30 seconds) |
36 | | `fadeSpeed` | Speed of the update animation. (Milliseconds)
**Possible values:**`0` - `5000`
**Default value:** `4000` (4 seconds) |
37 | | `compliments` | The list of compliments.
**Possible values:** An object with four arrays: `morning`, `afternoon`, `evening` and `anytime`. See _compliment configuration_ below.
**Default value:** See _compliment configuration_ below. |
38 | | `remoteFile` | External file from which to load the compliments
**Possible values:** Path or URL (starting with `http://` or `https://`) to a JSON file containing compliments, configured as per the value of the _compliments configuration_ (see below). An json object {} with at least one of the arrays: `morning`, `afternoon`, `evening`, `anytime`, `datetype` and/or `crontype`. - `compliments.json`
**Default value:** `null` (Do not load from file) |
39 | | `remoteFileRefreshInterval` | How often to reload the remote file, if remoteFile is specified. in ms
**Default value:** 0
**Minimum value:** 15 minutes (15\*60\*60\*1000) |
40 | | `classes` | Override the CSS classes of the div showing the compliments
**Default value:** `thin xlarge bright` |
41 | | `morningStartTime` | Time in hours (in 24 format), after which the mode of "morning" will begin
**Possible values:** `0` - `24`
**Default value:** `3` |
42 | | `morningEndTime` | Time in hours (in 24 format), after which the mode of "morning" will end
**Possible values:** `0` - `24`
**Default value:** `12` |
43 | | `afternoonStartTime` | Time in hours (in 24 format), after which the mode "afternoon" will begin
**Possible values:** `0` - `24`
**Default value:** `12` |
44 | | `afternoonEndTime` | Time in hours (in 24 format), after which the mode "afternoon" will end
**Possible values:** `0` - `24`
**Default value:** `17` |
45 | | `specialDayUnique` | Compliments configured with a date are by default added to the existing compliments list. Setting this option to `true` will show only your special day compliments on that day. See _Example use with date_ below
**Default value:** `false` |
46 |
47 | All the rest of the time that does not fall into the
48 | morningStartTime-morningEndTime and afternoonStartTime-afternoonEndTime ranges
49 | is considered "evening".
50 |
51 | ### Compliment configuration
52 |
53 | The `compliments` property contains an object with at least four arrays:
54 | morning, afternoon, evening and
55 | anytime. Based on the time of the day, the compliments will be
56 | picked out of one of these arrays. The arrays contain one or multiple
57 | compliments.
58 |
59 | Compliments can be set for a specific day in the format `YYYY-MM-DD`. `.` can be
60 | used as a wildcard.
61 |
62 | starting in Version 2.29, the compliments configuration can use a cron type
63 | specification, which provides more options. In addition to date, one can use
64 | hours, minutes and day of week for additional control the cron format string is
65 | 5 groups of space separated values
**minute hour day month
66 | day_of_week**
each can be a range, and use numbers or names see
67 | https://crontab-generator.org for a visual cron syntax creator.. this tool asks
68 | for the command to be executed (cron is usually used to execute commands on a
69 | schedule), just use anything, and take the first 5 space separated tokens of the
70 | result.
71 |
72 | If set, the weather can be used for compliments. The available properties are:
73 |
74 | - `day_sunny`
75 | - `day_cloudy`
76 | - `cloudy`
77 | - `cloudy_windy`
78 | - `showers`
79 | - `rain`
80 | - `thunderstorm`
81 | - `snow`
82 | - `fog`
83 | - `night_clear`
84 | - `night_cloudy`
85 | - `night_showers`
86 | - `night_rain`
87 | - `night_thunderstorm`
88 | - `night_snow`
89 | - `night_alt_cloudy_windy`
90 |
91 | #### Example use with date
92 |
93 | ```javascript
94 | config: {
95 | compliments: {
96 | "....-01-01": [
97 | "Happy new year!"
98 | ],
99 | "....-10-31": [
100 | "Happy Halloween!"
101 | ]
102 | }
103 | }
104 | ```
105 |
106 | #### Example use with a cron entry
107 |
108 | ```javascript
109 | config: {
110 | compliments: {
111 | "48-50 16-18 * * 5,6": [
112 | "Happy Hour!", "Its a Party"
113 | ]
114 | }
115 | }
116 | ```
117 |
118 | this means, on Friday or Saturday, every week (\* (every) month/day) between
119 | 16:48-16:50, 17:48-17:50, and 18:48-18:50, the assigned messages will be used.
120 | note: like with the date only setting, if these are the only possible messages
121 | you want displayed, you need to set **specialDayUnique:true**
122 |
123 | As another example you could use this for scary messages ONLY between 8 and 9pm
124 | on Halloween evening:
125 |
126 | ```javascript
127 | config: {
128 | compliments: {
129 | "* 20-21 31 10 *": [
130 | "Boo!!"
131 | ]
132 | }
133 | }
134 | ```
135 |
136 | #### Example use with weather module
137 |
138 | ```javascript
139 | config: {
140 | compliments: {
141 | day_sunny: [
142 | "Today is a sunny day",
143 | "It's a beautiful day"
144 | ],
145 | snow: [
146 | "Snowball battle!"
147 | ],
148 | rain: [
149 | "Don't forget your umbrella"
150 | ]
151 | }
152 | }
153 | ```
154 |
155 | #### Default value:
156 |
157 | ```javascript
158 | config: {
159 | compliments: {
160 | anytime: [
161 | "Hey there sexy!"
162 | ],
163 | morning: [
164 | "Good morning, handsome!",
165 | "Enjoy your day!",
166 | "How was your sleep?"
167 | ],
168 | afternoon: [
169 | "Hello, beauty!",
170 | "You look sexy!",
171 | "Looking good today!"
172 | ],
173 | evening: [
174 | "Wow, you look hot!",
175 | "You look nice!",
176 | "Hi, sexy!"
177 | ],
178 | "....-01-01": [
179 | "Happy new year!"
180 | ]
181 | }
182 | }
183 | ```
184 |
185 | #### Multi-line compliments:
186 |
187 | Use `\n` to split compliment text into multiple lines, e.g.
188 | `First line.\nSecond line.` will be shown as:
189 |
190 | ```
191 | First line.
192 | Second line.
193 | ```
194 |
195 | ### External Compliment File
196 |
197 | You may specify an external file that contains the three compliment arrays. This
198 | is particularly useful if you have a large number of compliments and do not wish
199 | to crowd your `config.js` file with a large array of compliments. Adding the
200 | `remoteFile` variable will override an array you specify in the configuration
201 | file.
202 |
203 | This file must be straight JSON. Note that the array names need quotes around
204 | them ("morning", "afternoon", "evening", "snow", "rain", etc.).
205 |
206 | #### Example config/config.js of a Compliment File hosted on GitHub
207 |
208 | ```
209 | {
210 | module: 'compliments',
211 | position: 'middle_center',
212 | config: {
213 | remoteFile: 'https://gist.githubusercontent.com/user/e28a69665b8839f6e9a7acd6b4acc97d/raw/be1dee8f805a433f6ee0fa3556d1927da14e7799/compliments.json'
214 | }
215 | },
216 |
217 | ```
218 |
219 | (When copying the link from Github, you must use the 'Raw' link)
220 |
221 | #### Example compliments.json file:
222 |
223 | ```json
224 | {
225 | "anytime": ["Hey there sexy!"],
226 | "morning": [
227 | "Good morning, sunshine!",
228 | "Who needs coffee when you have your smile?",
229 | "Go get 'em, Tiger!"
230 | ],
231 | "afternoon": [
232 | "Hitting your stride!",
233 | "You are making a difference!",
234 | "You're more fun than bubble wrap!"
235 | ],
236 | "evening": [
237 | "You made someone smile today, I know it.",
238 | "You are making a difference.",
239 | "The day was better for your efforts."
240 | ]
241 | }
242 | ```
243 |
--------------------------------------------------------------------------------
/modules/configuration.md:
--------------------------------------------------------------------------------
1 | # Module Configuration
2 |
3 | The module configuration is used as part of the main configuration file. Please
4 | see [configuration](/configuration/introduction.md) for more information.
5 |
6 | | **Option** | **Description** |
7 | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
8 | | `module` | The name of the module. This can also contain the subfolder. Valid examples include `clock`, `default/calendar` and `custommodules/mymodule`. |
9 | | `position` | The location of the module in which the module will be loaded. The built in values are `top_bar`, `top_left`, `top_center`, `top_right`, `upper_third`, `middle_center`, `lower_third`, `bottom_left`, `bottom_center`, `bottom_right`, `bottom_bar`, `fullscreen_above`, and `fullscreen_below`. This field is optional but most modules require this field to set. (if not set, the module will not be shown, but will run the same) Check the documentation of the module for more information. Multiple modules with the same position will be ordered based on the order in the configuration file, top down. |
10 | | | Note:
if your implementation of MagicMirror wishes to use custom position values, they need to be used in **index.html** , and in the format
class="region newpos-a newpos-b"
MagicMirror will join the last two terms with an underscore to make a position value like
newpos-a_newpos-b
example: class="region top3 left"
the position will be "top3_left"
newpos_b is optional
class="region top3" would be valid and produce a position of "top3"
the new position values will be checked during MagicMirror startup and also in the configuration checker
npm run config:check
AND you have to have the appropriate css settings in custom.css for these new region values (top3 and left as used in the example above) |
11 | | `classes` | One or more additional CSS classes which will be set on the module, as a string of space-separated values. This field is optional. |
12 | | `header` | To display a header text above the module, add the header property. This field is optional. |
13 | | `hiddenOnStartup` | Set module as being hidden on startup. This field is optional. |
14 | | `disabled` | Set disabled to `true` to skip creating the module. This field is optional. |
15 | | `configDeepMerge` | Allow to merge with internal configuration in deep (Array and/with object). This field is optional (on developer choice generaly). |
16 | | `animateIn` | Special animate name when a module appears (see below) This field is optional. |
17 | | `animateOut` | Special animates name when a module should hide (see below) This field is optional. |
18 | | `config` | An object with the module configuration properties. Check the documentation of the module for more information. This field is optional, unless the module requires extra configuration. |
19 |
20 | ## Example
21 |
22 | ```javascript
23 | let config = {
24 | modules: [
25 | {
26 | module: "clock",
27 | position: "top_left",
28 | },
29 | {
30 | module: "compliments",
31 | position: "lower_third",
32 | },
33 | {
34 | module: "weather",
35 | position: "top_right",
36 | classes: "myclass1 myclass2",
37 | config: {
38 | weatherProvider: "openweathermap",
39 | type: "current",
40 | location: "New York",
41 | locationID: "5128581", //ID from http://bulk.openweathermap.org/sample/city.list.json.gz; unzip the gz file and find your city
42 | apiKey: "YOUR_OPENWEATHER_API_KEY",
43 | },
44 | },
45 | ],
46 | };
47 | ```
48 |
49 | ## Position
50 |
51 | The locations can be found in the following screenshot by their color:
52 |
53 | - `top_bar` and `bottom_bar` are light gray
54 | - `top_left` and `bottom_left` are red
55 | - `top_center` and `bottom_center` are blue
56 | - `top_right` and `bottom_right` are green
57 | - `upper_third` is yellow
58 | - `middle_center` is cyan
59 | - `lower_third` is magenta
60 |
61 | 
62 |
63 | Missing are the fullscreen_below and fullscreen_above as those cover the whole
64 | screen, one under everything else and the other above.
65 |
66 | All these regions will resize as needed.
67 |
68 | ## Animated
69 |
70 | (_Introduced in version: 2.25.0_)
71 |
72 | Animated feature allows to define an animation to a module
73 |
74 | - `animateIn`: When module appears
75 | - `animateOut`: When module should hide
76 |
77 | The whole of animation names are available [there](animate.md).
78 |
79 | ::: tip Preview of animations
80 |
81 | Check the [animate.css](https://animate.style/) library to see a preview of the
82 | animation name result
83 |
84 | :::
85 |
86 | ### Example with `newsfeed` module
87 |
88 | For this example, news will come from the left (`slideInLeft` animation), wait
89 | in the middle, and exit from the right (`slideOutRight` animation)
90 |
91 | 
92 |
93 | ```javascript
94 | {
95 | module: "newsfeed",
96 | position: "bottom_bar",
97 | animateIn: "slideInLeft",
98 | animateOut: "slideOutRight",
99 | config: {
100 | feeds: [
101 | {
102 | title: "New York Times",
103 | url: "https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml"
104 | }
105 | ],
106 | showSourceTitle: true,
107 | showPublishDate: true,
108 | broadcastNewsFeeds: true,
109 | broadcastNewsUpdates: true
110 | }
111 | },
112 | ```
113 |
--------------------------------------------------------------------------------
/modules/customcss.md:
--------------------------------------------------------------------------------
1 | # Custom CSS
2 |
3 | MagicMirror² comes with a default theme but it can be customized by placing a
4 | custom css-file in `css/custom.css`.
5 |
6 | ### Example
7 |
8 | One common request is to make the weather icons colorful, this can easily be
9 | achieved in the custom css, this makes the sunny weather icon yellow:
10 |
11 | ```css
12 | .wi-day-sunny {
13 | color: #ffff00;
14 | }
15 | ```
16 |
17 | MagicMirror² uses these weather icons:
18 | [https://erikflowers.github.io/weather-icons/](http://erikflowers.github.io/weather-icons/).
19 | On that page you can find what class name is used for the displayed icon and add
20 | it to your `custom.css`-file like in the example above.
21 |
22 | ### Target a specific module
23 |
24 | Each module has a class set for the div it resides in named after the module
25 | (including all the 3rd-party modules). As an example the
26 | [Clock-module](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/modules/default/clock)
27 | could be customized by using the class `.clock`.
28 |
29 | ### Help
30 |
31 | For questions and inspiration visit the
32 | [forum category](https://forum.magicmirror.builders/category/8/custom-css)
33 | dedicated to this.
34 |
--------------------------------------------------------------------------------
/modules/helloworld.md:
--------------------------------------------------------------------------------
1 | # Hello World
2 |
3 | The `helloworld` module is one of the default modules of the MagicMirror. It is
4 | a simple way to display a static text on the mirror.
5 |
6 | ## Using the module
7 |
8 | To use this module, add it to the modules array in the `config/config.js` file:
9 |
10 | ```javascript
11 | modules: [
12 | {
13 | module: "helloworld",
14 | position: "bottom_bar", // This can be any of the regions.
15 | config: {
16 | // See 'Configuration options' for more information.
17 | text: "Hello world!",
18 | },
19 | },
20 | ];
21 | ```
22 |
23 | ## Configuration options
24 |
25 | The following properties can be configured:
26 |
27 | | Option | Description |
28 | | ------ | ---------------------------------------------------------------------------------------------------- |
29 | | `text` | The text to display.
**Example:** `'Hello world!'`
**Default value:** `'Hello world!'` |
30 |
--------------------------------------------------------------------------------
/modules/introduction.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Introduction
3 | ---
4 |
5 | # Modules
6 |
7 | The following modules are installed by default.
8 |
9 | - [**Clock**](clock.md)
10 | - [**Calendar**](calendar.md)
11 | - [**Weather**](weather.md)
12 | - [**News Feed**](newsfeed.md)
13 | - [**Compliments**](compliments.md)
14 | - [**Hello World**](helloworld.md)
15 | - [**Alert**](alert.md)
16 |
17 | For more available modules, check out out the wiki page
18 | [MagicMirror² 3rd Party Modules](https://github.com/MagicMirrorOrg/MagicMirror/wiki/3rd-party-modules).
19 | If you want to build your own modules, check out the
20 | [MagicMirror² Module Development Documentation](/development/introduction.md)
21 | and don't forget to add it to the
22 | [wiki](https://github.com/MagicMirrorOrg/MagicMirror/wiki) and the
23 | [forum](https://forum.magicmirror.builders/category/7/showcase)!
24 |
--------------------------------------------------------------------------------
/modules/newsfeed.md:
--------------------------------------------------------------------------------
1 | # News Feed
2 |
3 | The `newsfeed ` module is one of the default modules of the MagicMirror. This
4 | module displays news headlines based on an RSS feed. Scrolling through news
5 | headlines happens time-based (`updateInterval`), but can also be controlled by
6 | sending news feed specific notifications to the module.
7 |
8 | ## Screenshot
9 |
10 | 
11 |
12 | ## Using the module
13 |
14 | ### Configuration
15 |
16 | To use this module, add it to the modules array in the `config/config.js` file:
17 |
18 | ```javascript
19 | modules: [
20 | {
21 | module: "newsfeed",
22 | position: "bottom_bar", // This can be any of the regions. Best results in center regions.
23 | config: {
24 | // The config property is optional.
25 | // If no config is set, an example calendar is shown.
26 | // See 'Configuration options' for more information.
27 |
28 | feeds: [
29 | {
30 | title: "New York Times",
31 | url: "https://www.nytimes.com/services/xml/rss/nyt/HomePage.xml",
32 | },
33 | {
34 | title: "BBC",
35 | url: "https://feeds.bbci.co.uk/news/video_and_audio/news_front_page/rss.xml?edition=uk",
36 | },
37 | ],
38 | },
39 | },
40 | ];
41 | ```
42 |
43 | ### Notifications
44 |
45 | #### Interacting with the module
46 |
47 | MagicMirror's
48 | [notification mechanism](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/modules#thissendnotificationnotification-payload)
49 | allows to send notifications to the `newsfeed` module. The following
50 | notifications are supported:
51 |
52 | | Notification Identifier | Description |
53 | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54 | | `ARTICLE_NEXT` | Shows the next news title (hiding the summary or previously fully displayed article) |
55 | | `ARTICLE_PREVIOUS` | Shows the previous news title (hiding the summary or previously fully displayed article) |
56 | | `ARTICLE_MORE_DETAILS` | When received the _first time_, shows the corresponding description of the currently displayed news title.
The module expects that the module's configuration option `showDescription` is set to `false` (default value).
When received a _second consecutive time_, shows the full news article in an IFRAME.
This requires that the news page can be embedded in an IFRAME, e.g. doesn't have the HTTP response header [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) set to e.g. `DENY`.
When received the _next consecutive times_, reloads the page and scrolls down by `scrollLength` pixels to paginate through the article. |
57 | | `ARTICLE_LESS_DETAILS` | Hides the summary or full news article and only displays the news title of the currently viewed news item. |
58 | | `ARTICLE_TOGGLE_FULL` | Toggles article in fullscreen. |
59 | | `ARTICLE_INFO_REQUEST` | Causes `newsfeed` to respond with the notification `ARTICLE_INFO_RESPONSE`, the payload of which provides the `title`, `source`, `date`, `desc` and `url` of the current news title. |
60 |
61 | #### Notifications sent by the module
62 |
63 | MagicMirror's
64 | [notification mechanism](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/modules#thissendnotificationnotification-payload)
65 | can also be used to send notifications from the current module to all other
66 | modules. The following notifications are broadcasted from this module:
67 |
68 | | Notification Identifier | Description |
69 | | ----------------------- | ------------------------------------------ |
70 | | `NEWS_FEED` | Broadcast the current list of news items. |
71 | | `NEWS_FEED_UPDATE` | Broadcasts the list of updates news items. |
72 |
73 | Note the payload of the sent notification event is ignored.
74 |
75 | #### Example
76 |
77 | The following example shows how the next news article title can be displayed on
78 | the MagicMirror.
79 |
80 | ```javascript
81 | this.sendNotification("ARTICLE_NEXT");
82 | ```
83 |
84 | #### `newsfeed` specific notification emitting modules
85 |
86 | The third party [MMM-Gestures](https://github.com/thobach/MMM-Gestures) module
87 | supports above notifications when moving your hand up, down, left or right in
88 | front of a gesture sensor attached to the MagicMirror. See module's readme for
89 | more details.
90 |
91 | ## Configuration options
92 |
93 | The following properties can be configured:
94 |
95 | | Option | Description |
96 | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97 | | `feeds` | An array of feed urls that will be used as source.
More info about this object can be found below.
**Default value:** `[{ title: "New York Times", url: "https://www.nytimes.com/services/xml/rss/nyt/HomePage.xml", encoding: "UTF-8" }]`
You can add `reloadInterval` option to set particular reloadInterval to a feed. |
98 | | `showAsList` | Display the news as a list.
**Possible values:** `true` or `false`
**Default value:** `false` |
99 | | `showSourceTitle` | Display the title of the source.
**Possible values:** `true` or `false`
**Default value:** `true` |
100 | | `showPublishDate` | Display the publish date of an headline.
**Possible values:** `true` or `false`
**Default value:** `true` |
101 | | `broadcastNewsFeeds` | Gives the ability to broadcast news feeds to all modules, by using `sendNotification()` when set to `true`, rather than `sendSocketNotification()` when `false`
**Possible values:** `true` or `false`
**Default value:** `true` |
102 | | `broadcastNewsUpdates` | Gives the ability to broadcast news feed updates to all modules
**Possible values:** `true` or `false`
**Default value:** `true` |
103 | | `showDescription` | Display the description of an item.
**Possible values:** `true` or `false`
**Default value:** `false` |
104 | | `showTitleAsUrl` | If set, the displayed title is a link to the article which is useful when running in a browser and you want to read this article.
**Possible values:** `true` or `false`
**Default value:** `false` |
105 | | `wrapTitle` | Wrap the title of the item to multiple lines.
**Possible values:** `true` or `false`
**Default value:** `true` |
106 | | `wrapDescription` | Wrap the description of the item to multiple lines.
**Possible values:** `true` or `false`
**Default value:** `true` |
107 | | `truncDescription` | Truncate description?
**Possible values:** `true` or `false`
**Default value:** `true` |
108 | | `lengthDescription` | How many characters to be displayed for a truncated description?
**Possible values:** `1` - `500`
**Default value:** `400` |
109 | | `hideLoading` | Hide module instead of showing LOADING status.
**Possible values:** `true` or `false`
**Default value:** `false` |
110 | | `reloadInterval` | How often does the content needs to be fetched? (Milliseconds)
**Possible values:** `1000` - `86400000`
**Default value:** `300000` (5 minutes) |
111 | | `updateInterval` | How often do you want to display a new headline? (Milliseconds)
**Possible values:**`1000` - `60000`
**Default value:** `10000` (10 seconds) |
112 | | `animationSpeed` | Speed of the update animation. (Milliseconds)
**Possible values:**`0` - `5000`
**Default value:** `2500` (2.5 seconds) |
113 | | `maxNewsItems` | Total amount of news items to cycle through. (0 for unlimited)
**Possible values:**`0` - `...`
**Default value:** `0` |
114 | | `ignoreOldItems` | Ignore news items that are outdated.
**Possible values:**`true` or `false`
**Default value:** `false` |
115 | | `ignoreOlderThan` | How old should news items be before they are considered outdated? (Milliseconds)
**Possible values:**`1` - `...`
**Default value:** `86400000` (1 day) |
116 | | `removeStartTags` | Some news feeds feature tags at the **beginning** of their titles or descriptions, such as _[VIDEO]_. This setting allows for the removal of specified tags from the beginning of an item's description and/or title.
**Possible values:**`'title'`, `'description'`, `'both'` |
117 | | `startTags` | List the tags you would like to have removed at the beginning of the feed item
**Possible values:** `['TAG']` or `['TAG1','TAG2',...]` |
118 | | `removeEndTags` | Remove specified tags from the **end** of an item's description and/or title.
**Possible values:**`'title'`, `'description'`, `'both'` |
119 | | `endTags` | List the tags you would like to have removed at the end of the feed item
**Possible values:** `['TAG']` or `['TAG1','TAG2',...]` |
120 | | `prohibitedWords` | Remove news feed item if one of these words is found anywhere in the title (case insensitive and greedy matching)
**Possible values:** `['word']` or `['word1','word2',...]` |
121 | | `scrollLength` | Scrolls the full news article page by a given number of pixels when a `ARTICLE_MORE_DETAILS` notification is received and the full news article is already displayed.
**Possible values:** `1` or `10000`
**Default value:** `500` |
122 | | `logFeedWarnings` | Log warnings when there is an error parsing a news article.
**Possible values:** `true` or `false`
**Default value:** `false` |
123 |
124 | The `feeds` property contains an array with multiple objects. These objects have
125 | the following properties:
126 |
127 | | Option | Description |
128 | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
129 | | `title` | The name of the feed source to be displayed above the news items.
This property is optional. |
130 | | `url` | The url of the feed used for the headlines.
**Example:** `'https://www.nytimes.com/services/xml/rss/nyt/HomePage.xml'` |
131 | | `encoding` | The encoding of the news feed.
This property is optional.
**Possible values:** `'UTF-8'`, `'ISO-8859-1'`, etc ...
**Default value:** `'UTF-8'` |
132 | | `useCorsProxy` | Uses the internal cors proxy to avoid cors errors.
This property is optional.
**Possible values:** `true` or `false`
**Default value:** `true` |
133 | | `ignoreOldItems` | Overrides the property defined for the module (see above) for the specific feed |
134 | | `ignoreOlderThan` | Overrides the property defined for the module (see above) for the specific feed |
135 |
--------------------------------------------------------------------------------
/modules/screenshots/animate.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/animate.gif
--------------------------------------------------------------------------------
/modules/screenshots/clock.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/clock.png
--------------------------------------------------------------------------------
/modules/screenshots/compliments.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/compliments.png
--------------------------------------------------------------------------------
/modules/screenshots/customEvents_transform_after.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/customEvents_transform_after.png
--------------------------------------------------------------------------------
/modules/screenshots/customEvents_transform_before.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/customEvents_transform_before.png
--------------------------------------------------------------------------------
/modules/screenshots/newsfeed.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/newsfeed.png
--------------------------------------------------------------------------------
/modules/screenshots/regions.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/regions.png
--------------------------------------------------------------------------------
/modules/screenshots/weather_current.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/weather_current.png
--------------------------------------------------------------------------------
/modules/screenshots/weather_forecast.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MagicMirrorOrg/MagicMirror-Documentation/691533aaaa1e272d194f5f60216e0751ba0bddb0/modules/screenshots/weather_forecast.png
--------------------------------------------------------------------------------
/modules/updatenotification.md:
--------------------------------------------------------------------------------
1 | # Update Notification
2 |
3 | The `updatenotification` module is one of the default modules of the
4 | MagicMirror. This will display a message whenever a new version of the
5 | MagicMirror application is available.
6 |
7 | ## Using the module
8 |
9 | To use this module, add it to the modules array in the `config/config.js` file:
10 |
11 | ```javascript
12 | modules: [
13 | {
14 | module: "updatenotification",
15 | position: "top_center", // This can be any of the regions.
16 | config: {
17 | // The config property is optional.
18 | // See 'Configuration options' for more information.
19 | },
20 | },
21 | ];
22 | ```
23 |
24 | ## Configuration options
25 |
26 | The following properties can be configured:
27 |
28 | | Option | Description |
29 | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30 | | `updateInterval` | How often do you want to check for a new version? This value represents the interval in milliseconds.
**Possible values:** Any value above `60000` (1 minute)
**Default value:** `600000` (10 minutes) |
31 | | `ignoreModules` | An array of module names that should not check for update.
**Example:** `["MMM-ExampleModule1", "MMM-ExampleModule2"]`.
You can exclude MagicMirror by adding "MagicMirror" to the array.
**Default value:** `[]` (empty array, no modules) |
32 | | `sendUpdatesNotifications` | Allow to broadcast update with **UPDATES** notification to other modules.
**Default value:** `false` |
33 | | `updates` | Array of updates modules commands.
**Default value:** `[]` (see bellow) |
34 | | `updateTimeout` | Maximum Update duration before cancel it.
**Default Value:** `120000` (2 minutes) |
35 | | `updateAutorestart` | Restart automaticaly MagicMirror² after update is done.
**Default Value:** `false` |
36 | | `useModulesFromConfig` | If `false` iterate over modules directory instead using modules defined in `config.js`.
**Default Value:** `true` |
37 |
38 | ### `updates` Array
39 |
40 | `updates` is an array of command for updating 3rd party modules modules
41 |
42 | It consists of an object containing the name of the module and the associated
43 | update command
44 |
45 | Sample:
46 |
47 | ```javascript
48 | modules: [
49 | {
50 | module: "updatenotification",
51 | position: "top_center", // This can be any of the regions.
52 | config: {
53 | updates: [
54 | // array of module update commands
55 | {
56 | // update of MMM-Test with embed npm script
57 | "MMM-Test": "npm run update",
58 | },
59 | {
60 | // update of MMM-OtherSample with "complex" process command
61 | "MMM-OtherSample":
62 | "rm -rf package-lock.json && git reset --hard && git pull && npm install",
63 | },
64 | {
65 | // update of MMM-OtherSample2 with git pull && npm install command
66 | "MMM-OtherSample2": "git pull && npm install",
67 | },
68 | {
69 | // update of MMM-OtherSample3 with a simple git pull
70 | "MMM-OtherSample3": "git pull",
71 | },
72 | ],
73 | },
74 | },
75 | ];
76 | ```
77 |
78 | Note: Don’t hesitate to ask the module developer for the ideal command to update
79 | their module.
80 |
81 | ## Developer notes
82 |
83 | ### Broadcast notifications (notifications send to modules)
84 |
85 | | Notification | Description | Requirement |
86 | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
87 | | UPDATES | When updates are available, an Array of updatable modules is sended.
This is the best way to update your own module! (a guide will be available soon)
Note: It will not include default modules and MagicMirror.
**Example:** `["MMM-MyOwnModule","MMM-Test"]` | `sendUpdatesNotifications: true` |
88 |
89 | ### Received notification (notifications send from modules)
90 |
91 | | Notification | Description |
92 | | ------------ | --------------------------------------------------- |
93 | | SCAN_UPDATES | Allow force scanning any updates from other modules |
94 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "version": "2.31.0",
3 | "devDependencies": {
4 | "@vuepress/bundler-vite": "^2.0.0-rc.21",
5 | "@vuepress/plugin-back-to-top": "^2.0.0-rc.94",
6 | "@vuepress/plugin-docsearch": "^2.0.0-rc.95",
7 | "@vuepress/plugin-google-analytics": "^2.0.0-rc.94",
8 | "@vuepress/theme-default": "^2.0.0-rc.95",
9 | "cspell": "^8.18.1",
10 | "prettier": "^3.5.3",
11 | "prettier-config-vuepress": "^5.0.0",
12 | "sass-embedded": "^1.86.3",
13 | "vue": "^3.5.13",
14 | "vuepress": "^2.0.0-rc.21"
15 | },
16 | "scripts": {
17 | "start": "npm run docs:dev",
18 | "docs:dev": "vuepress dev .",
19 | "docs:build": "vuepress build .",
20 | "lint": "prettier . --write",
21 | "test": "npm run test:format && npm run test:spelling",
22 | "test:format": "prettier . --check",
23 | "test:spelling": "cspell . --gitignore"
24 | }
25 | }
26 |
--------------------------------------------------------------------------------
10 |
11 | 
12 | 
13 |
14 | 
15 |
16 | 
32 |