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 On Wednesday, September 30, 2020 at 10:17:43 PM UTC-4 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. > > 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 <https://tiddlywiki.com/#TextWidget>, $macrocall > <https://tiddlywiki.com/#MacroCallWidget>, $wikify > <https://tiddlywiki.com/#WikifyWidget> and $transclude > <https://tiddlywiki.com/#TranscludeWidget>, 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 > <https://tiddlywiki.com/#HTML%20in%20WikiText>, 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 > <https://tiddlywiki.com/#Macro%20Calls%20in%20WikiText> > > 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 > <https://tiddlywiki.com/#Filter%20Operators> 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 transclusionsAlso 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 > <https://anthonymuscio.github.io/#somename> a tiddler link > 2. {{{ some name }}} some <https://anthonymuscio.github.io/#some>name > <https://anthonymuscio.github.io/#name> two tiddler links > 3. {{{ [[some name]] }}} some name > <https://anthonymuscio.github.io/#some%20name> tiddler whos title > contains spaces > 4. {{{ [[somename]get[caption]else{!!title}] }}} caption of somename > <https://anthonymuscio.github.io/#caption%20of%20somename> tiddler > whos title contains spaces > 5. filtered transclusions can be placed inside a TextWidget > <https://anthonymuscio.github.io/#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 > <https://anthonymuscio.github.io/#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 widgetsSometimes 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 resultIn many cases such > as the ListWidget <https://anthonymuscio.github.io/#ListWidget> the > content is used such as for the display templated of the list resultsIf > 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; > > <¯ocall $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 SubstitutionsA 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 parametersEach 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 > evaluatedOther > 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. > -- You received this message because you are subscribed to the Google Groups "TiddlyWikiDev" group. To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywikidev+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidev/79bae84e-8c8e-4058-a02d-9d9b08a3b33fn%40googlegroups.com.
