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