How to use Templates?

Tutorials and Examples
1

Is there a straightforward, elementary tutorial devoted to the function and uses of templates?

2

Hey @wajakob, great question. Templates are one of the most powerful features of Tinderbox.

Why

Templates help you think about your notes—they are effectively new views. Likewise, they help you prepare your raw notes to get your processed material out of Tinderbox, i.e., copy and paste or export your refined information and insights. Once you’ve copied and pasted or exported your material from Tinderbox, you can then share it with others or enhance it further by processing it through additional workflows.

What

You use templates to prepare an individual note, a note and all its descendants, or your entire file for preview or export into whatever structure, e.g., linear document, bulleted presentation, table, complex visualization (i.e., images using JS rendered graphs, plots, and diagrams, etc.) and output format, e.g., HTML, markdown, CSV, JSON, etc., you want.

From this point, you can copy and paste the preview or export output into other apps (e.g., a text editor, Google Docs, MS Word, email, a learning management system, etc.) or send the output through a different parser (e.g., Apple Script, Pandoc, Quatro) to generate HTML, Word Docs, PDFs, Powerpoints, and more. With the latter, if can also have your citations automatically converted to APA, MSL, Chicago, etc. reference formats.

How

You’ll use Tinderbox attributes, action code, and export code to help you prepare your output. The action code and export code will help you use the values of your attributes (including notes $Name and $Text) to transform, transmute, transclude, calculate, etc., the values and place them in your output in the structure and appearance you want.

I know it sounds like a lot, but in the end, it is a learnable combination of structured systems: markup/markdown languages, accepted and standardized data formats, accepted and standard syntaxes, command-line arguments (including options and flags sent to applications), and your own incrementally formalized personal conversions and workflow.

Disclaimer: Undefined Terms and A Broader Perspective

Sorry about the undefined or complex terms. I realize that numerous terms above may be unfamiliar to some and indeed were, and in some cases and contexts still are, to me. It is a challenge in a single post to define everything and the context needed to fully grasp the comprehensive tools like Tinderbox, let alone the ecosystem in which it thrives.

I’ve come to realize that Tinderbox is not your run-of-the-mill app. It does not say, “follow these steps and you’ll get these outcomes.” Rather, it is a toolbox; it is more akin to an integrated development environment (IDE) where you can 1) enter text (e.g., words/code), 2) edit/debug your text and code, 3) compile your text into a human-readable output (linear docs, spreadsheet, presentation, image), 4) build automation to offload repetitive tasks, 5) navigate, search, and rediscover your text, 6) version control your text, 7) create plug-in/extension like capability with action code and template (your own and JS visualizers), 8) integrate with the terminal to use 3rd-party processes and application. In the end, our thinking/writing is a lot like programming code, with the former being read and interpreted by human or non-human agents (i.e., AI) and the latter be read and interpreted by a machine (i.e., computer) to ultimately learn something and to perform some action.

In the end, I’ve found that Tinderbox has helped me learn, improved my critical thinking, helped me develop reusable assets, boosted my productivity, reduced my errors (or at least helped me catch them earlier), streamlined my workflow, reduced my stress levels, given me community and friends. Again, it is pretty powerful!

Resources

There are TONS of FREE resources (video tutorials from me, others, and the meetups):

Last week’s meetup was particularly good on this front: Tinderbox Meetup, Jan. 12, 2025 (Video): Using TBX to Write, List Temp, Dynamically Create Days Demo.

A Tinderbox Reference File (aTbRef) is also an instrumental resource. PSA to ALL: Please consider making a donation to @mwra for his 20 years and continued support and development of aTbRef (link also on the footer of aTbRef).

Finally, if you want to dig deeper into all of this, you can check out my Mastering Tinderbox courses.

Becker (5Cs and Mastering Tinderbox)

3

The Tinderbox Manual has a good description (using Manual version 9.6.0 starting at page 104 onwards).

4

May I check if we’re talking about the same thing, please. Am I right in thinking you mean the Tinderbox Help guide which is on the Help menu in the program itself? I think so, but I wanted to check.

I can’t find an up to date version of this User Manual as a PDF though – the version that’s available for separate download here is only version 9.2, and export in that is only covered on page 28.

If I’ve got that wrong, where can I find the pdf version of the User Manual, please?

If we are talking about the same thing, @eastgate, would it be possible to put the up to date version on the web page?

Thanks!

5

Yes, I noted that the Eastgate web-page now points to version 9.2.
Sorry, but I do not know how to put the file here (size 5.5 MB).

6

It seems to me that the 9.6.0 Manual is what is shown in the Help menu. My earlier reference to page 104 would be what is shown doing Help->Tinderbox Help->Export->Simple Export and onwards.

7

Thanks!

The help version I see initially on Help > Tinderbox Help isn’t explicitly versioned (the Release Notes have 10.02) and doesn’t have page numbers, which is why I was a bit confused.

There is a single page help file (only accessed via the in-help search bar (cmd-opt-f and enter ‘Help’)), which seems to be version 9.20 – the same one as on the website.

Screenshot 2025-01-16 at 10.47.02
Screenshot 2025-01-16 at 10.47.021926×1518 223 KB

I can’t find a page numbered version, nor 9.60.

Never mind – it’s not a big deal. Thanks.

8

I modified my initial post to add a bit more of an explanation of what Tinderbox templates can do for you. As for the “manual,” I don’t recall seeing an updated version for quite some time—Tinderbox foundations in the manual are still relevant, but the application has evolved significantly since 9.2 (the current public version is 10.0.3; the backstage version has become even farther).

The Tinderbox template mechanism is very flexible and powerful. @wajakob and others, it would be helpful to understand what kind of work you’re trying to do in Tinderbox and what kinds of output you’re trying to generate. We can use your questions and the basis of a future meetup, like we did with @_Bill last weekend.

9

Michael,
Thanks much for the What, Why, How supplement to your initial reply to my query. I am building a research file consisting of the following containers: Bibliography, Notes (viewed in Outline,Table, and Attribute Browser), Timelines, and Draft Essays plus backstage stuff. I will extract from Notes and Essays by copy and paste. For many years I have used Tinderbox as a sort of data warehouse and paid very little attention to templates. I have limited my use of action code to note explode operations. I am now looking to create a solid research file from which I can build out some additional functions, hence the query about templates.

1 Like
10

A clarification. the Tinderbox app’s ‘Help’ is in the app. Because the HTML is generated from a TBX it offers the opportunity to make it into a PDf. But the TBX file is the developer’s and I’m the one who—occasionally—re-edits a copy of the TBX to make single-page HTML output that I can then further process to make a PDF. This is why the PDFs available are not canonical Help source or always for the latest release.

As the tool used to make the PDF is no longer developed and I’ve moved Macs since last using it, as I write, I don’t know if the method even still works. If you want to read the current Tinderbox release’s Help use in-app Help.

1 Like
11

That is awesome! :slight_smile: I completed my entire doctoral dissertation using Tinderbox and it family of tools for thought. I’ll DM you. Happy to jump on a call.

12

Yes and ‘No’. The latter only because “How to use Templates?” is a broad, open-ended, question given the nature of Tinderbox. At their most basic, i.e .most simple to understand, is HTML export. From that use templates are bent to all sorts of additional uses both internal and for export. But if you grasp the HTML export basics—even if you don’t understand HTML code or wish to do HTML export—you will understand the core mechanism. From there you will have the

But also ‘Yes’, as here is a demo file https://www.shoantel.com/acrobatfaq.com/tbdemos/HTML-v6.zip with 5 simple exercises, one task per file building in complexity. The exercises were written for the v6+ app re-design and steps through the basic building blocks, so works with current release (v10.0.2, as I write this).

Its README file notes:

Please open each exercise in order, and follow the instructions in the ‘HOW TO USE’ note.

Sample HTML export for each exercise is provided as a zip file but you will get most
value by doing the exercise before looking at the examples.

This demo shows the basics of HTML [sic] export. Export is possible using other forms
of mark-up but that is not included in this demo.

Exporting a file for the first time, you will be asked for an export location. Once given,
the TBX file will remember the location is used on the same Mac.

Export doesn’t over-write pages that have already been exported. When testing, it can
be useful to delete any previously exported pages before doing a fresh export, or pick a new
export folder.

Although most things people want to learn involve more complex scenarios, I’ve noticed over time that starting with the basics makes people struggle less when faced with the more complex tasks.

Even if you only intend to use templates for in-app Preview mode, you need to understand is it still export that does’t export to disk†.

For those whose only past experience of HTML is Markdown-based apps (Obsidian and many, many, like it) be aware that Tinderbox pre-dates the invention of Markdown and is not based around Markdown. So, in order to ‘just’ use the Markdown support provided for Tinderbox you still understand the basics of Tinderbox’s HTML export.

†. Actually, even then it still does, but the export files are hidden internally on the Mac by the app so it only appears to export nothing (from the use user’s perspective).

13

Thank you for the references/links to the shoantel exercises. Most helpful.

1 Like
14

Thanks.

To clarify a different aspect—terminology, a few notes might help. In Tinderbox a ‘template’ is something used only for exporting data (even if only for internal ‘export’, i.e. preview). The template uses Export code to insert document data on export/preview, e.g. a note’s title or some of its attributes’ values.

In some other apps, ‘template’ implies a predefined (visual) style/layout. Such apps’ perspective might make a Tinderbox template seem more like a form design. Neither perspective/descriptive approach is right or wrong—it’s only confusing if we apply the wrong perspective to the wrong app.

FWIW, the aTbRef site I link to above is—apart from images—produced entirely from a single TBX file (you can get a copy). Most of the over 2k HTML pages are produced from a single template, albeit one with lots of conditional export code. Thus, different conditions means the same template makes:

The simple demos you now have should help you understand how the move complex templates as in aTbRef (yes—the TBX has all its templates too) are constructed. Start simple and add in ‘extra’ complexities one at a time and you’ll soon master templates that suit your own needs.

I ought to add, there is no requirement to export from Tinderbox (or use preview mode). Some folk like/need it but not using this feature does not imply one is missing out. Some people get everything they need without having to bother about export. So don’t rush to worry about export if you don’t yet need it as it helps to have an export-related task in mind when moving beyond the basics.