# Elementname: `Image`

## Description

Includes an external Graphic. Allowed graphic formats are PDF (.pdf), PNG (.png) and JPEG (.jpg). See below for a limitation on the number of included PDF files.

Allowed attributes: bleed, class, clip, dpiwarn, fallback, file, height, href, id, maxheight, maxwidth, minheight, minwidth, padding, padding-bottom, padding-left, padding-right, padding-top, page, rotate, visiblebox, width

Child elements: (none)

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

### Attributes

bleed (optional, since version 2.9.5)

  Should the image size increase by the amount of bleed setting (Options)?

  auto: | If the image touches a paper edge, extend the image in that direction.
  no: | Do not extend the image.

class (text, optional, since version 2.5.11)

  CSS class for this element.

clip (optional)

  When yes, the image keeps its aspect 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 resolution than given.

fallback (optional, since version 2.3.77)

  The filename of the replacement image if the file is not found. If none given, a red 'file not found' image will gets displayed.

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://` or `file:`) of the image. If external, it will be downloaded and cached in `TEMPDIR/sp/images` (which can be configured by setting the configuration file key `imagecache`). Alternative to ›file‹. When `file:` is used as a protocol, it can be a relative path. If no protocol is given, `file:` is assumed.

id (text, optional, since version 2.5.11)

  CSS id for this element.

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.

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 minimum 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.

padding (length, optional, since version 2.9.5)

  Set padding for all four sides.

padding-bottom (length, optional, CSS property: padding-bottom, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the bottom edge.

padding-left (length, optional, CSS property: padding-left, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the left edge.

padding-right (length, optional, CSS property: padding-right, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the right edge.

padding-top (length, optional, CSS property: padding-top, since version 2.5.11)

  Set the inner distance (width between contents and the border) to the top edge.

page (number, optional)

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

rotate (number, optional)

  Rotate the image in steps of 90°. The amount of movement is defined by the specified angle; if positive, the movement will be clockwise, if negative, it will be counter-clockwise.

visiblebox (optional)

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

  artbox: | Use the artbox as the visible area. The artbox is usually not contained in a PDF.
  bleedbox: | Use the bleedbox of the included PDF.
  cropbox: | Use the cropbox of the included PDF (default).
  mediabox: | Use the mediabox of the included PDF. This is the largest box.
  trimbox: | Use the trimbox of the includes PDF. The trimbox is the final paper size. For example, the trim box of an A4 PDF is 210mm x 297mm.

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().`

Attention. The number of PDF files that can be included in a document is limited. This limit can be increased in is system dependant. On Mac OS X it can be queried with `ulimit -a` and set for example with `ulimit -n 1024`.

## See also

PlaceObject

# Commands

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

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