mPDF Manual – HTML control tags

annotation

(mPDF ≥ 2.2)

annotation – Add an Annotation to the document

Description

<annotation $content [ $pos-x ] [ $pos-y ] [ $icon ] [ $author ] [ $subject ] [ $opacity ] [ $color ] [ $popup ] [ $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.

The attribute $file can be used to specify a file (any type) which is to be embedded inside the PDF document.

Annotations cannot be moved or deleted by the reader.

Parameters

$content

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

$content cannot contain any of the characters: <, >, &, ' or " and must use the appropriate HTML entities e.g. <annotation content="This is &lt; 40" />

It is recommended that you use htmlspecialchars('Content', ENT_QUOTES) for this.

$pos-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.

$pos-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: 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 is 1.

$color

Specify the colour of the Annotation marker background.

Values

Any valid CSS color recognised by mPDF:

  • "#RRGGBB"
  • "#RGB"
  • "rgb(255,255,255)"
  • named colours such as "white", "yellow", "blue" etc.

Default: "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 or 0  - the popup box is not shown.

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

Values

<nn nn> - A string of 2 numbers (separated by spaces) will set the X and Y position in mm e.g. '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.

<nn nn nn nn> - A string of 4 numbers (separated by spaces) will set the X and Y position and also the width and height in mm e.g. '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 PDF document.

Default: BLANK

Changelog

Version Description
2.2 The function was added.
2.4

Annotations cannot be moved or deleted.

(function SetUserRights() removed)

4.3 Attribute $popup was added
5.1 Attribute $file was added
7.0

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

Examples

Example #1

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

$html =
'This is a paragraph about violas<annotation content="Violas are like big violins" /> about
which I know very little.';

$mpdf->WriteHTML($html);
$mpdf->Output();

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;

$html =
'This is a paragraph about violas<annotation content="Violas are like big violins" /> about
which I know very little.';

$mpdf->Output();

See Also

  • annotMargin - Specify the x (horizontal) placement of Annotation markers
  • annotOpacity - Specifiy the default opacity used for Annotation markers
  • Annotation() - PHP equivalent to <annotation>

  • title2annots - Convert all HTML element $title attributes to Annotations
Fork me on GitHub