TiddlyWiki5/editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid

caption: macrocall
created: 20131024141900000
modified: 20200928102843275
tags: Widgets
title: MacroCallWidget
type: text/vnd.tiddlywiki

! Introduction

The macro call widget provides a more flexible alternative syntax for invoking macros compared to the usual `<<macroname>>` syntax documented in [[Macros in WikiText]].

For example, a macro called `italicise` that takes a single parameter called `text` would usually be invoked like this:

```
<<italicise "Text to be made into italics">>
<<italicise text:"Text to be made into italics">>
```

The same macro can be invoked using the macro call widget like this:

```
<$macrocall $name="italicise" text="Text to be made into italics"/>
<$macrocall $name="italicise" text={{Title of tiddler containing text to be italicised}}/>
<$macrocall $name="italicise" text=<<textMaker "Another macro to generate the text to be italicised">>/>
```

The advantages of the widget formulation are:

* Macro parameters are specified as widget attributes, thus allowing indirection via `{{title!!field}}`, `<<macroname>>` or `{{{filter}}}`
* The output format can be chosen from several options:
** `text/html` wikifies the result of the macro
** `text/plain` wikifies the result of the macro and then extracts the plain text characters (ie. ignoring HTML tags)
** <<.from-version "5.1.23">> `text/raw` returns the result of the macro, without wikification

You can see several examples of the macro call widget within the core:

* Listing module information: [[$:/snippets/modules]]
* Listing field information: [[$:/snippets/allfields]]
* Generating `data:` URIs: [[$:/themes/tiddlywiki/starlight/styles.tid]]

! Content and Attributes

The content of the `<$macrocall>` widget is ignored.

|!Attribute |!Description |
|$name |Name of the macro to invoke |
|$type |ContentType with which the macro text should be parsed (defaults to `text/vnd.tiddlywiki`) |
|$output |ContentType for the output rendering (defaults to `text/html`, can also be `text/plain` or `text/raw`) |
|//parameters// |Macro parameters specified as attributes |