TiddlyWiki5/editions/tw5.com/tiddlers/dev/JavaScript Macros.tid

created: 20131211222303769
modified: 20140424130146763
tags: dev
title: JavaScript Macros
type: text/vnd.tiddlywiki

Macros can be implemented as JavaScript modules as well as via the [[wikitext syntax|Macros in WikiText]].

! Overview

JavaScript macros are modules with their ''module-type'' field set to ''macro''. They must export these three properties:

* ''name'': A string giving the name used to invoke the macro
* ''params'': An array of objects with the following properties:
** //name//: name of the parameter
** //default//: (optional) default value for the parameter
* ''run'': Function called when the macro requires evaluation. The parameters are pulled from the macro call and arranged according to the ''params'' array. The ''run'' function should return the string value of the macro. When invoked, `this` points to the widget node invoking the macro.

Note that if the ''params'' array is missing or blank, then all the supplied parameters are passed to the `run()` method.

! Writing JavaScript macros

There are several JavaScript macros built into the core which can serve as a jumping off point for your own macros:

https://github.com/Jermolene/TiddlyWiki5/tree/master/core/modules/macros

Note that JavaScript macros work on both the client and the server, and so do not have access to the browser DOM.

!! Macro Behaviour

Macros are just used to return a chunk of wikitext for further processing. They should not make modifications to tiddlers in the wiki store. The reason is that you cannott control when the macro is called; it may be called repeatedly as part of refresh processing. So it is important that macros do not have any other side effects beyond generating their text.
Docs updates 2013-12-12 09:48:08 +00:00			`created: 20131211222303769`
Update JS macro docs 2014-04-24 10:08:22 +00:00			`modified: 20140424130146763`
Docs updates 2013-12-12 09:48:08 +00:00			`tags: dev`
			`title: JavaScript Macros`
			`type: text/vnd.tiddlywiki`

			`Macros can be implemented as JavaScript modules as well as via the [[wikitext syntax\|Macros in WikiText]].`

Update JavaScript Macro docs 2014-01-20 13:02:12 +00:00			`! Overview`

Docs updates 2013-12-12 09:48:08 +00:00			`JavaScript macros are modules with their ''module-type'' field set to ''macro''. They must export these three properties:`

			`* ''name'': A string giving the name used to invoke the macro`
			`* ''params'': An array of objects with the following properties:`
			`** //name//: name of the parameter`
			`** //default//: (optional) default value for the parameter`
			* ''run'': Function called when the macro requires evaluation. The parameters are pulled from the macro call and arranged according to the ''params'' array. The ''run'' function should return the string value of the macro. When invoked, `this` points to the widget node invoking the macro.

			Note that if the ''params'' array is missing or blank, then all the supplied parameters are passed to the `run()` method.
Update JavaScript Macro docs 2014-01-20 13:02:12 +00:00
			`! Writing JavaScript macros`

			`There are several JavaScript macros built into the core which can serve as a jumping off point for your own macros:`

			`https://github.com/Jermolene/TiddlyWiki5/tree/master/core/modules/macros`

			`Note that JavaScript macros work on both the client and the server, and so do not have access to the browser DOM.`
Update JS macro docs 2014-04-24 10:08:22 +00:00
			`!! Macro Behaviour`

			`Macros are just used to return a chunk of wikitext for further processing. They should not make modifications to tiddlers in the wiki store. The reason is that you cannott control when the macro is called; it may be called repeatedly as part of refresh processing. So it is important that macros do not have any other side effects beyond generating their text.`