| 1 |
lars |
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">
|
|
|
6 |
div.note {
|
|
|
7 |
margin: 0.5em 0;
|
|
|
8 |
}
|
|
|
9 |
|
|
|
10 |
div.class {
|
|
|
11 |
margin: 0.5em 0 0.5em 2em;
|
|
|
12 |
}
|
|
|
13 |
|
|
|
14 |
div.interface {
|
|
|
15 |
margin: 1em 0 0.5em 0;
|
|
|
16 |
padding: 2px 5px;
|
|
|
17 |
background-color: #f0f0f0;
|
|
|
18 |
}
|
|
|
19 |
|
|
|
20 |
span.interface_name {
|
|
|
21 |
font-weight: bold;
|
|
|
22 |
}
|
|
|
23 |
|
|
|
24 |
span.method_name {
|
|
|
25 |
font-weight: bold;
|
|
|
26 |
}
|
|
|
27 |
</style>
|
|
|
28 |
</head>
|
|
|
29 |
<body>
|
|
|
30 |
|
|
|
31 |
<h1>Events</h1>
|
|
|
32 |
<p>
|
|
|
33 |
Sometimes you'd want to add your own code to the rendering routines; for example, you could want to make your own watermarks,
|
|
|
34 |
count pages in the multiple-document batch, add digital signature to the generated PDF file or
|
|
|
35 |
perform any other actions requiring low-level access to PDF file at the certain moments. Now you may do this using
|
|
|
36 |
HTML2PS events. Pipeline object will fire events at predefined moments while rendering PDF file; you may catch them and
|
|
|
37 |
do something useful.
|
|
|
38 |
</p>
|
|
|
39 |
|
|
|
40 |
<p>The code below illustrates installation of a simple callback to be called immediately after
|
|
|
41 |
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)</p>
|
|
|
42 |
<pre>
|
|
|
43 |
$dispatcher =& $pipeline->get_dispatcher();
|
|
|
44 |
$dispatcher->add_observer('after-page', 'my_watermark_callback_func');
|
|
|
45 |
</pre>
|
|
|
46 |
|
|
|
47 |
<p>
|
|
|
48 |
A 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>
|
|
|
116 |
A nice sample of events usage was contributed by <b>marco_snake</b> on tufat html2ps/pdf community forum. In this sample,
|
|
|
117 |
events are used to display specific HTML code only on pages with predefined numbers.
|
|
|
118 |
PHP and HTML code is available in <tt>samples/API/events/1</tt> directory in the distribution package.
|
|
|
119 |
</p>
|
|
|
120 |
|
|
|
121 |
</body>
|
|
|
122 |
</html>
|