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