Adding Images, Pictures, and Figures

HTML offers a few different ways to incorporate images into your content:

• <img> elements are the most common and easiest to use, and are supported in all versions of HTML. An <img> can reference a single image file (typically .jpg, .png, or .svg), or it can use the srcset attribute added in HTML 5 to offer the same bitmapped image at a variety of display resolutions. (This can be useful when building content to adapt to Apple Retina displays and other high-resolution screens.)
• <picture>, added in HTML 5, offers another, very flexible way to specify alternative images for various situations. It’s generally intended for “art direction” (selecing from among intrinsically different images for a variety of use cases, such as mobile vs. desktop and portrait vs. landscape) rather than simply offering the same image in various resolutions. Correct <picture> usage can get fairly complex, but <picture> is also a powerful tool.
• <figure>, added in HTML 5, provides a way to wrap an <img> with an associated caption (<figcaption>).

TypeMetal supports working with all of these. See below for how to create them, and Editing Image Attributes for how to edit their properties and specify additional representations.

Inserting an <img>

To add an image (<img> element) to an HTML document:

• Drag and drop an image file (such as a .jpg, .png, or .svg) into the document, or
• Insert an <img> element into the document, using the usual completion mechanism for inserting elements. TypeMetal will prompt you to choose the image file you want it to reference.

Either way, this results in a new <img> element in your document, that references the given image file using the src attribute. TypeMetal tries to infer a reasonable presentation size for the image — the size at which the image should be displayed, as specified by width and height attributes — based on the width of the enclosing element and whether the image’s filename contains a resolution suffix such as “@2x” or “-2x”, but you can overrule this initial size and make other changes to the <img> element using the attribute editor.

See Editing Image Attributes for how to:

• Choose the desired presentation size for the image (the size at which it is displayed).
• Check whether the image’s resolution is adequate for presentation at various display scale factors (1x, 2x, etc.).
• Add additional representations for other scale factors or presentation widths, if desired.
• Create downsampled copies of a high-resolution representation, for use at lower display scale factors.

Inserting a <picture>

<img> elements are the appropriate choice for most cases, but when you really want a <picture> element, you can insert one using the usual completion mechanism for inserting elements. TypeMetal will prompt you to choose the image file you want it to reference, and will then create a simple <picture> element, that wraps an <img> child element, that in turn references the chosen image file as its src.

An example result:

<picture>
    <img src="lake-sunset.jpg" />
</picture>

This gives you the minimal beginning of a <picture> element, as specified in the HTML 5 standard. The <img> serves as the <picture>’s fallback representation in older browsers that don’t understand <picture> elements, and in cases where none of the <picture>’s other representations applies.

From here, you’ll likely want to edit the properties of the <img> element, and add one or more <source> children to the <picture> to specify additional representations and when to use them. See Editing Pictures for how to do this.

Note that <picture> elements were added in HTML 5, and aren’t usable in XHTML or HTML 4 content.

Inserting a <figure>

The <figure> element, which provides for an image, diagram, illustration, or other such content to be annotated with a caption. The picture content of a <figure> is often provided by an <img>, though it isn’t required to be.

Typical usage looks like this:

<figure>
    <img src="lake-sunset.jpg" alt="a picture of the lake, taken from our cabin" />
    <figcaption>Sunset at The Lake</figcaption>
</figure>

TypeMetal provides a little extra assistance to make <figure> elements easier to create.

You can wrap a <figure> around an existing <img> element (or other valid <figure> content), by selecting the <img> and then requesting a <figure> using the usual “Insert or Wrap In…” or completion mechanism. TypeMetal automatically adds a <figcaption> to the <figure> element, whose placeholder caption text you can edit.

When you ask it to insert a <figure> element at an insertion point (instead of wrapping around a selection), TypeMetal drops a sheet prompting you to choose an image file for the <figure> to contain. If you choose an image file and click the “Open” button, TypeMetal inserts an <img> wrapped in a <figure> that has a placeholder caption, similar to the usage example above. (The caption text might not be visible until after you dismiss the attribute editor that TypeMetal automatically opens for the <img>.) To edit the caption, just double-click to select it, and type the caption text you want.

In rarer cases where you want a <figure> whose content isn’t an <img>, you can click “Cancel” in the image file selection sheet (or press Esc). TypeMetal then inserts a <figure> that contains only a <figcaption>. You’ll probably find Block Mode useful, to help you position the insertion point within the <figure> and before the <figcaption>, so you can insert whatever element will provide the figure’s illustration content.

Note that <figure> elements were added in HTML 5, and aren’t usable in XHTML or HTML 4 content.