Tinderbox Forum

Coding & Syntax tutorial

Hi there, help is needed. :). First off, I’m not an engineer. I’ve read the tinderbox ref files, but I’m getting lost. Is anyone aware of a Tinderbox coding & syntax tutorial? I have the basic .contain and $MyString= elements down, but for the life of me I can’t figure out expressions, conditions, counts, or other calculation efforts so as to gather more insights or espresso insights (e.g. twitter())from my data. I get confused by when to use a { or an |, etc.


I’d start with the two large PDF tutorial docs you can access in the app’s Help menu: “Getting Started With Tinderbox” and “Actions and Dashboards”. If you’ve completed those, where are the bit where you got stuck? Which concepts are you struggling to map from the tutorials to your own work?

1 Like

Wonderful, thanks. :slight_smile:

1 Like

The guides do help, a lot, but what would really help those on the Green and Blue slopes would be for some Double Black Diamond pro to make a list of the 20 most common pieces of basic coding with a short description of what each of them do they do. What does the dollar sign do? What does a period do? What do brackets do? Etc.

1 Like
  • $ dollar signs designate that the item is an attribute. For example $DisplayExpression, or $Name, etc.
  • Periods (more accurately “dots”) are used as .dot operators, and list of dot operators
  • (round brackets) and {curly brackets} are used in conditional expressions
  • [square brackets] are not code elements – it is a common convention in coding dictionaries to use square brackets to indicate optional syntax. That convention is used extensively in aTbRef.

Learning coding in Tinderbox is like learning coding in any other context. Start. And continue. Read. Test. Experiment. Fail. Redo. Test. Succeed.

Learning to code anything in the abstract (“show me a list of the 20 most common coding pieces”) is as useful as learning the alphabet for a language you’ve never seen before. The alphabet has little useful information. If you learn Linear B you still won’t be able to speak Minoan. Use dictionaries. Read coding examples. Talking to others. Ask questions…

This forum is full of coding examples as forum readers seek and figure out approaches to doing what they want to accomplish. You need to start with a problem (“I want to make a stamp to do this and that…”) and begin to unravel it.

Eastgate provides no comprehensive coding manual. But there is aTbRef which is indispensable, and this forum, and email to Eastgate, and now the frequent Zoom calls, etc.

Coding is always unfamiliar to someone on the beginner slope because there is not much in the real world to relate it to. The only way to learn to code is to code.

If someone just never gets it, after attempts to try to wrap their mind around it, then stop. It’s not for everyone, and it is by no means essential to using Tinderbox. If all the coding support disappeared from Tinderbox, the value of the software would remain high.


Amen. Couldn’t have put it better, not least having climbed the slope described from not-clue to know-enough-to-be-dangerous.

What holds us back is fear of looking dumb, which is no different to visit the next village over. Being clever, as lots of Tinderbox users are, doesn’t meant stuff that’s hard to learn mean it’s the other party’s fault. Eat big things in small pieces. I spun my wheels when first using the app by assuming i had only to cast the right spell. Read the available doc, _ask questions, and you’ll move ahead. Tinderbox is a deep app: won’t say deepest as that’s a pointless competition. Suffice to say I use it first when faced with a new problem.

As aTbRef’s author I’d say, just start somewhere and follow the links. It is deliberately not a ‘how to’ as that field is too large to cover. Think of your task less in terms of an idealised end point but more in terms of ‘how do I get from here to there?’.

Paul, I could not agree more with your statements and am so grateful for you, Mark, and this forum and post.

A few comments.

Let’s start with @PaulWalters’ comment:

“If someone just never gets it, after attempts to try to wrap their mind around it, then stop. It’s not for everyone, and it is by no means essential to using Tinderbox.”

This was me for at least 5~7 years when it came to Tinderbox (longer truth be told). I intuitively knew it was useful, but I could just not wrap my head around it. I used it as a glorified shoebox. I’d find snippets of information, notes, that were important to me, and put them in. I tried playing with prototypes, etc… linking, attributes management, etc. But my usage was in fits and starts, the value of Tinderbox eluded me. I never fully gave up though, I maintained a sense of grit and kept coming back to it. I built a Tinderbox with hundreds of notes with people, companies, ideas, but they were all in different formats, containers, and not connected in any way. I was unable to pull any insight from them.

The Eureka moment

About 10 days ago something clicked in my brain and the power of Tinderbox revealed itself to me. I’m still by no means “good” at it, yet, but now I have the confidence to dive in and use it. In fact, I taught someone to use it yesterday. :slight_smile:. In looking back, there were a number of ingredients to my breakthrough:

1. Necessity, start with a problem , as @PaulWalters says “You need to start with a problem (“I want to make a stamp to do this and that…”) and begin to unravel it.”

In my case I had two problems,

  1. I needed to build an industry ecosystem map for my work, and
  2. I’ve gotten sick and tired of doing the same work over and over again in Excel.

I’ve gotten sick and tried on focusing on the outcome, e.g. an industry report, and not building an asset of notes that would enable the generation of numerous future and alternative outcomes. In the Excel model, I was wasting 90% of my research time because I’d just grab the information that fit at the moment, put it in a cell, and I’d ignore the rest of the insights I was coming across, even if I knew they were important. With Excel, I did not have the structure to capture the notes because they did not fit into my rigged 2 dimensional Excel framework. Tinderbox lets you capture insight and come back and refine it later.

Need alone, however, did not unveil Tinderbox for me. Again, I’ve had the need for years, so there were a few other pieces (lessons, insights, tools, processes, ideas, personal growth) of the puzzle that I needed for it to all take shape.

1. Zettlekasten , about 18 months ago I stumbled across Zettlekasten. The key insight I took away was that knowledge is created not in the final output but in the process of inputs, with note creation and curation. And if do this creation and curation effectively the final output basically writes itself. And it is much richer in insight than it would be otherwise. What worked for me was How to Take Smart Notes by Ahrens (2017). Again, the asset of notes built over time is the fodder of knowledge, as you steep in them, add to them, more knowledge and insight is created. The insight that can be used for any output — whether it is written, verbal, or visual.


2. 49’ Monitor, I got myself a 49’ monitor. Now I can see all my work. Simply amazing!

3. Don’t do too much in one Tinderbox , the key insight here is not to try to do too much in one Tinderbox. Now, I now have six Tinderboxes that I keep open all the time: 1) My ecosystem project, 2) personal development, 3) meetings & action items, 4) course development (I teach mobile marketing), 5) the old shoebox I’ve been filling for years—I’m pulling notes from this and putting them into the Tinderboxes that work, and 6) my test bed for trying out code. Also, I use other tools to get other things done, like DEVONthink for files and images management, TextExpaner to rapidly insert export code in my writing, Scrivner, Grammarly, and Zotero to help with my writing.

Looking back, the vast majority of my tools today I picked up from Mark and the team at Eastgate.

4. Massage the data scheme, don’t be afraid to create/delete/re-configure/rename attributes, for my ecosystem project, working on the “problem,” i.e. the data scheme was the breakthrough. I started with the key prototype I needed, Organizations. I then started breaking it down. Organizations have Products. Products have Features. Features have Benefits. Solutions (Products, Features, Benefits) have Use Cases. Substantiation of assertions and linkages among all these require Sources (aka References), Definitions, and Statistics. Each of these groups became prototypes with their own unique visible attributes and containers. My key insight here was that attributes are universal and can be used everywhere, regardless of the notes, the prototype simply helps manage the visualization.

I also, learned that it was OK to rename prototypes and attributes along the way as my model matured. The only challenge with this is you need to go back and update Agents, Stamps, and Rules if you change names, but this is a small price to pay. All of this may sound simple, but it took days (actually years if I’m truthful) to connect the dots in my brain and put this framework together.

5. Trust me, drop the fear, this was a HUGE leap. I’ve been afraid to write, afraid to code, afraid I’d never figure it out. Even though it has taken years, I’m starting to get over it.

6. Trust Tinderbox and the community, as I was building my data scheme I started to have ideas, as @PaulWalters notes above. I was thinking of my problems and breaking them down to “small Ps,” tactical problems like creating links vs. the “big Ps,” strategic schema problems.

For example, I thought “what if I used linking to pass attribute data bank and forth between notes as I linked them.” By doing this I would not have to manually enter the data every time into an attribute field and copy and paste across notes, which was a pain. Also, this would put the power of Tinderbox and Zettlekasten into action.

So, with a lot of help from the forum I came up with this:

$KeyAttributes=;$Prototype="Feature Prototype";$Type="Feature";$Benefits=links.inbound."Benefit".$Name(original).

What this does for me is that it allows me to pass data back and forth between notes with links. When I link a Benefit to Feature, the attribute $FTRBenefit in a note gets copied to the $Feature in another note. I have something similar upstream for $Organization linking,


What this does for me is it adds all the names of products in the $Products attribute and all the features related to every product in the organization’s $Features attribute. Now, I can generate insight up and downstream. I can just look at an organization and see everything it has, or I can look at its products and features, benefits, etc.

I’m not saying the above is perfect. There is a lot of tinkering to do. But it works.

7. Stamps and the attribute browser are your friend, I’ve learned to LOVE Stamps. They’re like a surgeon’s scalpel. They’re great for testing and give you much better control when manipulating notes. Once you get them right you can turn them into rules. Also, I LOVE the attribute browser now. I can output a set of notes, analyze them, but also edit and link them within the attribute browser to ensure consistency for the final output report. In fact, being able to see notes in various visuals is a very powerful value of Tinderbox It helps me to ensure consistency and generate insights.

8. Too many links in Map view really slows things down, I’ve found the value of leveraging containers and trusting that I can pull the notes back up to the forefront when I need them with agents. Before I tried to put everything in one giant map view and my Tinderbox just got unwieldily and slow. So, When I start to map a new org I do it at the top level, setup the org., add its products, use the Link Parking Space to link to features I’ve already created, etc. Once I have all the associations right I add the $Container attribute and then change the value to have it automatically moved and stored in the right place.


What I’m still trying to figure out now is if there is a way to run an agent that pulls the aliases of notes but also retains/redraws the original linking between the notes and their sub notes for the newly created aliases. In other words, I’d like to run an agent that shows the links between organizations, products, and features. I was experimenting earlier on this and had it totally wrong. Paul was very polite in telling me my code was a mess. :slight_smile: Now that I know better I realize just how polite he was being…“a mess” was kind. Anyway, I’ll come back once I figure it out.

9. The universality of some notes, in my schema $Features, another key insight I found along the way, products are a collection of features. Most products have the same base feature concept, e.g. Password Management, which may have nuances on exactly how they implement it but the primary feature of Password Management is the same. So I can use a common Feature note, delineated by $Type, and link it in multiple products and create unique linkages between a product or company. If a company is doing something particularly unique or different I can create a note to explain this.

10. Writing is small chunks, e.g. notes, and leverage export code variables, this was my big breakthrough. Each note is a piece of writing. I can use links, ziplinks, etc. to interlink my pieces of writing, and leverage the export features to pull them all together. Also, the use of export code, e.g. ^value($Name), in my writing was a HUGE breakthrough. Why, because now I could address item 5 above. I can pull in attribute names into my writing, like an organization’s name, and if I misspell it I can fix it in one place, i.e. in the attribute, and it would update everywhere. So, now, when I’m writing organization or product descriptions I can do stuff like “^value($Name) is a leading provider of [[Password Managers…” This insight has made my writing SOOOO much more fun.

Finally, 11, as “this one goes to 11”:

11. Humanity Power, a friend of mine recently released a concept “Humanity Power.” The idea is simple, there is “unity’ in humanity and we can all drive to eradicate the “isms” plaguing our lives. This may not be directly related to Tinderbox, but the idea of “unity” has been really profound for me. I also see there is “unity” in community and I’ve found exactly this with the Tinderbox community and this forum. For example, two weeks ago we held a Saturday afternoon session amongst community members. I felt the community. It was tangible.I was able to learn that others are in the same space, some more advanced, others less advanced, but I was able to both learn and for me most importantly contribute. For example, I knew something about Tinderbox and attribute browser usage that someone did not. This realization helped me understand that I actually could do it. I can make Tinderbox work. I then dove in. I’ve spent about 60 hours with Tindebox this last week.

This last week I’ve been drawing insight from the Tinderbox community bank. I’ve not given as much as I received. I am grateful to you all for your assistance. Now that I’m becoming more self-reliant with Tinderbox I’m looking forward to giving back as soon as I can.

Anyway, thank you all. This is a brief glimpse of my Tinderbox journey. It is all very exciting. I’m looking forward to the rest unfolding in due course.


Just seeing this post now. So useful! And rings true to everything I have learned about the program over the past dozen years. (The 49" monitor, alas, is still somewhere in the future.)

Very impressive of you to have thought this all out, and very generous to have laid it out.

Practical question: How would you feel about my tweeting a link to your post, “in public”? Or, if you have a site outside this discussion forum where you could reproduce it, happy to do a tweet of that. In any case, very well done.

1 Like

Hmm. That means moving splitting threads. Might a tag be a better methoD. Then, figure out how to get users not used to the forum s/w to find tags. Does that make sense?

49" monitor. Great for assisting social distancing in the office. :rofl: Actually, I’m well impressed that my 2019 top-spec MBAir can run 2 x 24" 4k displays (albeit at only at default res, or a macOS bug eats all the resources) as well as the built-in screen.

Never mind

Hi @JFallows, very kind of you. :). If you think it would helpful to others, yes please share. Please feel free to share the post, or if you’d prefer I recreated it on Medium A community and self-reliance story: Tinderbox. How it has become one of the most influential tools I’ve ever used.

1 Like

Thanks, truly, but…Paul’s list of four things high up was a good start. Three of the four gave me exactly what I’m looking for. The one that didn’t was dot operator. What IS a dot operator? What’s its function? What’s the difference between a dot operator and a simple operator?

I know this is very basic. I should have put my request this way: A list of the ten or 20 most common symbols and what their functions are. What are they meant to accomplish.

I’m not asking how to do certain things. I’m not seeking algorithms, or any procedural steps. I’m asking for a description of the basic tools used to do those things, so I can start doing stuff myself.

On the alphabet comparison, yes, I am asking, what is a B, what does it sound like? That elementary.

I know everyone’s a volunteer here, and I do respect and appreciate all the time and effort. But plenty of people are coming in to try Tinderbox with no more programming experience than I have. I believe a simple such list, crafted with education in mind, would keep more beginners from giving up on Tinderbox and enlarge the community. If that’s what you want.

PS - Satikusala, great stuff.

Hey @hrmhrm,

What a great question. I’ve been trying to figure out dot operators for a while too and your post inspired me to do just that.

Dot operators are a way to 1) manipulate and get values from attributes, like a color, e.g. change or set them, or query their value to be used in another operation, or 2) perform a function like sort, list, change case, count words, count characters used (size), etc.

Here is an explanation of dot operators and a list of them.

As they say, “innovation is born out of necessity.”

Truthfully, I was not successful with Tinderbox in any material way until about 2 months ago when necessity drove me to figure it out. Now I spend about 65% of my day in Tinderbox. I do the majority of my work in it and only turn to other apps for data collection and output (.e.g. PowerPoint). I use Tinderbox for everything else: collection, curation (lining and thinking), and contribution (authoring).

To illustrate dot operators, check out this include-test4.tbx (104.9 KB) (this also has my include explanation).

In this file, I created a note called Dot Operators and am displaying the attributes: Tags;StartDate;MyDate;MyString;MyNumber;MyBoolean;Mylowercase;DisplayedAttributes.

As I don’t want these operators to affect any other notes I used the Inspector (use ⌘1, click the Gear button, i.e. the Action Inspector) and wrote a Rule that only applies to this note. If I wanted this Rule to apply to any other notes I’d apply the Rule on a prototype note or an agent query action (more on this later, if you’d like).

You’ll see in my example rule that I’m running three dot operators: .count, .day, and .lowercase.


$MyNumber=Tags.count;  - This one counts the number of items in the $Tags attribute and returns the total to the attribute $MyNumber.

$MyString=StartDate.day; - This one grabs the day from today's date and puts it in $MyString.

$Mylowercase=$Name.lowercase - This one turns the grabs the $Name attribute for the notes and puts it all in lowercase in the $Mylowercase attribute (a user attribute I created for this example)

Frankly, I don’t know what I’d do with nearly 90 percent of these operators as the need has not driven the necessity for me to learn them yet. However, I could see the String.size, for example $Text.size, to be used to calculate the number of characters for a tweet note where the week was in the $Text of the note.

I hope this helps.

Dot operator allow operators to be chained together. It is also the case that some things can be used in dot and non-dot forms, for instance count() and list.count(). These are functionally the same thing:

$MyList = "ant;bee";
$MyNumberA = count($MyList);
$MyNumberB = $MyList.count;

In this case both $MyNumberA and $MyNumberB will have a value of 2. So why have both? History! Tinderbox is actually 18-odd years old, very long lived in software terms. Although the app launched in 2002, it wasn’t until v.5.70 in late 2010 (see) that the first dot codes were added.

Indeed, you will see many functions have only a dot form as they are newer to the app. Thus whilst a count() and .count() pair of operators exist, there is a .reverse() but no dot-operator equivalent. But it’s not some existential challenge:

To take the second part first, it’s function is whatever that function does, but the rationale has long been described here (I originally documented this back when the feature was added). As described the point is chaining. Though perhaps obvious to those who’ve used modern coding languages (i.e. not many people!) the basic rationale is making purpose more explicit. This becomes apparent when you want to to do as task involving several discrete functions. Again these do the same:

$MyListA = functionC(functionB(functionA($MyList)));
$MyListB = functionA($MyList).functionB().functionC();

Both do the same, but note the first is more difficult to read (or understand as the functions have to be nested inside-out to be evaluated in the desired order (A>B>C), whereas the dot.chained method is (I’d argue) more understandable to a wider range of users

Well, if you read, as stated, @satikusala you will have noted his point that you don’t have to use every tool in the box and @PaulWalters point to him that the way to learn is to have a purpose.

I could tell you the hammer() tool is the best in the box, but tho the person with a hammer everything is is a nail. It’s an , albeit unintentionally_, silly question to ask as different users will give you different ‘top’ lists as they use different aspects of the app.

Nearly all the codes listed here have example code. Have you tried them? That would be a better way to start. Even better, pick a task (not a whole workflow) and look at the function(s) you might need.

Trivial example. I’ve a list, in $MyList, “COW;ANT:DOG;BEE”. How do I get the second item in the list, once listed in alphabetical sort, and in lowercase? So, we need to sort the list, find item #2 and it lowercase:

$MyString = $MyList.sort.at(1).lowercase;

Wait, what’s the ,at(1)? We want item #2. Sso, we look up .at() and find it is zero-based . The result is we get ‘bee’ in $MyString, and we learned how to use _three operators. Like I say start small.

. IOW, the first item is number zero, second is 1, etc. Don’t shoot the messenger. Back in pre-historic computing days, every byte mattered so starting numbering from 0 rather an 1 made sense. Yes, unguessable to non-techies, but that’s coding for you. Like many trades, they evolve less fast than you think.

As Dr Lanning puts it in the film “I,Robot”:

“my responses are limited, you must ask the right questions”

But, seriously, that’s not snark. Pick a small task and solve it. This does two things: oyu learn some functionS) and you begin to see how you may use them to address your larger workflow. Tinderbox is not an app with a limited range of canned ‘choices’ of what you are allowed to use. Rather, it offers lots of tools that you choose to address your task. It’s a different way of working and why you’ll often read answers saying “it depends on what you are doing” or “there is mote than one way”.

@hrmhrm, hey there. Again, thanks for your question. Serendipity linked your question here with another question I had on a different post on wildcard searches.

Check this out. include-test4.tbx (110.8 KB), a great use of the dot operator. :slight_smile:

I run a rule with two dot operators, sort and format. This rule pulls the items from $DisplayedAttributes, sorts them, formats the set to a string, and then codes them with the HTML so that on export they become a bulleted list (see this).

Here is the export preview: