dokuwiki api images

This section describes the functions used to insert images.

_odtAddImage($src, $width = NULL, $height = NULL, $align = NULL, $title = NULL, $style = NULL, $returnonly = false)

The function adds the image with path $src to the document. $src is the local path to the image file. $width and $height can be used to specify in which size the image shall be displayed. If omitted the image will be displayed in full size. $align gives the alignment to use and can have the values 'left', 'center' and 'right'. $title specifies the title for the picture. $style can be used to give an alternative draw:style-name for the image but is usually omitted. If given the value in $align will have no effect. Parameter $returnonly is for internal use only in case the function is called by the DokuWiki core/parser and should simple be omitted by plugins.

---

_odtGetImageSize($src, $maxwidth=NULL, $maxheight=NULL)

The function returns the size of image $src as an array($width, $height). $src is the local path to the image file. $maxwidth and $maxheight specify the maximum size to be returned. If the image is actually smaller or equal to the given maximum size then the size returned is the original image size. Otherwise the size returned is scaled down to fit to the given maximum size with respect to the X/Y ratio. The size is returned as numbers not as strings. But it is important to know that the unit for the returned size is centimeters. That means if the returned size values shall be passed to _odtAddImage() you need to append 'cm' as a unit to them.

---

_addStringAsSVGImage($string, $width = NULL, $height = NULL, $align = NULL, $title = NULL, $style = NULL)

The function adds the content of $string as an SVG image to the document. $width and $height can be used to specify in which size the image shall be displayed. If omitted the image will be displayed in full size. $align gives the alignment to use and can have the values 'left', 'center' and 'right'. $title specifies the title for the picture. $style can be used to give an alternative draw:style-name for the image but is usually omitted. If given the value in $align will have no effect.

---

_odtAddImageUseProperties($src, array $properties, $returnonly = false)

The function adds an image with path $src to the document just like _odtAddImage() does but lets you pass the parameters in array $properties. The following parameters in $properties are supported ($properties [key]=value):

• width and height
• title
• background-color
• margin-left, margin-right, margin-top, margin-bottom

Code examples

Add an image in full size

The following code:

    $renderer->_odtAddImage ('/home/myuser/pictures/myimage.png');

adds the image /home/myuser/pictures/myimage.png to the document in full size.

Add an image in 5x5 cm size

The following code:

    $renderer->_odtAddImage ('/home/myuser/pictures/myimage.png', '5cm', '5cm');

adds the image /home/myuser/pictures/myimage.png to the document in with a size of 5x5 cm. This might look ugly as it does not respect the X/Y ratio.

Add an image in 300x300 px size, respecting the X/Y ratio

The following code:

    $imagepath = '/home/myuser/pictures/myimage.png';
    list($width, $height) = $renderer->_odtGetImageSize ($imagepath, '300px', '300px');

    // The values returned are always in centimeters.
    // So we have to append 'cm' to it.
    $renderer->_odtAddImage ($imagepath, $width.'cm', $height.'cm'); 

adds the image /home/myuser/pictures/myimage.png to the document with a maximum size of 300x300 px, respecting the X/Y ratio. The image will be scaled down if required but will not be scaled up. If the image is smaller then the original size will be used.

Add an string as an SVG image

The following code:

    $SVGcode =
'<svg width="400" height="400">
  <rect width="400" height="400" style="fill:rgb(0,0,255);stroke-width:3;stroke:rgb(0,0,0)"/>
  Example-Image
</svg>';
    $renderer->_addStringAsSVGImage($SVGcode);

will add an SVG coded blue rectangle to the document. In that way you can dynamically calculate drawings using SVG and add them to your ODT document.

Add an string as an SVG image, scaled to maximum page width

The following code:

    $SVGcode =
'<svg width="400" height="400">
  <rect width="400" height="400" style="fill:rgb(0,0,255);stroke-width:3;stroke:rgb(0,0,0)"/>
  Example-Image
</svg>';

    $widthInCm = $renderer->_getAbsWidthMindMargins();
    $heightInCm = $widthInCm * ($iHeightSvg/$iWidthSvg);
    $renderer->_addStringAsSVGImage($SVGcode, $widthInCm.'cm', $heightInCm.'cm');

will add the same SVG coded blue rectangle to the document but scaled up to the maximal page width.