Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Documentation and code clean up for plugin events
After my question in issue #20183, here is some clean up for the events
documentation:

- Added doc for missing parameters:
  - EVENT_LOG
  - EVENT_DISPLAY_FORMATTED
  - EVENT_MENU_ISSUE
  - EVENT_VIEW_BUG_ATTACHMENT
  - EVENT_MANAGE_OVERVIEW_INFO
- Missing documentation for event EVENT_DISPLAY_EMAIL_BUILD_SUBJECT
- Code clean up on usage of events:
  - EVENT_UPDATE_BUG_FORM
  - EVENT_UPDATE_BUG_FORM_TOP
- Change comments to reflect actual types for function event_type_chain()
- Apply consistent formating to documentation

Backported from master 9fcdd06
  • Loading branch information
dregad committed Oct 25, 2015
2 parents a6bb2d1 + 0683d7d commit 35a89d8
Show file tree
Hide file tree
Showing 5 changed files with 91 additions and 33 deletions.
4 changes: 2 additions & 2 deletions bug_update_advanced_page.php
Expand Up @@ -140,7 +140,7 @@
}


event_signal( 'EVENT_UPDATE_BUG_FORM_TOP', array( $tpl_bug_id, true ) );
event_signal( 'EVENT_UPDATE_BUG_FORM_TOP', array( $tpl_bug_id ) );

if ( $tpl_show_id || $tpl_show_project || $tpl_show_category || $tpl_show_view_state || $tpl_show_date_submitted | $tpl_show_last_updated ) {
#
Expand Down Expand Up @@ -578,7 +578,7 @@
echo '</tr>';
}

event_signal( 'EVENT_UPDATE_BUG_FORM', array( $tpl_bug_id, true ) );
event_signal( 'EVENT_UPDATE_BUG_FORM', array( $tpl_bug_id ) );

# spacer
echo '<tr class="spacer"><td colspan="6"></td></tr>';
Expand Down
5 changes: 3 additions & 2 deletions core/event_api.php
Expand Up @@ -257,8 +257,9 @@ function event_type_output( $p_event, $p_callbacks, $p_params = null ) {
* final callback's return value will be returned to the event origin.
* @param string Event name
* @param array Array of callback function/plugin basename key/value pairs
* @param string Input string
* @return string Output string
* @param mixed Input data
* @param array $p_params Parameters.
* @return mixed Output data
* @access public
*/
function event_type_chain( $p_event, $p_callbacks, $p_input, $p_params ) {
Expand Down
6 changes: 6 additions & 0 deletions docbook/developers/en/event-reference-manage.sgml
Expand Up @@ -14,6 +14,12 @@
Any output here should be defining appropriate rows and columns for the
surrounding &lt;table&gt; elements.
</para>

<itemizedlist>
<title>Parameters</title>
<listitem><para>&lt;Boolean&gt;: whether user is administrator</para></listitem>
</itemizedlist>

</blockquote>
</blockquote>

Expand Down
105 changes: 76 additions & 29 deletions docbook/developers/en/event-reference-output.sgml
Expand Up @@ -22,13 +22,13 @@

<itemizedlist>
<title>Parameters</title>
<listitem><para>String: bug ID string to be displayed</para></listitem>
<listitem><para>Int: bug ID number</para></listitem>
<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>String: modified bug ID string</para></listitem>
<listitem><para>&lt;String&gt;: modified bug ID string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -46,12 +46,32 @@

<itemizedlist>
<title>Parameters</title>
<listitem><para>String: input string to be displayed</para></listitem>
<listitem><para>&lt;String&gt;: input string to be displayed</para></listitem>
</itemizedlist>

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: modified input string</para></listitem>
<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>
Expand All @@ -69,12 +89,13 @@

<itemizedlist>
<title>Parameters</title>
<listitem><para>String: input string to be displayed</para></listitem>
<listitem><para>&lt;String&gt;: input string to be displayed</para></listitem>
</itemizedlist>

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: modified input string</para></listitem>
<listitem><para>&lt;String&gt;: modified input string</para></listitem>
<listitem><para>&lt;Boolean&gt;: multiline input string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -91,13 +112,13 @@

<itemizedlist>
<title>Parameters</title>
<listitem><para>String: input string to be displayed</para></listitem>
<listitem><para>Boolean: multiline input string</para></listitem>
<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>String: modified input string</para></listitem>
<listitem><para>&lt;String&gt;: modified input string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -114,13 +135,13 @@

<itemizedlist>
<title>Parameters</title>
<listitem><para>String: input string to be displayed</para></listitem>
<listitem><para>Boolean: multiline input string</para></listitem>
<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>String: modified input string</para></listitem>
<listitem><para>&lt;String&gt;: modified input string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -145,7 +166,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the user account menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the user account menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -160,7 +181,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the documents menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the documents menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -175,7 +196,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the issue list menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the issue list menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -188,9 +209,14 @@
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>Array: List of HTML links for the documents menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the documents menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -208,7 +234,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the main menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the main menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -226,7 +252,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the main menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the main menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -243,7 +269,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the management menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the management menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -260,7 +286,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the manage configuration menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the manage configuration menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -275,7 +301,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>Array: List of HTML links for the summary menu.</para></listitem>
<listitem><para>&lt;Array&gt;: List of HTML links for the summary menu.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand Down Expand Up @@ -303,7 +329,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: HTML code to output.</para></listitem>
<listitem><para>&lt;String&gt;: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -319,7 +345,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: HTML code to output.</para></listitem>
<listitem><para>&lt;String&gt;: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -334,7 +360,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: HTML code to output.</para></listitem>
<listitem><para>&lt;String&gt;: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -349,7 +375,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: HTML code to output.</para></listitem>
<listitem><para>&lt;String&gt;: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -365,7 +391,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: HTML code to output.</para></listitem>
<listitem><para>&lt;String&gt;: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -381,7 +407,7 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: HTML code to output.</para></listitem>
<listitem><para>&lt;String&gt;: HTML code to output.</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>
Expand All @@ -397,7 +423,28 @@

<itemizedlist>
<title>Return Value</title>
<listitem><para>String: HTML code to output.</para></listitem>
<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 attachement 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>
Expand Down
4 changes: 4 additions & 0 deletions docbook/developers/en/event-reference.sgml
Expand Up @@ -108,6 +108,10 @@
This event receives the logging string as a parameter.
</para>

<itemizedlist>
<title>Parameters</title>
<listitem><para>&lt;String&gt;: the logging string</para></listitem>
</itemizedlist>
</blockquote>
</blockquote>

Expand Down

0 comments on commit 35a89d8

Please sign in to comment.