1<html> 2<head> 3<title>Events</title> 4<link rel="stylesheet" type="text/css" medial="all" title="Default" href="css/help.css"/> 5<style type="text/css"> 6div.note { 7 margin: 0.5em 0; 8} 9 10div.class { 11 margin: 0.5em 0 0.5em 2em; 12} 13 14div.interface { 15 margin: 1em 0 0.5em 0; 16 padding: 2px 5px; 17 background-color: #f0f0f0; 18} 19 20span.interface_name { 21 font-weight: bold; 22} 23 24span.method_name { 25 font-weight: bold; 26} 27</style> 28</head> 29<body> 30 31<h1>Events</h1> 32<p> 33Sometimes you'd want to add your own code to the rendering routines; for example, you could want to make your own watermarks, 34count pages in the multiple-document batch, add digital signature to the generated PDF file or 35perform any other actions requiring low-level access to PDF file at the certain moments. Now you may do this using 36HTML2PS events. Pipeline object will fire events at predefined moments while rendering PDF file; you may catch them and 37do something useful. 38</p> 39 40<p>The code below illustrates installation of a simple callback to be called immediately after 41new page was rendered. (If you're using PHP 5, you can write this way more elegant, but we're keeping PHP 4 compatibility here)</p> 42<pre> 43$dispatcher =& $pipeline->get_dispatcher(); 44$dispatcher->add_observer('after-page', 'my_watermark_callback_func'); 45</pre> 46 47<p> 48A single parameter is passed to the callback function: an associative array containing information related to event. 49</p> 50 51<p>Following events are available:</p> 52<table> 53<thead> 54<tr> 55<th>Name</th> 56<th>Fired…</th> 57<th>Event information</th> 58</tr> 59</thead> 60<tbody> 61<tr> 62<td class="event-name">after-batch</td> 63<td>after all documents in current batch were rendered</td> 64<td>pipeline: reference to current pipeline object</td> 65</tr> 66<tr> 67<td class="event-name">after-batch-item</td> 68<td>after current batch item was processed, rendered and removed from the memory</td> 69<td>pipeline: reference to current pipeline object</td> 70</tr> 71<tr> 72<td class="event-name">after-document</td> 73<td>after all pages in a current document were rendered</td> 74<td>pipeline: reference to current pipeline object; document: reference to the body box object</td> 75</tr> 76<tr> 77<td class="event-name">after-page</td> 78<td>after all elements were rendered on current page, but before new page is added.</td> 79<td>pipeline: reference to current pipeline object; document: reference to the body box object; pageno: current page number (1-based)</td> 80</tr> 81<tr> 82<td class="event-name">after-parse</td> 83<td>Called immediately after XML parser but before any tree filters</td> 84<td>pipeline: reference to current pipeline object; document: reference to the body box object; media: reference the current output media object.</td> 85</tr> 86<tr> 87<td class="event-name">before-batch</td> 88<td>before new document batch starts rendering</td> 89<td>pipeline: reference to current pipeline object</td> 90</tr> 91<tr> 92<td class="event-name">before-batch-item</td> 93<td>just before current batch item is fetched</td> 94<td>pipeline: reference to current pipeline object</td> 95</tr> 96<tr> 97<td class="event-name">before-document</td> 98<td>before new document in a batch starts rendering</td> 99<td>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</td> 100</tr> 101<tr> 102<td class="event-name">before-page</td> 103<td>after new blank page is added to the PDF document but before any elements are rendered</td> 104<td>pipeline: reference to current pipeline object; document: reference to the body box object; pageno: current page number (1-based)</td> 105</tr> 106<tr> 107<td class="event-name">before-page-heights</td> 108<td>after content has been laid out, just before running the page breaking algorithm</td> 109<td>pipeline: reference to current pipeline object; document: reference to the body box object; media: reference the current output media object.</td> 110</tr> 111</tbody> 112</table> 113 114<h2>Event usage</h2> 115<p> 116A nice sample of events usage was contributed by <b>marco_snake</b> on tufat html2ps/pdf community forum. In this sample, 117events are used to display specific HTML code only on pages with predefined numbers. 118PHP and HTML code is available in <tt>samples/API/events/1</tt> directory in the distribution package. 119</p> 120 121</body> 122</html>