diff --git a/editions/tw5.com/tiddlers/Custom Widgets.tid b/editions/tw5.com/tiddlers/Custom Widgets.tid new file mode 100644 index 000000000..e5c165673 --- /dev/null +++ b/editions/tw5.com/tiddlers/Custom Widgets.tid @@ -0,0 +1,52 @@ +created: 20221007144237585 +modified: 20221007145934733 +tags: Concepts Reference +title: Custom Widgets +type: text/vnd.tiddlywiki + +!! Introduction + +A <<.def "custom widget">> is a special kind of [[procedure|Procedures]] that can be called using the same syntax as widgets. + +Custom widgets can also be used to override built-in JavaScript widgets to customise their behaviour. + +!! Defining Custom Widgets + +Custom widgets are usually defined with the [[Pragma: \widget]]: + +``` +\widget $$my-widget(attribute:"Default value") +This is the widget, and the attribute is <>. +\end +``` + +The name of the widget must start with one or two dollar signs: + +* A ''single dollar sign'' is used to override existing core widgets +** for example, `$text` or `$codeblock` +* ''Double dollar signs'' are used to define a custom widget +** for example, `$$mywidget` or `$$acme-logger` + + + The <<.wlink "GenesisWidget">> widget For example: + + + + +!! Using Custom Widgets + +The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way of [[transcluding|Transclusion]] the snippet. Each of these <<.def "procedure calls">> can supply a different set of parameters: + +``` +<> +<> +``` + +The parameters that are specified in the procedure call are made available as variables. + +!! How Custom Widgets Work + +Custom widgets are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that they can be called as a custom widget with attributes mapped to parameters. + +!! Using Custom Widgets + diff --git a/editions/tw5.com/tiddlers/Pragma_ _procedure.tid b/editions/tw5.com/tiddlers/Pragma_ _procedure.tid new file mode 100644 index 000000000..f4dfb5d09 --- /dev/null +++ b/editions/tw5.com/tiddlers/Pragma_ _procedure.tid @@ -0,0 +1,35 @@ +created: 20221007132845007 +modified: 20221007133003128 +tags: Pragmas +title: Pragma: \procedure +type: text/vnd.tiddlywiki + +The ''\procedure'' [[pragma|Pragmas]] is used to [[define procedures|Procedure Definitions]]. It is a shortcut syntax for the SetVariableWidget. + +The usual form allows procedures to span multiple lines: + +``` +\procedure ([:],[:]...) + +\end +``` + +There is also a single line form for shorter procedures: + +``` +\define ([:],[:]...) +``` + +The first line of the definition specifies the procedure name and any parameters. Each parameter has a name and, optionally, a default value that is used if no value is supplied on a particular call to the macro. The lines that follow contain the text of the procedure text (i.e. the snippet represented by the procedure name), until `\end` appears on a line by itself: + +For example: + +``` + +``` + +Alternatively, the entire definition can be presented on a single line without an `\end` marker: + +``` +\define sayhi(name:"Bugs Bunny") Hi, I'm $name$. +``` diff --git a/editions/tw5.com/tiddlers/Procedure Calls.tid b/editions/tw5.com/tiddlers/Procedure Calls.tid new file mode 100644 index 000000000..934d6d179 --- /dev/null +++ b/editions/tw5.com/tiddlers/Procedure Calls.tid @@ -0,0 +1,56 @@ +caption: Macro Calls +created: 20221007130006705 +modified: 20221007130607159 +tags: WikiText Procedures +title: Procedure Calls +type: text/vnd.tiddlywiki + +!! Introduction + +This tiddler describes the different ways in which [[macros|Procedures]] can be called. + +!! Procedure Call Transclusion Shortcut + +To call a [[procedure|Procedures]], place `<<`double angle brackets`>>` around the name and any parameter values. + +``` +<> +``` + +By default, parameters are listed in the same order as in the procedure definition. A parameter can be labelled with its name and a colon to allow them to be listed in a different order. + +If no value is specified for a parameter, the default value given for that parameter in the [[procedure definition|Procedure Definitions]] is used instead. (If no default value was defined, the parameter is blank). + +Each parameter value can be enclosed in `'`single quotes`'`, `"`double quotes`"`, `"""`triple double quotes`"""` or `[[`double square brackets`]]`. Triple double quotes allow a value to contain almost anything. If a value contains no spaces or single or double quotes, it requires no delimiters. + +See the discussion about [[parser modes|WikiText parser mode: macro examples]] + +!! Procedure Calls with <<.wlink TranscludeWidget>> Widget + +The shortcut syntax expands to the <<.wlink TranscludeWidget>> widget with the `$variable` attribute specifying the name of the procedure to transclude. + +``` +<$transclude $variable="my-procedure" param="This is the parameter value"/> +``` + +The widget itself offers greater flexibility than the shortcut syntax, including the ability to specify dynamic parameter values. + +!! Assigning Procedure Calls to Attribute Values + +The text of a procedure can be directly assigned to an attribute of a widget or HTML element. The result of the procedure is not wikified, which means that [[parameter handling|Procedure Parameter Handling]] does not take place. + +``` +
>> +... +
+``` + +!! Using Procedure Calls in Filters + +Procedure calls can be used in filters. The text is not wikified which again means that the parameters will be ignored. + +``` +<$list filter="[]"> +... + +``` \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/Procedure Definitions.tid b/editions/tw5.com/tiddlers/Procedure Definitions.tid new file mode 100644 index 000000000..63ae9c47e --- /dev/null +++ b/editions/tw5.com/tiddlers/Procedure Definitions.tid @@ -0,0 +1,44 @@ +caption: Macro Definitions +created: 20221007125701001 +modified: 20221007130618079 +tags: WikiText Procedures +title: Procedure Definitions +type: text/vnd.tiddlywiki + +!! Introduction + +This tiddler describes the different ways in which [[macros|Procedures]] can be defined. + +!! Procedure Definition Pragma + +Macros are created using the [[Pragma: \procedure]] at the start of a tiddler. The definitions are available in the rest of the tiddler that defines them, plus any tiddlers that it transcludes. + +``` +\define my-procedure(param) +This is the macro text (param=<>) +\end +``` + +!! Procedure Definition with Set Widget + +Procedures are implemented as a special kind of [[variable|Variables]] and so internally are actually defined with a <<.wlink SetWidget>> widget. + +``` +<$set name="my-procedure" value="This is the procedure text"> +... + +``` + +<<.note """that it is not currently possible to specify parameters when defining a procedure with the <<.wlink SetWidget>> widget.""">> + +!! Importing Procedure Definitions + +The [[Pragma: \import]] or <<.wlink ImportVariablesWidget>> widget can be used to copy procedure definitions from another tiddler. + +!! `$:/tags/Macro` Tag + +Global procedures can be defined using the [[SystemTag: $:/tags/Macro]]. + +The tag [[SystemTag: $:/tags/Macro/View]] is used to define procedures that should only be available within the main view template and the preview panel. + +The tag [[SystemTag: $:/tags/Macro/View/Body]] is used to define procedures that should only be available within the main view template body and the preview panel. diff --git a/editions/tw5.com/tiddlers/Procedure Parameter Handling.tid b/editions/tw5.com/tiddlers/Procedure Parameter Handling.tid new file mode 100644 index 000000000..46d45b529 --- /dev/null +++ b/editions/tw5.com/tiddlers/Procedure Parameter Handling.tid @@ -0,0 +1,25 @@ +caption: Macro Definitions +created: 20221007130538285 +modified: 20221007130953725 +tags: WikiText Procedures +title: Procedure Parameter Handling +type: text/vnd.tiddlywiki + +!! Introduction + +[[Procedure|Procedures]] parameters are made available as variables when the procedure contents are wikified. + +!! Accessing Parameters as Variables + +When procedures are wikified, the parameters can be accessed as variables. + +For example: + +<$macrocall $name="wikitext-example-without-html" src="""\procedure say-hi(name,address) +Hi, I'm <> and I live in <
>. +\end + +<> +"""/> + +Accessing parameters as variables only works in procedures that are wikified and not, for example, when a procedure is used as an attribute value. diff --git a/editions/tw5.com/tiddlers/Procedures.tid b/editions/tw5.com/tiddlers/Procedures.tid new file mode 100644 index 000000000..050a00bcb --- /dev/null +++ b/editions/tw5.com/tiddlers/Procedures.tid @@ -0,0 +1,35 @@ +created: 20221007124007426 +modified: 20221007144806995 +tags: Concepts Reference +title: Procedures +type: text/vnd.tiddlywiki + +!! Introduction + +A <<.def procedure>> is a named snippet of text. They are typically defined with the [[Pragma: \procedure]]: + +``` +\procedure my-procedure(parameter:"Default value") +This is the procedure, and the parameter is <>. +\end +``` + +The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way of [[transcluding|Transclusion]] the snippet. Each of these <<.def "procedure calls">> can supply a different set of parameters: + +``` +<> +<> +``` + +The parameters that are specified in the procedure call are made available as variables. + +!! How Procedures Work + +Procedures are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled. + +!! Using Procedures + +* [[Procedure Definitions]] describes how to create procedures +* [[Procedure Calls]] describes how to use procedures +* [[Procedure Parameter Handling]] describes how procedure parameters work + diff --git a/editions/tw5.com/tiddlers/concepts/Macros.tid b/editions/tw5.com/tiddlers/concepts/Macros.tid index ead9fdfc0..f7aabb5e8 100644 --- a/editions/tw5.com/tiddlers/concepts/Macros.tid +++ b/editions/tw5.com/tiddlers/concepts/Macros.tid @@ -1,12 +1,12 @@ created: 20140211171341271 -modified: 20220917154956636 +modified: 20221007144757675 tags: Concepts Reference title: Macros type: text/vnd.tiddlywiki !! Introduction -A <<.def macro>> is a named snippet of text. It is typically defined with the [[Pragma: \define]]: +A <<.def macro>> is a named snippet of text. They are typically defined with the [[Pragma: \define]]: ``` \define my-macro(parameter:"Default value") @@ -26,11 +26,11 @@ The parameters that are specified in the macro call are substituted for special * `$parameter-name$` is replaced with the value of the named parameter * `$(variable-name)$` is replaced with the value of the named [[variable|Variables]]). -<<.from-version "5.3.0">> Macros have been superseded by [[Procedures]], [[Custom Widgets]] and [[Functions]] which together provide more robust and flexible ways to encapsulate and re-use code. It is now recommended to only use macros when textual substitution is specifically required. +<<.from-version "5.3.0">> Macros have been [[superseded|Macro Pitfalls]] by [[Procedures]], [[Custom Widgets]] and [[Functions]] which together provide more robust and flexible ways to encapsulate and re-use code. It is now recommended to only use macros when textual substitution is specifically required. !! How Macros Work -Macros are implemented as a special type of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled. +Macros are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled. !! Using Macros diff --git a/editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid b/editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid index c853ea2f9..452dc92fa 100644 --- a/editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/MacroCallWidget.tid @@ -1,11 +1,13 @@ caption: macrocall created: 20131024141900000 -modified: 20220909111836951 -tags: Widgets +modified: 20221007121724264 +tags: Widgets $:/deprecated title: MacroCallWidget type: text/vnd.tiddlywiki -<<.from-version "5.3.0">> The <<.wlink MacroCallWidget>> widget is now deprecated. While it will continue to work, users are advised to use the <<.wlink TranscludeWidget>> widget, converting the `$name` attribute to `$variable`. +<<.deprecated-since "5.3.0" "TranscludeWidget">> + +The <<.wlink MacroCallWidget>> widget is deprecated. While it will continue to work, users are now advised to use the <<.wlink TranscludeWidget>> widget, converting the `$name` attribute to `$variable`. For example, diff --git a/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid b/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid index 2191d6971..9454165c5 100644 --- a/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/TranscludeWidget.tid @@ -1,6 +1,6 @@ caption: transclude created: 20130824142500000 -modified: 20220917113915710 +modified: 20221007123821494 tags: Widgets title: TranscludeWidget type: text/vnd.tiddlywiki @@ -87,7 +87,7 @@ There are several different ways to declare parameters within a transclusion: * the <<.wlink ParametersWidget>> widget * the [[Pragma: \parameters]] * the [[Pragma: \procedure]] for declaring procedure -* the [[Pragma: \widgets]] for declaring custom widgets +* the [[Pragma: \widget]] for declaring custom widgets * the [[Pragma: \define]] for declaring macros An example of declaring parameters with the <<.wlink ParametersWidget>> widget: diff --git a/editions/tw5.com/tiddlers/wikitext/Macro Calls.tid b/editions/tw5.com/tiddlers/wikitext/Macro Calls.tid index ab939f1c4..cff95f824 100644 --- a/editions/tw5.com/tiddlers/wikitext/Macro Calls.tid +++ b/editions/tw5.com/tiddlers/wikitext/Macro Calls.tid @@ -1,6 +1,6 @@ caption: Macro Calls created: 20150220182252000 -modified: 20220918115347941 +modified: 20221007132734417 tags: WikiText Macros title: Macro Calls type: text/vnd.tiddlywiki @@ -25,7 +25,7 @@ Each parameter value can be enclosed in `'`single quotes`'`, `"`double quotes`"` A more formal [[presentation|Macro Call Syntax]] of this syntax is also available. -See some [[examples|Macro Calls in WikiText (Examples)]] and discussion about [[parser modes|WikiText parser mode: macro examples]] +See some [[examples|Macro Calls in WikiText (Examples)]] and discussion about [[parser modes|WikiText parser mode: macro examples]]. !! Macro Calls with <<.wlink TranscludeWidget>> Widget