Events_Reference_Output.xml

<?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>&lt;String&gt;: bug ID string to be displayed</para></listitem>
					<listitem><para>&lt;Integer&gt;: bug ID number</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;String&gt;: 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>&lt;String&gt;: input string to be displayed</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;String&gt;: 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>&lt;String&gt;: input string for email subject</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;String&gt;: 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>&lt;String&gt;: input string to be displayed</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;String&gt;: modified input string</para></listitem>
					<listitem><para>&lt;Boolean&gt;: 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>&lt;String&gt;: input string to be displayed</para></listitem>
					<listitem><para>&lt;Boolean&gt;: multiline input string</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;String&gt;: 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>&lt;String&gt;: input string to be displayed</para></listitem>
					<listitem><para>&lt;Boolean&gt;: multiline input string</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;String&gt;: 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>&lt;Array&gt;: 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>&lt;Array&gt;: 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>&lt;Array&gt;: 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>&lt;Integer&gt;: bug ID</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem>
						<para>&lt;Array&gt;: 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( '&lt;a href="' . plugin_page( 'mypage' ) . '">' . plugin_lang_get( 'mypage_label' ) . '&lt;/a>' );
</programlisting>
							However, this usage is deprecated.
						</para>
					</listitem>
				</itemizedlist>
			</blockquote>
		</blockquote>

		<blockquote id="dev.eventref.output.menu.issue.relationship">
			<title>EVENT_MENU_ISSUE_RELATIONSHIP (Default)</title>
			<blockquote>
				<para>
					This event allows plugins to add new links to the menu
					under the <emphasis>Relationships</emphasis> section
					in the View Issue Details page.
				</para>

				<itemizedlist>
					<title>Parameters</title>
					<listitem><para>&lt;Integer&gt;: bug ID</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem>
						<para>&lt;Array&gt;: List of elements to add to the 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>
					</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>&lt;Array&gt;: 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' =&gt; 'My Link',
		'access_level' =&gt; DEVELOPER,
		'url' =&gt; 'my_link.php',
		'icon' =&gt; 'fa-random'
	),
	array(
		'title' =&gt; 'My Link2',
		'access_level' =&gt; DEVELOPER,
		'url' =&gt; 'my_link2.php',
		'icon' =&gt; '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>&lt;Array&gt;: 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' =&gt; 'My Link',
		'access_level' =&gt; DEVELOPER,
		'url' =&gt; 'my_link.php',
		'icon' =&gt; 'fa-random'
	),
	array(
		'title' =&gt; 'My Link2',
		'access_level' =&gt; DEVELOPER,
		'url' =&gt; 'my_link2.php',
		'icon' =&gt; 'fa-shield'
	)
);
</programlisting>
					</listitem>
				</itemizedlist>
			</blockquote>
		</blockquote>

		<blockquote id="dev.eventref.output.menu.mainfilter">
			<title>EVENT_MENU_MAIN_FILTER (Chained)</title>
			<blockquote>
				<para>
					This event gives plugins the opportunity to modify the complete main menu
					before it is output (for example re-order items, add items in the middle,
					remove built-in items, change icons of built-in items).
				</para>
				<para>
					A single parameter is passed as an array of associate arrays containing
					the items in the main sidebar menu. The format of this array is the same as
					EVENT_MENU_MAIN and EVENT_MENU_MAIN_FRONT, and will also contain any entries
					added as a result of these events.
				</para>
				<para>
					Plugins should do any modifications needed and return the array back.
					Returning an empty array will hide the main menu.
				</para>

				<itemizedlist>
					<title>Parameters</title>
					<listitem><para>&lt;Array&gt;: menu items</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem>
						<para>&lt;Array&gt;: modified menu items</para>
						<note>
							<para>
								When returning the updated menu, the plugin's hook
								function needs to wrap it in an array, i.e.
								<literal>return array( $p_menu_data );</literal> and not
								<literal>return $p_menu_data;</literal>.
								The reason for this is that the Event API relies on
								call_user_func_array() to execute callback functions.
							</para>
						</note>

					</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>&lt;Array&gt;: 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>&lt;Array&gt;: 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>&lt;Array&gt;: 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>&lt;head&gt;</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>&lt;String&gt;: 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>&lt;body&gt;</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>&lt;String&gt;: 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>&lt;String&gt;: 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>&lt;String&gt;: 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>&lt;String&gt;: 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>&lt;String&gt;: 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>&lt;/body&gt;</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>&lt;String&gt;: 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>&lt;Array&gt;: the attachment data as an array (see <filename>core/file_api.php</filename>)</para></listitem>
				</itemizedlist>

				<itemizedlist>
					<title>Return Value</title>
					<listitem><para>&lt;String&gt;: HTML code to output.</para></listitem>
				</itemizedlist>
			</blockquote>
		</blockquote>
	</section>
</section>