Introducing a "User Attribute Management" package for Tinderbox

[echuck (Chuck Wade)]

I am posting a working version of the Tinderbox package I have developed that facilitates managing and copying User Attributes. I suspect this package will primarily benefit users who often want to pass User Attributes between their documents.

This effort parallels work by @satikusala and @mwra, though I have approached things differently. The package provided with this posting represents a minimal solution to the problems of managing User Attributes. Also worth referencing is the work by @webline some time ago where he developed AppleScripts to copy User Attributes between documents.

I should further note that this approach borrows concepts from the way that @eastgate implemented the “/Hints/Stamps” container, eventually moving the focus for building and maintaining stamps from the Inspector to discrete Tinderbox notes—a welcome improvement.

The User Attribute Management package has been designed and implemented to enable nearly frictionless copying of User Attributes between documents. At the same time, it should make it easier to keep track of, and maintain, User Attributes in each document. The package offers these features:

• A simple bootstrap procedure is used to incorporate this package into any Tinderbox document, whether newly created or an existing document. This procedure requires copying one container into the target document, and then turning on a couple of switches. The ability to represent User Attributes as Attribute Notes is provided, but no User Attributes are added or modified by the bootstrap process.
• Once this package has been installed in a document, it can be used to copy User Attributes from this document to other documents, and also to receive User Attributes from other source documents that have been similarly configured. This is a simple copy-and-paste procedure using Attribute Notes.
• Every User Attribute can be reflected into a unique Attribute Note, including all the settings for the User Attribute.
• Changes made to an Attribute Note will be reflected back to the corresponding User Attribute’s settings. Controls are provided to prevent automatic updating of User Attributes, and also restrict which settings get updated.
• By default, editing the ‘description’ for a User Attribute can be done using the Text pane for the corresponding Attribute Note. This is usually easier than editing descriptions via the Inspector.
• Since Attribute Notes are just plain Tinderbox notes, they can be referenced within a Tinderbox document and linked to other notes. This should make it easier to document the structure of, and applications embedded in, a Tinderbox document.
• This User Attribute Management package is lightweight, and includes very little baggage. It is also self-maintaining within the document’s hierarchy. It does not require any User Attributes of its own. Code included with this package is executed infrequently, and controls are available to selectively disable features permanently or on a temporary basis.
• Detailed documentation is included in the provided Tinderbox document that explains the technical working details as well as practical usage.

An initial implementation of this package is provided via this Tinderbox Toolbox document:
Toolbox v2.0.1a.tbx (2.9 MB)

Detailed documentation for the package, including this ReadMe, can be found near the top of this document or by following this path hierarchy:

/Document Commons/Packages/User Attribute Management/

In addition to this ReadMe, there are notes providing Deployment guidance, Implementation details, and a package Manifest. The Deployment guide is fairly detailed, not because it is hard to bootstrap this package, but because the guide describes exactly what is going on with each step. The TL;DR version is simply:

1. Make sure that the target document has the “/Hints” container installed (invoke “Built-in Hints” from Tinderbox’s File menu).
2. Select and Copy the “Document Commons” container from the “Commons Templates” container under the top-level “Document Commons” container (i.e., the ‘Template’ container) as shown here:
   
   
   
   Aside: I tend to set containers that are used for maintaining document structure or code to be separators, since that makes them stand out visually as being different from the rest of my document, but with the added advantage that separators will not be shown in the Map view—hence less map clutter.
3. Paste the “Document Commons” template container into the destination (target) Tinderbox document. It doesn’t matter where it is placed. Turn off the $RuleDisabled checkbox for the “Document Commons” container. It will now position itself as the last top-level note in the document, and it will continuously maintain this position even if other top-level notes are added or if this container is unintentionally moved (just like a homing pigeon ).
4. In your target document, select the “Document Attributes” container under “Document Commons” and turn off the $RuleDisabled checkbox. This will complete setup of the package, and the $RuleDisabled checkbox will be turned back on since this is a one-time procedure. Also, turn on $Checked for this container to allow User Attributes to be represented as Attribute Notes.
   (Aside, for this to work as expected, Tinderbox 10.1.1b704 or later is required. Otherwise, make benign edits to the code text for the “OnAdd…” and “Edict…” code notes that will now be in the Hints container to force them to be recognized by Tinderbox. Just adding a space and then removing it should force recognition.)

That is it! Attribute Notes can be copied and pasted between documents that have been set up with this package. Any existing User Attributes in your documents will automatically appear as Attribute Notes under the “Document Attributes” container, thereby making them easy to copy to other documents. Just copy Attribute Notes from-, and to-, the “Document Attributes” containers.

One last note: The Tinderbox Toolbox document provided here also includes my “LogRec” function and related prototypes. I use this extensively for debugging code, and so I include it in my own Tinderbox documents and the documents I share if they have application code. For anyone interested, some code to make path strings safe is provided for your entertainment. My Diagram package is included as well, but that will be addressed in a subsequent posting to the Forum.