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.
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. From v5.8.0 - two special attributes control $Rule and $Display Expression 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 aren't 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 Created, Modified, Height, Width, $Xpos, and $Ypos. It also inherits various layout features and prototypes text if any. Prototypes aren't 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. Newly-created notes take their initial $Height and $Width from their prototype.
If a note or agent is copied and pasted, the new item does not inherit its source's $Prototype value. This is a defensive assumption by Tinderbox as it can't 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 helps sets Prototype values directly or indirectly via rules and actions. Use if 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. 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.
As it may be that 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. From v5.8.0, inheriting notes gain all descendants of the prototype, not just immediate children. Children/descendants of such prototypes should not themselves be prototypes if the intent is for the bequeathed items to be prototype-based. 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 bequeather copies inherit the same prototype (i.e. achieve the original desired aim).
From v5.10.0, agent prototypes can bequeath any adornments saved within them.
From v5.10.1 the limit on bequeathed items - limited to avoid accidental infinite recursion - is raised from 2500 to 500 notes.
It is possible to designate some prototypes as 'private', meaning it doesn't appear in the selector lists available in Map & Outline view. Private prototypes can only be applied via code or via the prototype pop-up list on the note name/rename dialog.
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 added in v5.8.0 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.
- Inspector's Quickstamp pane. Select one or more items. Select 'General' group (left), 'Prototype' attribute (right) and type the name of the desired pop-up.
- Create/Rename dialogs. These dialogs for notes, agents and adornments all have a Prototype pop-up menu.
- Action code, via Stamps, or OnAdd, Rule , etc. Set the prototype directly in code, e.g.
$Prototype="Person".