28. image-viewport

28. image-viewport
	Chapter 5. Content objects

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:

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')")
    );
}


27. image		29. label