Inheritance in Tinderbox v6+

Tinderbox 'TBX' document files pre-define over 350 attributes, the majority of which the user can modify. A few are read-only because they are constantly re-calculated. For instance, a count of the number of child notes of the current note. Those familiar with databases can think of the attributes as being like database fields. For the general user, it is easier think of them as things you may want to view and/or alter as part of the way your use of Tinderbox. They might control how a note looks on screen (as in this tutorial) or store information about the note that either does not in the note's text or might best be accessed separately. They are the note's metadata: an event's due date, the price of a purchase, a list of tags reflecting the subject of the note, etc.

For historical reasons, the attributes are shown in Tinderbox listings as named groups or 'categories' that, due to the march of progress, may in some cases seem slightly arbitrary. Generally, you do not need to know or understand the group names—as long as you know the attribute you need there should be at least one method to find it directly. Over time most places in the UI where you may need to select an attribute there is a search box with auto-complete, lessening the need to first find the right group listing to see an attribute.

As well as the built-in or 'System' attributes, users can add their own attributes to the document. Unsurprisingly, these are referred to as 'User' attributes. Aside from how they get created and that they only exist in their parent document, System and User attributes behave alike, especially in terms of general inheritance.

This tutorial uses Key Attributes for illustrative purposes, but remember Key Attributes are simple a method to display a user-selected choice of attributes in a note's text: they have no special function beyond that task. This noted specifically as some who are new to Tinderbox assume the term 'key' implies some special purpose.

Tip: Every object—note, container, agent, etc.—possesses every attribute in the document. Not every object uses every attribute, but this is a nuance the average user will not notice and need not worry about. For instance, only agents use an agent query. As data is not stored for attributes that do not yet have a non-default value this helps keep TBX flies more compact. For a database person, this is like a flat-file database. For the less computer-based user, this is like a spreadsheet (every row has every column even if unused, and vice versa. A paper analogy is the printed library index card or Rollodex address card: every card has every box printed, whether filled in or not.

In Tinderbox's internal scripting language called 'action code' (that not everyone may need to use), references to attributes are made by using the attribute's name prefixed with a '$', e.g. $Color. This also makes it a convenient shorthand to use in documentation, support forums, etc., when talking about an attribute. If you use any Tinderbox related forums, you will likely encounter the same method for referring to an attribute name in text.

Therefore, in the context of this article "$Color" should be read as referring to "the attribute with the name Color".

The relationship above shows the possible sources of the default for an attribute value as found in a Tinderbox note. As attributes also control many aspects of the how data is displayed, knowing how these values are inherited and (re-)set will help you understand the look and feel of a Tinderbox document as well as any data the user adds.

The inheritance principle applies to attributes of all data types. There is a slight difference of scope in the case of user attributes. As these are created within a document, their inheritance tree starts part way down the above sequence, at "Document attribute defaults".

Regardless of how other outliners behave, Tinderbox's attribute value inheritance is not connected with a note's outline position. Simply placing one item inside another does not create inheritance. In Tinderbox, notes inherit from their grandchild as easily as from their parent, or indeed from a completely different branch of the outline.

Pro tip: if desired, Tinderbox can be manually configured by the user to make notes inherit values from their parent, but that is outside the scope of this tutorial.

[Note the above dialog tends to get tweaked over successive OS releases so your own Mac version of the dialog may differ slightly in layout & labelling]

This section is a slight aside, as OS Settings inform how some data types are shown rather than actual attribute values. However, it is pertinent to consider in inheritance terms, as these setting affect how you will see some data displayed in Tinderbox (and dictate the format used to enter things like dates). Here the author is British so the OS is set to use UK settings. These will affect things like:

• Date formats, including day/month vs. month/day order, date format delimiters (slashes, hyphens, etc.), time formats.
• Currency delimiters (full stop, coma, hyphen, etc.).
• Alpha-numeric sort order: for accented languages this may differ from English.

So, the 'locale' of settings used on your Mac will affect how attribute data is shown and/or edited. The most obvious example is that of dates: on a UK system, 24 March 2014 would be shown or entered as "24/03/2014" whereas for a US locale it would be "03/24/2014". If you change your OS settings, Tinderbox will adapt to reflect the change (if Tinderbox is open during the OS settings change to may need to restart the app).

Tip: New to Tinderbox v6+ is action code support for altering the locale used in certain aspects of the app. If you need this, see documentation, aTbRef, or ask tech support.

When Tinderbox creates a new document, it pre-configures all the System attributes and assigns each a default value (which can be a value of nothing/no value). If no other changes intervene, when a new note is added to the document, it directly inherits those values as the defaults of its own attributes. Data-type defaults in aTbRef.

N.B: this is an expert user feature—general users can skip straight to the next section.

Config files are a way of pre-setting some document preferences/attribute defaults so that all new documents receive that customisation. Effectively it customises the app's built-in defaults. More at aTbRef.

These are effectively per-document preferences that can, if desired, alter the defaults for some System attributes. The Settings dialogs do not list attributes directly, but rather some of the controls have the effect of altering the built-in default values of some of the System attributes. More at aTbRef.

For instance, the font used for all note text is 'MercurySSm-Book', a serif font. You may prefer a non-serif such as 'Helvetica Neue'. By changing the Documents Settings 'Text' tab's 'Text font' setting to 'Helvetica Neue' you are in fact seeding a new default—but only for the current document—of an attribute $TextFont, which tells Tinderbox which font to use when adding text to a note.

Document attribute defaults are the result of all of the processes already described and are effectively the baseline for attributes' default values once a document is created.   Defaults are documented in resources like aTbRef but can always be viewed in Tinderbox via the Document Inspector…

1. The Document Inspector is accessed by clicking the second button on the top button bar on the Inspector.
2. Click the System tab to see data about System attributes.
3. Two pop-ups allow selection of an attribute category and then the attribute within that category. If unsure, use documentation to find the category to whichan attribute belongs.
4. The current default—this is where the default value is edited. As this is a 'boolean' attribute (tick-box, yes/no), the choices are 'true' or 'false' (lowercase, case-sensitive).
5. A short description, derived from aTbRef, is provided for each System attribute to help identify its purpose.

Once a change is made (at #4) the effect is immediate for all notes inheriting that attribute default. For those System attributes that inherit from Document Settings, the latter is an alternative way to alter a default during the life of the document.

1. The Document Inspector is accessed by clicking the second button on the top button bar on the Inspector.
2. Click the User tab to see data about user-created attributes.
3. The current default—this is where the default value is edited. As this attribute holds year data and will not be arithmetically manipulated, a string-type (text) attribute is as useful as a number-type. The attribute value will vary for each actual data note so there is no point in giving a specific default value in this case.

Once a change is made (at #3) the effect is immediate for all notes inheriting that attribute default.

Note that unlike System attributes, for User defaults you may (optionally) add your own definition for the attributes you add to the document.

A way to think of a prototype in Tinderbox is as a pre-customised note. Any note may be made into a prototype at any time (or indeed cease to act as a prototype); that process is not covered here. This customisation is achieved by setting (non-inherited) values for some attributes.

Remember that intrinsic attributes are excluded from inheritance via prototypes.

Tip: the status of a note acting as a prototype is stored in the attribute $IsPrototype. The prototype used by a note is stored in $Prototype.

Lastly, an attribute value can be set in a note, the lowest and most local level. Although other notes may use the same value for the same attribute this is coincidental, they may either inherit as similar value or have the same local value. The note with a local value is now no longer inheriting a value for that attribute, though—not generally by intent—it can be the same as the inherited value. Note though, that inheritance is per attribute. Even if one or more attributes have a local value, all other attributes still retain their inheritance.

For most users, this is the context where you will do the majority most of your editing of attribute values. Attributes can also be altered by action code as well as by manual edit or inheritance.

A reminder for those use to hierarchy based inheritance in other programs, this is not so in Tinderbox! If you want child notes to inherit their parent's (relevant) attributes, this is possible to do via prototypes and $OnAdd—but outside the scope of this tutorial.

An exception to the inheritance principle is that intrinsic attributes do not inherit. This is deliberate as, for instance, this allowaliases to have a different $Xpos and $Ypos from that of their original note, whether they are in the same map or a different one.

This tutorial has used a very simple and visual way to demonstrate inheritance. Remember that these techniques can be used on any attribute(s). It is also not necessary to use note Key Attributes to change values—it is just a simple way to get used to the process. Values can be changed in the Get Info panel, in the Inspector and via action code. It is all very flexible.

This can all seem overwhelming at first. A good tip is to try out the techniques here in a new file so no harm is done if you really mess up the settings. It makes it much easier to experiment, which is an ideal way to learn this aspect of Tinderbox. Now it is time to go and try it for yourself!

Tip: for experimenting, make a new document so nothing is broken if you mess up.