Scripting a tour through a map

For my Tinderbox tutorial I’d like to find an elegant way of taking a user on a tour through a map in Tinderbox.

The tour would have series of steps, in each step the the map is zoomed in or out to a defined area, and there is a simple way for the user to go to the next step (e.g. a floating button, or a keypress).

I should be simple and straightforward to define and adjust the area for each step, maybe through an adornment, or by two or more notes that must be visible in that step. Those steps could then be kept in a lookup table, to even simpler, in the case of notes as aliases of notes in a series of linked containers.

I probably can use aTbRef to figure out how to write the code, once I know how to zoom the map, and how trigger transition to the next step via user input (e.g. via said floating buttons or keypresses).

Or maybe I am missing something obvious, and there is an more idiomatic way accomplishing this in Tinderbox?

A simple thing to do is to use Quick Links within the text of the notes to provide the reader with navigation through the document. E.g., in the text of your “Welcome to Tinderbox Note” you add a Quick Link to Navigating the map view. In the Navigating the map view you can have a link to Welcome to Tinderbox (e.g., a “go-home” link) plus a link to Other Views

If you are looking for a way to have Tinderbox automatically in one step generate links within the text of all notes to add navigation throughout the document, that doesn’t exist. However, it is possible with templates (and having the reader view the document in Preview mode) to add inbound and outbound links, a standard-format for pages (using CSS and HTML tags). In other words, I think you can get what you want. Examine the source Tinderbox document of aTbRef for a very advanced set of navigation features.

The linking and templating capabilities of Tinderbox are very robust and also require learning and experimentation. Like everything else, Tinderbox does not impose structure on your documents by auto-generating navigation – but it provides all the tools necessary to build navigation however you want.

Of course, in many ways, what you’re looking too do is what Tinderbox’s sibling application Storyspace does.

Thanks for your suggestions.

My aim is for the tutorial to be visual and experiential, that is why my first attempt is centered on the map view. Have you had a chance to take a brief look at it?

As far as my limited understanding goes, Quick Links work in the text pane and in an export, and any navigation created through a template would only be available in an exported document, right?

While I am not yet qualified to speak to the robustness, I do agree to the “learning and experimentation” part, e.g. I have several notes with identical names but different text, and I have a hard time figuring out how I would create a quick link to a specific one. Also, when I change the title of a note, the text in the quick links is not updated, there is not even a warning.

I’m afraid my concept of creating a visual tutorial for Tinderbox inside Tinderbox would exclude the approach of using Storyspace :wink:

However, I’m curious what exactly Storyspace would bring to the table that I might find useful but is missing in Tinderbox.

I was looking for examples to illustrate what it is I have in mind, and I found zoom animations in Prezi.

If I could create a sequence of those, the user could step through, that’s all I need.

If a note has an assigned template, then the Preview tab (see Windows > Show/Hide Text Pane Selector) will display the templated note as it would appear on export. (The HTML tab shows the raw code, which is helpful for debugging sometimes.). So, when I suggested that a template can add the display of inbound/outbound links, then I would suggest using the Preview tab to see the result. Just a thought.

Notes with similar names sometimes defeat Quick Link’s value since it is not obvious when creating a Quick Link which note is intended. So, in that case one would use the procedure to create Text Links.

I just mention Storyspace by way of example. Storyspace is used for creating hypertext documents that rely heavily on the user using navigation to find their way through the story or narrative. I wouldn’t suggest trying to learn Storyspace and Tinderbox at the same time, though, although they are very highly congruent.

And, yes, I’ve read through your Tinderbox file posted in the other topic. I’m impressed by how quickly you’ve advanced in your use of the software. Very nice work!!!

Tinderbox was not designed as presentation software, like Powerpoint or Keynote or Omnigraffle or Prezi, etc. In part this is because the are perfectly good tools already for such things, there’s little ROI in making the app into a presentation tool when you can export data and use it in a tool designed from the ground up for such a purpose.

Tinderbox can be used to show things in useful and subtle ways but trying to use it like a slideshow will be a journey in frustration.

Sidenote: aTbRef being presented as a web site is not an accident and actually a carefully considered choice.

Maybe that is a viable way forward, let’s play with this for a moment.

How would I export sections of the map view to use as images in a presentation software? Do I have to provide coordinates, or can I just export and adornment and all it contains or touches?

I’m beginning to see that the views in Tinderbox are more for working with information, rather than for helping other people understand that information.

Well, I will make do with what I have. There may be still a trick or two that will help me with my tutorial.

I’m curious, how else did you consider to present it? On first glance, that choice appears so obvious to me.

I’m beginning to see the potential here. There’s a lot more flexibility when using HTML to creating notes, especially for potential tutorials about coding (if I ever get that far). It might be possible to do syntax highlighting, and other nice things.

Now I need to find a way to integrate that into the concept of small guided experiments the tutorial is based on.

Thank you!!!

One more thing: Thanks a lot for creating aTbRef, many of the things I know now about Tinderbox I learned from it. It’s really helpful once one has learned the basics.

TL;DR, not as a map. I’ve been around this buoy several times, first in the mid-200s and a few times since. Tinderbox units don’t map exactly to pixels (as might be expressed in a web page). Why, I’m not sure but it’s not Tinderbox’s focus. I repeat the point that Tinderbox isn’t intended as ‘presentation’ software. If you really really want Tinderbox → HTML SVG or Canvas support, drop and email to Eastgate with your use case.

I’ve held off from comment on the tutorial you posted as it’s clearly a lot of work and I don’t want to be the grinch. I’d just note that I’m not sure it’s as helpful to a new user as intended, but only because you’re writing it as you explore the app and so misunderstanding many of its facets.

Maps - spatial hypertexts - don’t need links. Links imply order/hierarchy and are antithetical to information exploration. If I’m just documenting a process there are better box-and line tools (e.g. Omnigraffle which has a nice presentation mode that does many of the things you’re asking about).

I’d encourage you to explore views other than map view before writing more as I think you’ll see Tinderbox is much deeper than a presentation app.

If you’re going to export, you’ll need to get to understand outline view and the fact that you don’t want to write your main content in the document root. It’s hard to explain in advance of a deeper understanding of the app but best practice advice is to start your map content inside a container rather than at root level.

Beware busy backgrounds. Check out your tutorial doc in Outline - it’s (unintentionally) unreadable.

I’d repeat, my observations aren’t meant in a negative fashion. I’m really heartened to see the effort that’s gone into your tutorial. But, do be careful about making judgmental comments about how the app does/should work before understanding how it does work or else the output is the blind leading the blind. I say that in acknowledgement of making just such mistakes in my own early documentation of and tutorials for Tinderbox.

For perspective, there’s an underlying tension in tools like Tinderbox between using them for presentation and using them for analysis. A number of promising early analytic tools were swallowed by presentation; we don’t want that.

Early Tinderbox did have a facility for scripted demos. In practice, it turned out to be fragile: improvements to the program tended to break details of the script and its mechanism. The scripting was meant to appeal to corporate IT management, but Tinderbox has never had traction there. We dropped it in Tinderbox 6.

Rather than touring through a huge map a la Prezi, I might be inclined to think about expanding your tutorial by adding tabs that zoom the reader to specific places and specific containers. When that becomes awkward — you don’t want dozens of tabs! — I’d split the tutorial into several smaller, topical documents.


Another way of thinking about the presentation/analysis tension: it’s the distinction between designing a persuasive document for a particular audience or occasion, and designing a document to assist your own gradual comprehension of a field of discourse over the span of months or years.

You might use Prezi or Keynote to convince your management about Why We Should Use Python 3.. You’d know from the outset how your presentation would be structured, though of course many details might change and you flesh it out.

You might use Tinderbox to explore The Impact of Deep Learning On Our Artisanal Bakery.. At the outset, you’d have very little idea of where this research might lead, and it’s bound to take you months to examine all the possibilities.

The one thing that led me to try out Tinderbox was that it is said to so very flexible that can do so many different things for different people. So I intend to see how far I can take the idea of explaining Tinderbox inside Tinderbox. I know there are probably limitations I am not aware of today, but I’m quite confident working in in complex spaces, and in environments with a lot of uncertainty.

Your experience and feedback is very welcome. I learn a lot from it, even though I might not always do what you suggested.

And you are correct, I do misunderstand a lot. I know I make a lot of mistakes. That’s why I’m putting my tutorial out to get feedback early. When I learn something, I simply update the tutorial.

That being said, the tutorial does not need to be perfect to be of value, as long as it’s helpful for some people — and initial feedback would indicate that might be the case — that’s something.

Tight feedback loop with users appear to work pretty well for me and for the organizations I am coaching.

When things I say come across as judgmental, I am sorry for that. I will try to consider if there is a better way of expressing what I think. I am German, and I have heard people say I do get to the point fast without pleasantries, so there might limitations how far I will be able to overcome my character and cultural heritage.

So whenever you can point me to a specific judgement you find factually inaccurate, or provide a more elegant description of something I wrote, I’ll be happy to consider it.

1 Like

I find myself wondering if it might be beneficial to look at how various people use Tinderbox in order to get a sense of what is possible, and indeed how different the app can be when the user’s requirements are different. If I’m not mistaken the home page of the app website has some examples of different use cases. And there are many discussions in the forum. I’ve been involved in a few myself, which I have found very helpful. I started this one, which went a lot further than I was expecting when I began it:
http://forum.eastgate.com/t/user-attributes-or-tags/1069?u=martinboycott-brown
I remember James Fallows commenting that for him the app was more about associations than hierarchies, and that has stayed with me ever since. Perhaps one of the most useful insights I’ve had into using the app. And what follows from that is that various ways of displaying those associations are very useful.

Sounds reasonable.

That also sounds reasonable.

It also sounds like overkill for what I was trying to do. I was just looking for a way to access some properties of the window, mainly path, coordinates, and zoom factor, to see if I could use that to make the first part of the tutorial foolproof, until the user has learned enough about navigating a Tinderbox document. But maybe it’s really already good enough, and all that is not necessary.

It’s not my intention to create a huge map, currently I have individual lessons inside containers, and I think that works quite well.

For now, my idea is limit the tutorial to one tab, I believe there should be one obvious way to start to keep it simple for new users… I intend to teach the user how to open more tabs for exploring other views, so that they can keep open the tutorial as a map in one tab, and then look at e.g. the outline view inside a container that has data that makes sense in an outline.

Yes, that is obvious.

I really like the challenge of using Tinderbox to teach Tinderbox. And what I learn is very helpful for using Tinderbox to make sense of my actual field of study.

Yes, I have read those already, and also linked up inside my tutorial because that is a relevant resource for a new user.

Thanks, that thread looks interesting, I will read that more thoroughly when I find some time.

The idea of associations over hierarchies resonates strongly with me. Hierarchies are a dominant and normative ideology: We are trained to see hierarchies everywhere, even though they are quite rare in the real world. Letting go of that leads to surprising insights.

And the tutorial succeeds in doing that in a way that a more passive presentation might not. In the first couple of versions, using the map rather than text links is valuable; by moving through the tutorial, the user has to navigate a map - not a typical thing to do, and your text guides both that navigation and learning. Your use of Next as link names, along with your placement of note spaces on the map, seems to be plenty to guide navigation - as well as being examples of good practices for novices to be aware of.

Is it foolproof? Probably not, but there are ways to recover from getting lost. Centering the learner’s attention can be done by pointing to elements with text (over to the left, at the top). Might be possible to bold or color a text element to focus on. You use color to give the learner focus on specific notes: that could be done with text elements.

As you move into tutorial sections about text links, then moving to using text links to navigate instead of the map might be the thing to do.

Ditto when you introduce hierarchies of containers: Introducing navigating by outline view seems appropriate at that point. Doing so makes your point that “Hierarchies are a dominant and normative ideology: We are trained to see hierarchies everywhere”. By starting with map view, which lets the learner get comfortable with the map, containers, and navigating using a map, and bringing hierarchies later, you set things up for that larger idea of association. You’ll be hard pressed to do that in a Prezi.

You make a convincing argument that it works well enough. They means I can focus my time on creating more content, rather than on finding better ways of navigation.

These are very helpful suggestions, I will think about how to implement them.

I think that is the way forward, especially so for exploring other views that the map view. Once the user knows how to use ⌘’ repeatedly to backtrack to previously visited notes, they can always come back to the last tutorial note they visited.

One thing I have yet to find out is what is the set of basic skills I need to cover in a guided tour of mini-tutorials, so that on top of that I can create other tutorials the user can tackle in any ordert they chose. Navigating Text Links is definitely part of that set.

I am currently working on a tutorial for the Hyperbolic View, where at then end of the tutorial I let the user explore my (still unfinished) map of Tinderbox concepts that is also part of the document, so the user can see how different that map looks in this view.

To build on what you’re saying, it’s probably a good idea to have the user revisit the same map in the Outline View, to appreciate the difference that makes.

Thanks for your insights, I now see some things much more clearly.

Dear Lizard-of-Oz.
Thanks a lot for your TinderBox tutrial.

This may be a silly question, but when I open with TinderBox 8.6.2 , tutorial map view window become Black.
I can not read it absolutely, non of the tutorial messages under right-hand side"map view".
Using TinderBox 8.5.1, strangely enough, I can get revert to type where evry indicative informations without difficulty.
I would like to know and to take advantage of your expertise,
why I have such a difference between TinderBox 8.6.2 and 8.5.1?
My circumstance : OSX10.12.6 (Sierra) with Mac mini 2012.

thx and regards, WAKAMATSU kunimitsu

There are lots of tutorial files, and you don’t give a filename, but my guess is the issue here is files crossing light/dark OS mode. I realise you are using macOS 10.12.6 but the issue is not just the OS but the effect on the file.

Open the tutorial, then Document Settings (Cmd+8), Colors tab and select ‘Tinderbox 7’ and apply. I hope that will fix the issue (if it does, the ‘fix’ should work for other files).

Did that help?

Dear mwra,
Thank you for your help.
I get it. Curious to say, I need not to change Colors from Document Settings.
I do not know why and where comes this modifier?
Anyway, TNKU.
thx and regards, WAKAMATSU Kunimitsu
P.S
Tutorial file comes from here.
Scripting a tour through a map - Tinderbox Tasks - Tinderbox Forum