树莓派魔镜项目源代码

# MagicMirror² Module Development Documentation This document describes the way to develop your own MagicMirror² modules. Table of Contents: - Module structure - Files - The Core module file: modulename.js - Available module instance properties - Subclassable module methods - Module instance methods - Visibility locking - The Node Helper: node_helper.js - Available module instance properties - Subclassable module methods - Module instance methods - MagicMirror Helper Methods - Module Selection - MagicMirror Logger --- ## General Advice As MagicMirror has gained huge popularity, so has the number of available modules. For new users and developers alike, it is very time consuming to navigate around the various repositories in order to find out what exactly a certain modules does, how it looks and what it depends on. Unfortunately, this information is rarely available, nor easily obtained without having to install it first. Therefore **we highly recommend you to include the following information in your README file.** - A high quality screenshot of your working module - A short, one sentence, clear description what it does (duh!) - What external API's it depend on, including web links to those - Wheteher the API/request require a key and the user limitations of those. (Is it free?) Surely this also help you get better recognition and feedback for your work. ## Module structure All modules are loaded in the `modules` folder. The default modules are grouped together in the `modules/default` folder. Your module should be placed in a subfolder of `modules`. Note that any file or folder your create in the `modules` folder will be ignored by git, allowing you to upgrade the MagicMirror² without the loss of your files. A module can be placed in one single folder. Or multiple modules can be grouped in a subfolder. Note that name of the module must be unique. Even when a module with a similar name is placed in a different folder, they can't be loaded at the same time. ### Files - **modulename/modulename.js** - This is your core module script. - **modulename/node_helper.js** - This is an optional helper that will be loaded by the node script. The node helper and module script can communicate with each other using an intergrated socket system. - **modulename/public** - Any files in this folder can be accesed via the browser on `/modulename/filename.ext`. - **modulename/anyfileorfolder** Any other file or folder in the module folder can be used by the core module script. For example: *modulename/css/modulename.css* would be a good path for your additional module styles. ## The Core module file: modulename.js This is the script in which the module will be defined. This script is required in order for the module to be used. In it's most simple form, the core module file must contain: ````javascript Module.register("modulename",{}); ```` Of course, the above module would not do anything fancy, so it's good to look at one of the simplest modules: **helloworld**: ````javascript //helloworld.js: Module.register("helloworld",{ // Default module config. defaults: { text: "Hello World!" }, // Override dom generator. getDom: function() { var wrapper = document.createElement("div"); wrapper.innerHTML = this.config.text; return wrapper; } }); ```` As you can see, the `Module.register()` method takes two arguments: the name of the module and an object with the module properties. ### Available module instance properties After the module is initialized, the module instance has a few available module properties: | Instance Property | Type | Description | |:----------------- |:---- |:----------- | | `this.name` | String | The name of the module. | | `this.identifier` | String | This is a unique identifier for the module instance. | | `this.hidden` | Boolean | This represents if the module is currently hidden (faded away). | | `this.config` | Boolean | The configuration of the module instance as set in the user's `config.js` file. This config will also contain the module's defaults if these properties are not over-written by the user config. | | `this.data` | Object | The data object contain additional metadata about the module instance. (See below) | The `this.data` data object contain the follwoing metadata: - `data.classes` - The classes which are added to the module dom wrapper. - `data.file` - The filename of the core module file. - `data.path` - The path of the module folder. - `data.header` - The header added to the module. - `data.position` - The position in which the instance will be shown. #### `defaults: {}` Any properties defined in the defaults object, will be merged with the module config as defined in the user's config.js file. This is the best place to set your modules's configuration defaults. Any of the module configuration properties can be accessed using `this.config.propertyName`, but more about that later. #### `requiresVersion:` *Introduced in version: 2.1.0.* A string that defines the minimum version of the MagicMirror framework. If it is set, the system compares the required version with the users version. If the version of the user is out of date, it won't run the module. Make sure to also set this value in the Node helper. **Note:** Since this check is introduced in version 2.1.0, this check will not be run in older versions. Keep this in mind if you get issue reports on your module. Example: ````javascript requiresVersion: "2.1.0", ```` ### Subclassable module methods #### `init()` This method is called when a module gets instantiated. In most cases you do not need to subclass this method. #### `loaded(callback)` *Introduced in version: 2.1.1.* This method is called when a module is loaded. Subsequent modules in the config are not yet loaded. The `callback` function MUST be called when the module is done loading. In most cases you do not need to subclass this method. **Example:** ````javascript loaded: function(callback) { this.finishLoading(); Log.log(this.name + ' is loaded!'); callback(); } ```` #### `start()` This method is called when all modules are loaded an the system is ready to boot up. Keep in mind that the dom object for the module is not yet created. The start method is a perfect place to define any additional module properties: **Example:** ````javascript start: function() { this.mySpecialProperty = "So much wow!"; Log.log(this.name + ' is started!'); } ```` #### `getScripts()` **Should return: Array** The getScripts method is called to request any additional scripts that need to be loaded. This method should therefore return an array with strings. If you want to return a full path to a file in the module folder, use the `this.file('filename.js')` method. In all cases the loader will only load a file once. It even checks if the file is available in the default vendor folder. **Example:** ````javascript getScripts: function() { return [ 'script.js', // will try to load it from the vendor folder, otherwise it will load is from the module folder. 'moment.js', // this file is available in the vendor folder, so it doesn't need to be available in the module folder. this.file('anotherfile.js'), // this file will be loaded straight from the module folder. 'https://code.jquery.com/jquery-2.2.3.min.js', // this file will be loaded from the jquery servers. ] } ```` **Note:** If a file can not be loaded, the boot up of the mirror will stall. Therefore it's advised not to use any external urls. #### `getStyles()` **Should return: Array** The getStyles method is called to request any additional stylesheets that need to be loaded. This method should therefore return an array with strings. If you want to return a full path to a file in the module folder, use the `this.file('filename.css')` method. In all cases the loader will only load a file once. It even checks if the file is available in the default vendor folder. **Example:** ````javascript getStyles