Tinderbox 7 - make a note for each value of an attribute

The values() operator returns a Set, i.e. a list of unique values, for a specified attribute. That attribute is passed (without a $-prefix) as a values() parameter. In v7+, there is an optional first parameter that controls the scope of the values returned. If omitted, the scope is whole-document.

To collect only characters from scenes in Chapter 1 (which we'll assume are child notes of 'Chapter 1'):

$MySet = values(find(inside("Chapter 1")),"CharacterSet");

To return characters only from scenes in Chapter 1 that take place in the country of 'Molvania '(as stored in user attribute $SceneCountry):

$MySet = values(find(inside("Chapter 1")& $SceneCountry=="Molvania"),"CharacterSet");

Tip: If either or both of the group of notes to test or the 'if' condition are complex, you might want to consider first adding a user attribute tio the target notes to make them easier to specify in queries/conditional tests.

To obtain values at less than document-scope, it is necessary to use either collect() or collect_if(). These both return a List [sic] so you will definitely need pass the return values to a Set which will result in a de-duped list of unique values.

To collect only characters from scenes in Chapter 1 (which we'll assume are child notes of 'Chapter 1'):

$MySet = collect(find(inside("Chapter 1")),$CharacterSet);

To return characters only from scenes in Chapter 1 that take place in the country of 'Molvania '(as stored in user attribute $SceneCountry):

$MySet = collect_if(find(inside("Chapter 1")),$SceneCountry=="Molvania",$CharacterSet);

Tip: If either or both of the group of notes to test or the 'if' condition are complex, you might want to consider first adding a user attribute tio the target notes to make them easier to specify in queries/conditional tests.

This is done in a simple rule for the "Character Listing" note:

$Text = $MySet.format("\n")

The rule tells Tinderbox to reformat the list as a single string putting a line return character between each list item. The result is that $Text has a list of characters which each as a separate line/paragraph (the paragraph aspect is pertinent for the next step). Don't worry if the sorting is not as desired as this can be corrected later.

Before continuing, take a look at the $Text and scan the values for anything unexpected. If using collect()/collect_if() this will help spot missing/extra values. If errors are found, fix the $MySet data and let the rule run again. You may find it useful to add $MyNumber and $MySet as key attributes to assist with diagnostic efforts if you have problems.

Next, the selected note's $Text is 'exploded' into discrete per-line notes. The Explode operation is called from the Note menu. Be aware the option is only available if focus is in the main pane and not in the text pane).

There a few things to note on the Explode pop-over:

1. Use the default radio button selection 'Break at paragraphs', i.e. at each hard line-break in the source $Text. (but, see notes blow)
2. Choose the non-default value of 'First Paragraph' from the pop-up list. The default choice is 'First Sentence' such as might cause a source value like 'Fr. Gonzalez' to make a note titled 'Fr', which is not what you want.
3. Tick the box to 'Omit text'. Otherwise the character name will be used as both the new note title and as its $Text. Of coure, if that's what you want, leave the box un-ticked.
4. This pane shows the title and text (if any) of for the new note to be created from the first source paragraph. It can help with checking you've selected the right choice of settings.
5. This shows the number of new notes to be created.
6. (v7+ only). An optional action can be set, which is functional equivalent to a container's OnAdd action.
7. When ready, click the Explode button.

Notes:

• Tip: the number at #5 above should match the source note's $MyNumber. If not, re-check your settings.
• Settings made on this dialog are retained (for the current document) making it easy to repeat the same task
• Whilst breaking a paragraphs is sensible tasks, for many tasks such a importing data formatted in/exported from other apps the use of a custom delimiter is often the better/necessary choice.

Note: in v6, no prototype is applied (see optional step below)

The result of the Explode is a new child container called 'exploded notes'. This name is used for every Explode result, which can be useful if you work involves using this process regularly as it makes it easy to look for such containers and work on their content, e.g. to move them elsewhere, apply attribute values. The container has a key attribute of $ChildCount which helps check the result of the explode when using large datasets.

The other result (v7+ only) is to add a new prototype 'Exploded notes' (note capitalisation difference from container name). By configuring this prototype it can remove the need to use the optional action in the Explode step. From v7.5.0+, this built-in prototype can be added manually before the document's first Explode task. This makes it easier to pre-configure an import process that makes use of the prototype; prior to this you had to do an Explode just to create the prototype.

At this point, if you have made a prototype, e.g. here called 'Character', select the new exploded notes and apply the prototype. You can do this either via the Inspector or by right-clicking the icon of any of the selected notes and selecting the desired prototypes from a pop-up list.

Select all the new notes and then press Shift+Tab to promote them out of 'exploded notes'. Then select and delete 'exploded notes'.

The original post-explode sort order had no particular logic. Setting a new sort ($Sort) to the 'Character Listing' to use note title ($Name) doesn't help much either - as shown here - because the first names are influencing the sort order.

On the sort inspector, the right-hand pop-up (which sets $SortTransform) has a useful option 'last word', which takes the last word of the nominated sort attribute's value.

The 'last word' transform gives a better result. For more simple string values there are usually fewer issues relating to sorting. However, if you have a mix of source values starting with uppercase and lowercase letters, the 'case insensitive' sort transform is probably more useful than the default.

If you have more complex character names like 'Henry Wultz III' or 'Steve P Mollem, Jr.', it might be useful to add new custom String-type attributes $FirstName and $LastName to assist specifically with sorting (or use something like $SortName for the (last) name on which to sort). Either add these to the notes, or more likely to the prototype they use.

For the above example, these might hold the values 'Steve' and 'Mollem' to assits more precise sorting. Again, this sort of sort intricacy is most common with people's names. Generally, just sorting on $Name will suffice for an alphabetical list.

In this case, author notes using the prototype 'Author' will link from the note to any reference(s) using the link type 'Authored'.

As you have likely done some customisation of the original exploded notes, it is probably best to add new items manually as new notes. If the list is big, to detect the new values copy $MySet to $MyList in a new note. In the latter sort the list as per the existing per-character notes and then put the list into the new note's $Text. The new list can then be cross-read against the existing notes and anything missing can be manually inserted/configured.

As above, but use the secondary list to find and delete notes for characters you've discarded.