diff --git a/docbook/Admin_Guide/en-US/Customizing.xml b/docbook/Admin_Guide/en-US/Customizing.xml index 8b55ead9cd..6dfa5d2fcb 100644 --- a/docbook/Admin_Guide/en-US/Customizing.xml +++ b/docbook/Admin_Guide/en-US/Customizing.xml @@ -1,5 +1,5 @@ - Customizing MantisBT + Customizing MantisBT
Strings / Translations @@ -54,75 +54,76 @@ $s_CODE = STRING;
-
- Custom Fields +
+ Custom Fields
- Overview - - Different teams typically like to capture different information - as users report issues, in some cases, the data required is even - different from one project to another. Hence, MantisBT provides the - ability for managers and administrators to define custom fields as way - to extend MantisBT to deal with information that is specific to their - teams or their projects. The aim is for this to keep MantisBT native - fields to a minimum. - - Following are some facts about the implementation of - custom fields in MantisBT: - - - Custom fields are defined system wide. - - - Custom fields can be linked to multiple - projects. - - - - The sequence of displaying custom fields can be different - per project. - - - - Custom fields must be defined by users with access level - ADMINISTRATOR. - - - - Custom fields can be linked to projects by users with - access level MANAGER or above (by default, this can be - configurable). - - - - Number of custom fields is not restricted. - - - Users can define filters that include custom fields. - - - Custom fields can be included in View Issues, Print - Issues, and CSV exports. - - - Enumeration custom fields can have a set of static - values or values that are calculated dynamically based on - a custom function. - - - -
+ Overview + + Different teams typically like to capture different information + as users report issues, in some cases, the data required is even + different from one project to another. Hence, MantisBT provides the + ability for managers and administrators to define custom fields as way + to extend MantisBT to deal with information that is specific to their + teams or their projects. The aim is for this to keep MantisBT native + fields to a minimum. + + Following are some facts about the implementation of + custom fields in MantisBT: + + + + + Custom fields are defined system wide. + + + Custom fields can be linked to multiple + projects. + + + + The sequence of displaying custom fields can be different + per project. + + + + Custom fields must be defined by users with access level + ADMINISTRATOR. + + + + Custom fields can be linked to projects by users with + access level MANAGER or above (by default, this can be + configurable). + + + + Number of custom fields is not restricted. + + + Users can define filters that include custom fields. + + + Custom fields can be included in View Issues, Print + Issues, and CSV exports. + + + Enumeration custom fields can have a set of static + values or values that are calculated dynamically based on + a custom function. + + +
- Custom Field Definition + Custom Field Definition - - The definition of a custom field includes the following logical - attributes: + + The definition of a custom field includes the following logical + attributes: - - + + Caption variable name. This value is supplied to the lang_get() API; it is therefore mandatory to set this to a @@ -136,204 +137,206 @@ $s_CODE = STRING; custom_strings_inc.php, then it will be displayed as-is. - - - Custom field type (string, numeric, float, - enumeration, email, checkbox, radio, list, multi-selection list, date). - - Type 'string' is used for strings of up to 255 characters. - Type 'numeric' is used for numerical integer values. - Type 'float' is used for real (float / double) numbers. - Type 'enumeration' is used when a user selects one entry from a list. The user interface for such type is a combo-box. - Type 'email' is used for storing email addresses. - Type 'checkbox' is like enumeration but the list is shown as checkboxes and the user is allowed to tick more than one selection. The default value and the possible value can contain multiple values like 'RED|YELLOW|BLUE' (without the single quote). + + + Custom field type (string, numeric, float, + enumeration, email, checkbox, radio, list, multi-selection list, date). + + Type 'string' is used for strings of up to 255 characters. + Type 'numeric' is used for numerical integer values. + Type 'float' is used for real (float / double) numbers. + Type 'enumeration' is used when a user selects one entry from a list. The user interface for such type is a combo-box. + Type 'email' is used for storing email addresses. + Type 'checkbox' is like enumeration but the list is shown as checkboxes and the user is allowed to tick more than one selection. The default value and the possible value can contain multiple values like 'RED|YELLOW|BLUE' (without the single quote). Type 'radio' is like enumeration but the list is shown as radio buttons and the user is allowed to tick on of the options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values. - Type 'list' is like enumeration but the list is shown as a list box where the user is only allowed to select one option. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values. - Type 'multi-selection list' is like enumeration but the list is shown as a list box where the user is allowed to select multiple options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'RED|BLUE'. Note that in this case the default value contains multiple values. - Type 'date' is for date values. The default value can be empty, or {tomorrow}, {yesterday}, {next week}, {last week}, {+3 days}, {-2 days}. - - - Enumeration possible values (eg: RED|YELLOW|BLUE). - Use the pipe ('|') character to separate possible values for an - enumeration. One of the possible values can be an - empty string. The set of possible values can also be - calculated at runtime. For example, "=versions" would - automatically resolve into all the versions defined - for the current project. - - - - Default value - see details above for a sample default value for each type. - - - Minimum/maximum length for the custom field value (use 0 - to disable). Note that these metrics are not really relevant to custom fields that are based on an enumeration of possible values. - - - - Regular expression to use for validating user input (use PCRE syntax). - - - - Read Access level: Minimum access level for users to be - able to see the value of the custom field. - - - - Write Access level: Minimum access level for users to be - able to edit the value of the custom field. - - - - Display when reporting issues? - If this custom - field should be shown on the Report Issue page. - - - - Display when updating issues? - If this custom - field should be shown on the Update Issue page. - - - - Display when resolving issues? - If this custom - field should be shown when resolving an issue. For - example, a "root cause" custom field would make sense to - set when resolving the issue. - - - - Display when closing issues? - If this custom - field should be shown when closing an issue. - - - - Required on Report - If this custom - field is a mandatory field on the Report Issue page. - - - - Required on Update - If this custom - field is a mandatory field on the Update Issue page. - - - - Required on Resolve - If this custom - field is a mandatory field when resolving an issue. - - - - Required on Close - If this custom - field is a mandatory field when closing an issue. - - - - - - - If the value of a custom field for a certain defect is not found, - the default value is assumed. - -
- -
- Adding/Editing Custom Fields - - - - - The logged in user needs $g_manage_custom_fields_threshold - access level. - - - - Select "Manage" from the main menu. - - - Select "Manage Custom Fields" from the management - menu. - - - - In case of edit, click on the name of an existing - custom field to edit its information. - - - - In case of adding a new one, enter the name of the - new custom field then click "New Custom Field". - - - - - - Added custom fields will not show up in any of the issues - until the added custom field is linked to the appropriate - projects. + Type 'list' is like enumeration but the list is shown as a list box where the user is only allowed to select one option. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values. + Type 'multi-selection list' is like enumeration but the list is shown as a list box where the user is allowed to select multiple options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'RED|BLUE'. Note that in this case the default value contains multiple values. + Type 'date' is for date values. The default value can be empty, or {tomorrow}, {yesterday}, {next week}, {last week}, {+3 days}, {-2 days}. + + + Enumeration possible values (eg: RED|YELLOW|BLUE). + Use the pipe ('|') character to separate possible values for an + enumeration. One of the possible values can be an + empty string. The set of possible values can also be + calculated at runtime. For example, "=versions" would + automatically resolve into all the versions defined + for the current project. + + + + Default value - see details above for a sample default value for each type. + + + Minimum/maximum length for the custom field value (use 0 + to disable). Note that these metrics are not really relevant + to custom fields that are based on an enumeration of possible values. + + + + Regular expression to use for validating user input (use + PCRE syntax). + + + + Read Access level: Minimum access level for users to be + able to see the value of the custom field. + + + + Write Access level: Minimum access level for users to be + able to edit the value of the custom field. + + + + Display when reporting issues? - If this custom + field should be shown on the Report Issue page. + + + + Display when updating issues? - If this custom + field should be shown on the Update Issue page. + + + + Display when resolving issues? - If this custom + field should be shown when resolving an issue. For + example, a "root cause" custom field would make sense to + set when resolving the issue. + + + + Display when closing issues? - If this custom + field should be shown when closing an issue. + + + + Required on Report - If this custom + field is a mandatory field on the Report Issue page. + + + + Required on Update - If this custom + field is a mandatory field on the Update Issue page. + + + + Required on Resolve - If this custom + field is a mandatory field when resolving an issue. + + + + Required on Close - If this custom + field is a mandatory field when closing an issue. + + + + + + + If the value of a custom field for a certain defect is not found, + the default value is assumed. + +
+ +
+ Adding/Editing Custom Fields + + + + + The logged in user needs $g_manage_custom_fields_threshold + access level. + + + + Select "Manage" from the main menu. + + + Select "Manage Custom Fields" from the management + menu. + + + + In case of edit, click on the name of an existing + custom field to edit its information. + + + + In case of adding a new one, enter the name of the + new custom field then click "New Custom Field". + + + + + + Added custom fields will not show up in any of the issues + until the added custom field is linked to the appropriate + projects.
Linking/Unlinking/Ordering Existing Custom Fields in Projects - - - - The logged in user needs to have access level that is - greater than or equal to $g_custom_field_link_threshold and - $g_manage_project_threshold. - - - - Select "Manage" from the main menu. - - - Select "Manage Projects". - - - - Select the name of the project to manage. - - - Scroll down to the "Custom Fields" box. - - - Select the field to add from the list, then click "Add - This Existing Custom Field". - - - - To change the order of the custom fields, edit the - "Sequence" value and click update. Custom fields with smaller - values are displayed first. - - - - To unlink a custom field, click on "Remove" link next to - the field. - Unlinking a custom field will not delete the values that are - associated with the issues for this field. These values are only - deleted if the custom field definition is removed (not unlinked!) - from the database. This is useful if you decide to re-link the - custom field. These values may also re-appear if issues are moved to - another project which has this field linked. - - - - - - - Moving Issues - - When an issue is moved from one project to another, custom - fields that are not defined for the new project are not deleted. - These fields will re-appear with their correct values if the issue is - moved back to the original project, or if these custom fields are - linked to the new project. - - + + + + The logged in user needs to have access level that is + greater than or equal to $g_custom_field_link_threshold and + $g_manage_project_threshold. + + + + Select "Manage" from the main menu. + + + Select "Manage Projects". + + + + Select the name of the project to manage. + + + Scroll down to the "Custom Fields" box. + + + Select the field to add from the list, then click "Add + This Existing Custom Field". + + + + To change the order of the custom fields, edit the + "Sequence" value and click update. Custom fields with smaller + values are displayed first. + + + + To unlink a custom field, click on "Remove" link next to + the field. + Unlinking a custom field will not delete the values that are + associated with the issues for this field. These values are only + deleted if the custom field definition is removed (not unlinked!) + from the database. This is useful if you decide to re-link the + custom field. These values may also re-appear if issues are moved to + another project which has this field linked. + + + + + + + Moving Issues + + When an issue is moved from one project to another, custom + fields that are not defined for the new project are not deleted. + These fields will re-appear with their correct values if the issue is + moved back to the original project, or if these custom fields are + linked to the new project. + +
-
- Localizing Custom Field Names +
+ Localizing Custom Field Names It is possible to localize the custom fields' labels. This can be done as follows: @@ -395,11 +398,11 @@ switch( $g_active_language ) {
-
- Dynamic default values +
+ Dynamic default values -
- Dynamic defaults for Date fields +
+ Dynamic defaults for Date fields Custom fields of type date can be defaulted to either specific or relative dates. @@ -420,66 +423,84 @@ switch( $g_active_language ) { strtotime() function. -
-
+
+
- Dynamic values for Enumeration Custom Fields - - As discussed earlier, one of the possible types of a custom - field is "enumeration". This type of custom field allows the user - to select one value from a provided list of possible values. The - standard way of defining such custom fields is to provide a '|' - separated list of possible values. However, this approach has two - limitations: the list is static, and the maximum length of the list - must be no longer than 255 characters. Hence, the need for the - ability to construct the list of possible values dynamically. - - -
- Dynamic possible values included by default - - MantisBT ships with some dynamic possible values, these - include the following: - - - =categories - a list of categories defined - in the current project (or the project to which the issue - belongs). - =versions - a list of all versions defined - in the current project (or the project to which the issue - belongs). - =future_versions - a list of all versions that - belong to the current project with - released flag set to false. - =released_versions - a list of all versions - that belong to the current project with released flag set to - true. - - + Dynamic values for Enumeration Custom Fields + + As discussed earlier, one of the possible types of a custom + field is "enumeration". This type of custom field allows the user + to select one value from a provided list of possible values. The + standard way of defining such custom fields is to provide a '|' + separated list of possible values. However, this approach has two + limitations: the list is static, and the maximum length of the list + must be no longer than 255 characters. Hence, the need for the + ability to construct the list of possible values dynamically. + + - The '=' before the name of the dynamic list of options is used - to tell MantisBT that this is a dynamic list, rather than a static - list with just one option. +
+ Dynamic possible values included by default + + MantisBT ships with some dynamic possible values, these + include the following: + + + + + =categories - a list of categories defined + in the current project (or the project to which the issue + belongs). + + + + =versions - a list of all versions defined + in the current project (or the project to which the issue + belongs). + + + + =future_versions - a list of all versions that + belong to the current project with + released flag set to false. + + + + =released_versions - a list of all versions + that belong to the current project with released flag set to + true. + + + -
+ + The '=' before the name of the dynamic list of options is used + to tell MantisBT that this is a dynamic list, rather than a static + list with just one option. + + -
- Defining Custom Dynamic Possible Values +
- If the user selects =versions, the actual custom function - that is executed is custom_function_*_enum_versions(). The reason - why the "enum_" is not included is to have a fixed prefix for all - custom functions used for this purpose and protect against users - using custom functions that were not intended for this purpose. - For example, you don't want the user to use - custom_function_*_issue_delete_notify() which may be overridden - by the web master to delete associated data in other - databases. +
+ Defining Custom Dynamic Possible Values + + If the user selects =versions, the actual custom function + that is executed is custom_function_*_enum_versions(). The reason + why the "enum_" is not included is to have a fixed prefix for all + custom functions used for this purpose and protect against users + using custom functions that were not intended for this purpose. + For example, you don't want the user to use + custom_function_*_issue_delete_notify() which may be overridden + by the web master to delete associated data in other + databases. + - Following is a sample custom function that is used to - populate a field with the categories belonging to the currently - selected project: + Following is a sample custom function that is used to + populate a field with the categories belonging to the currently + selected project: + # -------------------- # Construct an enumeration for all categories for the current project. @@ -487,86 +508,98 @@ switch( $g_active_language ) { # Enumerations format is: "abc|lmn|xyz" # To use this in a custom field type "=categories" in the possible values field. function custom_function_override_enum_categories() { - $t_categories = category_get_all_rows( helper_get_current_project() ); + $t_categories = category_get_all_rows( helper_get_current_project() ); - $t_enum = array(); - foreach( $t_categories as $t_category ) { - $t_enum[] = $t_category['category']; - } + $t_enum = array(); + foreach( $t_categories as $t_category ) { + $t_enum[] = $t_category['category']; + } - $t_possible_values = implode( '|', $t_enum ); + $t_possible_values = implode( '|', $t_enum ); - return $t_possible_values; + return $t_possible_values; } - - -Notice the following: - - The custom function doesn't take any - parameters. - The custom function returns the possible values in the - format (A|B|C). - The custom function uses the current - project. - The custom function builds on top of the already - existing APIs. - - + Notice the following: + + + + The custom function doesn't take any + parameters. + + + + The custom function returns the possible values in the + format (A|B|C). + + + + The custom function uses the current + project. + + + + The custom function builds on top of the already + existing APIs. + + + + -To define your own function \u201c=mine\u201d, you will have to define it -with the following signature: + To define your own function \u201c=mine\u201d, you will have to define it + with the following signature: + # -------------------- # To use this in a custom field type "=mine" in the possible values field. function custom_function_override_enum_mine() { - $t_enum = array(); + $t_enum = array(); - : + : - $t_possible_values = implode( '|', $t_enum ); + $t_possible_values = implode( '|', $t_enum ); - return $t_possible_values; + return $t_possible_values; } - -Notice "override" in the function name. This is because this method is -defined by the MantisBT administrator/webmaster and not part of the MantisBT source. -It is OK to override a method that doesn't exist. - -As usual, when MantisBT is upgraded to future releases, the custom functions -will not be overwritten. The difference between the "default" implementation and -the "override" implementation is explained in more details in the custom -functions section. + Notice "override" in the function name. This is because this method is + defined by the MantisBT administrator/webmaster and not part of the MantisBT source. + It is OK to override a method that doesn't exist. + -
+ As usual, when MantisBT is upgraded to future releases, the custom functions + will not be overwritten. The difference between the "default" implementation and + the "override" implementation is explained in more details in the custom + functions section. + -
+
-
+
-
- Enumerations +
+
+ Enumerations - Enumerations are used in MantisBT to represent a set of - possible values for an attribute. Enumerations are used for access - levels, severities, priorities, project statuses, project view - state, reproducibility, resolution, ETA, and projection. MantisBT - provides the administrator with the flexibility of altering the - values in these enumerations. The rest of this topic explains how - enumerations work, and then how they can be customised. - + Enumerations are used in MantisBT to represent a set of + possible values for an attribute. Enumerations are used for access + levels, severities, priorities, project statuses, project view + state, reproducibility, resolution, ETA, and projection. MantisBT + provides the administrator with the flexibility of altering the + values in these enumerations. The rest of this topic explains how + enumerations work, and then how they can be customised. + - + How do enumerations work? - - core/constant_inc.php defines the - constants that correspond to those in the enumeration. These are - useful to refer to these enumerations in the configs and the code. + + core/constant_inc.php defines the + constants that correspond to those in the enumeration. These are + useful to refer to these enumerations in the configs and the code. define( 'VIEWER', 10 ); define( 'REPORTER', 25 ); @@ -575,13 +608,13 @@ define( 'DEVELOPER', 55 ); define( 'MANAGER', 70 ); define( 'ADMINISTRATOR', 90 ); - - + + - - config_defaults_inc.php includes the defaults for the - enumerations. The configuration options that are defaulted here are - used in specifying which enumerations are active and should be used + + config_defaults_inc.php includes the defaults for the + enumerations. The configuration options that are defaulted here are + used in specifying which enumerations are active and should be used in MantisBT. @@ -594,45 +627,45 @@ $g_access_levels_enum_string = enumeration is not found in the corresponding localised string (i.e. 70:manager), then it will be printed to the user as @70@. - - + + The Language Files (e.g. lang/strings_german.txt) provide the localised strings (German in this case) for enumerations. But again, the master list is the enumeration in the configs themselves, the ones in the language files are - just used for finding the localised equivalent for an entry. Hence, - if a user changes the config to have only two types of users - developers and administrators, then only those will be prompted to - the users even if the enumerations in the language files still - includes the full list. + just used for finding the localised equivalent for an entry. Hence, + if a user changes the config to have only two types of users + developers and administrators, then only those will be prompted to + the users even if the enumerations in the language files still + includes the full list. $s_access_levels_enum_string = '10:Betrachter,25:Reporter,40:Updater,55:Entwickler,70:Manager,90:Administrator'; - + - + How can they be customised? Let say we want to remove access level "Updater" and add access level "Senior Developer". - - - The file config/custom_constants_inc.php is supported for the - exclusive purpose of allowing administrators to define their own - constants while maintaining a simple upgrade path for future - releases of MantisBT. Note that this file is not distributed with - MantisBT and you will need to create it if you need such - customisation. In our example, we need to define a constant for the - new access level. + + + The file config/custom_constants_inc.php is supported for the + exclusive purpose of allowing administrators to define their own + constants while maintaining a simple upgrade path for future + releases of MantisBT. Note that this file is not distributed with + MantisBT and you will need to create it if you need such + customisation. In our example, we need to define a constant for the + new access level. define( 'SENIOR_DEVELOPER', 60 ); - + - - In config/config_inc.php + + In config/config_inc.php // Remove Updater and add Senior Developer $g_access_levels_enum_string = @@ -641,9 +674,9 @@ $g_access_levels_enum_string = // Give access to Senior developers to create/delete custom field. $g_manage_custom_fields_threshold = SENIOR_DEVELOPER; - + - + Update custom_strings_inc.php (see ) @@ -654,9 +687,9 @@ $s_access_levels_enum_string = entry from the localisation file if the current language is 'English'. - + - + Conclusion We have covered how enumerations work in general, and how to customise one of them. If you are interested in customising @@ -665,33 +698,33 @@ $s_access_levels_enum_string = config_defaults_inc.php. This section defines all enumerations that are used by MantisBT. - + -
+ -
- Email Notifications +
+ Email Notifications - See - in the Configuration section. - + See + in the Configuration section. + - Examples: - - - Notify only managers of new issues. + Examples: + + + Notify only managers of new issues. $g_notify_flags['new'] = array( 'threshold_min' => MANAGER, 'threshold_max' => MANAGER, ); - - - - Notify Developers and managers of all project events, - except, exclude developers from the 'closed' events. + + + + Notify Developers and managers of all project events, + except, exclude developers from the 'closed' events. $g_default_notify_flags = array( 'threshold_min' => DEVELOPER, @@ -702,47 +735,47 @@ $g_notify_flags['closed'] = array( 'threshold_max' => MANAGER, ); - - - - Exclude those who contributed issue notes from getting - messages about other changes in the issue. + + + + Exclude those who contributed issue notes from getting + messages about other changes in the issue. $g_default_notify_flags['bugnotes'] = OFF; - - - - Exclude those monitoring issues from seeing the 'closed' - message + + + + Exclude those monitoring issues from seeing the 'closed' + message $g_notify_flags['closed']['monitor'] = OFF; - - - - Only notify developers when issue notes are added. + + + + Only notify developers when issue notes are added. $g_notify_flags['bugnote'] = array( 'threshold_min' => DEVELOPER, 'threshold_max' => DEVELOPER, ); - - - - Notify managers of changes in sponsorship. + + + + Notify managers of changes in sponsorship. $g_notify_flags['sponsor'] = array( 'threshold_min' => MANAGER, 'threshold_max' => MANAGER, ); - - - - Notify originator and managers of changes in ownership - ("Assigned To:"). + + + + Notify originator and managers of changes in ownership + ("Assigned To:"). $g_notify_flags['owner'] = array( 'threshold_min' => MANAGER, @@ -750,13 +783,13 @@ $g_notify_flags['owner'] = array( 'reporter' => ON, ); - - - - I'm paranoid about mail. Only send information on issues - to those involved in them. Don't send mail people already know - about. Also send new issue notifications to managers so they can - screen them. + + + + I'm paranoid about mail. Only send information on issues + to those involved in them. Don't send mail people already know + about. Also send new issue notifications to managers so they can + screen them. $g_email_receive_own = OFF; $g_default_notify_flags = array(