Tinderbox Forum

Programming Guide

I have spent many many days and hours taking notes from tutorials, tbRef and Web articles, YouTube and more sources then I can mention here … and yet I’m still not able to write hardly any Agent, Actions, Stamps etc. programming code in TB. I have programmed in Visual Basic extensively and several other types of code. So I - do - clearly understand many of the TB code commands.
But … to get to the point … all of the info of learning TB programming seems to be scattered in so many sources, partially. I’ve searched Barnes & Noble and Amazon and I’d pay for a TinderBox Programming User Guide. I already understand many of the design concepts in TB. I would like to obtain a guide about programming in Tinderbox in one source. Is there such a guide?


There isn’t a guide as such. But then again, action and export codes aren’t a ‘programming language’ as with Visual Basic. Rather, the code in Tinderbox is an extended scripting language that has grown organically over some 18 years, in response to users needs. If you think of it as a programming language you’ll be looking for an IDE (there isn’t one) and ‘normal’ programming methods (different varieties of looping, variables) that action and export codes don’t have. Thus the best way to learn is to set yourself a task rather than try to learn in abstract, starting with small tasks and building in complexity as you go. A good tip is to start such explorations in a new file so you can see the wood for trees if you get an unexpected result—harder to do if the error is somewhere in 00s of valuable research notes.

The most comprehensive reference is my own aTbRef. Note that by intent it is not a task-based how-to, simply because the range of ways an open-ended tool like Tinderbox would make such a task near impossible. The best simple primers are the two PDFs available from Tinderbox’s Help menu. If you haven’t already, I would work through, or at least read through those, with aTbRef open in a browser so you can reference terms/concepts as yet unfamiliar. Lastly, when stuck, bring questions here. As this is a user to user forum it helps to post code or small example files so there is a common frame of reference. Also in describing a problem the task at hand is as important as to the (as yet) unachieved overall aim.

1 Like

Tinderbox scripting is kinda like SQL – agents are your reads (SELECT) and actions are your writes (UPDATE).

Export code is kinda like PHP, or any other templating language.

I come from a programming background too, and had a hard time wrapping my head around how to make TB do what I want.

My best suggestion is to follow Mark’s guidance above. When you want to do something with Tinderbox scripting, and you don’t know how, post your question here. Do that enough times, and you’ll start to get familiar with the techniques involved, and be able to solve more problems on your own.

I’ve been using Tinderbox since 2010. I’ve been programming since 1970, sometimes for a living, and I too have had a maddening experience trying to do something new with Tinderbox. Every time I do, I get very frustrated. Sometimes I spend 1-2 hours trying to get something to work, and occasionally I give up.

Tinderbox is essential to me and yes, its support is excellent. But I’ve described it as the Winchester Mystery House of software. Did you, for example, know that there are 8 ways to export to text? Here they are:

  • Export > as HTML
  • Export > as Outline (then as RTF, text, or doc)
  • Export > as Text (then as RTF, text, or doc)

…and each one behaves differently and gives different results. TBX has lots of edge cases and it is often counterintuitive.

OKAY, ENOUGH RANTING. Here’s something more constructive:

There are probably 100 different tasks that we all would like to do, but it’s not written down in a succinct way. For a given task, it’d be nice to know at least one way to get it done. Maybe it wouldn’t be the best way. Maybe it wouldn’t work for what you want it to. Even then, it’d be a good place to start.

I’d like to see a listing of “To make T happen, do X, then Y, then Z” entries. I envision a wiki that people just contribute to. I’d be willing to create a template for what a given “how to do T” page should look like (something simple) and a hierarchical structure for the wiki.

Would anybody be interested in contributing to this? Do you have other ideas about how to get this done? Let me know.

–Gregg W.

1 Like

There was a Tinderbox wiki at one point. It was difficult to sustain the community’s interest in maintaining it. These things tend to start enthusiastically, then peter out. The only comparable site that comes to mind is the Keyboard Maestro wiki, which is almost entirely a volunteer effort by some extraordinarily dedicated individuals (such as @JMichaelTX).

There’s nothing stopping anyone from creating a Tinderbox wiki site, of course, if you want to @gregginca?

But, wait, if it’s about “how do I do X”, then what’s the difference between the wiki suggestion and this forum? Or the legacy Tinderbox forum for old versions of the app? Or the books, or aTbRef? (Talk about someone contributing, sometimes I think @mwra lives his life so that we can understand and capitalize on Tinderbox – which he does for FREE!)

So, it’s not like no one is trying to help. I’d suggest that every single question arising in this forum gets answered in precise detail – that is to say, every question that the readers here understand. Some folks are unable to explain their requirements, which is another problem for a different thread.

Maybe it’s not possible to list “here’s the top 100 things you’ll want to do, and how to do them”. Because everyone’s top 100 is different, or maybe many of use have no idea what we want to do until a new project comes along and we have to use the tremendous power and flexibility of Tinderbox to figure out a new way.

Which leads, in a sense, to the “8 ways to export text”. There are eight (actually more) ways precisely because Mark B has listened to all of us over the years and responded to requests for different outcomes. From where I sit, I think that’s mainly how Tinderbox grew and continues to grow. It’s not a case of over-complexity, it’s more a case of “you don’t need this feature – don’t use it – someone else will”.


Paul, what I am proposing (which would happen only if others see a definite need for it) differs from the many useful support options that do already exist in the following ways:

  • For those cases that it handles, it would cut down on the friction and frustration of searching for an existing answer, decoding paragraphs of somebody’s text (or the comprehensive documentation that tells you what TBX will do but not whether this is what you want), and so on.

  • Standardizing the format will make it easier to read an understand an answer.

  • It would provide instant gratification for frustrated users instead of the time spent in describing your problem and waiting for a response.

  • Users will be more likely to use more TBX features if the process of beginning is not so daunting and discouraging.

  • More reasons than I have time to list today

Task-based documentaion (“If you want to do X, do the following three steps…”) is known to be effective and desired by customers. The formal documentation is a hypertext labyrinth of capabilites, full of unfamiliar terms and actions that are confusing–not just to a beginner, but also to me, an eight-year user of TBX.

The usefulness and popularity of TBX is severely limited by how intimidating the architecture and complexity the software is to use. TBX needs more guidance on how to use it, not more features.

If a lot of TBX users agree with me, a wiki would be an informal channel of self-help. But if there’s no call for such a thing, then I’m okay with that, too. I can’t be the whole solution, but I’d love to contribute a certain amount of work.

Best wishes to all who read this. Thanks.


It would probably be helpful (and a good exercise) if you could list 10 or 20 cases for “X”, from your perspective. Would make the proposal concrete. Apart from the formatting suggestion – which is fine – the concept needs to be fleshed out by someone who could find it useful.

1 Like

Thanks for reference.

A post was merged into an existing topic: Copy and Documentation Review