Tinderbox Forum

How to mirror the sort order of a source-container within an agent?

I create an agent named “1. Draft”. Its Query is: descendedFrom(/SourceMaterial) so that all notes from within the source-container named “SourceMaterial” will appear within the newly created agent “1. Draft”.

My twofold question is:

  1. How (in outlineview) do I configure the agent “1. Draft” to mirror the sort order of the source-container “SourceMaterial”? (Using attributes such as Created is no option here, since the notes created within SourceMaterial have not necessarily been chronologically created.)

  2. Is it possible to have the agent continuously update this sort order in case the sort order within SourceMaterial will occasionally change?

I was wrong the last time I hazarded a guess, but nonetheless I will try another! I think that if you sort on $SiblingOrder(original) you should get what you’re looking for.

  • $SiblingOrder gives you the sequence of notes within the parent container
  • the (original) ties the sort order of the agents to what you have in \SourceMaterial itself.

Details from aTbRef here. Hope this works.,

Thank you @JFallows. That works.

And to stop the agent form mirroring the occasionally changing sort-order of the SourceMaterial, it seems to work setting $SortTransform to “case-insensitive”. Or am I mistaken here, @mwra?

1 Like

My understanding is that ‘original note’ essentially sorts the container (usually an agent in this case) in the outline order of the original note. Although you can’t use code in this context, in action code terms this csort would be like sorting on $OutlineOrder(original).

By default, sorting is case-sensitive and sorts case-sensitive (so lowercase versions of letters sort before uppercase ones). In older versions that meant sort order aa,bb,AA,BB but in v7(?) that seems fixed to a more human-logical aa,AA,bb,BB.

That makes perfect sense, @mwra. Thanks for the needed clarification.

I delete my last comment to not confuse people.

What are the advantages or drawbacks of having an agent sorting its content “case-sensitve” by default rather than by default sorting as “original note”?

Could someone kindly give a hint here?

1 Like

A moment of existential doubt leads me to wonder: what does $SiblingOrder(original) do in the case where the agent is grabbing notes from multiple containers? I.e., the “originals” were never “siblings”.

1 Like

Interesting Q! A theoretical one, in regards to the original question, in that the first question referred to items all within the same container – ie, actual “siblings.”

But I tried it just now with an agent drawing in notes from a variety of containers. Then I set up a column to display the $SiblingOrder(original) of each note the agent collected.

It worked fine! Ranked them in their respective sibling orders from their different containers, and when there was a tie – two #1s or #2s, for instance – it treated them the way it would as if I’d specified “don’t sort” for the container. (Refinement: when I added a secondary sort, for $DueDate, it broke the ties that way.)

‘original note’ order sorting is useful if you want to know from where in the overall document notes have been matched as the listing is in $OutlineOrder of the originals. It makes little difference when notes are all from the same container.

‘case-sensitive’ order is more useful if you want an alphabetised listing within the agent regardless of from where the notes are matched.

Hmmm. I’m not sure. Here’s my test. I’m not sure how to interpret the result. The value of $SiblingOrder resets to “1” for the first child of each container. In the test shown in the image, the $DisplayExpression shows $SiblingOrder for each “original”. What the sort algorithm with sort == $SiblingOrder(original) seems to be doing is "grab and sort the ‘1s’, then grab and sort the ‘2s’ … ". But, I’m not sure why the sort order of the “1s” is different from the sort order of the “2s” – look at the image.

In true sibling order, I would assume that the agent would sort the parents then the siblings and then the children, to get:


or, perhaps the sibling sort would be the “1s” then the “2s” then the “3s”


but neither case is what happens.

Siborder Test.tbx (66.5 KB)

1 Like

Interesting question, @PaulWalters. Thanks for sharing your test-document.

I played around a little bit with it … and now I even more puzzled. But see for yourself: Video on playing with Siborder Test.tbx

Interesting test doc, but it confirms my thought that it’s better not to set $Sort at all and just to set $SortTransform to original note. I’d accept that’s slightly counter-intuitive, especially to a new user. Anyway, the latter has always given my $OutlineOrder-like output when I’ve wanted it.

So that I understand this, the suggest is to set $SortTransform in the Agent’s KA to “original”. That works.

I didn’t check to see if aTbRef gives that advice (not sure where it would be mentioned), but that’s a useful setting to mention explicitly somewhere so that future readers would find it.

(I agree it is counterintuitive because it means the Sort inspector’s "Sort By is “Sort by don’t sort original”. Odd, and not something I’d hazard a lot of folks would discover on their own.

1 Like

Yes, I concur. On the to-do list. There’s something of a history here and (default) sorting seems to have improved with case-sensistive now sorting aAbB rather than abAB as I recall it doing.

Generally, in simple agent use (1 agent, non-complx query) the agent returns matches in outline order though you can’t rely on that (use ‘original note’ sort transform if in doubt). If the query is complex with manual terms and/or there are lots of agents and/or some agent query other agents the default returned order on fist run is less predictable and a deliberate sort maybe needed.

TL;DR for newer users, don’t assume you need to set a sort until you find you need one.

Also, if setting a sort on containers, and if they change contents infrequently, you might consider removing the sort when not needed or I suspect it’s one more background process you don’t need. Setting a container - not an agent - to no sort simply leaves the current order as is.

I guess all my documents ignore the general rule – LOL. I’m glad to find the info in this thread, because my agents never sort in the correct order.

Indeed, I think that agent sort issue is the genesis of original sort transform which—to my surprise—first appears as late as v5.70 (here). Erstwhile Release notes about the feature state:

A new transformer option provides new flexibility in sorting inside agents.
In earlier versions of Tinderbox, agents often sorted their results using reverse OutlineOrder which implicitly used the OutlineOrder of the original note. In Tinderbox 5, however, aliases have their own OutlineOrder. Thus, sorting in OutlineOrder now reverses the order of the aliases on each pass, rather than sorting the aliases according to the position of the original note.

The new transformer, original note, instructs the sort routine to sort a note based on the properties of the original note, not on the intrinsic property of the alias. When applied to attributes that are not intrinsic, the transformer has no effect.

Which begs the question, as to what Tinderbox does when don't sort and original are selected. my Assumption is uses the outline order which is the canonical structure if the TBX data. But I may be wring…

Seems odd to be opening Tinderbox v5 for the first time in ages though it ran happily on OS 10.12!

If you change $SortTransform manually through a KA or QuickStamp, the inspector automatically displays the correct combination “don’t sort” and “original”. It’s also possible to change the setting in Sort in the Inspector.

For me (v7.1) if I set a $Sort attribute in the Sort Inspector and then use a Quickstamp to change $SortTransform, $Sort is unchanged. That is also what I’d expect based on the v5 RN which covered a niche case where it was desired to sort on intrinsic.

I suspect some aspects of Sort have changed a bit in the move v5 -> v6 and I probably need to review my notes/guidance.

I also note that the transform value is ‘original note’ (all lowercase) and not ‘original’. i’ll correct my posts up-thread.

Clarifying a question upthread, every note has a $SiblingOrder, based on its current position in the hierarchy. So, if an agent gathers notes from different containers and sorts them by $SiblingOrder(original), then all the eldest children should be listed first.

The sort order among the eldest siblings is undefined. A secondary sort criterion might be useful here.

Sorting by $OutlineOrder(original) might also be useful

“eldest children” – do you mean $Created?

My guess is that trying to invent sort algorithms that accommodate all feasible permutations of $SiblingOrder, as reflected in real agents and real containers/hierarchies in the wild, might be impossible. I think your suggestion of $OutlineOrder(original note) and @mwra’s other suggestions, above, are the way to go.

The “eldest child” is the note that appears first in outline order. For example:

  • Fruits
    ** Apples
    ** Pears
    ** Plums

Apples is the eldest child of Fruits.