0byt3m1n1

Path: /data/applications/aps/mantis/1.2.7-0/standard/htdocs/docbook/developers/en/ [ Home ]
File: event-reference.sgml
<chapter id="dev.eventref">
	<title>Event Reference</title>

	<sect1 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 <link linkend="dev.events.types">event type</link> 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>&lt;Type&gt;: Description of parameter one</para></listitem>
					<listitem><para>&lt;Type&gt;: Description of parameter two</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;Type&gt;: Description of return value</para></listitem>
				</itemizedlist>
			</blockquote>
		</blockquote>

	</sect1>

	<sect1 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>

			</blockquote>
		</blockquote>

	</sect1>

	&eventref-output;
	&eventref-filter;
	&eventref-bug;
	&eventref-notify;
	&eventref-account;
	&eventref-manage;

</chapter>