diff --git a/editions/tw5.com/tiddlers/Custom Widgets.tid b/editions/tw5.com/tiddlers/Custom Widgets.tid index e5c165673..87521fb35 100644 --- a/editions/tw5.com/tiddlers/Custom Widgets.tid +++ b/editions/tw5.com/tiddlers/Custom Widgets.tid @@ -1,5 +1,5 @@ created: 20221007144237585 -modified: 20221007145934733 +modified: 20221009121901496 tags: Concepts Reference title: Custom Widgets type: text/vnd.tiddlywiki @@ -27,26 +27,58 @@ The name of the widget must start with one or two dollar signs: * ''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: +Custom widgets are called in the same way as ordinary built-in widgets: ``` -<> -<> +<$my-widget/> + +<$my-widget attribute="The parameter"/> ``` -The parameters that are specified in the procedure call are made available as variables. +The attributes that are specified in the widget call are made available as parameter variables. + +!! Accessing Content of Custom Widgets + +Within the definition of a custom widget the content of the calling widget is available via the `<$slot $name="ts-raw"/>` widget. The contents of the <<.wlink SlotWidget>> widget is used as the default content if the widget was called without any content. + +For example: + +<>/> +<$slot $name="ts-raw"> + Whale + +\end + +<$$mywidget one="Dingo"> + Crocodile + + +<$$mywidget/>""">> !! 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 +!! Overriding Core ~JavaScript Widgets +Custom widgets can use the <<.wlink "GenesisWidget">> widget to invoke the original widget, bypassing the override. For example, here we override the <<.wlink CodeBlockWidget>> widget to add `≤≥` symbols around each string of text. + + +<addprefix[≤]addsuffix[≥]] }}}/> +\end + +<$codeblock code="Kangaroo"/> + +<$codeblock code={{$:/SiteTitle}}/> + +``` +Python +``` + +<$let test="Tiger"> +<$codeblock code=<>/> +""">> diff --git a/editions/tw5.com/tiddlers/Functions.tid b/editions/tw5.com/tiddlers/Functions.tid new file mode 100644 index 000000000..7d0da129e --- /dev/null +++ b/editions/tw5.com/tiddlers/Functions.tid @@ -0,0 +1,28 @@ +created: 20221009124003601 +modified: 20221009125246821 +tags: Concepts Reference +title: Functions +type: text/vnd.tiddlywiki + +!! Introduction + +A <<.def function>> is a named snippet of text containing a [[Filter Expression]]. Functions can have named parameters which are available within the function as variables. + +Functions are usually defined with the [[Pragma: \function]]: + +``` +\function my-function(parameter:"2") +[multiply[1.5]] +\end +``` + +Functions can be invoked in several ways: + +* Directly transclude functions with the syntax `<>` +* Assign functions to widget attributes with the syntax `
>>` +* Invoke functions via the [[function Operator]] with the syntax `[function[myfn],[value],...]` +* Directly invoke functions whose names start with a period as custom filter operators with the syntax `[.myfn[value]]` + +!! How Functions Work + +Functions 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. diff --git a/editions/tw5.com/tiddlers/Pragma_ _procedure.tid b/editions/tw5.com/tiddlers/Pragma_ _procedure.tid index f4dfb5d09..260256cb7 100644 --- a/editions/tw5.com/tiddlers/Pragma_ _procedure.tid +++ b/editions/tw5.com/tiddlers/Pragma_ _procedure.tid @@ -1,10 +1,10 @@ created: 20221007132845007 -modified: 20221007133003128 +modified: 20221009122437394 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 ''\procedure'' [[pragma|Pragmas]] is used to [[define procedures|Procedure Definitions]]. It is a shortcut syntax for the SetVariableWidget with an implicit ParametersWidget. The usual form allows procedures to span multiple lines: @@ -20,16 +20,20 @@ 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: +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 procedure. 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: ``` +\procedure sayhi(name:"Bugs Bunny") +Hi, I'm $name$. +\end +<> ``` Alternatively, the entire definition can be presented on a single line without an `\end` marker: ``` -\define sayhi(name:"Bugs Bunny") Hi, I'm $name$. +\procedure sayhi(name:"Bugs Bunny") Hi, I'm $name$. ``` diff --git a/editions/tw5.com/tiddlers/Pragma_ _widget.tid b/editions/tw5.com/tiddlers/Pragma_ _widget.tid new file mode 100644 index 000000000..904b69f33 --- /dev/null +++ b/editions/tw5.com/tiddlers/Pragma_ _widget.tid @@ -0,0 +1,25 @@ +created: 20221009121950630 +modified: 20221009122447180 +tags: Pragmas +title: Pragma: \widget +type: text/vnd.tiddlywiki + +The ''\widget'' [[pragma|Pragmas]] is used to [[define custom widgets|Custom Widgets]]. It is a shortcut syntax for the SetVariableWidget with an implicit ParametersWidget. + +The usual form allows custom widgets to span multiple lines: + +``` +\widget ([:],[:]...) + +\end +``` + +There is also a single line form for shorter widgets: + +``` +\widget ([:],[:]...) +``` + +The first line of the definition specifies the widget 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 widget. The lines that follow contain the text of the widget text (i.e. the snippet represented by the widget name), until `\end` appears on a line by itself: + +See [[Custom Widgets]] for more details. \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/variables/Variables.tid b/editions/tw5.com/tiddlers/variables/Variables.tid index f586141e8..1600d42ee 100644 --- a/editions/tw5.com/tiddlers/variables/Variables.tid +++ b/editions/tw5.com/tiddlers/variables/Variables.tid @@ -1,5 +1,5 @@ created: 20141002133113496 -modified: 20221006124708656 +modified: 20221009122532111 tags: Concepts Reference WikiText title: Variables type: text/vnd.tiddlywiki @@ -20,7 +20,7 @@ There are several special kinds of variable that extend their basic capabilities * [[Procedures]] are snippets of text that can be passed parameters when wikified * [[Functions]] are snippets of text containing [[filters|Filters]] with optional named parameters -* [[User Defined Widgets]] are snippets of text containing definitions of custom [[widget|Widgets]] +* [[Custom Widgets]] are snippets of text containing definitions of custom [[widget|Widgets]] * [[Macros]] are snippets of text that can contain placeholders that are filled in with parameters whenever the macro is used Note that these special kinds of variable can only be created with the associated shortcut definition syntax. @@ -31,7 +31,7 @@ The following core widgets are commonly used to define variables: * <<.wlink LetWidget>> widget -- the easiest way to define multiple variables * <<.wlink SetWidget>> widget -- the most flexible way to define a single variable -* <<.wlink ParametersWidget>> widget -- used to declare parameter variables within [[procedures|Procedures]] and [[user defined widgets|User Defined Widgets]] +* <<.wlink ParametersWidget>> widget -- used to declare parameter variables within [[procedures|Procedures]] and [[custom widgets|Custom Widgets]] * <<.wlink ListWidget>> widget -- defines a loop variable and optional counter variable * <<.wlink SetMultipleVariablesWidget>> widget -- allows creation of multiple variables at once where the names and values are not known in advance diff --git a/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid b/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid index 54a1d138d..28881b553 100644 --- a/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/ParametersWidget.tid @@ -38,12 +38,13 @@ The content of the <<.wlink ParametersWidget>> widget is the scope within which 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`, `$slotFillParseTreeNodes` and `$params` Attributes +!! `$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 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 `$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