Merge remote-tracking branch 'vsephpbb/ticket/12060' into develop

* vsephpbb/ticket/12060: (37 commits)
  [ticket/12060] A little less verbose cleanup of event docblocks
  [ticket/12060] Further clarifying new event docblocks as much as possible
  [ticket/12060] More fixes to dockblock for acp_bbcodes_modify_create event
  [ticket/12060] Remove whitespaces
  [ticket/12060] Fix docblock for acp_bbcodes_modify_create event
  [ticket/12060] Rename event in message parser to modify_format_display_text_after
  [ticket/12060] Add num_predefined_bbcodes to display_custom_bbcodes_modify_sql
  [ticket/12060] Further clarify/fix a var in acp_bbcodes_modify_create event doc block
  [ticket/12060] Use separate template event for acp user signature posting buttons
  [ticket/12060] Rename event from append to after in acp_bbcodes.html
  [ticket/12060] Correctly label alpha versions in event docblocks
  [ticket/12060] Fix u_action comments in docblocks
  [ticket/12060] Change @since in event docblocks
  [ticket/12060] Update the docblock comments in acp core events
  [ticket/12060] Refactor u_action in the events that use it
  [ticket/12060] Use $sql_ary instead of $sql
  [ticket/12060] Update docblock for core event due to addition of another var
  [ticket/12060] Remove re-tabbing of html from subsilver2 files
  [ticket/12060] Add $update_this_message var to the core event
  [ticket/12060] Adjust last item in array to use a comma instead of closing parenthesis
  ...

phpBB/adm/style/acp_bbcodes.html

@@ -47,6 +47,8 @@
 	</dl>
 	</fieldset>
 
+	<!-- EVENT acp_bbcodes_edit_fieldsets_after -->
+
 	<fieldset class="submit-buttons">
 		<legend>{L_SUBMIT}</legend>
 		<input class="button1" type="submit" id="submit" name="submit" value="{L_SUBMIT}" />&nbsp;
@@ -101,7 +103,7 @@
 	<!-- BEGIN bbcodes -->
 		<!-- IF bbcodes.S_ROW_COUNT is even --><tr class="row1"><!-- ELSE --><tr class="row2"><!-- ENDIF -->
 			<td style="text-align: center;">{bbcodes.BBCODE_TAG}</td>
-			<td style="text-align: right; width: 40px;"><a href="{bbcodes.U_EDIT}">{ICON_EDIT}</a> <a href="{bbcodes.U_DELETE}" data-ajax="row_delete">{ICON_DELETE}</a></td>
+			<td class="actions"><!-- EVENT acp_bbcodes_actions_prepend --> <a href="{bbcodes.U_EDIT}">{ICON_EDIT}</a> <a href="{bbcodes.U_DELETE}" data-ajax="row_delete">{ICON_DELETE}</a> <!-- EVENT acp_bbcodes_actions_append --></td>
 		</tr>
 	<!-- BEGINELSE -->
 		<tr class="row3">

phpBB/adm/style/acp_users_signature.html

@@ -49,6 +49,7 @@
 		<legend>{L_SIGNATURE}</legend>
 		<p>{L_SIGNATURE_EXPLAIN}</p>
 
+		<!-- EVENT acp_users_signature_editor_buttons_before -->
 		<div id="format-buttons">
 			<input type="button" class="button2" accesskey="b" name="addbbcode0" value=" B " style="font-weight:bold; width: 30px" onclick="bbstyle(0)" title="{L_BBCODE_B_HELP}" />
 			<input type="button" class="button2" accesskey="i" name="addbbcode2" value=" i " style="font-style:italic; width: 30px" onclick="bbstyle(2)" title="{L_BBCODE_I_HELP}" />
@@ -84,6 +85,7 @@
 				<input type="button" class="button2" name="addbbcode{custom_tags.BBCODE_ID}" value="{custom_tags.BBCODE_TAG}" onclick="bbstyle({custom_tags.BBCODE_ID})" title="{custom_tags.BBCODE_HELPLINE}" />
 			<!-- END custom_tags -->
 		</div>
+		<!-- EVENT acp_users_signature_editor_buttons_after -->
 
 		<dl>
 			<dt style="width: 90px;" id="color_palette_placeholder" data-orientation="v" data-height="12" data-width="15" data-bbcode="true">

phpBB/docs/events.md

@@ -1,3 +1,21 @@
+acp_bbcodes_actions_append
+===
+* Location: adm/style/acp_bbcodes.html
+* Since: 3.1.0-a3
+* Purpose: Add actions to the BBCodes page, after edit/delete buttons
+
+acp_bbcodes_actions_prepend
+===
+* Location: adm/style/acp_bbcodes.html
+* Since: 3.1.0-a3
+* Purpose: Add actions to the BBCodes page, before edit/delete buttons
+
+acp_bbcodes_edit_fieldsets_after
+===
+* Location: adm/style/acp_bbcodes.html
+* Since: 3.1.0-a3
+* Purpose: Add settings to BBCode add/edit form
+
 acp_forums_normal_settings_append
 ===
 * Location: adm/style/acp_forums.html
@@ -46,6 +64,20 @@ acp_users_overview_options_append
 * Since: 3.1.0-a1
 * Purpose: Add options and settings on user overview page
 
+acp_users_signature_editor_buttons_after
+===
+* Locations:
+    + adm/style/acp_users_signature.html
+* Since: 3.1.0-a3
+* Purpose: Add content after BBCode posting buttons in the ACP user signature
+
+acp_users_signature_editor_buttons_before
+===
+* Locations:
+    + adm/style/acp_users_signature.html
+* Since: 3.1.0-a3
+* Purpose: Add content before BBCode posting buttons in the ACP user signature
+
 forumlist_body_last_post_title_prepend
 ====
 * Locations:
@@ -189,6 +221,22 @@ overall_header_navigation_prepend
 * Since: 3.1.0-a1
 * Purpose: Add links before the navigation links in the header
 
+posting_editor_buttons_after
+===
+* Locations:
+    + styles/prosilver/template/posting_buttons.html
+    + styles/subsilver2/template/posting_buttons.html
+* Since: 3.1.0-a3
+* Purpose: Add content after the BBCode posting buttons
+
+posting_editor_buttons_before
+===
+* Locations:
+    + styles/prosilver/template/posting_buttons.html
+    + styles/subsilver2/template/posting_buttons.html
+* Since: 3.1.0-a3
+* Purpose: Add content before the BBCode posting buttons
+
 posting_editor_message_after
 ===
 * Locations:

phpBB/includes/acp/acp_bbcodes.php

@@ -24,7 +24,7 @@ class acp_bbcodes
 
 	function main($id, $mode)
 	{
-		global $db, $user, $auth, $template, $cache, $request;
+		global $db, $user, $auth, $template, $cache, $request, $phpbb_dispatcher;
 		global $config, $phpbb_root_path, $phpbb_admin_path, $phpEx;
 
 		$user->add_lang('acp/posting');
@@ -96,7 +96,7 @@ class acp_bbcodes
 			case 'edit':
 			case 'add':
 
-				$template->assign_vars(array(
+				$tpl_ary = array(
 					'S_EDIT_BBCODE'		=> true,
 					'U_BACK'			=> $this->u_action,
 					'U_ACTION'			=> $this->u_action . '&action=' . (($action == 'add') ? 'create' : 'modify') . (($bbcode_id) ? "&bbcode=$bbcode_id" : ''),
@@ -105,10 +105,27 @@ class acp_bbcodes
 					'BBCODE_MATCH'			=> $bbcode_match,
 					'BBCODE_TPL'			=> $bbcode_tpl,
 					'BBCODE_HELPLINE'		=> $bbcode_helpline,
-					'DISPLAY_ON_POSTING'	=> $display_on_posting)
+					'DISPLAY_ON_POSTING'	=> $display_on_posting,
 				);
 
 				$bbcode_tokens = array('TEXT', 'SIMPLETEXT', 'INTTEXT', 'IDENTIFIER', 'NUMBER', 'EMAIL', 'URL', 'LOCAL_URL', 'RELATIVE_URL', 'COLOR');
+
+				/**
+				* Modify custom bbcode template data before we display the add/edit form
+				*
+				* @event core.acp_bbcodes_edit_add
+				* @var	string	action			Type of the action: add|edit
+				* @var	array	tpl_ary			Array with custom bbcode add/edit data
+				* @var	int		bbcode_id		When editing: the bbcode id,
+				*								when creating: 0
+				* @var	array	bbcode_tokens	Array of bbcode tokens
+				* @since 3.1.0-a3
+				*/
+				$vars = array('action', 'tpl_ary', 'bbcode_id', 'bbcode_tokens');
+				extract($phpbb_dispatcher->trigger_event('core.acp_bbcodes_edit_add', compact($vars)));
+
+				$template->assign_vars($tpl_ary);
+
 				foreach ($bbcode_tokens as $token)
 				{
 					$template->assign_block_vars('token', array(
@@ -124,6 +141,27 @@ class acp_bbcodes
 			case 'modify':
 			case 'create':
 
+				$sql_ary = $hidden_fields = array();
+				
+				/**
+				* Modify custom bbcode data before the modify/create action
+				*
+				* @event core.acp_bbcodes_modify_create
+				* @var	string	action				Type of the action: modify|create
+				* @var	array	sql_ary				Array with new bbcode data
+				* @var	int		bbcode_id			When editing: the bbcode id,
+				*									when creating: 0
+				* @var	bool	display_on_posting	Display bbcode on posting form
+				* @var	string	bbcode_match		The bbcode usage string to match
+				* @var	string	bbcode_tpl			The bbcode HTML replacement string
+				* @var	string	bbcode_helpline		The bbcode help line string
+				* @var	array	hidden_fields		Array of hidden fields for use when
+				*									submitting form when $warn_text is true
+				* @since 3.1.0-a3
+				*/
+				$vars = array('action', 'sql_ary', 'bbcode_id', 'display_on_posting', 'bbcode_match', 'bbcode_tpl', 'bbcode_helpline', 'hidden_fields');
+				extract($phpbb_dispatcher->trigger_event('core.acp_bbcodes_modify_create', compact($vars)));
+
 				$warn_text = preg_match('%<[^>]*\{text[\d]*\}[^>]*>%i', $bbcode_tpl);
 				if (!$warn_text || confirm_box(true))
 				{
@@ -178,7 +216,7 @@ class acp_bbcodes
 						trigger_error($user->lang['BBCODE_HELPLINE_TOO_LONG'] . adm_back_link($this->u_action), E_USER_WARNING);
 					}
 
-					$sql_ary = array(
+					$sql_ary = array_merge($sql_ary, array(
 						'bbcode_tag'				=> $data['bbcode_tag'],
 						'bbcode_match'				=> $bbcode_match,
 						'bbcode_tpl'				=> $bbcode_tpl,
@@ -188,7 +226,7 @@ class acp_bbcodes
 						'first_pass_replace'		=> $data['first_pass_replace'],
 						'second_pass_match'			=> $data['second_pass_match'],
 						'second_pass_replace'		=> $data['second_pass_replace']
-					);
+					));
 
 					if ($action == 'create')
 					{
@@ -244,14 +282,14 @@ class acp_bbcodes
 				}
 				else
 				{
-					confirm_box(false, $user->lang['BBCODE_DANGER'], build_hidden_fields(array(
+					confirm_box(false, $user->lang['BBCODE_DANGER'], build_hidden_fields(array_merge($hidden_fields, array(
 						'action'				=> $action,
 						'bbcode'				=> $bbcode_id,
 						'bbcode_match'			=> $bbcode_match,
 						'bbcode_tpl'			=> htmlspecialchars($bbcode_tpl),
 						'bbcode_helpline'		=> $bbcode_helpline,
 						'display_on_posting'	=> $display_on_posting,
-						))
+						)))
 					, 'confirm_bbcode.html');
 				}
 
@@ -300,22 +338,57 @@ class acp_bbcodes
 			break;
 		}
 
-		$template->assign_vars(array(
+		$u_action = $this->u_action;
-			'U_ACTION'		=> $this->u_action . '&amp;action=add')
+
+		$template_data = array(
+			'U_ACTION'		=> $this->u_action . '&amp;action=add',
 		);
 
-		$sql = 'SELECT *
+		$sql_ary = array(
-			FROM ' . BBCODES_TABLE . '
+			'SELECT'	=> 'b.*',
-			ORDER BY bbcode_tag';
+			'FROM'		=> array(BBCODES_TABLE => 'b'),
-		$result = $db->sql_query($sql);
+			'ORDER_BY'	=> 'b.bbcode_tag',
+		);
+
+		/**
+		*  Modify custom bbcode template data before we display the form
+		*
+		* @event core.acp_bbcodes_display_form
+		* @var	string	action			Type of the action: modify|create
+		* @var	string	sql_ary			The SQL array to get custom bbcode data
+		* @var	array	template_data	Array with form template data
+		* @var	string	u_action		The u_action link
+		* @since 3.1.0-a3
+		*/
+		$vars = array('action', 'sql_ary', 'template_data', 'u_action');
+		extract($phpbb_dispatcher->trigger_event('core.acp_bbcodes_display_form', compact($vars)));
+
+		$result = $db->sql_query($db->sql_build_query('SELECT', $sql_ary));
+
+		$template->assign_vars($template_data);
 
 		while ($row = $db->sql_fetchrow($result))
 		{
-			$template->assign_block_vars('bbcodes', array(
+			$bbcodes_array = array(
 				'BBCODE_TAG'		=> $row['bbcode_tag'],
-				'U_EDIT'			=> $this->u_action . '&amp;action=edit&amp;bbcode=' . $row['bbcode_id'],
+				'U_EDIT'			=> $u_action . '&amp;action=edit&amp;bbcode=' . $row['bbcode_id'],
-				'U_DELETE'			=> $this->u_action . '&amp;action=delete&amp;bbcode=' . $row['bbcode_id'])
+				'U_DELETE'			=> $u_action . '&amp;action=delete&amp;bbcode=' . $row['bbcode_id'],
 			);
+
+			/**
+			*  Modify display of custom bbcodes in the form
+			*
+			* @event core.acp_bbcodes_display_bbcodes
+			* @var	array	row				Array with current bbcode data
+			* @var	array	bbcodes_array	Array of bbcodes template data
+			* @var	string	u_action		The u_action link
+			* @since 3.1.0-a3
+			*/
+			$vars = array('bbcodes_array', 'row', 'u_action');
+			extract($phpbb_dispatcher->trigger_event('core.acp_bbcodes_display_bbcodes', compact($vars)));
+
+			$template->assign_block_vars('bbcodes', $bbcodes_array);
+
 		}
 		$db->sql_freeresult($result);
 	}

phpBB/includes/functions_display.php

@@ -919,7 +919,7 @@ function topic_status(&$topic_row, $replies, $unread_topic, &$folder_img, &$fold
 
 /**
 * Assign/Build custom bbcodes for display in screens supporting using of bbcodes
-* The custom bbcodes buttons will be placed within the template block 'custom_codes'
+* The custom bbcodes buttons will be placed within the template block 'custom_tags'
 */
 function display_custom_bbcodes()
 {
@@ -928,11 +928,26 @@ function display_custom_bbcodes()
 	// Start counting from 22 for the bbcode ids (every bbcode takes two ids - opening/closing)
 	$num_predefined_bbcodes = 22;
 
-	$sql = 'SELECT bbcode_id, bbcode_tag, bbcode_helpline
+	$sql_ary = array(
-		FROM ' . BBCODES_TABLE . '
+		'SELECT'	=> 'b.bbcode_id, b.bbcode_tag, b.bbcode_helpline',
-		WHERE display_on_posting = 1
+		'FROM'		=> array(BBCODES_TABLE => 'b'),
-		ORDER BY bbcode_tag';
+		'WHERE'		=> 'b.display_on_posting = 1',
-	$result = $db->sql_query($sql);
+		'ORDER_BY'	=> 'b.bbcode_tag',
+	);
+
+	/**
+	* Event to modify the SQL query before custom bbcode data is queried
+	*
+	* @event core.display_custom_bbcodes_modify_sql
+	* @var	array	sql_ary					The SQL array to get the bbcode data
+	* @var	int		num_predefined_bbcodes	The number of predefined core bbcodes
+	*										(multiplied by factor of 2)
+	* @since 3.1.0-a3
+	*/
+	$vars = array('sql_ary', 'num_predefined_bbcodes');
+	extract($phpbb_dispatcher->trigger_event('core.display_custom_bbcodes_modify_sql', compact($vars)));
+
+	$result = $db->sql_query($db->sql_build_query('SELECT', $sql_ary));
 
 	$i = 0;
 	while ($row = $db->sql_fetchrow($result))
@@ -952,7 +967,7 @@ function display_custom_bbcodes()
 		);
 
 		/**
-		* Modify the template data block of a bbcode
+		* Event to modify the template data block of a custom bbcode
 		*
 		* This event is triggered once per bbcode
 		*

phpBB/includes/message_parser.php

@@ -103,6 +103,8 @@ class bbcode_firstpass extends bbcode
 	*/
 	function bbcode_init($allow_custom_bbcode = true)
 	{
+		global $phpbb_dispatcher;
+		
 		static $rowset;
 
 		// This array holds all bbcode data. BBCodes will be processed in this
@@ -162,6 +164,21 @@ class bbcode_firstpass extends bbcode
 				'regexp'	=> array($row['first_pass_match'] => str_replace('$uid', $this->bbcode_uid, $row['first_pass_replace']))
 			);
 		}
+
+		$bbcodes = $this->bbcodes;
+
+		/**
+		* Event to modify the bbcode data for later parsing
+		*
+		* @event core.modify_bbcode_init
+		* @var array	bbcodes		Array of bbcode data for use in parsing
+		* @var array	rowset		Array of bbcode data from the database
+		* @since 3.1.0-a3
+		*/
+		$vars = array('bbcodes', 'rowset');
+		extract($phpbb_dispatcher->trigger_event('core.modify_bbcode_init', compact($vars)));
+
+		$this->bbcodes = $bbcodes;
 	}
 
 	/**
@@ -1198,6 +1215,8 @@ class parse_message extends bbcode_firstpass
 	*/
 	function format_display($allow_bbcode, $allow_magic_url, $allow_smilies, $update_this_message = true)
 	{
+		global $phpbb_dispatcher;
+
 		// If false, then the parsed message get returned but internal message not processed.
 		if (!$update_this_message)
 		{
@@ -1226,6 +1245,28 @@ class parse_message extends bbcode_firstpass
 		$this->message = bbcode_nl2br($this->message);
 		$this->message = smiley_text($this->message, !$allow_smilies);
 
+		$text = $this->message;
+		$uid = $this->bbcode_uid;
+
+		/**
+		* Event to modify the text after it is parsed
+		*
+		* @event core.modify_format_display_text_after
+		* @var string	text				The message text to parse
+		* @var string	uid					The bbcode uid
+		* @var bool		allow_bbcode		Do we allow bbcodes
+		* @var bool		allow_magic_url		Do we allow magic urls
+		* @var bool		allow_smilies		Do we allow smilies
+		* @var bool		update_this_message	Do we update the internal message
+		*									with the parsed result
+		* @since 3.1.0-a3
+		*/
+		$vars = array('text', 'uid', 'allow_bbcode', 'allow_magic_url', 'allow_smilies', 'update_this_message');
+		extract($phpbb_dispatcher->trigger_event('core.modify_format_display_text_after', compact($vars)));
+
+		$this->message = $text;
+		$this->bbcode_uid = $uid;
+
 		if (!$update_this_message)
 		{
 			unset($this->message);

phpBB/styles/prosilver/template/posting_buttons.html

@@ -59,6 +59,7 @@
 	</dl>
 </div>
 
+<!-- EVENT posting_editor_buttons_before -->
 <div id="format-buttons">
 	<input type="button" class="button2" accesskey="b" name="addbbcode0" value=" B " style="font-weight:bold; width: 30px" onclick="bbstyle(0)" title="{L_BBCODE_B_HELP}" />
 	<input type="button" class="button2" accesskey="i" name="addbbcode2" value=" i " style="font-style:italic; width: 30px" onclick="bbstyle(2)" title="{L_BBCODE_I_HELP}" />
@@ -95,4 +96,5 @@
 		<input type="button" class="button2" name="addbbcode{custom_tags.BBCODE_ID}" value="{custom_tags.BBCODE_TAG}" onclick="bbstyle({custom_tags.BBCODE_ID})" title="{custom_tags.BBCODE_HELPLINE}" />
 	<!-- END custom_tags -->
 </div>
+<!-- EVENT posting_editor_buttons_after -->
 <!-- ENDIF -->

phpBB/styles/subsilver2/template/posting_buttons.html

@@ -36,6 +36,8 @@
 		<!-- INCLUDEJS {T_ASSETS_PATH}/javascript/editor.js -->
 
 <!-- IF S_BBCODE_ALLOWED -->
+	<!-- EVENT posting_editor_buttons_before -->
+	<div id="core-bbcode-buttons">
 		<input type="button" class="btnbbcode" accesskey="b" name="addbbcode0" value=" B " style="font-weight:bold; width: 30px;" onclick="bbstyle(0)" onmouseover="helpline('b')" onmouseout="helpline('tip')" />
 		<input type="button" class="btnbbcode" accesskey="i" name="addbbcode2" value=" i " style="font-style:italic; width: 30px;" onclick="bbstyle(2)" onmouseover="helpline('i')" onmouseout="helpline('tip')" />
 		<input type="button" class="btnbbcode" accesskey="u" name="addbbcode4" value=" u " style="text-decoration: underline; width: 30px;" onclick="bbstyle(4)" onmouseover="helpline('u')" onmouseout="helpline('tip')" />
@@ -66,15 +68,19 @@
 				<!-- ENDIF -->
 			<!-- ENDIF -->
 		</select></span>
+	</div>
+	<!-- EVENT posting_editor_buttons_after -->
 <!-- ENDIF -->
 	</td>
 </tr>
 <!-- IF S_BBCODE_ALLOWED and .custom_tags -->
 	<tr valign="middle" align="{S_CONTENT_FLOW_BEGIN}">
 		<td colspan="2">
+		<div id="custom-bbcode-buttons">
 		<!-- BEGIN custom_tags -->
 			<input type="button" class="btnbbcode" name="addbbcode{custom_tags.BBCODE_ID}" value="{custom_tags.BBCODE_TAG}" onclick="bbstyle({custom_tags.BBCODE_ID})"<!-- IF custom_tags.BBCODE_HELPLINE !== '' --> onmouseover="helpline('cb_{custom_tags.BBCODE_ID}')" onmouseout="helpline('tip')"<!-- ENDIF --> />
 		<!-- END custom_tags -->
+		</div>
 		</td>
 	</tr>
 <!-- ENDIF -->