Tinderbox can use calculated screen titles, based on the $DisplayExpression attribute. The output of this (single) expression is displayed as $DisplayName. For each note, Tinderbox evaluates that note's $DisplayExpression to create the note's name.
Be aware that if $DisplayExpression is empty, or not a valid action syntax expression, or the expression returns no value (such as an an empty string ""), then Tinderbox will instead display the note's $Name value as it will assume you want some form of title displayed.
Although the display expression may include conditional logic (see below) generally it is a good idea to avoid complex calculation within the expression. If the display expression needs to use pre-calculated values that aren't provided by system attributes, then a rule (or other such action method) should be used to calculate the value and place it in a user attribute which the display expression can then evaluate.
Example rule:
$Name +" (" + $WordCount + ")"
…will display the note's word count in brackets at the end of the note. Thus, "Trip Report" becomes "Trip Report (579)". $Name will continue to return "Trip Report".
This attribute is of the 'action' data type. It takes a string argument which must be valid action syntax.
Subtracting two dates returns the number of days between two times, even if the result is a string such as $DisplayExpression. For example:
$Name+": "+($DueDate-date("today"))
will generate strings like: "Buy groceries: 7"
Note the parenthesis around the second part of the expression; if omitted, the expression would be interpreted as an attempt to subtract two strings:
($Name+": "+$DueDate)-(date("today")
If just including a date attribute in an expression it is possible to confuse Tinderbox's parser. Assume $DemoDate for note "Project X" is 28/07/2009 17:57 (on a system using day/month order dates). Consider the following display expressions:
$DemoDate
gives the string: '28/07/2009 17:57'
$Name + " : " + $DemoDate
gives the number string: '3313478996'. This is because Tinderbox assumes the user is trying to do some form of date arithmetic. The way around this is to use the format(data,formatString) operator. The latter emits a string, telling Tinderbox that all it has to do is concatenate the strings. Thus:
$Name + " : " + $DemoDate.format("D/M0/y h:mm")
gives the string: 'Project X : 28/07/2009 17:57'.
Setting $DisplayExpression's code via action code
Another context where care is needed is if setting the $DisplayExpression of another note, e.g. via an $OnAdd action. In this cases it is important to ensure the application understands the result is a string. A good example is when the code returns something that might be a sum, like a date in "20/5/2010" form: The following is not good $OnAdd code:
$DisplayExpression=$Created WRONG
$DisplayExpression=$Created.format("l") WRONG
Although both the above right side values can safely be added into a Text Inspector Title sub-tab's Display Expression box, they do not work for code-based assignments. Instead, it is necessary to force a string:
$DisplayExpression='""+$Created+'"'GOOD
$DisplayExpression='$Created.format("l")'GOOD
Notice, in both how single quotes are needed. In the first case they enclose each instance single instance of a double quote (quote characters cannot be escaped in Tinderbox). In the second case they enclose the whole string as it already contains double-quotes surrounding the date format string.
Conditional Expressions in $DisplayExpression and complex expressions
Display expressions also accept conditional expressions, i.e. using 'if' statements. For example, in a TBX listing books there might be agents listing & sorting by ISBN and by Author. It would be useful if in each of the latter cases the matched note's alias showed the relevant attribute as part of the alias' screen title whilst using $Name in all other cases. Note that with a conditional expression we still need to define something for the 'no match' branch or else notes matching that condition get a display expression of nothing, which results in 'untitled' being shown on screen. Here's the expression:
if($Name(parent)=="ISBN"){$ISBN+" - "+$Name}else{if($Name(parent)=="Author"){$Author+" - "+$Name}else{$Name}}
That is quite a long and complicated piece of code, due to the nesting and that's for only 3 conditions (match 'ISBN', match 'Author, no match). For longer pieces of code it can be useful to put the expression in a note, as the note's text. Conveniently, when doing this, line breaks in the text are ignored making it easy to split apart the various clauses in the expression to check nesting, etc. Assume the expression above has been places in a note called "c_BookDisplay". Now for tour book notes (or their prototype!) you use this Display Expression:
eval($Text(c_BookDisplay))
The result is the same as putting the initial code into each note's $DisplayExpression except now it is easier to maintain and edit.
Another approach can be to store the output of all the complex code as a string attribute and use the latter as the display expression. Thus:
$Rule: $MyDisplayString = if($Name(parent)=="ISBN"){$ISBN+" - "+$Name}else{if($Name(parent)=="Author"){$Author+" - "+$Name}else{$Name}}
$DisplayExpression: $MyDisplayString