Merge pull request #2219 from sukima/feature/babel-plugins

Using ES2016 for Writing Plugins HowTo Documentation
2024-12-25 17:40:29 +00:00 · 2016-02-11 09:36:35 +00:00 · 2016-02-11 09:36:35 +00:00 · a19b4eeeed
commit a19b4eeeed
parent c61364f46a f79856a6d7
2 changed files with 259 additions and 0 deletions
--- a/editions/tw5.com/tiddlers/howtos/Adding
+++ b/editions/tw5.com/tiddlers/howtos/Adding
@ -0,0 +1,65 @@
+modified: 20160112175006000
+created: 20160112025328000
+title: Adding Babel Polyfill to TiddlyWiki
+tags: documenting Concepts
+type: text/vnd.tiddlywiki
+
+Not all browsers support the latest features of ES2015. The Babel project offers a polyfill that can be included into your TiddlyWiki so those features can be available to your plugins. To do this you will need a copy of the polyfill source.
+
+You can obtain the source either through <<.def "npm">> or downloaded/saved. See the [[Babel Polyfill documentation|https://babeljs.io/docs/usage/polyfill/]] for specific information on installing it.
+
+In your TiddlyWiki editions folder make sure you have a `plugins/babel-polyfill` folder. Then create the `plugins/babel-polyfill/plugin.info` file with the following in it:
+
+```json
+{
+  "title": "$:/plugins/babel/babel-polyfill",
+  "description": "Babel Polyfills for ES2015 support",
+  "author": "Your Name Here",
+  "core-version": ">=5.0.0"
+}
+```
+
+Create the folder `plugins/babel-polyfill/files` folder. Then create the `plugins/babel-polyfill/files/tiddlywiki.files` file with the following in it:
+
+```json
+{
+  "tiddlers": [
+    {
+      "file": "polyfill.min.js",
+      "fields": {
+        "title": "$:/plugins/babel/babel-polyfill/polyfill.min.js",
+        "type": "application/javascript",
+        "module-type": "library",
+        "global-module": "true"
+      }
+    }
+  ]
+}
+```
+
+Now copy the `polyfill.min.js` you downloaded/saved.
+
+<<.tip "If you downloaded this via ''npm'' then it would be available in `./node_modules/babel-polyfill/dist/polyfill.min.js`.">>
+
+Lastly you need a initializer so create the `plugins/babel-polyfill/plugin.js` file with the following in it:
+
+```javascript
+/*\
+title: $:/plugins/babel/babel-polyfill/plugin.js
+type: application/javascript
+module-type: startup
+
+Load the babel-polyfill library on startup
+
+\*/
+
+exports.startup = function() {
+  $tw.modules.execute('$:/plugins/babel/babel-polyfill/polyfill.min.js');
+}
+```
+
+<<.warning "Because the polyfill is meant to be used in the browser we need to conditionally load the library which ES2016 doesn't allow. This is why it is written using TiddlyWiki's dependency resolver instead of using ES2015 `import` statements.">>
+
+Now all the //runtime// ES2015 features are available like using `Promise` in your plugin code.
+
+See [[Using ES2016 for Writing Plugins]] on how to use the ES2015 //syntax// for your plugin code.
--- a/editions/tw5.com/tiddlers/howtos/Using
+++ b/editions/tw5.com/tiddlers/howtos/Using
@ -0,0 +1,194 @@
+modified: 20160112175004000
+created: 20160111034749658
+tags: documenting Concepts
+title: Using ES2016 for Writing Plugins
+type: text/vnd.tiddlywiki
+
+With the advent of ES2015 (also known as ES6) and the availability of [[Babel.js|http://babeljs.io/]] plugin developers can leverage ES2015 when writing TiddlyWiki plugins. Understanding the nuances between TiddlyWiki's module sandbox and how Babel compiles it's output ready for a module system like ~CommonJS/AMD.
+
+Please understand how the PluginMechanism works since this is all about writing a plugin using Babel to compile the output that will be included in the final TiddlyWiki (for example [[TiddlyWiki on Node.js]]).
+
+!! Installing and Configuring Babel
+
+You can install Babel using
+
+```
+$ npm install --global babel-cli babel-presets-es2015
+```
+
+If your developing the plugin for inclusion to the npm registry (or for convenience) you can avoid the global install and save it to the local `package.json` file with
+
+```
+$ npm install --save-dev babel-cli babel-presets-es2015
+```
+
+Inside your plugin project edit the file `.babelrc` and enter the following:
+
+```json
+{
+  "presets": [
+    "es2015"
+  ]
+}
+```
+
+<<.tip "I found it easier to manage my plugins as if they were ''npm'' modules complete with a `package.json` that compiles the output via `npm run build`. See [[npm-scripts documentation|https://docs.npmjs.com/misc/scripts]] for details.">>
+
+!! Compiling the Output
+
+Pick a folder to store the ES2015 JavaScript and a folder to output the TiddlyWiki ready JavaScript. In this example I will use `src` and `lib` respectively. With Babel installed and working I can compile all the JavaScript in the `src` folder to the `lib` folder by running this command:
+
+```
+$ babel src -d lib
+```
+
+<<.warning "Babel will //not// copy over non-JavaScript files. It is up to the developer to include all the supporting files themselves. Babel only converts the ~JavaScript files (ending in `.js`) from the `src` folder to the `lib` folder.">>
+
+!! Imports and Exports
+
+In a plugin written pre-ES2015 one would `require` a module through TiddlyWiki like so:
+
+```javascript
+var Widget = require('$:/core/modules/widgets/widget.js').widget;
+```
+
+But in ES2015 the following would look like:
+
+```javascript
+import { widget as Widget } from '$:/core/modules/widgets/widget.js';
+```
+
+Conveniently when Babel compiles this it will essentially output the same JavaScript as the first pre-ES2016 code.
+
+Also, in ES2016 you are required to declare your imports at the beginning and can not dynamically `require` things. This means you can not have an `import` statement in an if block or in a function. If that functionality is desired then you will have to go back to using the `require()` statement directly. But conciser that by doing so that you may be missing an oppertunity to make your code cleaner and better.
+
+Exporting is the same thing. Instead of assigning to a property of the `exports` variable you use the `export` keyword:
+
+```javascript
+export { MyWidget as mywidget };
+```
+
+<<.tip "It is illegal JavaScript to export with a name that is not an identifier even though it is ok to use a non-identifier (string) as a property key. What this means is if you want a widget to have a dash in it then you have to revert to using the `exports['my-widget'] = MyWidget;` syntax.">>
+
+It is important to understand that in ES2016 the ''default'' export is not supported in TiddlyWiki. This is mostly because the core code expects specific properties to be attached to the `exports` variable. Bable's `export` conversion plays well with this //except// with the default export.
+
+!! Classes
+
+In the example of a widget ES2016 plays well with class inheritance. To contrast the typical Widget definition would look something like this:
+
+```javascript
+function MyWidget() {
+  Widget.call(this);
+}
+MyWidget.prototype = new Widget();
+MyWidget.prototype.render = function(parent, nextSibling) {…};
+// And so on…
+```
+
+With classes this ceremony can be tightened up:
+
+```javascript
+class MyWidget extends Widget {
+  render(parent, nextSibling) {…}
+  // And so on…
+}
+```
+
+With classes one //could// eliminate much of the `Widget.execute()` cruft using <<.def "getters">>. I found this to be more readable then the typical mass assignment to `this`. It gave me the added benefit of allowing calculations in properties that normally would have conflated the `execute()` method. For example developing a compound property like so:
+
+```javascript
+class NameWidget extends Widget {
+  get title() { return this.getAttribute('title'); }
+  get firstName() { return this.getAttribute('first'); }
+  get lastName() { return this.getAttribute('last'); }
+  get fullName() { return `${this.title}. ${this.firstName} ${this.lastName}`; }
+}
+```
+
+!!! Non Class Modules
+
+For non class modules you can use the `export` keyword. Here is a simple [[Startup Module|ModuleType]]:
+
+```javascript
+export function startup() {
+  // Do stuff here
+}
+```
+
+Or in the case of a [[Macro|http://tiddlywiki.com/dev/#JavaScript%20Macros]]:
+
+```javascript
+export const name = 'my-macro';
+export const params = {};
+export function run() {…}
+```
+
+!! Polyfills
+
+ES2015 comes with some features that are part of the JavaScript core objects. These are not supported by all browsers. To use these features in [[most browsers|BrowserCompatibility]] you will need a <<.def "polyfill">>. Babel has a polyfill package that you can include. See [[Adding Babel Polyfill to TiddlyWiki]] for how to accomplish this.
+
+!! Example
+
+Here is an example ES2015 plugin/widget that will show the time and update it:
+
+```javascript
+
+/*\
+title: $:/plugins/sukima/clock-widget.js
+type: application/javascript
+module-type: widget
+
+A updating time stamp
+
+\*/
+import { widget as Widget } from '$:/core/modules/widgets/widget.js';
+
+class ClockWidget extends Widget {
+  constructor(parseTreeNode, options) {
+    super(parseTreeNode, options);
+    this.logger = new $tw.utils.Logger('clock-widget');
+  }
+
+  render(parent, nextSibling) {
+    if (!$tw.browser) { return; }
+    this.logger.log('Rendering clock DOM nodes');
+    this.computeAttributes()
+    this.parentDomNode = parent;
+    this.domNode = $tw.utils.domMaker('div', {class: 'tc-clock-widget'});
+    parent.insertBefore(this.domNode, nextSibling);
+    this.tick();
+  }
+
+  tick() {
+    this.logger.log('Tick!');
+    if (!document.contains(this.domNode)) {
+      // Apparently the widget was removed from the DOM. Do some clean up.
+      return this.stop();
+    }
+    this.start();
+    this.domNode.innerHTML = this.dateString;
+  }
+
+  start() {
+    if (!this.clockTicker) {
+      this.logger.log('Starting clock');
+      this.clockTicker = setInterval(this.tick.bind(this), 1000);
+    }
+  }
+
+  stop() {
+    this.logger.log('Stopping clock');
+    clearInterval(this.clockTicker);
+    this.clockTicker = null;
+  }
+
+  get dateString() {
+    const format = 'DDth MMM YYYY at hh12:0mm:0ss am';
+    return $tw.utils.formatDateString(new Date(), format);
+  }
+}
+
+export { ClockWidget as clock };
+```
+
+<<.tip "Adding an extra space at the top causes Babel's output the preamble tiddler comment without any obscene indenting. Although it doesn't affect TiddlyWiki any, when reading the output it can be confusing when the tiddler information is rendered off the screen to the right.">>