diff --git a/.vuepress/config.js b/.vuepress/config.js index d222fed3..77e4bf67 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -70,6 +70,7 @@ export default { "/module-development/introduction.md", "/module-development/core-module-file.md", "/module-development/node-helper.md", + "/module-development/rendering.md", "/module-development/helper-methods.md", "/module-development/logger.md", "/module-development/notifications.md", @@ -118,4 +119,3 @@ export default { }), ], }; - diff --git a/module-development/core-module-file.md b/module-development/core-module-file.md index b7b037c1..8ea1737f 100644 --- a/module-development/core-module-file.md +++ b/module-development/core-module-file.md @@ -205,6 +205,9 @@ starts, or because your module asked a refresh using `this.updateDom()`), the system calls the getDom method. This method should therefore return a dom object. +Read more about Rendering Components +[in the Rendering Component documentation](./rendering.md). + **Example:** ```js @@ -228,6 +231,9 @@ data to the template with `getTemplateData`. An example of a default module that uses this method is [newsfeed](https://github.com/MagicMirrorOrg/MagicMirror/blob/master/modules/default/newsfeed/newsfeed.js). +Read more about Rendering Components +[in the Rendering Component documentation](./rendering.md). + **Example:** ```js diff --git a/module-development/rendering.md b/module-development/rendering.md new file mode 100644 index 00000000..d9dc4ecc --- /dev/null +++ b/module-development/rendering.md @@ -0,0 +1,107 @@ +# Rendering Component + +There are two main approaches to rendering your component. Procedurally +generating a Dom object with `getDom`, or using the built in Nunjucks templating +engine. + +With both approaches, rendering is first triggered when the module is first +loaded. When your module's data changes, you can call +[`this.updateDom()`](/module-development/core-module-file.md#thisupdatedomsspeed) +to trigger a re-render. + +## Using `getDom` + +The `getDom` method is called by MagicMirror whenever it needs to update +information on the screen. This method should return an HTML +[Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) which +contains all the information you would like to display. + +**Example:** + +```js +getDom: function() { + const wrapper = document.createElement("div"); + wrapper.innerHTML = 'Hello world!'; + return wrapper; +} +``` + +## Using Nunjucks Templates + +If `getDom` is not overridden, MagicMirror will try and render a +[Nunjucks](https://mozilla.github.io/nunjucks/) template from `getTemplate`. + +Nunjucks is a templating language for JavaScript. You can read more about the +syntax in the +[Nunjucks Documentation](https://mozilla.github.io/nunjucks/templating.html). + +### Templates and Data + +Templates are rendered by calling `getTemplate` to get the path to the template +and `getTemplateData` to get the data used in the template. + +**Example:** + +`MMM-MyModule.js` + +```js +getTemplate: function() { + return "MMM-MyModule.njk"; +}, + +getTemplateData: function() { + return { + list: ["item 1", "item 2", "item 3"], + }; +} +``` + +`MMM-MyModule.njk` + +```nunjucks +