mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-12-24 17:10:29 +00:00
Update ParametersWidget and add Examples (#7464)
* Update ParametersWidget and add Examples This PR updates the ParametersWidget.tid and adds several examples * Update Procedure and Parameters Pragma This PR improve documentation for using parameters inside procedures * Update Pragma_ _procedure.tid A caution when use parameters inside procedures * Resolved conversation All comments by Jeremy were implemented.
This commit is contained in:
parent
d4846bae6c
commit
9b78e871aa
@ -1,10 +1,10 @@
|
||||
created: 20220917113154900
|
||||
modified: 20230419103154329
|
||||
modified: 20230518143557045
|
||||
tags: Pragmas
|
||||
title: Pragma: \parameters
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
<<.from-version "5.3.0">> The ''\parameters'' [[pragma|Pragmas]] is used within [[procedure|Procedure Definitions]] and [[widget|Widget Definitions]] definitions to declare the parameters that are expected, and their default values. It is a shortcut syntax for the ParametersWidget.
|
||||
<<.from-version "5.3.0">> The ''\parameters'' [[pragma|Pragmas]] is used within [[procedure|Procedure Definitions]] and [[widget|Custom Widgets]] definitions to declare the parameters that are expected, and their default values. It is a shortcut syntax for the ParametersWidget.
|
||||
|
||||
```
|
||||
\parameters (<name>[:<default-value>],<name>[:<default-value>]...)
|
||||
@ -16,3 +16,11 @@ For example:
|
||||
\parameters (firstname:"Joe",lastname:"Blogs")
|
||||
```
|
||||
|
||||
To illustrate the use of ''\parameters'' pragma, see [[Core Icons]] which are parameterised. The first parameter `size` specified the size at which the icon should be rendered. For example see the text of [[$:/core/images/print-button]] tiddler. The first line defines the size parameter as `\parameters (size:"22pt")`
|
||||
|
||||
<<wikitext-example-without-html """{{$:/core/images/print-button|16px}}
|
||||
<$transclude $tiddler="$:/core/images/print-button" size="32px"/>
|
||||
""">>
|
||||
|
||||
In the above example, the first line shows a simple transclusion of [[$:/core/images/print-button]] icon with `size` parameter passed by position and is set to 16px. The second line is a transclusion of image with `size` parameter passed by name and is set to 32px.
|
||||
|
||||
|
@ -1,5 +1,5 @@
|
||||
created: 20221007132845007
|
||||
modified: 20230419103154329
|
||||
modified: 20230518152756112
|
||||
tags: Pragmas
|
||||
title: Pragma: \procedure
|
||||
type: text/vnd.tiddlywiki
|
||||
@ -53,3 +53,58 @@ Procedure definitions can be nested by specifying the name of the procedure in t
|
||||
|
||||
<<special-button>>
|
||||
""">>
|
||||
|
||||
! Use of Parameters Inside Procedures
|
||||
The parameters can be declared inside procedures. The parameters widget is necessary in a procedure if you want to use computed default values. For example:
|
||||
|
||||
<<wikitext-example-without-html
|
||||
src:"""\procedure myproc()
|
||||
<$parameters name={{$:/SiteTitle}} desc={{$:/SiteSubtitle}}>
|
||||
This is <<name>> demonstrates <<desc>>.
|
||||
</$parameters>
|
||||
\end
|
||||
|
||||
<<myproc>>
|
||||
""">>
|
||||
|
||||
!! Caution in Using Positional Parameters
|
||||
Procedures are a shortcut syntax for the SetVariableWidget with an implicit ParametersWidget, so generally there is no reason to have multiple parameters widgets within a definition. In the below example when passing `x` to `myproc`, it will also be set to `a`:
|
||||
|
||||
<<wikitext-example-without-html
|
||||
src:"""\procedure myproc(x:10)
|
||||
\parameters (a:100, b:200)
|
||||
|
||||
x=<<x>>, a=<<a>>, b=<<b>>
|
||||
\end
|
||||
|
||||
<<myproc 50>>
|
||||
""">>
|
||||
|
||||
The reason for that result is clearer if we consider an equivalent with explicit parameters widgets.
|
||||
|
||||
<$macrocall $name=wikitext-example-without-html
|
||||
src='<$let myprog="""
|
||||
\parameters (x:10)
|
||||
\parameters (a:100, b:200)
|
||||
|
||||
x=<<x>>, a=<<a>>, b=<<b>>
|
||||
""">
|
||||
<<myprog 50>>
|
||||
</$let>'
|
||||
/>
|
||||
|
||||
This is because those two parameters widgets are entirely independent. They are both processed as if the other parameter widget is not there.
|
||||
|
||||
<<.tip "The positional parameters are only required when using the parameterised transclusion shortcut syntax, and that in other cases it is generally clearer to use named parameters.">>
|
||||
|
||||
To prevent such situation of above example, pass parameters by name as below.
|
||||
|
||||
<<wikitext-example-without-html
|
||||
src:"""\procedure myproc(x:10)
|
||||
\parameters (a:100, b:200)
|
||||
|
||||
x=<<x>>, a=<<a>>, b=<<b>>
|
||||
\end
|
||||
|
||||
<<myproc x:50>>
|
||||
""">>
|
@ -1,6 +1,6 @@
|
||||
caption: parameters
|
||||
created: 20220909111836951
|
||||
modified: 20230419103154328
|
||||
modified: 20230518134032228
|
||||
tags: Widgets
|
||||
title: ParametersWidget
|
||||
type: text/vnd.tiddlywiki
|
||||
@ -48,14 +48,5 @@ These attributes provide low level access to the contents of the transcluding wi
|
||||
* The `$slotFillParseTreeNodes` attribute provides access to the raw parse tree nodes corresponding to the filled slots within the contents of the transcluding widget. Represented in JSON as an object with keys of the slot name and values being an array of parse tree nodes
|
||||
|
||||
! Examples
|
||||
{{ParametersWidget (Examples)}}
|
||||
|
||||
Here the <<.wlink ParametersWidget>> widget is used to declare a parameter whose default value is transcluded from another tiddler.
|
||||
|
||||
<$macrocall $name='wikitext-example-without-html'
|
||||
src="""\procedure mymacro()
|
||||
<$parameters name={{$:/SiteTitle}} age="21">
|
||||
My name is <<name>> and my age is <<age>>.
|
||||
</$parameters>
|
||||
\end
|
||||
|
||||
<$transclude $variable="mymacro" age="19"/>"""/>
|
||||
|
@ -0,0 +1,39 @@
|
||||
created: 20230518124403282
|
||||
modified: 20230518135109977
|
||||
tags: ParametersWidget
|
||||
title: ParametersWidget (Examples)
|
||||
|
||||
''Example i'': Shows transclusion of [[Sample Tiddler Template]]. The template tiddler has two parameters `name` and `age` and here their default values are used.
|
||||
|
||||
<$macrocall $name=".example" n="1" eg="""<$transclude $tiddler="Sample Tiddler Template" />"""/>
|
||||
|
||||
''Example ii'': Shows, another transclusion of [[Sample Tiddler Template]], here the value of `age` is passed, but `name` uses its default value.
|
||||
|
||||
<$macrocall $name=".example" n="2" eg="""<$transclude $tiddler="Sample Tiddler Template" age=33/>"""/>
|
||||
|
||||
''Example iii'': Shows, another transclusion of [[Sample Tiddler Template]], here the value of both `name` and `age` are passed.
|
||||
|
||||
<$macrocall $name=".example" n="3" eg="""<$transclude $tiddler="Sample Tiddler Template" age=45 name="Jeremy Ruston" />"""/>
|
||||
|
||||
In the simple form the above transclusion is equivalent to
|
||||
|
||||
<$macrocall $name=".example" n="3.1" eg="""{{Sample Tiddler Template|Jeremy Ruston|45}}"""/>
|
||||
|
||||
In this simple form, parameters passed by position not by name. So the first value is passed to the first parameter, here `name` and the second value is passed to the second parameter, here `age`.
|
||||
|
||||
''Remarks''
|
||||
|
||||
# Passing parameter by name is good practice and is recommended for clarity. So for parameterized transclusions, the use of <<.wid transclude>> is recommended over simple form transclusion.
|
||||
# When passing parameters value by position, you cannot pass the second parameter while the first one has not been passed.
|
||||
|
||||
|
||||
''Example iv'': Here the <<.wlink ParametersWidget>> widget is used to declare a parameter whose default value is transcluded from another tiddler.
|
||||
|
||||
<$macrocall $name=".example" n="4" eg="""\procedure myproc()
|
||||
<$parameters name={{$:/SiteTitle}} age="21">
|
||||
My name is <<name>> and my age is <<age>>.
|
||||
</$parameters>
|
||||
\end
|
||||
|
||||
<$transclude $variable="myproc" age="19"/>
|
||||
"""/>
|
@ -0,0 +1,9 @@
|
||||
created: 20230518124140604
|
||||
description: This example tiddler is used to illustrate some of the new features in Parameterized Transclusions
|
||||
modified: 20230518125337219
|
||||
tags: [[ParametersWidget Examples]] Demonstrations
|
||||
title: Sample Tiddler Template
|
||||
|
||||
<$parameters name=Jeremy age="21">
|
||||
My name is <<name>> and my age is <<age>>.
|
||||
</$parameters>
|
Loading…
Reference in New Issue
Block a user