From db88eed88f5fa8db9390e1288dd4c673c70e6fe5 Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Tue, 17 Jan 2023 17:45:51 +0100 Subject: [PATCH] Improve docs for genesis-widget (#7174) * Improve docs for genesis-widget * improve wording * use <<.attr macro instead of <<.param --- .../tiddlers/widgets/GenesisWidget.tid | 24 ++++++++++++------- .../tiddlers/wikitext/HTML in WikiText.tid | 11 +++++++-- 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/editions/tw5.com/tiddlers/widgets/GenesisWidget.tid b/editions/tw5.com/tiddlers/widgets/GenesisWidget.tid index 4f60c96dc..acc4c36ec 100644 --- a/editions/tw5.com/tiddlers/widgets/GenesisWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/GenesisWidget.tid @@ -1,34 +1,34 @@ caption: genesis created: 20221101100729587 -modified: 20221101100729587 +modified: 20230115101800345 tags: Widgets title: GenesisWidget type: text/vnd.tiddlywiki ! Introduction -<<.from-version "5.2.4">> The <<.wlink GenesisWidget>> widget allows the dynamic construction of another widget, where the name and attributes of the new widget can be dynamically determined, without needing to be known in advance. +<<.from-version "5.2.4">> The <<.wid genesis>> widget allows the dynamic construction of another widget, where the name and attributes of the new widget can be dynamically determined, without needing to be known in advance. ! Content and Attributes -The content of the <<.wlink GenesisWidget>> widget is used as the content of the dynamically created widget. +The content of the <<.wid genesis>> widget is used as the content of the dynamically created widget. |!Attribute |!Description | |$type |The type of widget or element to create (an initial `$` indicates a widget, otherwise an HTML element will be created) | |$names |An optional filter evaluating to the names of a list of attributes to be applied to the widget | -|$values |An optional filter evaluating to the values corresponding to the list of names specified in `$names` | +|$values |An optional filter evaluating to the values corresponding to the list of names specified in <<.attr $names>> | |//{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 applied as attributes to the output widget, but with the attribute name changed to use a single dollar sign | |//{attributes not starting with $}// |Any other attributes that do not start with a dollar are applied as attributes to the output widget | -Note that attributes explicitly specified take precedence over attributes with the same name specified in the `$names` filter. +<<.tip """Note that attributes explicitly specified take precedence over attributes with the same name specified in the <<.attr $names>> filter.""">> ! Examples -<$macrocall $name='wikitext-example-without-html' -src='<$genesis $type="div" class="tc-thing" label="Squeak">Mouse'/> +<$macrocall $name="wikitext-example" +src="""<$genesis $type="div" class="tc-thing" label="Squeak">Mouse"""/> -<$macrocall $name='wikitext-example-without-html' +<$macrocall $name="wikitext-example" src="""\define my-banner(mode:"inline",caption) <$genesis $type={{{ [<__mode__>match[inline]then[span]else[div]] }}} class="tc-mybanner"> <<__caption__>> @@ -39,3 +39,11 @@ src="""\define my-banner(mode:"inline",caption) <> """/> + +! Important + +<$macrocall $name=".warning" _=""" +In the following example the widget attribute named `one` is absent from the HTML output, since HTML attributes with the prefix `on` are removed for security reasons. See [[HTML in WikiText]] "Security" for more details. + +<Test Genesis Widget'>> +"""/> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid index 544c3c5fc..ea926336d 100644 --- a/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/HTML in WikiText.tid @@ -1,6 +1,6 @@ caption: HTML created: 20131205160816081 -modified: 20220123174919252 +modified: 20230115100934146 tags: WikiText title: HTML in WikiText type: text/vnd.tiddlywiki @@ -31,7 +31,14 @@ some text ! Important -<<.tip """[[Widgets share the same syntax as HTML tags|Widgets in WikiText]], and so the following information applies to them, too.""">> +!! Security + +<<.warning """Every HTML attribute prefixed with `on` is removed from rendered HTML content for security reasons. eg: `onclick="some evil code"` would be executed, if no sanitation is active. In ~TiddlyWiki It's important to remove every attribute prefixed with `on` so future extensions to the HTML spec will be secure by default. This can lead to some inconvenience since custom attributes like eg: `one` are removed too. """>> + +!! Widgets + +<<.tip """[[Widgets share the same syntax as HTML tags|Widgets in WikiText]]
and so the following information applies to them, too.""">> + ! Block mode versus Inline mode