Tutorial: How to add an embedded image

How to control caption, size, and position

In BoxPress, you include images in your text-flow elegantly—by naming them in a macro.  The macro for basic image export is MediaImg. It requires two args: the filename and the title. The title will only appear on hover and as alternate text for non-imaging browsers.

Images are automatically centered, responsive, in a well, and include both alt and title. Just add an optional 3rd arg to change size and/or position (doing so also removes the well). Images are automatically links to themselves as full-page views. Just add an optional 4th arg to link it elsewhere.

To export the image with a caption, use MediaFig.

Let me demonstrate. I will now embed a centered and responsive image in this midst of my writing. I will do so by typing the following text:

^do(MediaImg, "tesseract.gif", "Contemplating the very notion of a three-dimensional shadow is never a waste of time!")^

In Tinderbox, text that starts and ends with carets (^) is called export code. To embed a macro, you use the ^do()^ export code. I will now type the above macro as my next paragraph:

Contemplating the very notion of a three-dimensional shadow is never a waste of time!

You should see an image above. It’s that easy!

To embed an image with a caption, all I need to do is type this:

^do(MediaFig, "tesseract.gif", "Now I have a caption!")^

Which I will do right now:

Now I have a caption!
Now I have a caption!

That is, by using MediaFig rather than MediaImg, a caption was added.

BoxPress includes convenience classes for position, size, well, and shadow. The default classes for your image are img-responsive img-center img-well, meaning that the image will be centered, responsive, and in a well. Override this with convenience classes for image position (img-left, img-center, img-right) and size (img-large, img-medium, img-small, and img-xs). Adding any override will remove img-well effect. (Thus, to simply remove the well, use a redundant img-center.) Ultimate convince with minimal intervention!

Let’s make the image small, keep it centered, and remove the well. All I need to do is type this:

^do(MediaFig, "tesseract.gif", "Adding any class will remove my well.", "img-small")^
Adding any class will remove my well.

Since any class will remove the well, we can pass a default class if our goal is nothing but well removal. Let’s pass img-center and see what happens:

^do(MediaFig, "tesseract.gif", "Adding any class will remove my well. Since I am already centered, adding img-center only removes my well.", "img-center")^
Adding any class removes my well. Since I am already centered, adding img-center only removes my well.

To pull the image to the left or right margin and have the text wrap around it, add img-left or img-right to your third argument. Size and position classes combine nicely. To restore the well, add it explicitly:

Notice that the well is back

^do(MediaImg, "tesseract.gif", "I am small, floating left, and my well is back.", "img-small img-left img-well")^
I am small, floating left, and my well is back.

Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping.

To use a shadow instead of a well, use img-shadow:

Now I am small, floating right, and have a shadow.

^do(MediaFig, "tesseract.gif", "Words to live by!", "img-small img-right img-shadow")^
Now I am small, floating right, and have a shadow.
Now I am small, floating right, and have a shadow.

Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping.

If you use only img-left or img-right, then img-medium is kindly added to make sure that wrapping occurs on all devices. You can always override if you disapprove. But let’s just use the default here:

^do(MediaFig, "tesseract.gif", "Moving me to a side resizes me to encourage decent text wrapping.", "img-right")^
Moving me to a side resizes me to encourage decent text wrapping.
Moving me to a side resizes me to encourage decent text wrapping.

Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping.

And if you want to deposit a window snapshot, use MediaWin. It applies special margins to compensate for the outrageously deep shadow. The img-shadow and img-well classes are ignored here:

^do(MediaWin, "bp_view_topnote_map.png", "Just move me to the left.", "img-left")^
Just move me to the left.
Just move me to the left.

Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping. Here is some sample text to demonstrate wrapping.

There is an export option related to basic links: NOIMAGE.

For the full listing of media macros, see here.