Tinderbox Forum

How to use OnVisit actions and increment Visits in Tinderbox?


I’m just getting started with Tinderbox, and I’m stuck on my first problem: what’s the recommended way to perform an action when a note is selected?

In Storyspace I can do exactly what I want using OnVisit — for example, in Storyspace if I set OnVisit to $Color="red" then click on the note, it turns red. At the same time, I can also see that $Visits is incremented. This is perfect.

But — the OnVisit event only fires in StorySpace. If I open the same .tbx in Tinderbox and click on the same note, nothing happens, and $Visits isn’t incremented.

I know I’ve probably missed something elementary, but this has been bothering me all evening and I’m really stuck. I want to be able to take action on my notes based on my recency and frequency of reading them, and OnVisit seems as if it would be the perfect way to do this. Is there a different way to achieve the same effect in Tinderbox?

Thanks for your patience in reading this, and thank you so much to anyone who can point me in the right direction.


Tinderbox 8.2.3 (b426) and Storyspace 3.2 (b013)
macOS Catalina 10.15.3

I’m not sure you can right now, because it hadn’t occurred to me that this would be useful!

Could you tell us a bit more about what you want to do?

$OnVisit does work in Tinderbox (I just tested!). I suspect the harder part is how do you set it? You might intuit it being the Actions Inspector but to do so you’d logically add $OnRemove as well. But this makes the sub-tab bar busy and adds two obscure actions most Tinderbox users will never use.

If you want to use OnVisit, there are 3 methods so to do:

  • The Quickstamp Inspector.
  • Get Info dialog, attributes tab. $OnVisit is in the ‘storyspace’ [sic] attributes group—as is $OnRemove, though you can find the attribute using the search facility on the dialog.
  • As a key attribute. The table functions much akin to the Get Info table (above).

Aside, from a Tinderbox perspective, both apps have $SelectionCount which increments every time the note is selected (i.e. visited). Pre the Tinderbox v6 Storyspace v3, there was also $ReadCount that recorded opening a note. The latter is moot in the current interface as selecting a note in a view pane ‘opens’ that note in the text pane.

So ‘visit’ is essentially the same as (==) selecting the note.

There is no attribute tracking when a note was last ‘visited’, as in recording the date/time. But you could do this (though I’m not convinced it would be good for a large document.). Still, if you make a Date-type user attribute $LastVisited and then set the doc default for $OnVisit to:


Now, every time you select (visit) a note, $LastVisited is set to the current system date/time. By querying $LastVisited and sorting on reverse date order you will have a list of most recently visited notes!

I think what we, as users, get wrong here is to assume the app can tell when we intentionally chose to look at a note, as opposed to when we did so by simply selecting it. it don’t think the app can easily disambiguate the two.

@eastgate Thank you for replying so promptly to my message, and for showing interest in how I would like to use Tinderbox.

When I wrote my original message, my immediate aim was to keep a record of notes I have viewed recently, as a memory-jog to help me when I’m writing up my work progress in my journal or preparing progress reports for my manager. In DEVONthink, I accomplish this by using Smart Groups to review files I’ve viewed today or this week. If a colleague distracts me with a question and to help them I need to look up a PDF or an email in DEVONthink, I don’t need to take extra time to note this down before continuing with my work. This is a great time-saver, and I would love to be able to do it with note-level granularity.

I do have some other ideas for how I would like to use this feature. Off the top of my head, here are some other possible uses:

  • I’d love to implement a note-history agent as a navigational aid to help me quickly jump back and forth between recently-consulted notes.
  • I’d like to keep a record of notes frequently viewed within five or ten minutes of each other which aren’t otherwise linked, so I can be prompted to consider whether to formally link them or combine them.
  • I’d like to see a list of notes I haven’t viewed since creating them, so I can consider whether they’re still useful to me.
  • It could be useful to me to implement more complex cosmetic “ageing” of notes than that which is available natively in Tinderbox.
  • This is a slightly more job-specific goal and a little tricky to abstract, but given an arbitrary software feature, I’d like to view a list of notes concerning the feature that I last viewed before a historical change to the feature about which I’ve belatedly become aware. (I’m sure this sounds contrived, but I can promise you that all technical authors are familiar with this scenario!)

I can think of ways I might accomplish some of these aims using Keyboard Maestro, although this would introduce maintenance cost and extra potential for human error. I would find it so useful to be able to implement some of this functionality within Tinderbox itself using OnVisit and $Visits.

I’ve since read @mwra’s response and will respond separately — but assuming this isn’t something Tinderbox can do at present, will you please consider this message a feature request for OnVisit functionality?

Thank you again for your help,

@mwra, thank you for your response and the extra context you’ve provided. Thanks in particular for alerting me to $SelectionCount, which was new to me and for my purposes works as a good proxy for $Visits.

Could I please ask which version of Tinderbox you’ve used to test $OnVisit? I’ve attached a screenshot showing my effort to reproduce your steps — so far, I’m still struggling.


My apologies, I was testing in the current beta (as I wasn’t aware of any recent changes relating to OnVisit. It appears otherwise as testing v8.2.3, the current release, OnVisit doesn’t work. So it appears it has recently been fixed and should work in the next public release. Apologies for the unintended mis-direction!

@mwra Ah, that explains it! And there are no apologies required; I enjoyed your post and learned about $SelectionCount, which was new to me.

May I ask — how does one become a beta tester for Tinderbox?

Beta testing - drop and email to Eastgate.

Meanwhile, it looks like a new release is out, v8.5.0b434, and $OnVisit is working. Yay!

1 Like