Tinderbox Training Video 12 - Working with media in your TBX files (Part 1)

Tinderbox Training Video - Working with media in your TBX files (Part 1)

Level Intermediate
Published Date 1/1/21
Tags Tinderbox, aTbRef, Images, Video, Audio, value(expression), Export Code
Video Length 14:39
URL Tinderbox - Working with media (Part 1) - YouTube
Example File TBX - L Working with media (Part 1).tbx (215.8 KB)
Revision 1
TBX Version 8.9

In this lesson, I discuss how to manage media files. Specifically, I show you how to embed images and reference (display and play) images, video, and audio files from your hard drive within your Tinderbox files. Referencing media, rather than embedding it, keeps your TBX file sizes to a manageable level and really helps with streamlining media file management. I also explain how to dynamically insert values from your attributes and use them in your text ($Text)†. Using the attribute value insertion method means that you won’t have to mess with your HTML each time you want to update a media file name the related configuration values (path, width, height); it will also help you in working with straight vs. curly quotes (something else I explain in the lesson).‡

NOTE: Be sure to download the sample file and play with the examples in this tutorial.

†Since recording this lesson, I’ve taken my own advice. I have created $MediaPath, $MediaDIR, $MediaWidth, and $MediaHeight attributes so that these values, like the file name, are pulled in from attributes. Another way to think about this method is to consider it a configuration setting method. This configuration method, especially when used with prototypes, enables me (and you) to change where files are stored on the hard drive. I can update the paths without the headache of having to manually change the values in every related note within Tinderbox. I can simply update the related prototypes or apply stamps to update all my notes if and when I change my file paths on my hard drive. I’ve updated the example TBX file that accompanies this lesson.

‡If you’re like me; you’ll find great value in knowing the attribute value insertion technique, also know as ^value( expression )^. You’ll learn to use it in so many different ways.

TBX - L Working with media (Part 1)

Reference materials

Code Snippets

Image HTML
<img src="^value($MediaPath)^^value($MediaDIR)^^value($MediaFile)^" width="^value($MediaWidth)^" height="^value($MediaHeight)^"><br>^if($MediaCaption)^<b>^value($MediaCaption)</b>^endif^ ^if($MediaSource)^(^value($MediaSource)^)^endif^</br>

Video HTML
<video width="^value($MediaWidth)^" height="^value($MediaHeight)^" controls><source src="^value($MediaPath)^^value($MediaDIR)^^value($MediaFile)^" type="video/mp4"></Video><br>^if($MediaCaption)^<b>^value($MediaCaption)</b>^endif^ ^if($MediaSource)^(^value($MediaSource)^)^endif^</br>

Audio HTML
<audio controls><source src="^value($MediaPath)^^value($MediaDIR)^^value($MediaFile)" type="audio/mpeg"> </audio><br>^if($MediaCaption)^<b>^value($MediaCaption)</b>^endif^ ^if($MediaSource)^(^value($MediaSource)^)^endif^</br>


Really helpful just like the others Michael

Two questions…

(1) Can you clarify a bit more how Tinderbox works with your template to your media directory. Does it automatically give you options in the dropdown for which file within that directory? I gave up Textexpander when I started using Keyboard Maestro but I am now wondering whether there are features in Textexpander that Keyboard maestro does not perform

(2) Can you talk a bit more about how large a file is “too large” for Tinderbox? In a computer where RAM and SSD size are not really limited, what is the downside of embedding images directly in a Tinderbox file - among other reasons for portability/sharing convenience?

In short, no. You manually specify the text you want. But this does not determine. I use TextExpander constantly. As noted, however, since recording this I have refined my approach.

Here is the latest example of my code, which I use inline in notes via TextExpander and in export templates.

^if^(^value($MediaFileName)!=="")<a href="^value($URL)^"><img src="^value($MediaPath)^^value($MediaDIR)^^value($MediaFileName)^" width="^value($MediaWidth)^" height="^value($MediaHeight)^"></a>^endif^<br>^if($MediaCaption)^<b>Figure: </b>^value($MediaCaption)^ ^endif^ ^if($MediaSource)^(^value($MediaSource)^)^endif^</br>

You can see here how I’m using it as a config parameter to pull into my notes:

Too large is a relative term. If the TBX file gets bloated it gets slow and sluggish. A few images is fine but when you get a lot you end up with necessarily large files to mange, when you could just you the approach I share here. Moreover, your images and media stay in their native format, which will make it easier to use them in export, in other apps and edit/update them.

1 Like


What do you think about storing them instead in Devonthink with X-Devonthink links to them from Tinderbox?

My concern is how feasible it will be to keep scattered directories/files intact and accessible long-term. For sure my Devonthink database will always be easy to find.

That said- I am not sure what the syntax would be to use an x-devonthink link with img src - is that possible? An isolated link works but is it possible to render the image automatically without clicking the link?

Not sure, not tried this.

I tried but could not get it to work - maybe there is some syntax that has to be changed

If not possible, then perhaps it could be considered as a feature. I would suggest that a local “media folder” is fine for short-term use of mostly transient documents. But if you are talking about documents of greater importance - like a collection of notes intended to be a career’s work, or a document which is part of a legal case or some other professional work - then a way to save the media in Devonthink seems to me less likely to be lost in the long-term. Also for confidentiality reasons you might want to separate media files into subfolders (especially if you have images which are sensitive for some reason); again it is much easier to retain such multiple subfolders as part of a broader database like Devonthink.

I think I understand, but why can’t you simply have a file folder structure in your finder. How would the DeveonThink structure be any safer or more reliable than a folder path on your finder, especially if you had the path linking to GoogleDrive or Dropbox, where these files are being automatically backed up and saved? I must be missing some critical piece of thinking.

First Michael - let me say again this video series is stupendous - really a huge help to anyone learning Tinderbox.

As for media files, one major concern is handling confidential or private content. An attorney or physician or accountant or others working with such content probably would not want such photos or video in random folders on a hard drive or Google drive or Dropbox. Putting them all in an encrypted Devonthink database makes them much more secure.

Related to that, if images are in a folder in the Finder, they may find thumbnails lurking in Foxtrot Search, accidentally imported to iPhoto, etc etc. Those sorts of accidental spread of images are less likely to happen to images stored inside a database.

Another issue is continuity of access when you move to another computer in the future. You can put both a Tbx document and its related media in the same Devonthink database and then move that to any other computer and it will still function with no issues on the new computer. If you instead need to re-create the directory structure of your media files on a new computer, then there is a chance that links will no longer work.

The issue of confidentiality/security is most important to me. If I am responsible for someone’s private data, I can keep that trust with more confidence if both the .tbx files and the media files are all in one encrypted database file. Nobody wants their medical or legal records in a random directory in someone’s computer and then uploaded to the cloud in similar fashion.

PS - I did several document reviews this morning where I put the Tinderbox .tbx file itself inside Devonthink - it works well to keep all aspects of a particular client/case connected. For now I am including the images inside the .tbx file, but if there is some way to link instead to images stored elsewhere in the Devonthink database so the .tbx file size stays small, that would be great.

All good points. I’ll try playing around with DT3 and see what I can figure out. Interesting stuff.

1 Like

Hi Michael,
first of all: thank you for all the work you put into your lessons - they are really helpful!

Two suggestions:

  • I made a special prototype only for using external images. So I can add the text snippet there and don’t need any additional software
  • you don’t need the “file:///” prefix. The absolute path without it works fine.

I do have two problems too:

  • in your demo file everything works like a charm, in my own file instead of the rendered image I see a “0” only. I think this problem is connected to the export templates - I think I have to watch another one of your lessons to get this fixed :wink:
  • I looked for the documentation of the syntax used with the value function and the attribute. I found no explanation why those “^” characters appear in the source… any hint?

I’m using embedded images so far. But tinderbox files grow in size by a large amount with even small images and tinderbox becomes slow when I open a container with some images. So to use external images is fine for me (no security problems since most of the images are copied from Wikipedia) - but I need them to appear in the map view and they don’t. I see the html element (<img…) instead.



The ^ (caret) characters are used to distinguish placeholders in HTML export; these elements are replaced by values extracted from your document. They’re all discussed in Tinderbox Help: Export and in aTbRef, but only a few are used very often:

^title     the document title
^text     the note's text, with style translated to HTML
^value(expression)   the value of any expression

Thus, ^value($Price) is the replaced by the value the Price attribute for this note.

Thanks. yes, I think you’re right. the file:/// may note be needed.

Not sure what you mean by the 0. I’d need to see an image or sample file to figure it out.

The ^ is the designator that Tinderbox uses to call out “export code”’

Referenced images won’t appear in map view. The best way to do this is use the $Fill attribute. The problem with this, however, is the images must be in the Tinderbox’s support directory. We’ve made a request to the developer to be able to supply a path to in $Fill so that the image can be stored anywhere on the drive.

@eastgate thanks a lot. I search the help but… so thanks for the hint.
I’m wondering why @satikusala is using the caret twice - why is there a 2nd caret after the expression?

<img src="^value($MediaFile)^">


never used $Fill so far - another tasks to learn :wink:

I suspect that you have no value in the $MediaFile attribute. You should put something in there like, /documents/image.png.

You need to include the path and the image file name.

nope - I do have a value in the $MediaFile - the same value and the same code works fine in your sample.

Can you share a sample TBX file?

The closing caret marks the end of a placeholder. It is always permitted but is usually unnecessary. Many Tinderboxers who use export templates extensively prefer to include it for clarity.

By any chance is your image a “0”? I just tried to reproduce this and can’t. Image works fine for me.

No - the image is a portrait of Ferdinand de Saussure :wink:
Here is a demo file - I still think the problem is related to the export templates… just a wild guess

sample.tbx (118.5 KB)

Got it! Change your export template to HTML. It is the Scrivener template that is messing you up.