When Tinderbox generates a new TBX document, all current system attributes are added to the document. Each such attributes also stores the (then current) default for that attribute.
But, over time, new versions of Tinderbox are released. Occasionally, an existing system attribute may change its default. An example is the default font used in text ($TextFont). Separately, new system attribute may appear. Less often, old system attributes are no longer added to new files.
So, what happens to existing TBX files in these situations?
A new default value for an existing system attribute
This has no effect on existing documents as they retain their originally defined default value. By comparison, new documents will define the same attribute use the newer, now current default. If the user wishes to use the newer value, then they edit the attribute's default—see the 'review actions' section below. This avoids nasty surprises where the new default to be auto adopted and where the existing document behaviour assumed the old default value, such as might affect automation within the document.
A new app version gains a new system attribute
On first use in the new version of the app, the new system attribute(s) will be added to the documents existing system attribute, using the current default values.
An existing system attribute is dropped from the schema in a new app version
No change occurs—existing apps retain their pre-existing system attributes, even if some are now moribund. There is no way for the user to delete these now obsolete or un-needed attributes but they should simply be ignored. Any new documents will lack these attributes completely. A point to bear in mind is that occasionally a new attribute replaces an old one, but both are supported. Thus $AccentColor replaced $Color2. Whilst, newer TBXs will lack $Color2, older documents will likely have both and both will store the same values. This ensures old document's action code does not just break. Ideally, if such a 'replacement' occurs, users should review code and replace any use of to the old attribute name with the new name.
Review actions for the user to consider
If any of the above happen:
- Consider if a new default value for a system attribute is appropriate for existing document(s). For those documents where change is appropriate, manually change the default value in the System Inspector or, for attributes whose value is set via Document Settings, in the appropriate tab of Document Settings.
- Where new attributes are added, deprecating older ones, review documents for use of the older attribute. The two key places to check:
- Displayed Attributes. Those using prototypes will find this easier than where Displayed Attributes are set per note. Do not forget, a note's list of Displayed Attributes is stored in $DisplayedAttributes. Thus, using $Color2 as an example a query like
hasLocalValue("DisplayedAttributes")&$DisplayedAttributes.contains("Color2")
will find all notes that have Displayed Attributes set and which not inherited (e.g. not using a prototype) AND where the Displayed Attributes table includes the 'Color2' attribute. - Action code. For attribute based code such as rules, edicts, OnAdd etc. ,the same sort of query as above can be used, e.g. for edicts:
hasLocalValue("Edict")&$DisplayedAttributes.contains("Edict")
. For stamps and functions, add the built-in Hints (if not already in the document) and test the $Text of Stamp and Library notes.
- Displayed Attributes. Those using prototypes will find this easier than where Displayed Attributes are set per note. Do not forget, a note's list of Displayed Attributes is stored in $DisplayedAttributes. Thus, using $Color2 as an example a query like