Peer Review please Cheat sheet

[TonyM]

Folks,

I have being building a "CheatSheet" that I would appreciate expert review if possible. Please respond with references to the number of each item.

You can see it is built on Tobias and Eric's work to name a few. It tries and make simple, some particularly tricky issues that new and experienced users face.

Now an abridged version can be found here https://anthonymuscio.github.io/#Standard%20Nomenclature

Regards

Tony

Important note:

• The following is a Cheatsheet or quick reference to the following
  wikitext, variables, widgets, filters, operators and the use of references variables, macros, html tags and their attributes/parameters
• Key widgets that are used sometimes, for a complete solution are $text, $macrocall, $wikify and $transclude, otherwise this documentation relates to all widgets.
• Many non-coders may find this intimidating however should keep the following in mind;
  • much of this is actually essential not just for programming, but logical necessary, similar to the use of punctuation in hand writting.
  • Whilst it may seem complex at first, the application of these rules is not only consistent throughout TiddlyWiki, but has a lot in common with most other implementations of html, programming languages, mark-up and a lot more.
  • This document is a summary of things learned over a number of years by the author, don't expect to understand it overnight.
  • Somewhere on this learning curve you will have to stop calling yourself a non-coder.
• Prior knowledge of these will help, and regardless what you learn to use TiddlyWiki it will include transferable skills.
  • You are not required to learn much that is single purpose, and all will unleash the power of TiddlyWiki
• In this cheat sheet the use of single square brackets indicates something optional, eg; <<macroname [params]>> [params] means that is optional.

❶ General wiki text (including inside macros)

For additional possibilities with inside macros see ❸ Within macro definitions below.

1. literal values when literal values are used as parameters or attributes the quoting rules apply see ➃ Using literals and parameters
2. <br> <hr> html tags immediate closure
3. <section> </section> later closure
4. <<variable/macrocall [params]>> immediate closure, see ➀ for later closure
5. <$widgetname [params] /> immediate closure
6. <$widgetname [params]> inside the widget </$widgetname> later closure (for more see ➁ Content of widgets)
7. {{tiddlername}} transclude the content of the tiddlername's text field and render
8. {{!!fieldname}} transclude the content of the currentTiddlers fieldname and render
9. {{tiddlername!!fieldname}} transclude the content of the tiddlername's fieldname and render
10. {{{ [<currentTiddler>addprefix[$:/myprefix/]] }}} filtered transclusion, see also ❻ More on filtered transclusions
11. Not valid in General wiki text
    1. <variable>
    2. "<variable>",
    3. [[<variable>]]

❷ Widget and HTML attributes or parameters html element attributes, e.g. $macrocall

1. <$widget attribute="literal value"/> see ➃ Using literals and parameters
2. <$widget attribute=<<variable>>/> using a variable
3. <$widget attribute=<<callMacroToComputeValue>>/> using a macro
4. <$widget attribute={{transclusion}}/> using a transclusion see
5. <$widget attribute={{{ filter }}}/> filtered transclusion ;❻
6. <htmltag attribute="literal value"/> see ➃ Using literals and parameters
7. <htmltag attribute=<<variable>>/> using a variable as a HTML attribute
8. <htmltag attribute=<<callMacroToComputeValue>>/> using a variable as a HTML attribute
9. <htmltag attribute={{transclusion}}/> using a variable as a HTML attribute see more on transclusions ❻ and ❼
10. <htmltag attribute={{{ filter }}}/> filtered transclusion ;❻
11. {{!!transclusion}} a field who's value can also be inside [[ ]]????
12. Not valid in widget attributes/parameters
    1. <$widget attribute="prefix-<<variable>>"/> can not concatenate literals and variables in a parameter
    2. <$widget attribute=[[prefix-<<variable>>]]/> can not concatenate literals and variables in a parameter or treat it as a tiddler link at same time
    3. <$widget attribute="prefix-{{transclusion}}"/> can not concatenate literals and transclusions/textreferences in a parameter

❸ Within macro definitions

Within macro definitions refers to the following cases

\define macrocname(parms) In here
\define macrocname(parms) here
and in here
\end

Keep in mind macros definitions also have full access to wiki text as documented in ❶ General wiki text

Note: representations using the $ sign are 'substitutions' so you must provide the delimiters such as quotes with the substitution if required'"

See footnote ➂ The value of Substitutions for more,

it is importiant you understand ➃ Using literals and parameters if you want to use substitutions.

1. $macroParameter$, "$macroParameter$", [[$macroParameter$]] <<__macroParameter__>>
2. $(variable)$ references a variable from the context of the calling macro, this is away to avoid the use of a parameter in macrocalls.
3. : <<__macroParameter__>> Parameter-as-variable access to a parameter defined in the macro parameters list as it it were a variable.
   1. There are a few cases where a substitution may not be suitable but a variable is.
4. <$widget attribute="prefix-$macroParameter$"/>
5. <$widget attribute=$macroParameter$/> unsafe when $macroParameter$ has spaces or other special characters.
6. $variable$, "$variable$", [[$variable$]] ?????

❹ Macro parameters Macro Calls in WikiText

1. When literal values are used as parameters or attributes the quoting rules apply, see ➃ Using literals and parameters
2. <<macroname "1st" "2nd">> refers to Nth parameter in macro definition
3. <<macroname param:"value">> refers to the name parameter
4. <<macroname param:"$macroParameter$">> only inside macro were $param$ and $(varname)$ are valid see
5. Since parameters in macros is limited, we use the macrocall widget to give the same paramater possibilities as widgets.
6. <$macrocall $name=macroname param="literal" param1=<<variable>> param2={{transclusion}} param3={{{ filter }}} />
   1. in the macrocall widget you need to know the parameter name to pass a value
7. The following missuses can be replaced by the use of
   1. $(variable)$ in the macro definition
   2. use the $macrocall widget to allow evaluated parameters
8. Not valid in Macro parameters but the $macrocall widget offers a work around.
   1. <<macroname <<variable>> >> the << and >> get confused
   2. <<macroname "<<variable>>" >> The paramerter will contain the value of <<variable>> ?? the << and >> get confused ??
   3. <<macroname param:<<variable>> >> the << and >> get confused
   4. <<macroname {{transclusion}}>> the transclusion will not occur before the macrocall
   5. <<macroname param:{{transclusion}}>> the transclusion will not occur before the macrocall

❺ In filters

1. There is no need in filters to differentiate between html and widgets tags so only single delimiters are needed.
2. Also once a delimiter is in use, you must avoid using the [] you would have needed. So an operator[literalvalue] becomes operator<varname>
3. Operator below refers to any filter operator eg "tag"
4. [operator<variable>] (no inner square brackets!)
5. [operator{transclusion}] only single curly brackets!
6. [operator{!!fieldname}] only single curly brackets!
7. [operator{tiddlername!!fieldname}] only single curly brackets!
8. operator[$macroParameter$] (only filters within macros)
9. Not valid in filters
   1. [operator[$(variable)$]] test this!
   2. [operator<macroname parameter>] Macros used in filters can not contain parameters to the macro
      1. workaround - use the wikify widget
10. Note: If a tiddler or tiddler!!fieldname contains a complete filter, you can transclude that whole filter as a parameter
    1. For example filter={{tiddlername}} filter={!!fieldname}} filter={{tiddlername!!fieldname}}
    2. however in this case you can't now manipulate the filter eg; ~filter="{{tiddlername}}addprefix[$:/]]~
11. Wikify workaround for parameters to a macro

<$wikify name=newvar text="""<<macroname parameter>>""">
... [operator<newvar>] ....
</$wikify>

❻ More on filtered transclusions

Also refered to as triple curly braces {{{ filter }}} they excel in particular uses such as concatenation, evaluation, maths and as parameter to widget especially the $macrocall widget.

1. {{{ somename }}} somename a tiddler link
2. {{{ some name }}} somename two tiddler links
3. {{{ [[some name]] }}} some name tiddler whos title contains spaces
4. {{{ [[somename]get[caption]else{!!title}] }}} caption of somename tiddler whos title contains spaces
5. filtered transclusions can be placed inside a TextWidget to return only text (not something later rendered)
6. '<$text text={{{ [[somename]get[caption]else{!!title}] }}}/>' 'caption of somename' use text so the caption does not become a link
7. filtered transclusions can be placed inside a WikifyWidget to evaluate a result for subsequent use
   

rather that containing something which is later evaluated at render time)

<$wikify name=result text="""{{{ [[somename]get[caption]else{!!title}] }}} >
The <<result>> variable containes the result of the wikify only before its closure
</$wikify>

❼ More on transclusions - as templates

• See ❶ General wiki text (including inside macros) for the reference to tiddlername and fieldnames
• some times a parameter accepts a "text reference" which is similar in apperence to a transclusion
  • eg; "tiddlername", "!!fieldname" or "tiddlername!!fieldname" these are "references"
• See ❻ More on filtered transclusions for the use of triple curly braces.

SO far

1. Transclude transclusions
2. Transclude with current tiddler
   1. Eg button
3. Transclude with named tiddler
   1. Eg button?
4. transclude widget.
5. Not valid for transclusions
   1. {{||tiddlername!!caption}} as it aske for the field caption in tiddlername, but insists on using the currentTiddler.

---

Footnotes

➀ The following is an example of later closure of a macro;

<<variable 
[params]
>>

➁ Content of widgets

Sometimes used OR for example The content of the <$text> widget is not used.

This may be an opportunity to add notes in your wiki text that will not be displayed in the result

In many cases such as the ListWidget the content is used such as for the display templated of the list results

If the template=parameter is used then the widget content is not used

<$widgetname [params]> inside the widget </$widgetname> later closure

<$widgetname [params]>
   inside the widget 
</$widgetname>

The macrocall widget is a case in point, The content of the <$macrocall> widget is ignored. So we can use it as such;

<&macrocall $name=macroname param="literal" param1=<<variable>>  param2={{transclusion}} param3={{{ filter }}} >
So in here we could document the function and parameters of this particular macrocall
/>

➂ The value of Substitutions

A key advantage of substitutions (in macros) is their placement can also be a concatenation of values.

see also ❻ More on filtered transclusions (also for concatenation)

it is important you understand ➃ Using literals and parameters with substitutions

\define concatenate-parameters(param1 param2) $param1$/$param2$
\define concatenate-variables() $(currentTiddler)$/$(subtiddler)$

<<concatenate-parameters tiddlername subtiddler>>

<$set name=subtiddler value="mysubtiddler">
  <<concatenate-variables>>
</$set>

• The $(...)$ syntax means "substitute the variable, defined before this macro was invoked".

This is a way of accessing values without the use of actual macro parameters, get or set the variable before calling the macro

➃ Using literals and parameters

Each parameter value can be enclosed in 'single quotes', "double quotes", """triple double quotes""" or [[double square brackets]].

Triple double quotes allow a value to contain almost anything. If a value contains no spaces or single or double quotes, it requires no delimiters.

You can choose ' or " or """ if you want to wrap something that contains (or may contain) one of the other quotes. In this regard the """literal""" is the safest.

However often wrapping a macrocall, or widget in quotes will turn it into a literal and it will not be evaluated

Other uses

• Double double Quotes "" are not used to delimit
• Double single quotes '' are used to open and close bold in wiki text.
• Triple Double Quotes """ is used to mark a block of text.
• Single tick back tick (unshifted ~ on QWERTY keyboards) highlight inline code eg; this is between single back ticks and will not be rendered.

Summarised as

• If value is a single word not containing spaces or other delimiters parname=value (no quotes)
• If value is two words spaces parname='value word2' parname="value word2" parname=value word2 all work. note double "" does not.
• If you want to use a delimiter such as ' or " in a string you must use the other
• If our value is parname="something "quote here" something else" it does not know when it is starting or ending
  • parname='something "quote here" something else' this works
  • parname="something 'quote here' something else" as does this

The advantage of the triple quotes is they rarely appear in content so parname=something 'quote here' and "here is another" something else works and is the most reliable.

The above are the rules for literals, or fixed typed values.

Tiddlywiki uses quotes for literals so if you put it around other things '<<macroname>>' "<<macroname>>" """<<macroname>>""" it turns it into a literal

However when we use the following as a parameter or attribute value they are already delimited by the << or {{ or {{{ so no need to add quotes and turn them into literals.

parname=<<macroname>> 
parname=<<varname>> 
parname={{{ [filter] }}} 
parname={{!!fieldname}} 
parname={{tiddlername}}  
parname={{tiddlername!!fieldname}} 
But in the above cases the value is retrieved from elsewhere, and that value needs to be appropriate for the parameter you are providing.

Keep in mind double and triple braces are used in wikitext because html tags <div></div> etc... are permitted in wiki text, So we need << to separate them from < only singles are required in filters, because filters do not handle html tags.

[TonyM]

Folks,

This working tiddler is published here;

https://anthonymuscio.github.io/#Standard%20Nomenclature

Regards

Tony

On Thursday, 1 October 2020 12:17:43 UTC+10, TonyM wrote:

Folks,

I have being building a "CheatSheet" that I would appreciate expert review if possible. Please respond with references to the number of each item.

You can see it is built on Tobias and Eric's work to name a few. It tries and make simple, some particularly tricky issues that new and experienced users face.

[coda coder]

Hi Tony

Bold effort!

I spotted something in there that I do quite often, but I do it a little differently:

You: 

<$wikify name=style-value text="""color: {{!!color}}""">

 style=<<style-value>> 

</$wikify>  

Me:

<span style={{{ [[color:]] [{!!c}] +[join[]] }}}>Check this in devtools</span>

Not sure which you might prefer...

[TonyM]

CodaCoda,

Yes I understand that, but I will review the cheat sheet to see if I give it sufficient weight.

Did you look at the online version https://anthonymuscio.github.io/#Standard%20Nomenclature the filtered transclusions section could promote its use more.

Tony

[saq.i...@gmail.com]

FYI, the solution using join[] (or addsuffix[]) is substantially faster than using wikify to assign widget attributes.

[coda coder]

Agreed. But syntax noise is... well, noisy :/

[coda coder]

Yes. But following along with your thinking was kinda slow. I had to reread a few times to "get" what you were saying. It was probably me - too tired at the time.

[coda coder]

On Wednesday, December 2, 2020 at 12:40:17 AM UTC-6 saq wrote:

FYI, the solution using join[] (or addsuffix[]) is substantially faster...

addsuffix - duh! - Jeez... thanks for the face-palm, Saq!

There's only so long I can stare at something (sometimes, anyway).

[saq.i...@gmail.com]

@codacoder interesting! While both syntaxes leave a lot to be desired, I personally find wikify so much uglier. 
Personally I use a filter that does something like this:

<span style={{{ [[color:$0$]printf{!!c}] }}}>Check this in devtools</span>  

Anyway be warned that depending on the complexity of the contents of the element you assign a class/style to with wikify, the performance can be noticeably worse.

[coda coder]

Yep, it is interesting. I do try to avoid wikify until I prove it's the only way.  In essence, even though the goal is simply stated, transclusion-filters (to me) seem to cloud the simplicity - leaving a lot of syntax noise behind. Wikify seems to read simpler, because it's "broken down" I guess (?) But I have to pause to read more carefully with {{{ [...] }}}.

Weird.

In the early days of 5, I "saw" lisp and forth in the code. I don't see that anymore. It's probably not TW's fault... probably just me aging  - I have to double-check even the simplest things these days. 

Can I get up off the couch now? :)

[coda coder]

Just dreaming out loud...

<span style=`color:{{!!c}}`>my span</span>

Note - backticks. They become a request for wikification. Of course, they could be any sensible alternative (though I don't support treading on/overloading quotes, either ' or " .

And if a substitution run could happen first...

<span style=`<<my-prop>>:{{!!field}}`>my span</span>

[saq.i...@gmail.com]

@codacoder There are issues on github discussing both approaches, using backticks to wikify OR using them to do substitution. I strongly prefer the latter due to the performance penalty associated with wikify.

See

• https://github.com/Jermolene/TiddlyWiki5/issues/5121
• https://github.com/Jermolene/TiddlyWiki5/issues/5110

But let's not derail Tony's thread by going too far off topic. If we want to discuss this further we should start a new thread.

Cheers,

Saq

[TonyM]

Saq et al,

Thinking a little further on this issue of "inline concatenation of various tiddlywiki values", I believe I have just found a quite elegant solution.

Given your complaint about Wikification performance this returns the "evaluated text"

Create a tiddler called "&" for concatenate containing

{{{ [<currentTiddler>split[ ]] +[join[]] }}}

This spits the input by spaces/run and then joins them.

Now to concatenate use;

{{{ filter || & }} 

{{{ filter-run filter-run ||&}}

Where filter can access any value available to a filter, use space separation of runs

{{{ $:/string/ [<var>] / [{!!fieldname}] [[/suffix]] ||&}}} 

{{{ $:/string/ [<var>] / [{!!fieldname}] [[/suffix/]] [all[current]] ||&}}}

{{{ $:/system/ [<currentTiddler>] ||&}}

Now I am already taking this code pattern further, 

• This allows the concatenation of values passed as a parameter/set of filters
• but for efficient use I know need to determine the best way to get a result into a filter. I expect we must use set or vars.
  

Regards

Tony

[TonyM]

And using codaCodas examples prior;

<$wikify name=style-value text="""color: {{!!color}}""">

 style=<<style-value>> 

</$wikify>  

<span style={{{ [[color:]] [{!!c}] +[join[]] }}}>Check this in devtools</span>  

<span style={{{ color: [{!!color}] ||&}}}>Check this in devtools</span>  

Again great for attribute values and parameters, but still need another step to get the result into a filter.

Tony

Tones

[coda coder]

Tony - Looks good on  a first pass... I'll need to look at it properly tomorrow (it's late here).

[TonyM]

codaCoda,

I have updated the content of "&" to return text only

<$text text={{{ [all[current]split[ ]] +[join[]] }}}/>

Important guidance is 

• the "filter" given to the transclusion needs each value to be treated as a title hence 

• • $:/string/ [<var>] / [{!!fieldname}] [[/suffix/]] [all[current]]

• • except for literals without white space, we need to wrap it in at least one [ ]

I think typically we are forced to use wikify still rather than set or vars to get such variables to operate in a filter.

<$set name=ghost-tiddler value={{{ $:/ghost/ [all[current]] || & }}}>

<$link to=<<ghost-tiddler>>/>

<$list filter="[<ghost-tiddler>has[title]]" emptyMessage="No ghost">

Ghost tiddler <<ghost-tiddler>> exists

</$list>

</$set>

This does just not result in <<ghost-tiddler>> "$:/ghost/currentTiddler"

I have raised this issue, but Saq has an argument that wikify is a poor performer.

Regards

Tony

[saq.i...@gmail.com]

An important distinction to make is that between filtered transclusions in wikitext, and filtered attributes for widgets.

In the former, the {{{ filter || template }}} format is supported because the output gets wikified.

In the latter, this is not supported as the literal value of the filter is assigned to the attribute, similar to attribute={{!!field}}

[TonyM]

Saq,

In effect are you a saying in the latter the reference to the value is the result rather than the value?, I understand the complexities here (I think) however I expect 99% of users 

• Do not understand this distinction
• Think the value is returned, and expects it in filter logic

This is why I believe strongly we should provide a short method to do this and my issue

Regards

Tones

[saq.i...@gmail.com]

@Tones wiki syntax for transclusions, and syntax for indirect and filtered attributes for widgets, are two entirely different things and changing them would not be backwards compatible.

Refer to this thread that explains the same difference but with regards to double brace transclusions and indirect attributes: https://groups.google.com/g/tiddlywiki/c/YCdcBV88h_g

Just as {{||template}} is not supported as a widget attribute, {{{filter||template}}} is not supported for filtered attributes.

The filter is evaluated and the literal result of the filter is assigned to the attribute. Filters do not have any concept of templates.

Regarding wikify, due to the performance implications, it is my personal opinion that we should NOT be facilitating its' usage and associated code patterns, and instead should be leading users towards more optimal ways of doing things. Wikify should be a tool of last resort when there are no alternative ways of doing the same thing. If you look through the TW core you will see that wikify is used exceedingly sparingly even though the entire UI is built from wikitext. Ultimately, however, it is not my call as what is supported in the core or not so its not me that you need to convince. :)

That said, I do completely agree that we do need some better form of variable substitution or string templating support.

Cheers,

Saq

[TonyM]

Saq,

As you are aware the wikification process is linked to the render process. I am trying to keep this issue focused and fix the gap I have highlighted. The term I try and use is "evaluate", basically to resolve a value from the wikitext elements and use it in logic and other tests, ideally without wikification, but evaluation. Can these be separated?, if not then wikification would be a good target for preperformance improvements, it's a nexus between the parsing and rendering, logic and practical use.

Just as {{||template}} is not supported as a widget attribute, {{{filter||template}}} is not supported for filtered attributes. 

I am not so sure about this statement. I understood the template pre-processes the result then delivers the value(s) to the attribute. I will look more closely.

Tones

[saq.i...@gmail.com]

@Tones

Just as {{||template}} is not supported as a widget attribute, {{{filter||template}}} is not supported for filtered attributes. 

I am not so sure about this statement. I understood the template pre-processes the result then delivers the value(s) to the attribute. I will look more closely.

Please feel free to confirm. My statement is based on the code, the documentation and the observed behaviour.

 Cheers,

Saq

[clutterstack]

Hi Tony,

Just seeing this now. I suspect that if I'd had this as a reference in the summer, collecting so many gotchas in one place, it would have saved me a lot of time thinking in circles. Thanks for sharing it!

Best,

Chris