/
Events_Reference_Output.xml
507 lines (440 loc) · 16.8 KB
/
Events_Reference_Output.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Developers_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="dev.eventref.output">
<title>Output Modifier Events</title>
<section id="dev.eventref.output.display">
<title>String Display</title>
<para>
These events make it possible to dynamically modify output strings to interpret or add
semantic meaning or markup. Examples include the creation of links to other bugs or
bugnotes, as well as handling urls to other sites in general.
</para>
<blockquote id="dev.eventref.output.display.bugid">
<title>EVENT_DISPLAY_BUG_ID (Chained)</title>
<blockquote>
<para>
This is an event to format bug ID numbers before being displayed, using the
<function>bug_format_id()</function> API call. The result should be plain-text,
as the resulting string is used in various formats and locations.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><String>: bug ID string to be displayed</para></listitem>
<listitem><para><Integer>: bug ID number</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: modified bug ID string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.display.email">
<title>EVENT_DISPLAY_EMAIL (Chained)</title>
<blockquote>
<para>
This is an event to format text before being sent in an email. Callbacks should
be used to process text and convert it into a plaintext-readable format so that
users with textual email clients can best utilize the information. Hyperlinks
and other markup should be removed, leaving the core content by itself.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><String>: input string to be displayed</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: modified input string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.display.email.subject">
<title>EVENT_DISPLAY_EMAIL_BUILD_SUBJECT (Chained)</title>
<blockquote>
<para>
This is an event to format the subject line of an email before it is sent.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><String>: input string for email subject</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: modified subject string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.display.formatted">
<title>EVENT_DISPLAY_FORMATTED (Chained)</title>
<blockquote>
<para>
This is an event to display generic formatted text. The string to be displayed is
passed between hooked callbacks, each taking a turn to modify the output in some
specific manner. Text passed to this may be processed for all types of formatting
and markup, including clickable links, presentation adjustments, etc.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><String>: input string to be displayed</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: modified input string</para></listitem>
<listitem><para><Boolean>: multiline input string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.display.rss">
<title>EVENT_DISPLAY_RSS (Chained)</title>
<blockquote>
<para>
This is an event to format content before being displayed in an RSS feed. Text
should be processed to perform any necessary character escaping to preserve
hyperlinks and other appropriate markup.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><String>: input string to be displayed</para></listitem>
<listitem><para><Boolean>: multiline input string</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: modified input string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.display.text">
<title>EVENT_DISPLAY_TEXT (Chained)</title>
<blockquote>
<para>
This is an event to display generic unformatted text. The string to be displayed is
passed between hooked callbacks, each taking a turn to modify the output in some
specific manner. Text passed to this event should only be processed for the most
basic formatting, such as preserving line breaks and special characters.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><String>: input string to be displayed</para></listitem>
<listitem><para><Boolean>: multiline input string</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: modified input string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
</section>
<section id="dev.eventref.output.menu">
<title>Menu Items</title>
<para>
These events allow new menu items to be inserted in order for new content to be added,
such as new pages or integration with other applications.
</para>
<blockquote id="dev.eventref.output.menu.account">
<title>EVENT_MENU_ACCOUNT (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new links to the user account
menu available to users from the 'My Account' link on the main menu.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><Array>: List of HTML links for the user account menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.docs">
<title>EVENT_MENU_DOCS (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new links to the documents
menu available to users from the 'Docs' link on the main menu.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><Array>: List of HTML links for the documents menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.filter">
<title>EVENT_MENU_FILTER (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new links to the issue list
menu available to users from the 'View Issues' link on the main menu.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><Array>: List of HTML links for the issue list menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.issue">
<title>EVENT_MENU_ISSUE (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new links to the issue
menu available to users when viewing issues.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><Integer>: bug ID</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem>
<para><Array>: List of HTML links for the issue page menu.</para>
<para>This is an associative array, with the link's label as key
and the link target as value, e.g. <programlisting>
array( plugin_lang_get( 'mypage_label' ) => plugin_page( 'mypage' );
</programlisting>
</para>
<para>For compatibility with MantisBT versions before 2.21.0,
it is also possible to return an array of cooked links :
<programlisting>
array( '<a href="' . plugin_page( 'mypage' ) . '">' . plugin_lang_get( 'mypage_label' ) . '</a>' );
</programlisting>
However, this usage is deprecated.
</para>
</listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.main">
<title>EVENT_MENU_MAIN (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new menu options to the main menu.
New links will be added AFTER the standard menu options.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem>
<para><Array>: Hooked events may return an array of menu options.
Each array entry will contain an associate array with keys 'title', 'url',
'access_level', and 'icon' (e.g. fa-pencil from <ulink url="http://fontawesome.io/icons/">Font Awesome</ulink>).
</para>
<programlisting>
return array(
array(
'title' => 'My Link',
'access_level' => DEVELOPER,
'url' => 'my_link.php',
'icon' => 'fa-random'
),
array(
'title' => 'My Link2',
'access_level' => DEVELOPER,
'url' => 'my_link2.php',
'icon' => 'fa-shield'
)
);
</programlisting>
</listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.mainfront">
<title>EVENT_MENU_MAIN_FRONT (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new menu options to main menu.
New links will be added BEFORE the standard menu options.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem>
<para><Array>: Hooked events may return an array of menu options.
Each array entry will contain an associate array with keys 'title', 'url',
'access_level', and 'icon' (e.g. fa-pencil from <ulink url="http://fontawesome.io/icons/">Font Awesome</ulink>).
</para>
<programlisting>
return array(
array(
'title' => 'My Link',
'access_level' => DEVELOPER,
'url' => 'my_link.php',
'icon' => 'fa-random'
),
array(
'title' => 'My Link2',
'access_level' => DEVELOPER,
'url' => 'my_link2.php',
'icon' => 'fa-shield'
)
);
</programlisting>
</listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.manage">
<title>EVENT_MENU_MANAGE (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new links to the management
menu available to site administrators from the 'Manage' link on the main menu.
Plugins should try to minimize use of these links to functions dealing with
core MantisBT management.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><Array>: List of HTML links for the management menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.manageconfig">
<title>EVENT_MENU_MANAGE_CONFIG (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new links to the configuration
management menu available to site administrators from the 'Manage Configuration'
link on the standard management menu. Plugins should try to minimize use of
these links to functions dealing with core MantisBT configuration.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><Array>: List of HTML links for the manage configuration menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.menu.summary">
<title>EVENT_MENU_SUMMARY (Default)</title>
<blockquote>
<para>
This event gives plugins the opportunity to add new links to the summary menu
available to users from the 'Summary' link on the main menu.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><Array>: List of HTML links for the summary menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
</section>
<section id="dev.eventref.output.layout">
<title>Page Layout</title>
<para>
These events offer the chance to create output at points relevant to the overall page
layout of MantisBT. Page headers, footers, stylesheets, and more can be created.
Events listed below are in order of runtime execution.
</para>
<blockquote id="dev.eventref.output.layout.resources">
<title>EVENT_LAYOUT_RESOURCES (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code from inside the
<literal><head></literal> tag, for use with CSS, Javascript, RSS,
or any other similar resources. Note that this event is signaled
after all other CSS and Javascript resources are linked by MantisBT.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.layout.bodybegin">
<title>EVENT_LAYOUT_BODY_BEGIN (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code immediately after the
<literal><body></literal> tag is opened, so that MantisBT may be
integrated within another website's template, or other similar use.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.layout.pageheader">
<title>EVENT_LAYOUT_PAGE_HEADER (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code immediately after the
MantisBT header content, such as the logo image.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.layout.contentbegin">
<title>EVENT_LAYOUT_CONTENT_BEGIN (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code after the top main
menu, but before any page-specific content begins.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.layout.contentend">
<title>EVENT_LAYOUT_CONTENT_END (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code after any page-
specific content has completed, but before the bottom menu bar
(or footer).
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.layout.pagefooter">
<title>EVENT_LAYOUT_PAGE_FOOTER (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code after the MantisBT
version, copyright, and webmaster information, but before the
query information.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.layout.bodyend">
<title>EVENT_LAYOUT_BODY_END (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code immediately before
the <literal></body></literal> end tag, to so that MantisBT may be
integrated within another website's template, or other similar use.
</para>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.output.view_bug_attachment">
<title>EVENT_VIEW_BUG_ATTACHMENT (Output)</title>
<blockquote>
<para>
This event allows plugins to output HTML code immediately after the line of an attachment.
Receives the attachment data as a parameter, in the form of an attachment array from within
the array returned by the <function>file_get_visible_attachments()</function> function.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><Array>: the attachment data as an array (see <filename>core/file_api.php</filename>)</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><String>: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
</section>
</section>