Events

Sometimes you'd want to add your own code to the rendering routines; for example, you could want to make your own watermarks, count pages in the multiple-document batch, add digital signature to the generated PDF file or perform any other actions requiring low-level access to PDF file at the certain moments. Now you may do this using HTML2PS events. Pipeline object will fire events at predefined moments while rendering PDF file; you may catch them and do something useful.

The code below illustrates installation of a simple callback to be called immediately after new page was rendered. (If you're using PHP 5, you can write this way more elegant, but we're keeping PHP 4 compatibility here)

$dispatcher =& $pipeline->get_dispatcher();
$dispatcher->add_observer('after-page', 'my_watermark_callback_func');

A single parameter is passed to the callback function: an associative array containing information related to event.

Following events are available:

Name Fired… Event information
after-batch after all documents in current batch were rendered pipeline: reference to current pipeline object
after-batch-item after current batch item was processed, rendered and removed from the memory pipeline: reference to current pipeline object
after-document after all pages in a current document were rendered pipeline: reference to current pipeline object; document: reference to the body box object
after-page after all elements were rendered on current page, but before new page is added. pipeline: reference to current pipeline object; document: reference to the body box object; pageno: current page number (1-based)
after-parse Called immediately after XML parser but before any tree filters pipeline: reference to current pipeline object; document: reference to the body box object; media: reference the current output media object.
before-batch before new document batch starts rendering pipeline: reference to current pipeline object
before-batch-item just before current batch item is fetched pipeline: reference to current pipeline object
before-document before new document in a batch starts rendering pipeline: reference to current pipeline object; document: reference to the body box object; page-heights: array of page heights (measured in points) for this document
before-page after new blank page is added to the PDF document but before any elements are rendered pipeline: reference to current pipeline object; document: reference to the body box object; pageno: current page number (1-based)
before-page-heights after content has been laid out, just before running the page breaking algorithm pipeline: reference to current pipeline object; document: reference to the body box object; media: reference the current output media object.

Event usage

A nice sample of events usage was contributed by marco_snake on tufat html2ps/pdf community forum. In this sample, events are used to display specific HTML code only on pages with predefined numbers. PHP and HTML code is available in samples/API/events/1 directory in the distribution package.