Prototypes are a method to let a single note specify the default value for an entire class of notes. This is achieved by specifying an existing note as the prototype, via the $IsPrototype attribute; this tells Tinderbox to use the prototype's values for the all the notes set to use that prototype. The easiest way to make a note a prototype is via the Properties Inspector's Prototype tab.
Whenever Tinderbox uses a prototype it will use attribute values from the prototype for its own attributes unless the attribute is specifically set for that note (by action or manual edit). Such manual edits break inheritance (for that attribute only) but inheritance can be reset. Two special attributes control $Rule and $DisplayExpression inheritance. The latter allow such action code to be set in the prototype but never executed there, but rather only run in notes inheriting from the prototype. For that reason, the these attribute values are not inherited or the actions would be suppressed in the inheriting notes too.
When you change an attribute in a prototype, you change it for the notes that use that prototype. A note inherits all attributes from its prototype except intrinsic attributes such as $Created, $Modified, $Height, $Width, $Xpos, and $Ypos (more on intrinsic attributes). It also inherits various layout features and prototypes text if any. Prototypes are not a necessary feature for everyday use but they can powerful time-savers for complex projects.
An existing agent may have $IsPrototype set to true, but in either case any notes set to use that prototype do not themselves become agents.
While most attributes are inherited from prototypes, a few attributes are intrinsic, i.e. they apply to specific notes and are not inherited. For example, $Xpos and $Ypos are not inherited (because moving a prototype should not move notes that happen to use the prototype!). $Width and $Height are also not inherited, but note changes allowing one-time setting of height and width on first applying a prototype (changes in v8.5.0 and v8.6.0). If they were, then resizing a prototype might in turn resize notes that inherit from that prototype—perhaps covering other notes or disrupting a complex map.
If a note or agent is copied and pasted to a new document, the new item does not inherit its source's $Prototype value. This is a defensive assumption by Tinderbox as it cannot be sure pasted notes are from the current TBX and thus that all source prototypes exist. When creating 'template' type notes/containers bear this in mind. Think about using an agent to help set prototype values directly or indirectly via rules and actions. The |= operator can be used to ensure actions occur once only.
Duplicated notes retain the source note's Prototype. For notes that are prototypes themselves, if Note A is a prototype for note B, then duplicating A makes a new note but the duplicate no longer has a prototype link to B. The duplicate does have copies of other outbound links for A, but prototype links are no longer duplicated.
Prototypes can have children that are created/added to a note if that prototype is applied, described in Tinderbox as 'bequeathing' notes. Note: prototype children are not copied recursively. When setting the prototype for a note that already exists, Tinderbox will add new children if the prototype has children, but Tinderbox will not delete any child notes that already exists. If the cloned note would have the same name as an existing child, the existing child will be unchanged and the prototype child will not be cloned.
Prototypes 'Bequeathing' Child Notes
If you want a note that has children to be a prototype, but without its children being inherited, there is an attribute ($PrototypeBequeathsChildren) to control this aspect of inheritance. Inheriting notes gain (a new copy of) all the descendants of the prototype, not just immediate children. The outline arrangement of descendants is preserved, i.e. the note using the prototype becomes a container with the same descendant layout as the prototype. The maximum limit on bequeathed items, limited to avoid accidental infinite recursion, is 500 children (originally 100).
A note with existing children will not be bequeather children, even if an applied prototype is set to do so. this is because the bequeathal notion was for implementing data structures rather than as some form of stamp to add additional children.
Do ensure that none of the bequeathed descendants are actual prototypes. If any of them need to be prototype-based, create separate prototypes and store these outside the bequeathing prototype container. Thus if prototype A has child AB and grandchild ABC, then if either both AB and ABC are prototyped, their bequeathed copies are non-prototype copies of AB or ABC. Instead, if AB and ABC are based on prototypes, then the bequeathed notes inherit their source note's prototype (i.e. achieving the original desired aim).
Agent prototypes can bequeath any adornments saved within them, including image adornments.
If nesting prototypes with no intent to bequeath children, $PrototypeBequeathesChildren should be set to False: note this is the non-default value.
It is possible to designate some prototypes as 'private' ($Private), meaning it does not appear in the selector lists available in Map & Outline view. Private prototypes can only be created via setting $Private and not via the UI.
Non-note Prototypes
Agents and adornments may be used as a prototype. With agents, ideally the prototype should not have a query set though Tinderbox will cope with such a configuration. The Rule and Display Expression disabling attributes can help by ensuring things like self-resetting rules only run in non-prototype notes.
Prototypes may themselves use prototypes. This can be useful where several different prototypes share a common base. In such circumstances, it can be useful to use one precursor template and then have several other prototypes using it as their prototype. Changing the upstream prototype will affect all prototypes using it and all notes/agents using the downstream prototype.
Built-in Prototypes
Tinderbox makes it easy to experiment with prototypes as a number of simple generic ones are predefined and built-in, noting that a few of these—such as for notes in DEVONthink watch folders—are added as-needed by the app and are not available for manual insertion via the File menu.
See more: