This post starts a new thread to introduce a demonstration/pilot of a diagramming capability in Tinderbox. While this was built with the latest backstage version (b706) of Tinderbox, it should also work with the latest released version (10.1) as well.
I am currently on the schedule to present a demonstration of this diagramming capability at the Tinderbox Meetup on March 1st. If this interests you, then you might find it helpful to look over this posting prior to the meetup. I’ll be glad to take questions and gear the demonstration to what interests the participants.
Note: The latest version of a working Tinderbox document that provides the diagramming capability with examples is provided here, and will be updated as appropriate.
Toolbox v2.0.2.tbx (8.3 MB)
TL;DR This approach to providing diagrams in Tinderbox does work surprisingly well. Once the necessary pieces are added to a Tinderbox document, it is relatively easy to create as many diagrams as the user would like. The diagrams can include notes and adornments that are specific/unique to the diagram, but they can also incorporate objects that reflect notes from anywhere else in the document. Furthermore, links between notes will also be reflected into the diagram, assuming that the links go between two notes that are both reflected into the same diagram. When the appearance of a reflected note is changed, these changes will automatically show up in the corresponding reflection note in the diagram. Similarly, when links are added or removed in the main document, the changes will be reflected into the diagram as well. Importantly, notes that are reflected into a diagram are never modified, with the exception that a link from the reflection object in the diagram will be established back to the original reflected note.
Overview
Reflection is the metaphor used to describe the relationship between notes in the user’s document and their corresponding objects in a diagram. A diagram is constructed as a Diagram Container that includes child notes representing the visual objects in the diagram. These children are either reflections of notes outside the Diagram Container or that are objects/adornments that exist only in the diagram. The Diagram Container is considered to be flat, in the sense that there are no other containers below the Diagram Container. The diagram itself will appear when the Diagram Container is opened in its own Map View window.
A Reflected Note can be located anywhere in the overall document to whatever outline depth that makes sense to the user. To reflect a note into a diagram, the user needs only to establish a link of type “Diagram<=Note” from the note to the Diagram Container that provides the diagram. Link Creation action code will create a Reflection Object in the diagram and establish a link back to the Reflected Note. This allows a Reflected Note to see all diagrams that it belongs to via links of type “Diagram_Reflection=>Note.” However, the original Reflected Note is otherwise unaffected, and it can be modified and moved at will without impacting the diagram. If the appearance of the Reflected Note is modified, then the Reflection Note will be similarly modified.
Any links from a Reflected Note will also be reflected, assuming that the links go to other notes that are reflected in the same diagram. A list of allowed link types can be used to determine which link types should appear in the diagram. Again, the links can traverse any outline structure of the main document, yet still appear in the diagram. The diagram links will actually be new links that only go between objects in the diagram. When links are changed in the main document, these changes will appear in the diagram.
The Diagram Container holds the information used to maintain the diagram and keep reflections up to date. This includes a dictionary used to map Reflected Notes to their corresponding Reflection Objects. A default set of appearance-oriented attributes used to reflect appearances onto Reflection Objects in the diagram is maintained in the Diagram Container, along with a default set of link types allowed in the diagram. Individual Reflection Objects can have their own copy of the appearance attributes used for reflections, and they also have an exclusion set of attributes that can be used to decouple an appearance attribute from the Reflected Note. Using these options, a Reflection Object can have its own appearance characteristics that will not be overridden by the Reflected Note or changes made to it. For example, if the user wants a Reflection Object to be blue even though the Reflected Note is Red, this is easily achieved.
At any time, the user can add more objects to their diagram, including Reflection Objects. They can also delete objects or move them out of the container without interfering with the rest of the diagram. Objects that can be included in the diagram include regular notes, adornments, charts, and posters. In other words, the full capabilities of Map View are available to build a diagram, but without the conflicts associated with mapping a hierarchical outline. Furthermore, export features can be applied to a Diagram Container to reproduce a diagram in just about any presentation format desired.
However, this is an initial version, and there are some limitations to what can be currently achieved. If there is sufficient interest, this package will be improved, and feedback may help develop an understanding of where this sort of diagramming capability fits within the Tinderbox ecosystem.
A quick tutorial
The “Toolbox” document provided with this posting is very much a work-in-progress. It is being offered as a way to let others try out this approach and to obtain feedback on its utility and features that users might want. It is hoped that this will become more polished in coming weeks (and months?) with an important objective to make it easier to incorporate this Diagram View package into any Tinderbox document.
For anyone who does want to try this out, a simple example is included. In the Toolbox, there is a separator titled “Playground.” This includes a “Simple Diagram Examples” container where there is at least one Diagram Container titled simply “Diagram A.” At the same level as the diagram, there is another container labeled “Example Notes,” which in turn includes four subordinate containers, each of which has multiple Notes. Although there are links between these notes, both within a container, and crossing between containers, the Map View of the Example Notes container looks something like this:
While the hierarchy is represented in this Map View, no links are visible. Even if one of the containers is opened in Map View, only links within that container are shown.
To demonstrate how Diagrams can be constructed, a subset of the example notes have been reflected into Diagram A, resulting in this Map View:
This presumably looks more like what users often want to see. Although no attempts have been made yet to pretty up this diagram other than some positioning of notes, its essential utility should be apparent. As can be seen, there is at least one other “UnReflected Note” that exists only in Diagram A as well as an adornment. Such unreflected notes can be manipulated in any way the user wants, including establishing links to other notes. However, any links added inside the diagram, whether between Reflection Objects or unreflected objects, will exist only in the Diagram. While users might want links added between Reflection Objects to appear in the main document, the way to achieve this would be to add the link in the main document (outside the diagram) so that the link then appears in the diagram.
Adornments can be useful in enhancing the visual appearance of diagrams. They can introduce pictures, or serve to visually group diagram objects. Objects overlapping adornments can also be pinned to the adornment so that they will move with it.
Posters are also supported as part of the Tinderbox Map View, so they may be included with diagrams as well. This opens up a lot of possibilities for rich, and even dynamic, content.
The method for reflecting a note into a diagram is by dragging a link of type “Diagram<=Note” to the “Diagram A” container as shown here:
When the Link Create pop-up appears, it should be set up like this:
As soon as the link is created, the Reflection Object corresponding to (in this case) Note X3 will appear in the diagram and appear just like the original. There will also be a link of type “Diagram_Reflection=>Note” created from the Reflection Object to the Reflected Note. Both types of links used for these diagram connections have been configured to be invisible, so they won’t interfere with the rest of the document. On the other hand, they are real links that can be followed to support additional features and tracking of the relationships between Reflected Notes and diagrams.
At this time, an Edict is set by the Diagram Prototype for each Diagram Container that will periodically update notes and link reflections in the diagram. If the user wants an immediate update, all they need to do is touch the Diagram Container, and the update should occur. It is possible that this could be set up as a rule for more immediate updating, but this will wait until performance implications are better understood.
A Real-World Example
A more interesting example is provided based on a real-world case study in this version of the Toolbox:
Diagram Example of Household Electrical System.tbx (8.5 MB)
In this case, it is a diagram of an electrical system for my own home. This is the result of a two-year project to eliminate fossil fuel consumption at our house. Geothermal heat pumps were deployed to replace our prior two gas furnaces. As part of the transition, we also included a standby power system based on battery storage and a standby generator. Many lessons have been learned from this project, and I’m now trying to document the experience and offer helpful information to others who go down this path.
I pulled into this Tinderbox Toolbox document some example hierarchies of notes related to various systems in our house’s electrical and HVAC systems but without all the details. This set of notes is shown here using Map view:
This map view shows only two levels of the hierarchy where there are three levels in several cases. By dragging links of type “Diagram<-Note” to the Diagram Container shown at the top, the notes shown above were added to the diagram. As an aside, it is generally easiest to drag these links in Outline view when working across multiple levels in a hierarchy. Link parking can also be used to connect notes from different parts of a larger document to a Diagram.
The resulting diagram includes the notes that were dragged into the Diagram Container thereby producing “Reflection object” notes in the diagram. The diagram also shows the many links between the various objects, with most of these links being reflections of the actual links that exist, but that were not visible in the Map View above. After positioning everything in a rational manner and adding some adornments, the resulting diagram looks like this:
For the curious, ATS stands for Automatic Transfer Switch, GSHP expands to Geothermal System Heat Pump, and the small black rectangles are either circuit breakers, relays, or power lugs. The value I get from this diagram is that it illustrates how power is physically distributed to the large loads (e.g., GSHPs, EV charger, Well pump). In addition, it shows the network communications to the entities that have some role in controlling energy usage.
An important point to emphasize is that this diagram is both viewed, and manipulated in the Map view provided by Tinderbox. This offers some unique benefits, since Map view maintains a close relationship between the diagram objects and the rest of the document. In particular, it is trivial to move from one of the Reflected Objects in the diagram to the original source note to view further details. If what you want is the text from the original document, this can be easily viewed in the link popup for the “Reflected_Diagram->Note” link type. It is also possible to configure the Diagram Container or individual Reflected Object notes to automatically copy text as part of the reflection process.
At the same time, Map view does not have some of the expanded drawing features that users might be familiar with from other drawing/diagramming tools. In other words, there is a tradeoff here. For my purposes, I find that the ability to work interactively with diagrams that are truly integrated with the rest of my document is of real value.
Integrating the Diagram View Package into your Tinderbox documents
To start with, I suggest following the procedure outlined in my recent post where I Introduced a “User Attribute Management” package for Tinderbox. This will not only make it easier to copy the necessary User Attributes from the Toolbox document to other documents, it also sets up some important structure that the Diagram package makes use of.
Further instructions outlining the steps to add the “Diagram Views” to your documents are provided in a note in the Toolbox document via this path:
“/Document Commons/Packages/Diagram Views/Deploying Diagram package to existing Tinderbox document”
There is additional documentation provided in the “/Document Commons/Packages/Diagram Views/” container, and most of the package components have embedded documentation in their Text panes.
Feedback and comments would be much appreciated. I can be reached at Chuck@Interisle.net and I will try to respond to comments added to this posting.