mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-09 11:29:58 +00:00
9b78e871aa
* 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.
53 lines
4.1 KiB
Plaintext
53 lines
4.1 KiB
Plaintext
caption: parameters
|
|
created: 20220909111836951
|
|
modified: 20230518134032228
|
|
tags: Widgets
|
|
title: ParametersWidget
|
|
type: text/vnd.tiddlywiki
|
|
|
|
<<.from-version "5.3.0">> The <<.wlink ParametersWidget>> widget is used within transcluded content to declare the parameters to be made available to the <<.wlink TranscludeWidget>> widget.
|
|
|
|
There are shortcuts for common scenarios that can often make it unnecessary to use the <<.wlink ParametersWidget>> widget directly:
|
|
|
|
* the [[Pragma: \parameters]]
|
|
* the [[Pragma: \procedure]] for declaring procedure
|
|
* the [[Pragma: \widget]] for declaring custom widgets
|
|
|
|
The <<.wlink ParametersWidget>> widget must be used directly in the following situations:
|
|
|
|
* When the default value of a parameter must be computed dynamically
|
|
* When the `$depth` attribute is used to retrieve parameters from a parent transclusion (see below)
|
|
|
|
! Content and Attributes
|
|
|
|
The content of the <<.wlink ParametersWidget>> widget is the scope within which the values of the parameters can be accessed as ordinary variables.
|
|
|
|
|!Attribute |!Description |
|
|
|$depth |The index of the parent transclusion from which to obtain the parameters (defaults to 1). See below |
|
|
|$parseMode |Optional name of a variable in which is made available the parse mode of the content of the parent transclusion (the parse mode can be "inline" or "block") |
|
|
|$parseTreeNodes |Optional name of a variable in which is made available the JSON representation of the parse tree nodes contained within the parent transclusion |
|
|
|$slotFillParseTreeNodes |Optional name of a variable in which is made available the JSON representation of the parse tree nodes corresponding to each fill widget contained within the parent transclusion (as an object where the keys are the slot names and the values are the parse tree nodes) |
|
|
|$params |Optional name of a variable in which is made available the JSON representation of the parameters passed to the parent transclusion (as an object where the keys are the parameter names and the values are the coresponding values) |
|
|
|//{attributes not starting with $}// |Any attributes that do not start with a dollar are used as parameters, with the value specifying the default to be used for missing parameters |
|
|
|//{other attributes starting with $}// |Other attributes starting with a single dollar sign are reserved for future use |
|
|
|//{attributes starting with $$}// |Attributes starting with two dollar signs are used as parameters to the transclusion, but with the name changed to use a single dollar sign. The value specifies the default to be used for missing parameters |
|
|
|
|
<<.note "Note the special treatment required for parameters names that start with a `$`; this can be avoided by using one of the pragmas">>
|
|
|
|
!! `$depth` Attribute
|
|
|
|
By default, the <<.wlink ParametersWidget>> widget retrieves parameters from the immediate parent transclusion. The `$depth` attribute permits access to the parameters of parent transclusions by specifying an index to the parent to be inspected ("1" is the immediate parent, "2" is the parent of that parent, etc.). This is useful in some situations where an intervening transclusion prevents immediate access to desired parameters.
|
|
|
|
!! `$parseMode`, `$parseTreeNodes`, `$slotFillParseTreeNodes` and `$params` Attributes
|
|
|
|
These attributes provide low level access to the contents of the transcluding widget:
|
|
|
|
* The `$params` attribute provides access to the raw parameters provided to the transcluding widget. Represented in JSON as an object with keys of the parameter names and values of the corresponding parameter values
|
|
* The `$parseMode` attribute contains `block` or `inline` to indicate whether the contents was parsed in block or inline mode
|
|
* The `$parseTreeNodes` attribute provides access to the raw parse tree nodes that represent the contents of the transcluding widget. Represented in JSON as an array of parse tree nodes
|
|
* 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)}}
|
|
|