Automating the updating of prototypes of an older file without breaking note-prototype inheritance

Q & A - getting started with Tinderbox
1

Hi everyone

I have an older rather large file with many prototypes I would like to update, including its prototypes. Replacing / updating the prototypes is the part that worries me since I want to try to avoid breaking the existing note-prototype inheritance

I know i can, one by one, copy and pastes new rules and edicts into the existing prototypes but that will take awhile. I was hoping to automate this.

is there a recommended easier way to update prototypes without breaking note inheritance.

I seem to remember a meetup in which MichaelB copied prototypes first before replacing them to preserve the inheritance. I don’t remember which session this was

Anyway, any guidance here would be great.

Tom

2

Unstated Assumption: this appears to be about built-in prototypes aded to the TBX, and not user-created prototypes. The latter are under the control of the user who should have notes as to changes they have made over time where a same custom prototype is used in multiple documents.

This is a little more complicated than imagined as:

  • Tinderbox system attribute defaults change over time
  • Built-in prototypes retain their customisation as when first installed
  • Not all customisations used by built-in prototypes are revealed as Displayed Attributes†
  • Action code has no easy way to iterate system attributes looking for locally set values (it can do this for user attributes)

So, even if there are changes between first adding a prototype the document and now, it is not automatic that all changes need be applied, unless the TBX has been updated to reflect all interim changes to Tinderbox default attribute values.

That said, there is no built-in ‘feature’ that automates your task. I would suggest:

  • Make a new TBX document and add to it all the built-in prototypes you wish to update in older documents. Save that TBX.
  • open the new TBX in BBEdit‡, and locate the XML for the <item> elements representing the aded prototype(s). Copy that XML, into a new text document in BBEdit. Close the TBX; the new document has all the reference info you need.
  • Open your old TBX in BBEdit (ensuring it is not also open in Tinderbox). Make sure this document and the new one above are in separate windows , tiled so both can be seen at the same time.
  • Review in turn each ‘old’ prototype for which you have a saved new copy. Update the TBX’s stored attribute values as necessary for each prototype.
  • Save and close the TBX. The other file (and the TBX used to make it) may now be discarded.

You may separately choose to do a similar exercise for system attributes, depending on the need. The same process applies: use XML from a new TBX document as a master reference to review/update an old doc’s XML.

Be aware that some settings are not stored via system attribute defaults but in the <preferences>. Experience shows the order of these can change over time, so you may need to extract old and new, then sort the lines, before making comparisons.

One could probably do much or all of this via AppleScript. But unless/until someone writes such a script, the manual way is faster.

This is perhaps something we could demo in a meet-up, as folk can see/ask questions and the recording is there as a reference for others. I’m happy to demo the process (with a little warning to give me time to make the demo materials before they’re needed).

†. What each prototype customises is not formally documented. The most accurate know summary of non-default settings for these is at aTbRef, in this section.

‡. Or similar text/code editor of your choice. Same applies throughout for mention of ‘BBEdit’.

1 Like
3

Thanks Mark.
I had not thought of using BBEdit and the tinderbox xml file! I will try this approach for my much needed updates to my older files. In the past, I would copy and paste edicts and rules and DisplayedAttributes from one prototype to another in a very manual way because I did not want to lose the relationships between my notes and their prototypes when updating the file. This was VERY Laborious but needed as I incrementally learned tinderbox, I learned better ways.
MichaelB and I spoke today about another way using agents to find notes linked to the old prototype, use action code to like them to the new prototype - one by one. Still time consuming but better (a step up from my old method)

Tom

4

Another thing not to overlook, and which took me the XML route is that if you have code running that uses the affect prototypes using prototype renaming can bite. I messed up a file like that in the past: pure error on my par–I thought I’d stopped all the code running but I hadn’t. Working outside the file is safer/easier IMO as there is no chance of stepping on running code.

But, as we see, there is rarely one way to achieve an end.

5

I thought it might be useful to show the task at hand. Here, I’ve copied a the <item> code for the ‘HTML’ prototype from an Oct 2023 TBX, using v9.6.1. I did the same for one for Oct 2014 (when the prototype was called ‘HTML Template’), c.6.1.0. For the current version of the app aTbRef has the prototype’s customisations in detail, for v6.x we have them in lesser detail.

I’ve copied each 'item into a new BBEdit document, selected both and opened a ‘compare’ window:

Differences — untitled text 464 vs. untitled text 465 2023-11-08 17-43-58
Differences — untitled text 464 vs. untitled text 465 2023-11-08 17-43-581920×706 195 KB

Notice that as I’d only briefly opened the old file, Tinderbox hadn’t yet updated the system attributes to add ones not present when the TBX as last used (e.g. $DominantLanguage, $Sentiment, etc.)

So what differs?

  • $ID. Well we could expect this but no change is needed in the ‘old’ doc as ID is how Tinderbox finds the right things under the hood
  • $Created, $Modified. Obviously different but no change needed.
  • $Dominant Language, $ScreenHeight, $ScreenWidth, $Sentiment, $Sentiments. These will get auto-added by the app but have no effect on the prototype’s function. you can either update the old file or let Tinderbox add these if/when it needs to do so.
  • $Name. In most cases you’d expect this to be the same, but here is a case where Tinderbox re-named a built-in prototype. Think carefully before changing the name just to look current. Consider where the old name may be used in action and export code as those instances would need updating
  • $NeverComposite, $NoSpelling, $ZipLinks. These are non-default customisations for the current app so do want adopting.
  • $OnAdd. This is where a deliberate check is worth while. Note how the code there uses the prototype’s $Name. The old addition of setting $IsTemplate is likely an edit by me and is not needed as the $OnAdd sets the new note’s prototype and that already sets $IsTemplate.
  • $Tabs. This recent addition is a boon so we’ll likely adopt in. TBH< I find the default set is never enough and are wasteful of horizontal space so usually (not here but for longterm TBX where I’ll export actively) put more, but closer spaced tabs. So this is a good example where you might want to keep you existing value over the default.

Hopefully this shows how ‘just’ updating via action code without any detailed check first may be sub-par. But would could always do a review like above and edit the data from within Tinderbox if that feels more comfortable.

Not shown here are the <preferences> which I’ve found to be as important as prototype settings when updating a file. As some are in Doc settings, some in the Inspector panes and some elsewhere, again the UI isn’t the most effective way to truly update your document.

If you have 10s of documents from the same era, you could do a detailed check for one document, not the changes and then use a mixture of action code and the UI set the desired’ updated values. If the docs are of different vintages you would do well to do the initial tests against one of the oldest docs.

Copies. Work on copies in case you make a mess. Once the copy is updated you can archive or delete the original version. Note that when you open an old document, Tinderbox will update it with new system attributes, etc. So. If you wish to keep the original in its original form this is another reason to use a copy.

Duplicate or copy with new ID? Note, each TBX document has an invisible Unique document ID (it is in the XML). But if you duplicate the document in-app or via Finder (or copy/paste in finder) the doc ID remains the same. To create a new version of the doc with a discrete ID, open the document in Tinderbox and then use File ▸ Save As (you need to hold down the Option key to see this in a menu). The saved copy will be given a new ID.

6

Beautiful and great detailed advice as always. Thanks Mark!
Game changer for me was your suggestion for working directly on the xml file in BBEdit
Makes it much easier to edit the Prototypes for my use case of updating

Many thanks
Tom

1 Like