A module for MagicMirror² that displays XKCD comic strips. I created this version since I wanted to have more control than with the already existing modules [1] [2] and have a way to interact with it's content.
Features:
- sequences
- randomness
- events for user interactions
- persistence
- supports multiple module instances
- supports multiple mirror instances, controlled by a single server
Just navigate to the modules
directory of your MagicMirror² installation and clone this repository.
git clone https://github.com/shin10/MMM-FF-XKCD.git
Example:
{
module: "MMM-FF-XKCD",
position: "bottom",
hiddenOnStartup: true,
config: {
header: "xkcd",
updateInterval: 1 * 60 * 1000,
grayscale: false,
inverted: true,
imageMaxWidth: null,
imageMaxHeight: null,
showTitle: true,
showDate: true,
showAltText: true,
showNum: true,
initialComic: "random",
sequence: "default",
updateOnSuspension: true,
events: {
COMIC_FIRST: "COMIC_FIRST",
COMIC_LATEST: "COMIC_LATEST",
ARTICLE_PREVIOUS: "COMIC_PREVIOUS",
ARTICLE_NEXT: "COMIC_NEXT",
COMIC_RANDOM: null
}
}
}
Option | Type | Default | Description |
---|---|---|---|
header |
string |
"xkcd" |
The header text. |
initialComic |
string |
"latest" |
Sets the comic on startup to be the "first" , "latest" , "random" , or a specific one by id (int ). |
sequence |
string |
"random" |
The direction to loop through the comic strips. null /"default" , "reverse" , "random" . |
updateInterval |
int |
3600000 (1 hour) |
The duration of the update interval in ms or null . |
updateOnSuspension |
bool |
null |
When to update the image. null , false or true . Further explanations below. |
grayscale |
bool |
false |
Reduce the colors to shades of gray. |
inverted |
bool |
true |
Invert the colors of the comic strip. |
imageMaxWidth |
string |
null |
Maximum width of the comic strip in any valid css unit like px , % , vw , vmin ... |
imageMaxHeight |
string |
null |
Maximum height of the comic strip in any valid css unit like px , % , vh , vmin ... |
showTitle |
string |
true |
Show/hide the title of the current comic strip. |
showDate |
string |
true |
Show/hide the date of the current comic strip. |
showAltText |
string |
true |
Show/hide the alt-text of the current comic strip. |
showNum |
string |
true |
Show/hide the id of the current comic strip. |
animationSpeed |
string |
1000 |
The duration of the page transition. |
events |
object |
A filter and list of event constants to remap if necessary. | |
events.sender |
string /array |
undefined |
Filter events to those dispatched by given module ids. |
persistence |
string |
null | Save current position in sequence. null , "electron" , "client" , "server" . See further explanations below. |
persistenceId |
string |
null | The localStorage key or fs filename to save the data to. |
persistencePath |
string |
null | The directory used for persistent data on the servers file system. Will fall back to "$MODULE_PATH/.store" |
These two parameters work together. The updateInterval
is used to set the minimal amount of time the displayed item has to exist, before it will be replaced by the next. When this actually will take place depends on the value of updateOnSuspension
.
If updateOnSuspension
is set to true
the item will wait till the interval timer fired and the module goes to the background. If set to false
the updateInterval
has to elapse while the item is in background and will replace the item when the module is shown again.
If updateOnSuspension
is set to null
the content will be replaced whenever the timer is done; visible or not.
If updateInterval
is set to null
the item won't be updated by the module. Instead you'll have to dispatch one of the events listed above.
The following events are supported:
- COMIC_FIRST
- COMIC_LATEST
- COMIC_PREVIOUS
- COMIC_NEXT
- COMIC_RANDOM
For ease of use they can be remapped in the events
object to custom strings. Refer to the example config above.
Events will be ignored if the module is currently hidden.
If the mirror will shut down regularly it might be desireable to save the current position in your sequence. Depending on your scenario and hardware setup the best place to save the data will be either on client or server-side.
If you have only one client it's probably the best idea to set persistence
to "electron"
.
"client"
will save the data to any browsers instance localStorage. A good default if you have only one MM² screen.
"electron"
will save the data to the electron client's localStorage but not to other browser instances. This comes in handy if you open the mirror parallel on another machine for development and want to avoid unexpected behaviour.
"server"
will save the data to your servers file system. This might be the best option if you're running multiple screens for one server instance. File system access however is dangerous if you don't know what you're doing. Use at own risk!
"persistenceId"
: The localStorage key or fs filename to save the data to. It defaults to the module identifier provided by MM² automatically to support multiple instances. It's perfectly fine to leave it that way, but if you're currently experimenting with the config and module instances are changing their position within the modules array of the config.js
file, it might be better to set this manually.
"persistencePath"
"./modules/MMM-FF-XKCD/.store"
only used by fs
. It might be important to customize this to a mounted directory if you are running MM² in a containerized environment like docker.