From 4714c1ac3b68a8c2c45c6c2adccfcf7288cbb1f3 Mon Sep 17 00:00:00 2001
From: Damien Regad <dregad@mantisbt.org>
Date: Fri, 12 Apr 2019 22:59:40 +0200
Subject: [PATCH] Obsolete print_bracket_link_prepared()

This function was used in MantisBT 1.x to display links surrounded by
square brackets for menus. With MantisBT Modern UI, it has been replaced
with CSS styling, to display the links as buttons.

One use case was not properly migrated, when displaying links on View
Issues Page (processing the EVENT_MENU_ISSUE hook).

The problem cannot be fixed properly within MantisBT code, it requires
an update of the Plugin's hook (returning an array of `label => link`
pairs instead of cooked links).

Consequently, the function has been marked as obsolete so that a warning
is displayed, to inform plugin developers that they should update their
code.

Fixes #23694
---
 core/print_api.php                               |  7 +++++++
 .../en-US/Events_Reference_Output.xml            | 16 +++++++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/core/print_api.php b/core/print_api.php
index d7b41459d7..4340e0238c 100644
--- a/core/print_api.php
+++ b/core/print_api.php
@@ -1450,8 +1450,15 @@ function print_form_button( $p_action_page, $p_label, array $p_args_to_post = nu
  * print brackets around a pre-prepared link (i.e. '<a href' html tag).
  * @param string $p_link The URL to link to.
  * @return void
+ * @deprecated 2.21.0
  */
 function print_bracket_link_prepared( $p_link ) {
+	error_parameters(
+		__FUNCTION__,
+		'print button functions or, in the context of an EVENT_MENU_ITEM hook, return link as associative array'
+	);
+	trigger_error( ERROR_DEPRECATED_SUPERSEDED, DEPRECATED );
+
 	echo '<span class="bracket-link">[&#160;' . $p_link . '&#160;]</span> ';
 }
 
diff --git a/docbook/Developers_Guide/en-US/Events_Reference_Output.xml b/docbook/Developers_Guide/en-US/Events_Reference_Output.xml
index fa7305debe..6ae66ea9e5 100644
--- a/docbook/Developers_Guide/en-US/Events_Reference_Output.xml
+++ b/docbook/Developers_Guide/en-US/Events_Reference_Output.xml
@@ -221,7 +221,21 @@
 
 				<itemizedlist>
 					<title>Return Value</title>
-					<listitem><para>&lt;Array&gt;: List of HTML links for the documents menu.</para></listitem>
+					<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>