# Elementname: `Image`

## Description

Includes an external Graphic. Allowed graphic formats are PDF (.pdf), PNG (.png) and JPEG (.jpg).

Allowed attributes: clip, width, file, dpiwarn, href, height, maxwidth, maxheight, maxsize, minwidth, minheight, naturalsize, page

Child elements: (none)

Parent elements: B, Case, Color, Fontface, ForAll, Frame, I, Loop, Otherwise, Paragraph, PlaceObject, Td, Transformation, U, URL, Until, While

### Attributes

clip (optional)

  When yes, the image keeps its apsect ratio if both width and hight is given. To be able to fit the image into the given dimensions, the image gets clipped.

  yes: | Keep the aspect ratio and cut off left/right or top/bottom edges.
  no: | Distort the image to make it fit in the given area.

dpiwarn (number, optional)

  Warn if the image gets lower resultion than given.

file (text, optional)

  Filename of the image. Can be a file in the search path or a file-URI for absolute paths (e.g. `file:///path/to/image.pdf`).

height (number or length, optional)

  Image height. One of 'auto' (default, take image width), length (such as '3cm') or number (in grid cells).

href (text, optional)

  An URL (http://....) of the image. Will be downloaded and cached in `TEMPDIR/sp/images` (which can be configured by setting the configuration file key `imagecache`) . Alternative to ›file‹.

maxheight (number or length, optional)

  The maximum height of the image. Only used when clip="no". Value is a number (grid cells) or a length.

maxsize (text, optional)

  The PDF box that represents the maximum width. Default is “cropbox”.

maxwidth (number or length, optional)

  The maximum width of the image. Only used when clip="no". Value is a number (grid cells), a length or the value »100%« for full width image.

minheight (number or length, optional)

  The minimum height of the image. Only used when clip="no". Value is a number (grid cells) or a length.

minwidth (number or length, optional)

  The nimimum width of the image. Only used when clip="no". Value is a number (grid cells), a length or the value »100%« for full width image.

naturalsize (text, optional)

  The PDF box that represents the visible area. Default is “cropbox”.

page (number, optional)

  The page number from the PDF. Default is 1 (include the first page).

width (number or length, optional)

  Image width. One of 'auto' (default, take image width), '100%' (whole area width), length (such as '3cm') or number (in grid cells).

### Remarks

The values of the attributes naturalsize and maxsize can be ‘artbox’, ‘bleedbox’, ‘cropbox’, ‘mediabox’ and ‘trimbox’. These two values are used to enlarge the image for the bleed. In the second example below the designated view port of the image is defined in the artbox, but the image has a larger area (the cropbox) that is used for bleeding.

## Example

    <Record element="productdata">
      <PlaceObject column="{ $column }">
        <Image width="10" file="{ string(.) }"/>
      </PlaceObject>
    </Record>

Takes the file name of the image from the contents of the current element in the data file (here: productdata). Sample data XML:

    <productdata>image.pdf</productdata>

## Info

The number of pages in a PDF file can be determined with the XPath function `sd:number-of-pages().`

## See also

PlaceObject

# Commands

- A
- Action
- AddToList
- AtPageCreation
- AtPageShipout
- Attribute
- B
- Barcode
- Bold
- BoldItalic
- Bookmark
- Box
- Br
- Case
- Color
- Column
- Columns
- Contents
- Copy-of
- DefineColor
- DefineFontfamily
- DefineTextformat
- Element
- EmptyLine
- Fontface
- ForAll
- Frame
- Grid
- Group
- HSpace
- Hyphenation
- I
- Image
- Include
- InsertPages
- Italic
- Layout
- Li
- LoadDataset
- LoadFontfile
- Loop
- Makeindex
- Margin
- Mark
- Message
- NewPage
- NextFrame
- NextRow
- Ol
- Options
- Otherwise
- Output
- Pageformat
- Pagetype
- Paragraph
- PlaceObject
- PositioningArea
- PositioningFrame
- ProcessNode
- Record
- Regular
- Rule
- SaveDataset
- SavePages
- Sequence
- SetGrid
- SetVariable
- SortSequence
- Stylesheet
- Sub
- Sup
- Switch
- Table
- Tablefoot
- Tablehead
- Tablerule
- Td
- Text
- Textblock
- Tr
- Transformation
- U
- URL
- Ul
- Until
- VSpace
- Value
- While

Version: 2.2.0 | Start page | Command reference | Other language: German