Skip to content

Commit a0e4b9b

Browse files
dregaddregad
committedSep 13, 2012
Documentation: revised admin guide Custom Functions section
Includes a couple comments corrections in custom_function_api.php.
·
release-2.27.1release-1.3.0-beta.1
1 parent 2d81544 commit a0e4b9b

File tree

2 files changed

+214
-85
lines changed

2 files changed

+214
-85
lines changed
 

‎core/custom_function_api.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ function custom_function_default_issue_update_notify( $p_issue_id ) {
177177
function custom_function_default_issue_create_validate( $p_new_issue_data ) {
178178
}
179179

180-
# Hook to notify after aa issue has been created.
180+
# Hook to notify after an issue has been created.
181181
# In case of errors, this function should call trigger_error()
182182
# p_issue_id is the issue number that can be used to get the existing state
183183
function custom_function_default_issue_create_notify( $p_issue_id ) {
@@ -394,7 +394,7 @@ function custom_function_default_enum_released_versions() {
394394
return $t_possible_values;
395395
}
396396

397-
# Construct an enumeration for released versions for the current project.
397+
# Construct an enumeration for future versions for the current project.
398398
# The enumeration will be empty if current project is ALL PROJECTS.
399399
# Enumerations format is: "abc|lmn|xyz"
400400
# To use this in a custom field type "=future_versions" in the possible values field.

‎docbook/Admin_Guide/en-US/Customizing.xml

+212-83
Original file line numberDiff line numberDiff line change
@@ -773,91 +773,220 @@ $g_status_enum_workflow[CLOSED] ='20:feedback,50:assigned';
773773
</para>
774774
</section>
775775

776-
<section id="admin.customize.customfuncs">
777-
<title>Custom Functions</title>
778-
779-
<para>Custom functions are used to extend the functionality of
780-
MantisBT by integrating user written functions into the issue
781-
processing at strategic places. This allows the system
782-
administrator to change the functionality without re-writing parts
783-
of the internals of the code.
784-
</para>
785-
<para>User versions of these functions are
786-
placed in a file called custom_functions_inc.php in the
787-
root directory of MantisBT. This is the same place that the
788-
"config_inc.php" file modifying MantisBT defaults is placed. In normal
789-
processing, MantisBT will look for override functions and execute
790-
them instead of the provided default functions.</para>
791-
<para>Custom functions have
792-
names like custom_function_override_descriptive_name where
793-
descriptive name described the particular function. The specific
794-
functions are described below. The simplest way to create a custom
795-
function is to copy the default function, named
796-
custom_function_default_descriptive_namefrom the
797-
core/custom_function_api.php file to your override file
798-
(custom_functions_inc.php), and rename it. The specific
799-
functionality you need can then be coded into the override
800-
function.
801-
</para>
776+
<section id="admin.customize.customfuncs">
777+
<title>Custom Functions</title>
778+
779+
<para>Custom functions are used to extend the functionality of
780+
MantisBT by integrating user-written functions into the issue
781+
processing at strategic places. This allows the system
782+
administrator to change the functionality without touching
783+
MantisBT's core.
784+
</para>
785+
<para>Default Custom Functions are defined in the API file
786+
<filename>core/custom_function_api.php</filename>
787+
, and are named
788+
<emphasis>custom_function_default_descriptive_name</emphasis>,
789+
where <emphasis>descriptive_name</emphasis> describes the
790+
particular function.
791+
See <xref linkend="admin.customize.customfuncs.defined" />
792+
for a description of the specific functions.
793+
</para>
794+
<para>User versions of these functions (overrides) are named like
795+
<emphasis>custom_function_override_descriptive_name</emphasis>,
796+
and placed in a file called
797+
<filename>custom_constants_inc.php</filename> that must be saved in
798+
MantisBT's root directory (This is the same place where the
799+
<filename>config_inc.php</filename> file resides).
800+
In normal processing, the system will look for override functions
801+
and execute them instead of the provided default functions.
802+
</para>
803+
<para>The simplest way to create a custom function is to copy the
804+
default one from the api to your override file
805+
(<filename>custom_constants_inc.php</filename>), and rename it
806+
(i.e. replacing 'default' by 'override').
807+
The specific functionality you need can then be coded into the
808+
override function.
809+
</para>
810+
811+
<section id="admin.customize.customfuncs.defined">
812+
<title>Default Custom Functions</title>
813+
814+
<para>Refer to <filename>core/custom_functions_api.php</filename>
815+
for further details.
816+
</para>
817+
818+
<informaltable>
819+
<tgroup cols="3">
820+
<thead>
821+
<row>
822+
<entry>Custom Function Name</entry>
823+
<entry>Description</entry>
824+
<entry>Return value</entry>
825+
</row>
826+
</thead>
827+
<tbody>
828+
<row>
829+
<entry>custom_function_default_auth_can_change_password()</entry>
830+
<entry>Determines whether MantisBT can update the password</entry>
831+
<entry>True if yes, False if not</entry>
832+
</row>
833+
<row>
834+
<entry>custom_function_default_changelog_include_issue( $p_issue_id )</entry>
835+
<entry>Determines whether the specified issue should be included in the Changelog or not.</entry>
836+
<entry>True to include, False to exclude</entry>
837+
</row>
838+
<row>
839+
<entry>custom_function_default_changelog_print_issue( $p_issue_id, $p_issue_level = 0 )</entry>
840+
<entry>Prints one entry in the Changelog</entry>
841+
<entry>None</entry>
842+
</row>
843+
<row>
844+
<entry>custom_function_default_enum_categories()</entry>
845+
<entry>Build a list of all categories for the current project</entry>
846+
<entry>Enumeration, delimited by "|"</entry>
847+
</row>
848+
<row>
849+
<entry>custom_function_default_enum_future_versions()</entry>
850+
<entry>Build a list of all future versions for the current project</entry>
851+
<entry>Enumeration, delimited by "|"</entry>
852+
</row>
853+
<row>
854+
<entry>custom_function_default_enum_released_versions()</entry>
855+
<entry>Build a list of all released versions for the current project</entry>
856+
<entry>Enumeration, delimited by "|"</entry>
857+
</row>
858+
<row>
859+
<entry>custom_function_default_enum_versions()</entry>
860+
<entry>Build a list of all versions for the current project</entry>
861+
<entry>Enumeration, delimited by "|"</entry>
862+
</row>
863+
<row>
864+
<entry>custom_function_default_format_issue_summary( $p_issue_id, $p_context = 0 )</entry>
865+
<entry>Format the bug summary</entry>
866+
<entry>Formatted string</entry>
867+
</row>
868+
<row>
869+
<entry>custom_function_default_get_columns_to_view( $p_columns_target = COLUMNS_TARGET_VIEW_PAGE, $p_user_id = null )</entry>
870+
<entry>Defines which columsn should be displayed</entry>
871+
<entry>Array of the column names</entry>
872+
</row>
873+
<row>
874+
<entry>custom_function_default_issue_create_notify( $p_issue_id )</entry>
875+
<entry>Notify after an issue has been created</entry>
876+
<entry>In case of invalid data, this function should call trigger_error()</entry>
877+
</row>
878+
<row>
879+
<entry>custom_function_default_issue_create_validate( $p_new_issue_data )</entry>
880+
<entry>Validate field settings before creating an issue</entry>
881+
<entry>In case of invalid data, this function should call trigger_error()</entry>
882+
</row>
883+
<row>
884+
<entry>custom_function_default_issue_delete_notify( $p_issue_data )</entry>
885+
<entry>Notify after an issue has been deleted</entry>
886+
<entry>In case of invalid data, this function should call trigger_error()</entry>
887+
</row>
888+
<row>
889+
<entry>custom_function_default_issue_delete_validate( $p_issue_id )</entry>
890+
<entry>Validate field settings before deleting an issue</entry>
891+
<entry>In case of invalid data, this function should call trigger_error()</entry>
892+
</row>
893+
<row>
894+
<entry>custom_function_default_issue_update_notify( $p_issue_id )</entry>
895+
<entry>Notify after an issue has been updated</entry>
896+
<entry>In case of invalid data, this function should call trigger_error()</entry>
897+
</row>
898+
<row>
899+
<entry>custom_function_default_issue_update_validate( $p_issue_id, $p_new_issue_data, $p_bugnote_text )</entry>
900+
<entry>Validate field issue data before updating</entry>
901+
<entry>In case of invalid data, this function should call trigger_error()</entry>
902+
</row>
903+
<row>
904+
<entry>custom_function_default_print_bug_view_page_custom_buttons( $p_bug_id )</entry>
905+
<entry>Prints the custom buttons on the current view page</entry>
906+
<entry>None</entry>
907+
</row>
908+
<row>
909+
<entry>custom_function_default_print_column_title( $p_column, $p_columns_target = COLUMNS_TARGET_VIEW_PAGE )</entry>
910+
<entry>Print a column's title based on its name</entry>
911+
<entry>None</entry>
912+
</row>
913+
<row>
914+
<entry>custom_function_default_print_column_value( $p_column, $p_bug, $p_columns_target = COLUMNS_TARGET_VIEW_PAGE )</entry>
915+
<entry>Print a column's value based on its name</entry>
916+
<entry>None</entry>
917+
</row>
918+
<row>
919+
<entry>custom_function_default_roadmap_include_issue( $p_issue_id )</entry>
920+
<entry>Determines whether the specified issue should be included in the Roadmap or not.</entry>
921+
<entry>True to include, False to exclude</entry>
922+
</row>
923+
<row>
924+
<entry>custom_function_default_roadmap_print_issue( $p_issue_id, $p_issue_level = 0 )</entry>
925+
<entry>Prints one entry in the Roadmap</entry>
926+
<entry>None</entry>
927+
</row>
928+
</tbody>
929+
</tgroup>
930+
</informaltable>
931+
932+
</section>
933+
934+
<section id="admin.customize.customfuncs.example">
935+
<title>Example Custom Function Override</title>
936+
937+
<para>The following function is used to validate an issue before
938+
it is resolved.
939+
</para>
940+
941+
<programlisting width="102"><![CDATA[<?php
942+
943+
/**
944+
* Hook to validate Validate field settings before resolving
945+
* verify that the resolution is not set to OPEN
946+
* verify that the fixed in version is set (if versions of the product exist)
947+
*/
948+
function custom_function_override_issue_update_validate( $p_issue_id, $p_bug_data, $p_bugnote_text ) {
949+
if( $p_bug_data->status == RESOLVED ) {
950+
if ( $p_bug_data->resolution == OPEN ) {
951+
error_parameters( 'the resolution cannot be open to resolve the issue' );
952+
trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR );
953+
}
954+
$t_version_count = count( version_get_all_rows( $p_bug_data-&gt;project_id ) );
955+
if( ( $t_version_count > 0 ) && ( $p_bug_data->fixed_in_version == '' ) ) {
956+
error_parameters( 'fixed in version must be set to resolve the issue' );
957+
trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR );
958+
}
959+
}
960+
}
802961
803-
<section id="admin.customize.customfuncs.defined">
804-
<title>Defined Functions</title>
805-
806-
<para>custom_function_default_changelog_include_issue( $p_issue_id
807-
) returns true or false if the issue if to be included in the
808-
Changelog. custom_function_default_changelog_print_issue( $p_issue_id
809-
) returns a formatted string to be included for the issue in the
810-
Changelog. custom_function_default_issue_update_validate( $p_issue_id,
811-
$p_new_bug, $p_bug_note_text ) validate issue field settings before
812-
an update occurs. It returns true or fails with an
813-
error. custom_function_default_issue_update_notify( $p_issue_id )
814-
notify after an issue has been
815-
updated. custom_function_default_issue_create_validate( $p_new_bug )
816-
validate issue field settings before an issue is created. It returns
817-
true or fails with an
818-
error. custom_function_default_issue_create_notify( $p_issue_id )
819-
notify after an issue has been
820-
opened. custom_function_default_issue_delete_validate( $p_issue_id )
821-
validate issue field settings before an issue can be deleted. It
822-
returns true or fails with an
823-
error. custom_function_default_issue_delete_notify( $p_issue_id )
824-
notify after an issue has been deleted
825-
</para>
826-
</section>
962+
?>]]>
963+
</programlisting>
827964

828-
<section id="admin.customize.customfuncs.example">
829-
<title>Example Custom Function</title>
965+
<para>The errors will also need to be defined, by modifying the
966+
following files
967+
</para>
830968

831-
<para>The following function is used to validate an issue before
832-
it is resolved.
833-
<programlisting width="102"><![CDATA[<?php
834-
# --------------------
835-
# Hook to validate Validate field settings before resolving
836-
# verify that the resolution is not set to OPEN
837-
# verify that the fixed in version is set (if versions of the product exist)
969+
<itemizedlist>
970+
<listitem>
971+
<para><filename>custom_constants_inc.php</filename>
972+
</para>
973+
974+
<programlisting>
975+
define( 'ERROR_VALIDATE_FAILURE', 2000 );
976+
</programlisting>
977+
</listitem>
978+
979+
<listitem>
980+
<para><filename>custom_strings_inc.php</filename>
981+
</para>
982+
983+
<programlisting>
984+
$MANTIS_ERROR['ERROR_VALIDATE_FAILURE'] = 'This change cannot be made because %s';
985+
</programlisting>
986+
</listitem>
987+
</itemizedlist>
988+
989+
</section>
990+
</section>
838991

839-
function custom_function_override_issue_update_validate( $p_issue_id, $p_bug_data, $p_bugnote_text ) {
840-
if ( $p_bug_data->status == RESOLVED ) {
841-
if ( $p_bug_data->resolution == OPEN ) {
842-
error_parameters( 'the resolution cannot be open to resolve the issue' );
843-
trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR );
844-
}
845-
$t_version_count = count( version_get_all_rows( $p_bug_data-&gt;project_id ) );
846-
if ( ( $t_version_count > 0 ) && ( $p_bug_data->fixed_in_version == '' ) ) {
847-
error_parameters( 'fixed in version must be set to resolve the issue' );
848-
trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR );
849-
}
850-
}
851-
}
852-
?>]]>
853-
</programlisting>
854-
The errors will also need to be defined by adding the following to <filename>custom_constants_inc.php</filename>
855-
<programlisting>
856-
define ( 'ERROR_VALIDATE_FAILURE', 2000 );
857-
To custom_strings_inc.php
858-
$MANTIS_ERROR['ERROR_VALIDATE_FAILURE'] = 'This change cannot be made because %s';
859-
</programlisting>
860-
</para>
861-
</section>
862-
</section>
863992
</chapter>

0 commit comments

Comments
 (0)
Please sign in to comment.