Code Type:
Code Scope of Action:
Code First Added:
Code Altered:
^value(expression)^
The argument to ^value^ is an expression, a value that could be assigned to an attribute. ^value^ evaluates the expression and exports the result, as a string (some data types may also require the format() operator too). This allows manipulations for export use without needing to, for instance, hold the value in a user attribute first.
^value^ is a more flexible replacement version of the deprecated codes ^get^ and ^getFor^ but which still allows the called attribute's value to be manipulated. For example:
^value($Width)^
exports the width of the current note. To export that attribute value for a different note (than in current scope) use action code style offset addressing. So, to call the value of $Width for "Some Other Note" rather than from the currently-processed note, use:
^value($Width("Some Other Note"))^
Examples
Number-type data:
^value(sqrt($Width))^ gives: "1.732050807568877".
^value(sqrt($Width).format(2))^ gives: "1.73".
String-type data:
^value("$Name: "+$Name(parent))^ gives: "$Name: Export Codes - Full Listing".
^value($Name(parent)+":"+$Name)^ gives: "Export Codes - Full Listing:^value(expression)^".
Note that ^value($Text)^ equates to ^text(plain)^.
Color-type data:
^value($AccentColor)^ gives: "dark warm gray dark".
^value(format($AccentColor))^ gives: "#403a35".
^value($AccentColor.format())^ gives: "#403a35".
Date-type data:
^value($Created)^ gives: "
^value(format($Created,"l h:mm"))^ gives: "03/07/2007 20:54".
^value($Created.format("l h:mm"))^ gives: "03/07/2007 20:54".
^value(format($Created,"l"))^ gives: "03/07/2007".
^value($Created.format("l"))^ gives: "03/07/2007".
^value(format($Created,"*"))^ gives: "Tue, 3 Jul 2007 20:54:36 +0000".
^value($Created.format("*"))^ gives: "Tue, 3 Jul 2007 20:54:36 +0000".
N.B. Unformatted Date-type data returns the host OS' local "short date" format plus time (in hh:mm form). For the aTbRef author's UK-locale OS that equates to a format string of "l h:mm" but it may vary for other OS locales. However, a date format string must be given if format() or .format() are used:
^value(format($Created))^ gives: "" (no date format string!).
^value(format($Created))^ gives: "03/07/2007, 20:54" (no date format string!).
See also ^action ( action )^ usage which allows action code to be run during export.
Another useful aspect of ^value^ is that it give access during export to 'raw' attribute data without any process. That is why there is the reference above to some data types needing use of format(). The upside of this raw state is attributes like HTMLMarkupText and HTMLQuoteHTML have no effect; unlike older versions non-ASCII are not encoded. If using the HTML Export process to generate/export formats other than HTML or if accessing the command line it is often necessary to use different forms of escaping. These different outputs can be achieved by using the action code formatting operators within the ^value()^ call. For exporting $Text, in HTML format, ^text^ will give a better result but for other export formats ^value($Text)^ may suffice.
Passing variables into export code
From v9.3.0, ^value()^ can be used, within the context a single template, to insert a var() variable declared within an ^action()^ code. Note that the variable must be declared before use, i.e. before as in reading template code top to bottom.
Replacing deprecated export codes
^value()^ replaces both the deprecated ^get()^ and ^getFor()^ codes. ^get()^ maps to ^value($SomeAttribute)^ and ^getFor()^ maps to offset use ^value($SomeAttribute("Some Other Note))^. If existing documents use the older codes they will work for the present but it is highly recommended updating them to use ^value()^ instead.