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 - 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. 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.
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 - was originally 100 children, later raised to 500 children from v7.3.0.
However, 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. From v7.2.0, this includes 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.
Agents and adornments may be used as a prototype. With agents, ideally the prototype shouldn't 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.
Tinderbox makes it easy to experiment with prototypes as a number of simple generic ones are predefined and built-in.
There are many ways to set prototypes, many using the prototype pop-up menu:
- Outline view. Right click icon of selected item(s), select from pop-up menu
- Map view. Right click prototype tab of selected item(s), select from pop-up menu.
- Text window. Either:
- Click Prototype pop-up in sidebar.
- Edit $Prototype attribute displayed as a key attribute.
- Properties Inspector, Prototype sub-tab. A tick-box is available to set prototype status.
- Properties Inspector, Quickstamp sub-tab. Select one or more items. Select 'General' group (left), 'Prototype' attribute (right) and type the name of the desired pop-up.
- Action code, via Stamps, or OnAdd, Rule , etc. Set the prototype directly in code, e.g.
$Prototype="Person".