TiddlyWiki5/tiddlywiki5/tiddlers/MacroInternals.tid

title: MacroInternals

! Macro Fields

Macros are implemented as conventional JavaScript modules that export a single variable called `macro` that contains these fields:

|!Field Name |!Description |
|`name` |The name of the macro |
|`params` |A hashmap of the parameters accepted by the macro (see below) |
|`events` |An optional hashmap of event handling functions (see below) |
|`execute` |The macro rendering function (see below) |
|`refreshInDom` |The optional macro rerendering function (see below) |
|`dependentAll` |True if the macro needs access to all available tiddlers |

! Macro Parameters
The `params` hashmap provides the following fields about each parameter:

|!Param Field Name |!Description |
|`byName` |Provided if the parameter should be referenced by name. The value can be `true` or `"default"` to indicate that anonymous parameters are acceptable |
|`byPos` |Provided if the parameter should be referenced by its numerical position (0-based) |
|`type` |The type of the parameter, either `text` or `tiddler` (used for dependency tracking) |
|`skinny` |True if the parameter is only dependent on the skinny fields of the target tiddler. The default is `false` which means that the target tiddler is treated as a fat dependency |

! Macro Rendering
The `execute` function should prepare the macro output. It is invoked with `this` pointing to the MacroNode object representing this macro invocation.

!Macro Rerendering
The `refreshInDom` function is called with the following parameters:

|!Param Name |!Description |
|`changes` |Hashmap of `{title: "created|modified|deleted"}` |

!Macro Event Handlers
Event handlers are called with the following parameters:

|!Param Name |!Description |
|`event` |The DOM node containing the existing rendering of the macro |

Event handlers should return `false` if they handle the event (and generally should also call `event.preventDefault()`), and `true` if they do not.