mPDF Manual – mPDF functions

Annotation()

(mPDF ≥ 2.2)

Annotation – Add an Annotation to the document

Description

void Annotation ( string $text [, float $x , float $y [, string $icon [, string $author [, string $subject [, float $opacity [, array $colarray [, mixed $popup [, string $file ]]]]]]])

Adds an Annotation to the document. An annotation is like a Tooltip on a webpage. The Annotation marker, like those of “Sticky Notes” in Adobe Reader. When the reader passes the cursor over, it will display a popup text box.

The exact position on the page can be specified using $x and $y, or left to position automatically. If $x and $y are not specified, the Annotation will be inserted at the current position of writing in the document. The $x position (horizontal) can be overridden by the variable annotMargin, which can be used to force the Annotation marker to display in the right margin.

Annotations cannot be moved or deleted by the reader

Parameters

$text

This parameter specifies the text to appear in the popup text box

$x

Sets the $x position of the (bottom left edge of the) Annotation marker, set in mm from the left of the page.

BLANK or omitted or 0 uses the current writing position on the page, unless overridden by $annotMargin.

$y

Sets the $y position of the (bottom left edge of the) Annotation marker, set in mm from the top of the page. When Annotation markers are used within the text (annotMargin= false, the marker is raised by the current lineheight to appear above the text.

BLANK or omitted or 0 uses the current writing position on the page.

$icon

Sets the appearance of the Annotation marker.

BLANK or omitted uses default value i.e. 'Note'

Values (case sensitive)

  • 'Note'
  • 'Comment'
  • 'Help'
  • 'Insert'
  • 'Key'
  • 'NewParagraph'
  • 'Paragraph'

DEFAULT: 'Note'

$author

This specifies the name of the Author which will appear at the top of the popup text box.

Default: BLANK

$subject

This specifies the text to appear in the Annotation properties.

Default: BLANK

$opacity

Sets the opacity of the Annotation marker. Values must be greater than 0 and ≤ 1.

BLANK or omitted or 0: sets the opacity to the value of annotOpacity (Default: 0.5), unless annotMargin forces the Annotations to appear in the margin, when the default value is 1

$colarray

An array containing RGB color specification, which determines the colour of the Annotation marker background

Default: array(255,255,0) i.e. Yellow

$popup

Specify whether to show the popup box for the annotation when the PDF document is opened, and optional specify its dimensions and/or position.

BLANK or omitted, 0 or "0"  - the popup box is not shown.

Any other value forces the popup box to appear when the document is opened.

An array of 2 numbers will set the X and Y position in mm e.g. $popup = array(30, 30) will show a popup box with the top left corner 30mm from the top of the page and 30mm from the left of the page.

An array of 4 numbers will set the X and Y position and also the width and height in mm e.g. $popup = array(30, 30, 80, 50) will show a popup box with the top left corner 30mm from the top of the page and 30mm from the left of the page, a width of 80mm and a height of 50mm.

Note that the PDF Reader (e.g. Adobe Reader) may reposition the popup box as it pleases.

$file

Path to the file to embed in the annotation

Default: NULL

Changelog

Version Description
2.2 The function was added.
2.4 Annotations cannot be moved or deleted
4.3 Parameter $popup was added
5.1 Attribute $file was added
7.0

Attribute $file is ignored unless allowAnnotationFiles config key is set to true

Examples

Example #1

<?php
$mpdf = new \Mpdf\Mpdf();

$mpdf->WriteHTML('Hello World');
$mpdf->Annotation("Text annotation example");
$mpdf->WriteHTML('Hello World');

$mpdf->Output('filename.pdf');

Example #2

<?php
$mpdf = new \Mpdf\Mpdf();

// The Annotation markers will appear 10mm in from the right margin of the page
$mpdf->annotMargin = 10;
// The Annotation markers need no transparency as they appear in the margins
$mpdf->annotOpacity = 1;

$mpdf->WriteHTML('Hello World');
$mpdf->Annotation(
    "Text annotation example\nCharacters test:\xd1\x87\xd0\xb5 \xd0\xbf\xd1\x83\xd1\x85\xd1\x8a\xd1\x82",
    145, 24, 'Comment', "Ian Back", "My Subject",
    0.7, array(127, 127, 255)
);
$mpdf->WriteHTML('Hello World');

$mpdf->Output('filename.pdf');

See Also

  • annotMargin - Specify the x (horizontal) placement of Annotation markers
  • annotOpacity - Specifiy the default opacity used for Annotation markers
  • <annotation> - Custom HTML tag - equivalent to Annotation()
  • title2annots - Convert all HTML element $title attributes to Annotations
Fork me on GitHub