/
Events_Reference.xml
132 lines (109 loc) · 4.96 KB
/
Events_Reference.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
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter 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;
]>
<chapter id="dev.eventref">
<title>Events Reference</title>
<section id="dev.eventref.intro">
<title>Introduction</title>
<para>
In this chapter, an attempt will be made to list all events used (or planned for later use)
in the MantisBT event system. Each listed event will include details for the event type, when
the event is called, and the expected parameters and return values for event callbacks.
</para>
<para>
Here we show an example event definition. For each event, the event identifier will be listed
along with the event types (see <xref linkend="dev.events.types" />) in parentheses. Below that
should be a concise but thorough description of how the event is called and how to use it.
Following that should be a list of event parameters (if any), as well as the expected return
value (if any).
</para>
<blockquote id="dev.eventref.example">
<title>EVENT_EXAMPLE (Default)</title>
<blockquote>
<para>
This is an example event description.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><Type>: Description of parameter one</para></listitem>
<listitem><para><Type>: Description of parameter two</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Return Value</title>
<listitem><para><Type>: Description of return value</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
</section>
<section id="dev.eventref.system">
<title>System Events</title>
<para>
These events are initiated by the plugin system itself to allow certain functionality to
simplify plugin development.
</para>
<blockquote id="dev.eventref.system.plugininit">
<title>EVENT_PLUGIN_INIT (Execute)</title>
<blockquote>
<para>
This event is triggered by the MantisBT plugin system after all registered and enabled
plugins have been initialized (their <function>init()</function> functions have been called).
This event should <emphasis>always</emphasis> be the first event triggered for any
page load. No parameters are passed to hooked functions, and no return values are
expected.
</para>
<para>
This event is the first point in page execution where all registered plugins are
guaranteed to be enabled (assuming dependencies and such are met). At any point
before this event, any or all plugins may not yet be loaded. Note that the core
system has not yet completed the bootstrap process when this event is signalled.
</para>
<para>
Suggested uses for the event include:
<itemizedlist>
<listitem><para>Checking for plugins that aren't require for normal usage.</para></listitem>
<listitem><para>Interacting with other plugins outside the context of pages or events.</para></listitem>
</itemizedlist>
</para>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.system.coreready">
<title>EVENT_CORE_READY (Execute)</title>
<blockquote>
<para>
This event is triggered by the MantisBT bootstrap process after all core APIs have
been initialized, including the plugin system, but before control is relinquished
from the bootstrap process back to the originating page. No parameters are passed
to hooked functions, and no return values are expected.
</para>
<para>
This event is the first point in page execution where the entire system is considered
loaded and ready.
</para>
</blockquote>
</blockquote>
<blockquote id="dev.eventref.system.log">
<title>EVENT_LOG (Execute)</title>
<blockquote>
<para>
This event is triggered by MantisBT to log a message. The contents of the message
should be hyper linked based on the following rules: #123 means issue 123, ~123
means issue note 123, @P123 means project 123, @U123 means user 123. Logging plugins
can capture extra context information like timestamp, current logged in user, etc.
This event receives the logging string as a parameter.
</para>
<itemizedlist>
<title>Parameters</title>
<listitem><para><String>: the logging string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
</section>
<xi:include href="Events_Reference_Output.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Events_Reference_Filter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Events_Reference_Bug.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Events_Reference_Notify.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Events_Reference_Account.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Events_Reference_Manage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</chapter>