What is a concrete example of using “link actions”? I read the write up, but I’m not sure what the real world implications or use cases are.
I have a file with films and filmmakers. The link type “wrote” has the action:
$Screenwriter(destination)=$Name(source);
I link from director note to a film note and the screenwriter attribute is automatically set.
It’s a small use case but is an example. The link actions are a new discovery for me.
1 Like
OnLink actions were a new addition to v8.0.0 (and added on the last build before release). They were initially described thus:
OnLink actions : LinkTypes can now define an OnLink action that will be performed whenever a new link of that type is created. When running the OnLink action, source is bound to the link’s source note and destination is bound to the link’s destination note. The designator this is also bound to the source note.
Notice, that unlike other actions (OnAdd, AgentAction, etc.), OnLink is not an attribute but is essentially a property of that link type. Not it is scope at link type level and not the individual note. Here, is a specimen action defined for link type ‘response’:
I now drag a ink from Note 1 to Note 2 and set the link type as response:
Setting colour is a trivial example, but it does give a clear indication of the mechanism. Note that if I change the link type of an existing note to ‘response’ the OnLink is not triggered. THere is also (lest you wonder) no notion of an OnUnLink:
From v8.1.0, OnLink actions no longer fire when a document is opened.
As to the real-world use case, I’m not sure. I can find anything that appears to be the original feature request (which doesn’t mean there wasn’t one!). Perhaps the person who asked for the feature could de-cloak and explain the rationale for the feature?
3 Likes
I have no connection to the feature request but before discovering this, I was setting attribute values manually and then trying to create links based upon them using stamps and agents. I wasn’t good enough at the process to make it anything but fragile.
Once I figured out the designators (destination, source), using the links to set attributes works much more easily and reliably for me. I’m currently using seven link types to set a variety of attributes automatically.
1 Like
Are you setting attribute values? I guess another use is to apply prototypes to a target. It’s not that there aren’t plenty of ways to set a prototype but I can see if one is a visual drag-link sort of person, this approach might seem more intuitive than simply selecting a note and setting the prototype pop-up menu.
In my case, I have author/director/artist notes with a lot of info packed into attributes. When I add a specific novel/film/installation note, I add basic object info (prototype, dates, etc.) and then use the link to fill in chunks of info already stored in the author notes rather than doing it manually. So the action code is pretty basic “fill this from that” stuff with the link types “wrote,” “directed,” “photographed,” etc. each filling in different pieces of the object note’s info.
There are many ways I could do this but being able to attach the action to the linking feels easier to me.
Interesting. For the OP, another way of seeing the last is of using links to do the same as might be done with a stamp, the stamp code being applied varying by the link type being created.
1 Like
Thank you Brian and Mark. The penny dropped 
True, but different.
(FWIW, I could see the link action using runcommand to run a script asking for text and using that result to add a note to an attribute in source that explains the purpose of the link. Different approach than the recent link “comment”.)
Another example: let’s suppose we have a container of SOURCES that we plan to consult for an upcoming project. It’s a reading list.
Now, we’ve settled down to write a review paper based on what we’ve learned. Our old list of SOURCES already has the bibliographic information; when we cite a source in the text, we add a reference link from the footnote to the source.
Now, the reference link can perform the OnLink action
$Cited(destination)=true;
to set the boolean user attribute Cited. This makes it easy to construct a bibliography of the sources we actually used:
Agent query: $Cited==true
sort: Author (last word)
sort also: PublicationYear
I also suspect that there may be interesting reasons to use OnLInk actions to set the prototype of the destination.
1 Like
I had not noticed this feature was added in 8.0, but I can see a use immediately along the lines you describe. In my translation project I have several types of footnote (philological, philosophical, word choice). I have link types for each, but with a link action I could set the destination note’s prototype correctly too.
One possible extension would be if there were a new automatically created NLP attribute for the note to determine the language (e.g. French or English) I might set my prototypes differently depending on this value.
See $DominantLanguage.
1 Like
Cool, thanks Mark.
This comment sent me to my stamp inspector. It turns out that placing if()else{} statements that evaluate for things like destination or source prototypes in the link action—and especially chaining them—allows for many of my stamps to become automatic on-link actions. It feels quite a bit like magic.
2 Likes
I take that to mean that rather than write an action per link type, you can write one conditional code stamp and get all the link types to call the same stamp.
This is the sunny uplands of the action code ‘toolbox’. You have to try stuff out rather than be given strict rules, but it leads to happy improvements. I’m guessing the single stamp is mainly larger but not significantly more complex than the many individual codes it might replace. As with prototypes, templates, etc., having one locus for edit/maintenance is a boon—especially as a document grows in amount of content.
2 Likes
Actually and surprisingly, no in my case. For example, I use a “navigation” link type for often temporary links between different notes I’m working on and realized that when I make these links I also always set some basic information about the destination note with a stamp. Now I do it in one go with a link action, in one case by evaluating the prototype and in another by evaluating source note’s name.
if($Prototype(source)=="p1_semester days"){$cDate(destination)=$cDate(destination)+$cDate(source)};if($Name(source)=="Wiki Project"){$AccentColor(destination)=$AccentColor(source);$Pattern(destination)="radial";}
So each time I make a navigation link, TBX now checks the two notes and makes the changes (or not) automatically. The other link types are starting to have different actions based on what I use them for.
2 Likes
Hi @PaulWalters here is a link I just wrote about how I started using Link Actions, Trouble with query in "if" test - #8 by satikusala. I’ve found it pretty useful the last few days.
1 Like