25. image-viewport
Prev | Chapter 5. Content objects | Next

## 25. image-viewport

image-viewport(`key`, `value`, ..., `key`, `value`)

Inserts an image in generated content.

The image is displayed, possibly after being scaled, in a viewport (that is, a rectangle possibly larger than the displayed image).

This content object, functionally close to the XSL-FO `fo:external-graphic` element, is a sophisticated variant of image().

Unless a source parameter is specified (see table below), the image-viewport is associated to an attribute or to an element (that is, the image-viewport is a ``view'' of the attribute or of the element). This attribute or this element may reference the URL of an external graphics file or may directly contain image data. In such case, the image-viewport object can also be used to edit this attribute or this element. To do this, the XXE user needs to double-click on the image-viewport and then specify a graphics file using a specialized dialog box. Alternatively the XXE user can also drag and drop a graphics file on the image-viewport.

Key | Value | Default | Description
--- | --- | --- | ---
source | url() | None. Image data comes from the element for which this image-viewport is a view. | Specifies the URL of graphics file to be displayed by the image-viewport. Rarely used. Most image-viewports are associated to attributes or to elements.
descendant | String evaluated as an XPath expression returning a node-set | None. Image data comes from the element for which this image-viewport is a view. | Specifies a descendant element of the element for which this image-viewport is a view. Example: DocBook 5's `imagedata/svg:svg` or `imagedata/mml:math`. Rarely used. Most image-viewports are associated to attributes or to elements.
attribute | Qualified name of attribute to be edited | None. Image data comes from the element for which this image-viewport is a view. | Specifies the name of the attribute containing the URL of graphics file to be displayed by the image-viewport (data-type=anyURI) or directly containing image data (data-type=hexBinary or base64Binary).
data-type | anyURI | hexBinary | base64Binary | XML | None. If the document is conforming to a W3C XML Schema or to a RELAX NG schema, this data-type can be found automatically. Otherwise (DTD, no grammar), specifying this parameter is mandatory. | Specifies how the image is ``stored'' in the attribute or in the element. data-type=XML is only allowed for elements (typically an `svg:svg` element).
gzip | Boolean: yes|no, 1|0, "true"|"false", "on"|"off" | no | Ignored unless data-type=hexBinary or base64Binary. If true, image data will be compressed with gzip before being encoded in hexBinary or in base64Binary.
viewport-width | Length (px, mm, em, etc) or percentage | None. | Specifies the width of the viewport. A percentage (ex. 50%) is a percentage of the available space.
viewport-height | Length (px, mm, em, etc) or percentage | None. | Specifies the height of the viewport. A percentage is a percentage of the available space. This is currently not supported.
content-width | Length (px, mm, em, etc) or percentage or scale-to-fit or a max. size | None. | Specifies the width of the image after rescaling it. A percentage is a percentage of the intrinsic width. scale-to-fit means change the width of the image to fit the viewport. A max. size is specified like this: `200max`. This means: at most 200 pixels. Therefore if the image is wider than 200 pixels, its width is scaled down to 200. Otherwise, the intrinsic width is used as is.
content-height | Length (px, mm, em, etc) or percentage or scale-to-fit or a max. size | None. | Specifies the height of the image after rescaling it. A percentage is a percentage of the intrinsic height. scale-to-fit means change the height of the image to fit the viewport. A max. size is specified like this: `400max`. This means: at most 400 pixels. Therefore if the image is taller than 400 pixels, its height is scaled down to 400. Otherwise, the intrinsic height is used as is.
preserve-aspect-ratio | Boolean: yes|no, 1|0, "true"|"false", "on"|"off" | yes | Ignored unless content-width and content-height are both set to scale-to-fit or are both set to a max. size. If false, the image is scaled non-uniformly (stretched) to fit the viewport.
smooth | Boolean: yes|no, 1|0, "true"|"false", "on"|"off" | no | If true, quality is favored over speed when rescaling the image.
horizontal-align | left | center | right | center | Specifies how the image is to be horizontally aligned in the viewport.
vertical-align | top | middle | bottom | middle | Specifies how the image is to be vertically aligned in the viewport.
fallback-image | url(), disc, circle, square, icon() | Automatically generated. May contain an error message displayed in red. | Specifies which image to display when the normal image cannot be displayed (image format not supported, file not found, corrupted image, etc)

`Key`, `value`, ..., `key`, `value` may also specify style parameters.

Simple example (XHTML):

    img {
      display: inline;
      content: image-viewport(attribute, src,
                              data-type, anyURI,
                              content-width, attr(width),
                              content-height, attr(height));
    }

Other example (DocBook 5, images displayed as 128x128 thumbnails):

    @namespace svg "http://www.w3.org/2000/svg";

    imagedata:contains-element(svg|svg) {
      content: image-viewport(descendant, "./svg:svg",
                              data-type, XML,
                              content-width, 128max,
                              content-height, 128max);
    }

Complex example (ImageDemo, see ``XXE_install_dir`/doc/configure/samples/imagedemo`):

    image_ab {
      /*
       * No need to specify data-type. The image-viewport will find it by itself.
       */

      content: image-viewport(attribute, data, gzip, true,
        viewport-width, attr(width),
        viewport-height, attr(height),
        preserve-aspect-ratio, attr(preserve_aspect_ratio),

        content-width,
        xpath("if(@content_width='scale_to_fit',\
                  'scale-to-fit',\
                  @content_width)"),

        content-height,
        xpath("if(@content_height='scale_to_fit',\
                  'scale-to-fit',\
                  @content_height)"),

        horizontal-align
        xpath("if(@anchor='west' or @anchor='north_west' or @anchor='south_west',\
                  'left',\
                  @anchor='center' or @anchor='north' or @anchor='south',\
                  'center',\
                  @anchor='east' or @anchor='north_east' or @anchor='south_east',\
                  'right',\
                  'center')"),

        vertical-align,
        xpath("if(@anchor='north' or @anchor='north_east' or @anchor='north_west',\
                  'top',\
                  @anchor='center' or @anchor='east' or @anchor='west',\
                  'middle',\
                  @anchor='south' or @anchor='south_east' or @anchor='south_west',\
                  'bottom',\
                  'middle')")
        );
    }

Prev | Up | Next
24. image | Home | 26. label