From 4954a6ac50853895f0c09e6fe89fc62354d88e53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9ophile=20Desmedt?= <34781168+DesignThinkerer@users.noreply.github.com> Date: Thu, 5 Dec 2024 13:27:18 +0100 Subject: [PATCH] Add example for the function operator (#8793) * Add example for the function operator * change the example to explicitly use the function operator * Use the standard example format, add detailed explanations and add an introductory function to gradually increase complexity * add missing "the" * add the end of the explanation for the diff.fields function * Update function Operator (Examples).tid Show the name of the plugin for the subtiddler used in the demo * fix example number * Update function Operator (Examples).tid fix typo --- .../tiddlers/function Operator (Examples).tid | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 editions/tw5.com/tiddlers/function Operator (Examples).tid diff --git a/editions/tw5.com/tiddlers/function Operator (Examples).tid b/editions/tw5.com/tiddlers/function Operator (Examples).tid new file mode 100644 index 000000000..c83b2e6c9 --- /dev/null +++ b/editions/tw5.com/tiddlers/function Operator (Examples).tid @@ -0,0 +1,63 @@ +created: 20241202134158579 +tags: [[Operator Examples]] [[function Operator]] +title: function Operator (Examples) + +\function get.destField(subTiddler,field) [get] + +\function get.sourceField(subTiddler,field) [shadowsource[]get[text]jsonget[tiddlers],,] + +\function get.sourceFields(subTiddler) [shadowsource[]]:map:flat[subtiddlerfields{!!title}] + +\function has.diff(subTiddler,field) [get.destField,else[]]:filter[get.sourceField,else[]!match{!!title}] + +\function diff.fields(subTiddler) [get.sourceFields] [fields:exclude[created creator modified modifier]] :filter[has.diff,{!!title}] + +\define subTiddler() $:/SiteTitle + +\procedure display-variable(name) ''<$text text=<>/>'': <$text text={{{ [getvariable[]] }}}/> + +These examples use the following predefined variable: + +* <> + +They also use the following predefined functions: + +``` +\function get.destField(subTiddler,field) [get] + +\function get.sourceField(subTiddler,field) [shadowsource[]get[text]jsonget[tiddlers],,] + +\function get.sourceFields(subTiddler) [shadowsource[]]:map:flat[subtiddlerfields{!!title}] + +\function has.diff(subTiddler,field) [get.destField,else[]]:filter[get.sourceField,else[]!match{!!title}] + +\function diff.fields(subTiddler) [get.sourceFields] [fields:exclude[created creator modified modifier]] :filter[has.diff,{!!title}] +``` + +<<.operator-example 1 "[function[get.destField],,[text]]" "get the overriden value of the field <<.field text>>.">> + +The function `get.destField` use the operator <<.olink get>> to get the overriden value of the field <<.field text>> for <>. + +<<.operator-example 2 "[function[get.sourceField],,[text]]" "get the original value of the field <<.field text>>">> + +The function `get.sourceField` use the operator <<.olink shadowsource>> to get the title of the plugin in which the shadow tiddler is defined ({{{ [shadowsource[]]}}}). It then use the operator <<.olink get>> to retrieve the content of the field <<.field text>>, in which is defined every tiddlers for that plugin, in a json format. Next, the operator <<.olink jsonget>> is used to retrieve the value of the original field <<.field text>> for <>. + +<<.operator-example 3 "[function[get.sourceFields],]" "get the original list of fields.">> + +The function `get.sourceFields` use the operator <<.olink shadowsource>> to get the title of the plugin in which the shadow tiddler is defined. The subsequent [[Map Filter Run Prefix]] iterate over the plugin title, and use the operator <<.olink subtiddlerfields>> to output every fields of the shadow tiddler <>, whose title is retrieved using a [[TextReference]]. + +<<.operator-example 4 "[function[has.diff],,[text]]" "compare the original value of the field <<.field text>> with the value set in the overriding tiddler. If the value is different, output the overriden value">> + +The function `has.diff` use the operator <<.olink get>> to retrieve the current value for the field <<.field text>>. If this field is missing or empty, the operator <<.olink else>> output an empty <<.em string>>. Next, the [[Filter Filter Run Prefix]] use the function `get.sourceField` to get the original value for that field, and the operator <<.olink match>> is used to check if the value does not match the current value for that field, using a [[TextReference]]. If the values do not match, it means that the value for that field was changed, and the value of the field is output. Otherwise, the `:filter` filter run prevent the field value to be output. + +<<.operator-example 5 "[function[diff.fields],]" "list the overriden fields">> + +The function `diff.fields` use the the function `get.sourceFields` to list every fields in the original <>. It then use the <<.olink fields>> operator to get every fields on the overriding tiddler, excluding the fields that are automatically set when a [[ShadowTiddler|ShadowTiddlers]] is overriden (<<.field created>>, <<.field creator>>, <<.field modified>>, <<.field modifier>>). The subsequent [[Filter Filter Run Prefix]] use the function `has.diff` to output only the title of the fields that were overidden. + +<<.tip """Theses functions can be used together to highlight the changes made to <>:""">> + +< + <$diff-text source={{{ [get.sourceField,] }}} dest={{{ [get.destField,] }}} > + <>: <> difference<%if [!match[1]]%>s<%endif%> + +""">>