Tutorial : ActionsAndDashboards.tbx

Tutorials and Examples
1

Hi, I have just had fun working my way through the tutorial supplied with Tinderbox and I wonder how the user gets information out of the Tinderbox file. I can see that it is possible to get text records out but I wonder if there is a method of including the Time Line and the summaries all in a single report.

Any thoughts?

Simon

2

In short - no.

Looking st the TBX I assume you mean the ‘cities’ tab which is a Timeline view and the ‘status’ tab which is a map view. In both cases, the best way to export them is to use Edit menu → Copy View As Image. Paste the resulting data to Preview (or a graphics editor). The data, as pasted, is in vector format so will scale. If using Preview saving as PDF retains the vector data or you can rasterise it to bitmap form as a PNG.

3

I was trying to think how I would use the information stored in the file and also why I would use Tinderbox rather than a spreadsheet or another outline application. At present I am trying to generate a report, for the “accounts department”, that contains the expense records in date order.

So i am attempting to get the data from the “Expense Account” group of records. While I can get the notes the attributes and values are resisting my attempts at export.

Simon

4

OK, I’ve taken the file and edited it so as to be able to export the ‘Expenses’ agents as a tab-delim text file. Here’s what I had to do - starting with Actions and Dashboards the tutorial file.

  • Open a new tab, set it to outline view, at root scope - i.e. so you can see container’s like ‘Prototypes’
  • Select and delte the (empty) container ‘Templates’ - will enter a new more up date version
  • Use File → Built-in Templates and click ‘HTML’, this creates and, configures the necessary containers/notes.
  • I then added two new templates: ‘Expense_Report’ and ‘Expense_item’. I’ll describe the code in more detail below.
  • Switch to the Examples tab and select the ‘All Expenses’ agent.
  • In the Action Inspector, select the ‘sort’ sub-tab and un-tick the reverse sort order. it makes more sense for the report to list in date order, earliest first.
  • Switch to the HTML Inspector and in the ‘Extension’ box change ‘.html’ to ‘.txt’ then select ‘Expense_Report’ as the ‘Template’ value.

The ‘Expense Report’ template uses this code:

Expense Report

^value($ChildCount)^ items with total value $^value(sum(children,$Dollars).precision(2).format("l"))^

Date	City	Recipient	Amount	Currency	USD	Method	Tags

^children("/Templates/Expense_report/Expense_item")^

Note the line starting ‘Date’ has a single tab between each column heading. Notw the code for the ‘Expense_item’ template:

^value($StartDate.format("l"))^	^value($City)^	^value($Recipient)^	^value($Amount)^	^value($Currency)^	^value($Dollars)^	^value($Method)^	^value(Tags.format(", "))^

Again, each column (each ^value()^ term) is separated by a single tab. Ensure there is a single line return after the last column. That ensures each expense lists on a new line.

Now you can select the ‘All Expenses’ agent. Use Window menu → Show Text Pane selector. Now select the ‘HTML’ sub pane and you’ll see the report previewed like so:

agentexpdemo1

In the grab above the lines have soft-wrapped so as to fit in the pane - don’t worry. Don’t use the ‘Preview’ tab to look as this data - that will show as a big block of text as it is treated as if HTML and there’s no HTML mark-up used here.

Use File → Export selected note. Select a location, e.g. the desktop and save the file. If you want, you can now import the file to Excel or Numbers. If using Excel, I’d use the Data ribbon and the text import feature remembering to set the data encoding to UTF-8. If you don’t the currency symbols will likely not import correctly.

A copy of the altered file and specimen tab-delim text output is uploaded here: http://www.acrobatfaq.com/tbdemos/Expense-report.zip

I hope that helps!

5

Mark,
Thanks for taking the time to make the changes and publish an answer. So the html code is fixed and the text that the user adds gets inserted by Tinderbox.

best wishes
Simon

6

Happy to help. But be aware, it’s just one approach. The longer-term learning point (for later readers) is that if you want to export more than titles/text then you need to use what has historically been called ‘HTML’ export

As my demo shows HTML export could actually be plain text rather HTML, indeed some other format. the takeaway points are:

  • there is much flexibility
  • some self-assembly is required
  • the forum can help with the latter if you can (a) explain the format your are using and (b) the structure required.

Thus if stuck, uploading a TBX of specimen data is useful as well as a file showing your intended output (even if made manually rather than via Tinderbox) as it gives us a common start/end point.

Tinderbox is very flexible but I accept it can seem impenetrable to the new user at first sight, especially if not from a tech background. But, it is not un friendly, if you can explain what you want and why likely someone here in the forum and help with the correct template to get you going.

7

Hi Mark,

My overall aim was to compare the demo tinderbox file with another tool. In this case I chose OmniOutliner. Looking at the tbx demo the key part seems to be the expense records. I see two other discrete sections namely the narrative of the trip and the list of organisations and people but the expense records are the reason for the document. To conduct the comparison I needed to export these expense notes from Tinderbox and import them into OmniOutliner. I can not use OPML as OPML does not support attributes/fields/columns. So I chose TSV. Hand crafted XML would have overcome some problems downstream but I was not brave enough to try it or ask.

I modified the code that you kindly provided to include the Title and the body text of the note. I also added a tab and the text “” at the end of each line. I exported by displaying the HTML text of the agent and using cut and paste. Once on the clipboard I pasted the data into BBEdit and then deleted all the line endings. Next I replaced “” with " \n" where “\n” is a new line. The updated text now has newlines to mark the end of the records. Unfortunately some of the text notes contained tab characters which had to be replaced with spaces before my output was ready for import. This was achieved by doing the import and then checking the final column contained “”, addition unwanted tabs caused the marker to be out of line. Once the unwanted tabs were removed in BBEdit the clean TSC was imported and an Applescript script was run to convert the Tinderbox notes into OmniOutline inline notes.

This means that the output specification I need (ed) includes all the fields in the agent , sorry visible attributes, cleaned of tab and new line characters output as TSV.

I have owned Tinderbox since version 5 although I stopped using it shortly after upgrading to version 6. Also, I have a background in testing of computerised avionic equipment so I believe that I am reasonably technical. I find Tinderbox pretty unfriendly once I move beyond the basics. It uses non standard terminology, any code that is written is dotted about all over the place. The UI looks old fashioned and in the case of version six the get info pane jumps all over the screen. I have to add more notes to describe agents I have created. In the end I seem to spend more time trying to configure Tinderbox than I do working with my data.

My recent tryout has been to assess if my teenage daughter should use Tinderbox while at university. The answer is no because she would never be off the phone and I would never be off this forum. I’m sure some users get great benefit from Tinderbox and I can sense the power that is in the application but I just know that I am never likely to use it enough to use it without continual reference to the documentation.

Thanks again for all the help that you have given.

best wishes
Simon

8

If your basic requirement is a tabular outliner, then OmniOutliner is probably a good bet. (Pages is also very good at that, BTW.)

Regarding Tinderbox – while I would suggest that with use comes familiarity and skill – rather quickly in most cases – it is definitely not one-size-fits-all, like the OmniGroup apps tend to be, and is extraordinarily feature-rich.

Looks like you’re picking the best tool that meets your needs, which is theall any of us can do. Thanks for your interesting posts, and good luck.

9

Hm. I don’t wish to seem curmudgeonly. Everyone is free to use whatever tools they need, as @PaulWalters just pointed out. However, I just feel your follow-up misrepresents Tinderbox based on the outcome of misplaced and unstated starting assumptions. Tinderbox is a toolbox more than a one-purpose tool, so it will often look less special (in context) that a utility honed for one purpose: OmniOutliner (outliner), Aeon Timeline (Timeline, etc…). A cruel irony is Tinderbox’s flexibility in import/export is normally blamed for problems caused by the inability of [some other app] to make/consume the desired format. Human nature is the second app in the chain is blamed for limitations in the first, especially if disproportionate amounts of time have been spent using them,

The last example I gave above started from a request for a ‘report’, of unspecified format. I chose TSV as it’s simpler to set up (and thus for the thread’s readers to follow) and has fewer edge case issues than CSV. The use of a tabular section within the report was based on my (correct!) guess you’d want to put it in a table.

Still, with the same source file we can make copies of the export templates, this time set to make a CSV tabular section. So, here are the same templates as above in CSV. Let’s try:

Expense Report

^value($ChildCount)^ items with total value $^value(sum(children,$Dollars).precision(2).format("l"))^

Date,City,Recipient,Amount,Currency,USD,Method,Tags,Dummy

^children("/Templates/Expense_report/Expense_item")^

and

"^value($StartDate.format("l"))^","^value($City)^","^value($Recipient)^","^value($Amount)^","^value($Currency)^","^value($Dollars)^","^value($Method)^","^value(Tags.format(" "))^,x

In each case I’ve added a ‘Dummy’ column and data at the end of the row to deal with (other app’s [sic]) inability to correctly process rows that may lack data in the last column due to poor input parsing routines.

In the revised item template I’ve not formatted the $Tags with comma+space as commas don’t pay well in a CSV setting. TSV is generally more robust as you only need to consider escaping/avoiding tabs. In CSV you have the double whammy of commas and double-quotes, and the fact so many people address those issues in slightly different ways.

I’m confused though. OmniOutliner imports TSV but not CSV (see OO’s Help file). So why use AppleScript (hardly uncomplicated/ or intuitive) just to import a CSV you’d made from a TSV? For instannce, I took the tabular part of my Tab-delim file (#1) used OO’s File>open method (as told in OO help) and the table comes in fine (#2). I can also, using the above new templates make a CSV version of the original expense report.

Those 3 files (#1-#3) are in this Zip: Archive.zip (9.3 KB)

As I opened, do choose tools that suit your style. Other styles are available. :grinning:

10

Mark,
You are obviously a highly skilled user of Tinderbox and all I am saying is that I don’t think that I can achieve anything like your level of skill with the tasks that I might use Tinderbox for.

You have misunderstood how I processed the information extracted from Tinderbox and I apologise for a typo I made in my description above. I exported and then imported a “Tab Separated Variable” (TSV) file. This started out in Tinderbox and was cleaned up in BBEdit. This was imported straight into OmniOutliner. The Applescript was used to move one of the columns to the special “note” column that is a feature of OmniOutliner and means that the OO notes have a title and a body text that may be hidden.
The Tinderbox attributes are stored as columns.

You are correct that I only chose a single tbx file and that there are many other use cases but it seemed a typical business like use of the application and therefore valid as a test case. Also I have a number of older files to experiment with that I created in the past and I watched the Stacy Maison videos.

Although I have looked at and used the export template notes you provided I do not fully understand how Tinderbox applies the template especially when the template has a parent child relationship. I can understand the structure that you have published below i.e. how the parent inserts or uses the child template for each child note of the parent container but I don’t understand why the html pane becomes involved or what its role is.

Also, if this was to be a long term template the issue of tabs and new lines appearing in the text of notes would have to be dealt with. Tabs are probably best replaced with spaces and new lines with \u2028 the UTF line separator character. My approach would be to write the data to a new report note using strings to indicate field and records e.g. and , search and replace the newlines and tabs then search and replace the strings to create the TSV for export.

I apologise if I have misrepresented Tinderbox’s capabilities and accept that my starting assumptions may be wrong. I certainly come from a SQL table based background so perhaps there is a whole new world for me to discover. I would be interested in what you consider to be the feature of Tinderbox that sets it apart from other applications and how you use this feature. For me that feature was the map display but I concluded that a visual display like the map does have limitations on a small computer screen.

As for Applescript yes I know what you mean but its a feature that Tinderbox is missing. The ability to add notes then extract them using Applescript would be a powerful.

best wishes
Simon

11

No worries. My ‘skill’ is only practice an inquisitive. I’m a retired mariner with no formal tech training - for instance SQL is something 'd consider complex and technical. I just read the available docs and it’s trial and error from there

I’m confused, the TSV in the demo looked clean - or were you talking about different data, in which case we’re comparing apples and pears in terms of my expectation of your behalf. If I’d put every possible data edge-case in the demo I’m sure you’d have thought it to complex. I may not be a tech body but I’ve been data -wrangling inter-app data for years - it’s more complex than assumed unless working within very fixed parameters - which is why some apps have little flexibility on import/export.

I do understand, but experience of inter-app work means I’ve long since stopped thinking in such terms as usually i have no tech support and have to fix what I, unwittingly, ‘break’

It’s recursion, if you’re familiar with the concept. If not, try this explanation of the ‘envelope and letter’ form of export template use. The built-in templates provided by Tinderbox’s File menu are nested simply to help newer users understand their relationship. As it happens as long as you configure the right template for the task at hand, the template itself can live anywhere.

The ‘HTML’ sub-pane of the text pane shows up a (plain-text) preview of the note as rendered via the template set** for that note. For plain text export as in this case, the ‘HTML’ pane is essentially the preview. The ‘preview’ pane is for actual HTML export and shows the code seen in the ‘HTML’ pane as rendered in a web-browser. These two views are really useful when setting up/testing templates. Otherwise you don’t need them - indeed for those who don’t use export they can be hidden away (which is the default - toggled via a Window menu option). The HTML Inspector shows export-related settings (attribute values) for the currently selected note.

** In the export case above the template used is set via the recursing code. This allows a note to have a different template at note level. IOW, you can export the note on its own in one template and transclude it using a different template in a recursing export. Thus in aTbRef, the note about aTbRef exports as a stand-alone HTML page and the note’s title is used in a recursing export that makes up the site map.

I can’t figure this out. If the issue was that the TSV exported with a blank line between the data rows, I’d wager it’s because you placed two line returns at the end of the ‘item’ template instead of one. Easily done, first time around. The approach of search and replace of export is very laborious and not needed if the templates are correctly set to start with.

We’ll for me:

  • the amazingly flexible export is a gem. it’s allowed me to make some very complex web pages of TB-derived content. As importantly, it was often for non-techie users - once set up and tested it didn’t need touching and just worked.
  • Prototypes and Inheritance. See more in my articles here.
  • The latter allow and foster incremental formalisation. You don’t need to build a complex data table and define all the fields before use. You can add/alter as you go. The app is very forgiving in that regard. That can seem challenging at first but my observation is that the more people find and embrace this aspect of the app the more they leverage them.
  • Maps. Most think of mind maps but spatial hypertext is the real derivation. The temptation is to box-and-line (mind-map style), but far more powerful is the ability to just use (relative) position as a way of exploring relationships. Plus, maps have a lot of visual customisations to show additional metadata variations.
  • Attribute Browser. Great for reviewing occurrence of emergent relationships or facts.
  • Outline + columns. Great for review.
  • Action code - I use this daily.

Others do thinks like GTD time management, timelines. It’s a toolbox. Use the tools you need. I think the best way to evaluate it is not to say something like is Tinderbox’s outline as good as OmniOutliner’s? Instead, ask what extra can I do in Tinderbox that I can’t do in a single-purpose app (or needs several different apps to achieve the workflow)

Sorry for the long post. I hope that helps clarify a few things.

12

I can’t rate the Attribute Browser too high. It is sui generis, as far as software search and display features go, and keeps getting better as the set of notes in a document expand. Anyone interested in the Attribute Browser should read everything that @JFallows has written about the feature.

1 Like
13

To cut to the chase I have concluded that I must have been missing something and need to give Tinderbox another try. If you are groaning at the thought then remember its down to your persuasive arguments!

The “dirty” output was caused by me adding additional attributes to the output. These included $Text which had newline characters and the odd tab in its text. (Digression: It is extremely unfortunate that computer science ever allowed CSV and to a lesser extent TSV to become data exchange formats, especially as there are all those unused teleprinter codes available and unused.). It is quite shocking that in 2018 there is no “simple” method of exchanging text with embedded new lines and tab between applications and no I don’t consider XML as simple.

Yes and also I need to be more objective as I said I chose the Expense report for comparison because I understood it and it was bounded. The export from Tinderbox and import into OmniOutliner was a means to an end as I wanted to see how well Omni could process the same data. When comparing them on this specific task and bearing in mind I have used OO for years I have to say that Tinderbox wins on data processing : For example Omni can’t do the maths to calculate the exchange rates or produce a summary of expenditure by every city without resorting to AppleScript which can get ugly. Where OmniOutliner wins is the UI which is more approachable although ultimately less powerful.

So I am going to have another try and fully explore the options for outputting information. I may even discover what “spatial hypertext” is and why it is useful.

best wishes
Simon

1 Like
14

CSV and TSV - I so agree. I mean, it’s ‘just’ data. Right? :thinking:

So, yes, $Text is problematic. Back in the '90s ('80s?) I think the plan was to use the ‘vertical tab’ (ASCII #11) to encode line breaks in free-text. I used Extensis Portfolio (ex-Aldus Fetch) a lot back then. It and FileMaker were some of the only apps to carry that through. But I digress…

Part of the problem with strings containing line breaks (e.g. $Text) are how the process plays at both ends, regardless of which direction the data’s travelling (or even round-tripping) via CSV/TSV. The chick and egg problem is that folk who understand the problem have a host of ways to fix this - even if they’d rather not. But, trying to implement such a process for a less tech-based user can be something of a death-march as in a ‘magical’ black-process edge-case fails are unacceptable. Which leads to…

Tinderbox’s action code is actually quite powerful if a little unusual in syntax at first site. It isn’t, and wasn’t envisaged’ as a full language/environment so from the latter perspective there are gaps (e.g. you might presume an if-else construct, etc.). However, Eastgate are a responsive if small shop so fixes improvements follow users actual needs and action code is constantly improving. The app’s help menu has a PDF tutorial on actions (with a TBX you can download) and my own aTbRef is probably the most fulsome reference for action code and such.

AppleScript. This is hard/expensive to add after the fact (so I’m told) and Tinderbox has never had it. Now Apple has rather lost interesting in AppleScript, the ROI of adding now would seem even worse. So, it would be lovely if it were there but it isn’t. That said, not Tinderbox (since v6) is using Apple frameworks, it is possible to get at info via the UI - though you might need UIBrowser and Script Debugger to find the addressing needed.

Spatial Hypertext? See here, here and here. I think the best analogy is doing a jigsaw. You tip out the parts (put notes on the map), sort out associations - shape/colour/etc. (use note position/attributes), and let the picture (data structure occur). Mind-maps, in original form are—whilst useful—far more structural. If you take an outline with a single root note and draw the rest of the outline in a radial fashion around the root, you’ve essentially got a mind-map.

You are correct that Tinderbox maps are to an extent constrained by screen space, but this is a desktop app rather than an business-scale database. People tend to display nice looking maps, but in truth most people use far messier maps because our data is often messy (so we can’t use a normal database for exploration) and this isn’t a shared environment - we’re making a picture that—initially at least—only we need to understand. Whilst doing qualitative research in Tinderbox at present, I work in outline but maps and spatial hypertext inform my use (admittedly I’ve been at this for some 14 years).

If taking a fresh look at the app don’t approach it from a feature or specific task approach - these are areas where a limited scope utility may work better. Instead use it for exploration of messy subjects and look for ways to tease meaning out. That will get you using rather than simply assessing features and will hopefully then help you see how you might use Tinderbox in things that you do understand.

HTH!