Clarification on the use of hashmap(s)

#1

If you search TiddlyWiki.com for “hashmap” you will receive a list of tiddlers, mostly WidgeMessages that mention a hashmap. Often in relationship to the parameter paramObject - Optional hashmap of additional tiddler fields.

  • There is a hint this is a json string of some kind.
  • I suspect someone writing core and JavaScript plugins may know this or it has a particular meaning, opaque and undocumented for most users.
  • There is a little more info in https://tiddlywiki.com/dev/

It seems to me to be able to generate and use a hashmap, may prove useful to some designers and perhaps more so now we have more JSON handling features, custom widgets and more.

If you understand this and can share some more details I would like to explore this, and possibly update the documentation.

  • I am interested primarily as it relates to TiddlyWiki Script, not writing JavaScript and perhaps, making use of the paramObject parameter

Perhaps “I am fishing a little here for possibilities” but one use case may be, being able to generate, store and apply, a combination of fieldnames and values for application creating new tiddlers, cloning or “synchronising” fields between two tiddlers.

Further use of $params with $parameters widget
#2

Yea, that’s an unlucky formulation, which was introduced very early in the documentation process and has never been changed since.

  • The tm-??? messages usually have 1 main parameter, which is named param.
  • Where param is a placeholder that can be anything.
  • It depends on the message function, what param really is.

eg: tm-new-tiddler documentation says:

The new tiddler message creates a new draft tiddler and adds it to the current story. It requires the following properties on the event object:

!Name !Description
param The optional title of a tiddler to use as a template for the new tiddler
paramObject Optional hashmap of additional tiddler fields
navigateFromTitle Title of the tiddler from which the navigation to the new tiddler was initiated

So param expects a tiddler title that can be used as a template.

  • In the example below if the “TaskTemplate” tiddler exists, it will be “cloned” with a new title.
  • If it does not exist an empty tiddler with the title: TaskTemplate will be created.

With very early (alpha) TW versions, the button-widget was the only widget that could define user actions.

<$button message="tm-new-tiddler" param="TaskTemplate">New Task</$button>

It turned out, that this mechanism is “clunky” and users requested improvements.

So a mechanism was introduced to allow users to add additional parameters by name. Since those parameters are user defined documentation authors do not know their names upfront.

That’s why the name paramObject was used. In reality paramObject is JavaScript internal variable and cannot be accessed or created by the user. It’s created by widgets that allow dynamic parameters to be sent to eg: actions.

An example: The user wants to add dynamic fields without a template tiddler

It’s possible to add dynamic fields as a paramObject as follows.

\procedure createNewTiddler()
<$action-sendmessage $message="tm-new-tiddler" 
    title="This is newly created tiddler"
    tags="OneTag [[Another Tag]]"
    text=<<now "Today is DDth, MMM YYYY">>/>
\end

<$button actions=<<createNewTiddler>>>New Tiddler</$button>

The parameters / fields are internally handled as a core JS-variable named paramObject.

This variable name was used in the wikitext documentation, which obviously is confusing since it’s not a real thing users can manipulate directly.

Hope that makes sense
-mario

2 Likes
#3

Thanks @pmario should we remove that attribute and references to hashmap? I can do it I am just not sure.

#4

IMO the WidgetMessage: tm-open-window uses better formulation. eg:

The tm-open-window [[message|Messages]] opens a tiddler in a new //browser// window. If no parameters are specified, the current tiddler is opened in a new window. Similiar to tm-modal any additional parameters passed via the <<.param “paramObject”>> are provided as variables to the new window.

!Name !Description
param //{default param}// Title of the tiddler to be opened in a new browser window, defaults to <<.var “currentTiddler”>> if empty
template Template in which the tiddler will be rendered
[. . .] shortened for better readability
//{any other params}// Any other parameters are made available as variables within the new window

The tm-open-window message is best generated with the ActionSendMessageWidget, which in turn is triggered by a widget such as the ButtonWidget. The message is handled by the core itself.

I don’t know if this makes more sense if you read it the first time without the info from the post above?

-m

#5

We should come to a conclusion first. @jeremyruston … Any thoughts?

#6

@Mark_S kindly contributed these improvements to the docs for tm-open-window in November 2021:

The idea in the discussion was to roll these changes out to the other message tiddlers.

#7

I wasn’t sure if the issues that had hung up that PR had been resolved satisfactorily. That is, can that documentation tiddler be used as an instructional tiddler going forward?

Coming full circle, I think the original inspiration for that PR was a post by @TW_Tones in the forum. Down in the documentation community thread.

#8

I think we can go forward if we put the actions out of the button-widget body. As the code below shows.

I do remember my concerns now. I had a problem with the action-widget inside the button-widget, which causes all sorts of update problems.

It seems I did have a typos somewhere while testing that’s why I thought we need to change the docs macros. — We do not

The following example code should work and would create an output I’m happy with.

<$macrocall $name='wikitext-example-without-html'
src="""\define openWindowAction()
<$action-sendmessage 
  $message="tm-open-window" 
  $param="$:/temp/openme" 
  template="SampleWindowTemplate" 
  windowTitle="My Window Title"
  width="640"
  height="480"
  something="This is my new window. There are many like it, but this one is mine." />
\end

<$button actions=<<openWindowAction>>>Open Window</$button>
""" />