This article describes how attribute default values are created, inherited and altered. The colours, shapes and general attribute values are based on default values, which can be altered. Tinderbox also offers very simple ways to build nuanced patterns of inheritance to help reflect your data and workflow.
Read to the end and you will understand why a given note in your own Tinderbox document looks as it does - or why it doesn't! Of course, the visual aspects of maps and such are only a small part of Tinderbox's attribute structure, but are the easiest context in which to show the general principles of attribute inheritance.
1. What are Tinderbox attributes?
Tinderbox 'TBX' document files are pre-configured with over 250 attributes, the majority of which the user can modify. A few are read-only because they are constantly re-calculated, for instance the count of the number of child notes that a note has. 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 doesn't 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 historic 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 don't 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.
As well as the built-in or 'System' attributes, users can add their own attributes to the document. These are referred to, unsurprisingly as 'User' attributes. Aside from how they get created and only existing in their parent document, System and User attributes behave alike, especially in terms of general inheritance.
Tip: Every object - note, container, agent, etc. - has 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.
2. Get ready for the $-prefix
In Tinderbox's internal scripting language (that not everyone may need to use), called 'action code', references to attributes are made by using the attribute's name prefixed with a '$', e.g.
$Color. This makes it a convenient shorthand to use in documentation, support forums, etc., when talking about an attribute.
Therefore, in the context of this article "$Color" should be read as referring to "the attribute with the name Color".
3. Attribute value inheritance flows downwards
The relationship above shows the possible sources of the default for an attribute value as found in a Tinderbox note. As attributes also control may 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".
4. Inheritance is NOT based on the actual outline of your data
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.
5. OS Settings
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 English 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 6 is action code support for altering the locale used in certain aspects of the app. If you need this, see documentation or as support.
6. Tinderbox app built-in defaults
When Tinderbox creates a new document, it makes all the System attributes and assigns each a default value (which can be a value of nothing). If nothing else intervenes, when a new note is added to the document, it directly inherits those values as the defaults of its own attributes.
7. Config files (for expert users only)
N.B: this is an expert user feature - general users can skip straight to the next section.
Config files - whose v6 status is still uncertain - 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.
8. Document Settings
These are effectively per-document preferences (and pre-version 6 were called that). They don't list attributes directly, but rather some of the settings have the effect of altering the built-in default values of some of the System attributes.
For instance, the font used for all note text is 'HoeflerText-Regular', a serif font. You may prefer a non-serif such as 'Lucida Grande'. By changing the Documents Settings 'Text' tab's 'Text font' setting to 'Lucida Grande' you are in fact seeding a new default - just for the present document - of an attribute
$TextFont, which tells Tinderbox which font to use when adding text to a note.
During the life of a document, Document Settings (the previous step) can still be used re-define of some attribute defaults.
8.1 Intrinsic Attributes, attribute defaults and non-inheritance
'Intrinsic' attributes are small subset of attributes that never inherit any value below the document-level default, such as
$RuleDisabled.This is deliberate design choice as the map icon size and location may need to vary between originals and aliases. Attributes like
$RuleDisabled help when a rule is set up in a prototype but should generally only run in notes using the prototype, thus the rule can be disabled in the prototype but that setting is not inherited. In some cases, like
$SiblingOrder, the attribute is calculated b Tinderbox but may still vary if a note has aliases.
A fuller list of intrinsic attributes (these may be added to over time so check if in doubt):
9. Document Attribute Defaults
Document attribute defaults are the result of all of the processes already described and are effectively the baseline for defaults once a document is created. Whilst , most are set once the document is first made. Defaults are documented in resources like aTbRef but can always be viewed in Tinderbox via the Document Inspector…
10. Document System Attribute Defaults
- The Document Inspector is accessed by clicking the second button on the top button bar on the Inspector.
- Click the System tab to see data about System attributes.
- Two pop-ups allow selection of an attribute category and then the attribute within that category. If unsure, use documentation to find which category an attribute belongs.
- 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).
- 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.
11. Document User Attribute Defaults
- The Document Inspector is accessed by clicking the second button on the top button bar on the Inspector.
- Click the User tab to see data about user-created attributes.
- The current default - this is where the default value is edited. As this attribute holds year data and won't be manipulated, a string-type (text) attribute is as useful as a number-type. The attribute value will vary per 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.
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. 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 as a prototype is stored in the attribute
12.1 Prototypes & Inheritance
Any note set to use a prototype then begins to inherit the prototype's customisations. Thus if the normal colour of a note (attribute
$Color) is 'warm gray dark', and a prototype then has its
$Color altered to 'green'…
12.2 Prototypes changes cascade
…then the notes using that prototype will inherit that change. This is true for any attribute, System or User, that can be altered by the user - i.e. all except read-only attributes.
Also notice that compared to the previous step's image, when
$Color is displayed as a Key Attribute, the name and value were shown in normal weight font but are now in bold. This is a deliberate tell-tale. Bold text indicates that this particular attribute in this particular note is set 'locally' (or immediately'). Local values always trump defaults.
The same normal/bold hinting is used in both Key Attribute tables in notes (as seen above) as well as in the attribute tables used in the Get Info dialog. One other styling used in these tables is a light grey text for attributes that are read-only, and which can't be edited.
12.3 Prototype values trump document defaults
Proving the point that the set-in-prototype values trump defaults inherited from higher levels in the inheritance chain, if the document default for
$Color is now set to 'red', notice that only the note not using the prototype takes on the revised document default of red. The prototype is green because its
$Color was expressly changed to 'green', whilst the current note is inheriting green from the prototype.
Notice also that for the note using the prototype, the listing for
$Color is not in bold. This is because, whilst the
$Color value is set locally in the prototype, the same value is simply inherited by the note using the prototype.
12.4 Are prototypes required in a document?
There is no requirement for you to use prototypes at all, or to use them with all notes if present. They are a simply, easy and powerful affordance offered by Tinderbox. It is important to understand how they work so you know their effect if you want to use them.
A note can be turned into a prototype at any point. This is part of Tinderbox's ability to allow for emergent structure (delayed formalisation). In a traditional application, such usage would likely have to be planned and implemented before other content was added, or re-added.
Prototypes can even inherit from other prototypes allowing for quite nuanced behaviours.
13. Note local values
Lastly, an attribute value can be set in a note. Although other notes may use the same value for the same attribute this is coincidental. The note is now not inheriting a value at all.
For most users, this is the context where you will do the majority most of your editing of attribute values. Of course, attributes can be altered by action code as well as by manual edit or inheritance.
13.1 Note local values trump inheritance
Consider the diagram above and the note at the bottom of the map. It is using a prototype ('A prototype'), inheriting the
$Color 'green'. If the the note has its
$Color set to 'orange', the new colour - by being set local to the note - trumps the prototype-inherited colour. Not the
$Color data in the Key Attributes is listed in bold as it is now set local to this note.
13.2 Can inheritance be restored after setting a local value
There is one other important aspect to consider: how to re-enable normal inheritance once a local value is set? What happens if the bottom note's
$Color is simply set to be the old inherited value? Whilst the bottom note is now green as before, notice the
$Color data is still in bold. So, the note has the same value as the prototype but is not inherited.
13.3 Re-enabling inheritance
The answer to the problem is to right click the attribute (in either the caption or value columns) and in the pop-up menu then click Use Inherited Value. This resets inheritance. Will the note be red or green?
13.4 Inheritance restored
'green', of course! As the
$Color entry is now not bolded, it is clear the 'green' value is now inherited from 'A prototype'.
Because the prototype's own
$Color is set locally, that blocks it inheriting the document's 'red' default. Another way to prove the point is to stop using the prototype…
Tip: to reset inheritance in action code, set a value of ';' . Thus:
13.5 Inherited local values without a prototype
Now, without a prototype, the bottom note inherits the altered document default colour of 'red'. Note too, that
$Color isn't shown as a Key Attribute any more, even though the bottom note has focus. Why? Because that too was a customisation inherited from the prototype, showing that inheritance isn't just things as obvious as note colour.
13.6 Re-setting all defaults
For completeness, restoring the document-level
$Color default back to the standard new document default re-applies a value of 'warm gray dark'.
13.7 Note local values can inherit directly or via prototype(s)
Summing up, the original inheritance hierarchy can be re-stated as shown above. Prototypes are an optional part of the inheritance chain - they are part of it only if a note is set to use a prototype**. Otherwise a note inherits from document level defaults.
It has also been shown that whilst local values trump inherited ones, it is still possible to re-enable inheritance, offering a lot of flexibility.
** Prototypes can inherit from other prototypes, so there may be several in the chain between the document level default and the inheriting note. However, this behaviour is uncommon and only needed in more specialist document with highly defined rule-based structure. Intrinsic attribute values are never inherited.
14. Remember: inheritance is not based on outline postion
A reminder for those use to hierarchy based inheritance, this isn't so in Tinderbox. If you want children to inherit their parent's (relevant) attributes, this is possible to do via prototypes and
$OnAdd - but outside the scope of this tutorial.
15. Intrinsic attributes don't inherit
An exception to the inheritance principle is that intrinsic attributes do not inherit. This is deliberate, so as to allow aliases to, for instance have a different $Xpos $Ypos from that of their original note.
16. More than one way…
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's 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's time to go and try it for yourself!
Tip: for experimenting, make a new document so nothing is broken if you mess up.