Wiki: Update to Tokens (manual page)

Wiki
1

Submitted for your review, comment, and/or revision, the following Wiki article has been updated:

Tokens (manual)

Primary Changes:

  1. Major rewrite to improve clarity, especially for new users and users with little or no programming experience
  2. Provide clear examples, including images
1 Like
2

It looks good to me, except it doesn't explain the why part, which is that without tokens the text is just plain text, and that the tokens exist to allow you to include non-contanst text.

The closest it comes is this line:

The “ []() ” are just characters you type.

Which is almost the reverse.

Somewhere near the top it should make it clear that these text fields contain static text, and that tokens are the way to enhance the text with non-static text, and since they have to me marked/differentiated from the static text in some way, that is what the percent character is for.

3

Well, actually I think this statement:

==You can enter a Token in any text field== in an Action, and when the Macro is triggered and the Action is executed, the token will be replaced by the value that is returned at run time.

Combined with the example:
image

does a good job of explaining the "why", or purpose / use case of Tokens.

However, to specifically address your concern, I have updated the wiki:

You can enter a Token in any text field in an Action, and when the Macro is triggered and the Action is executed, the token will be replaced by the value that is returned at run time. ==This allows you to easily combine static text with dynamic data that is supplied at run time==, in most any Action that has a text field, like Display Text and Set Variable to Text.

Will that do?

4

Its a good improvement. I think an action that has more static text my help, maybe something that is like a form letter, something like:

Dear %Variable%FirstName%,

On %Variable%Date% you purchased our lovely product.  You can find out more at (%SafariURL%).

Or even instead of using strict markdown (which is confusing because the only “text” characters are brackets with their own meanings, expand the text to something like:

Look at this neat article on %FrontBrowserTitle% I just saw at (%FrontBrowserURL%).

Basically something that makes it clearer that the tokens are frequently inserted as placeholders in text.

I suspect someone who doesn't know markup is going to be confused by the meaning of the brackets in the current example and think they are part of the token processing.

1 Like