color: #880000 created: 20140925193346003 modified: 20141128204032386 tags: Terminology title: Module type: text/vnd.tiddlywiki !Abstract A ''module'' in <> is a tiddler that contains executable [[JavaScript|http://en.wikipedia.org/wiki/JavaScript]] code. So <> modules always need to be implemented in ~JavaScript and there is no other programming language supported (at the time of this writing). In consequence, module tiddlers are those tiddlers with their `type` field set `application/javascript`. Oh ... pardon, that's [[ECMAScript|http://en.wikipedia.org/wiki/ECMAScript]] to be overly correct. But that's a complete story of its own. In this wiki, we stick to the ~JavaScript name as it is in so much widespread use. !Module Conventions There are quite a lot of different [[module types|Module Type]] in ~TiddlyWiki: for instance, macro modules, startup modules, wiki rules modules, just to name a few. ~TiddlyWiki's modules need to follow some simple conventions though. When a module gets activated (if it gets activated at all, see below for details) it is run in kind of its own sandbox environment so it cannot simply change the ~TiddlyWiki 5 core or other modules, except through well-defined extension mechanisms. This extension mechanism involves that modules can only export their functionality through an `exports` variable. Everything else is kept in the sandboxed environment set up especially for this particular module. Modules get activated only in the so-called [[boot phase|Boot Phase]] of a ~TiddlyWiki 5 instance. In consequence, there is no hot-plugging possible, such as updating a module in a live ~TiddlyWiki instance. Of course, as we've already hinted at above, this clean module concept now requires well-defined extension mechanisms. The downside is that this allows to extend ~TiddlyWiki only along the existing extension points. But ... the big, really big, upside of all this is that there is no more function reference hooking and rewiring needed, as was often necessary in ~TiddlyWiki Classic. !Third Flow Use of Modules The <> plugin itself defines the following modules to make developing plugins easier: <> !Technical !!Module Basics Modules are all those tiddlers that are of type `application/javascript` -- that is, their tiddler field `type` is set to this specific value. The `module-type` field then specifies the particular type of module. One of the big changes that ~TiddlyWiki 5 introduces is it incredible extensibility through these modules. For instance, modules not only can add macros but also extensions to the standard wiki parser, and they can even add in new parsers. Next, we can easily drop in new filters. More behind the scenes are such specialized modules as sync adaptors and new commands to be used on the command line. See the ~TiddlyWiki 5 documentation for details about [[available module types||http://tiddlywiki.com/#ModuleType]]. !!Bringing Modules to Life Creating a module tiddler doesn't automatically make its JavaScript code become activated. There always must be code that explicitly activates all modules of a certain type. For instance, the deal for several well-defined module types is that they get activated only when a specific [[startup]] module runs, the [[$:/core/modules/startup/load-modules.js]] startup module. Most modules get activated only during or at the end of the so-called [[boot phase|Boot Phase]] of a ~TiddlyWiki 5 instance. In consequence, there is no hot-plugging possible, such as updating a module in a live ~TiddlyWiki instance. !Organizing Modules While not strictly necessary, it is helpful to organize module titles so that they reflect the module type. One way is to put all modules below their own `modules` folder, as the ~TiddlyWiki 5 sources do. This is especially useful when maintaing a lot of other tiddler files that are not modules. However, when developing plugins using the <> this results in even longer tiddler titles without really improving tiddler organization. Personally, I don't care whether a tiddler is a module, but I care about its purpose, such as a //command// or //filter//. Thus, the following slightly flattened title organization may be of better help when developing with the <>. It simply indicates the functional group immediately in the first level of hierarchy inside the plugin itself: `$:/plugins/`//Publisher//`/`//Plugin// -- it is custom to put plugins into the system namespace and to specify also the publisher in addition to the plugin name. This reduces the chance of plugin name collisions. :...`/commands` :...`/filters` ::`/all` ::`/is` :...`/macros` :...`/parsers` :...`/templates` :...`/styles` :...`/syncadaptors` :...`/wikiparser` :...`/widgets` Of course, the above is nothing more than a suggestion. You are free to use whatever naming scheme you like.