| [ Index ] |
PHP Cross Reference of MantisBT |
[Summary view] [Print] [Text view]
1 <chapter id="admin.customize."> 2 <title>Customizing MantisBT</title> 3 4 <section id="admin.customize.customfields"> 5 <title>Custom Fields</title> 6 7 <section id="admin.customize.customfields.overview"> 8 <title>Overview</title> 9 10 <para>Different teams typically like to capture different information 11 as users report issues, in some cases, the data required is even 12 different from one project to another. Hence, MantisBT provides the 13 ability for managers and administrators to define custom fields as way 14 to extend MantisBT to deal with information that is specific to their 15 teams or their projects. The aim is for this to keep MantisBT native 16 fields to a minimum. 17 18 Following are some facts about the implementation of 19 custom fields in MantisBT: 20 <itemizedlist> 21 <listitem> 22 <para>Custom fields are defined system wide.</para> 23 </listitem> 24 <listitem> 25 <para>Custom fields can be linked to multiple 26 projects. 27 </para> 28 </listitem> 29 <listitem> 30 <para>The sequence of displaying custom fields can be different 31 per project. 32 </para> 33 </listitem> 34 <listitem> 35 <para>Custom fields must be defined by users with access level 36 ADMINISTRATOR. 37 </para> 38 </listitem> 39 <listitem> 40 <para>Custom fields can be linked to projects by users with 41 access level MANAGER or above (by default, this can be 42 configurable). 43 </para> 44 </listitem> 45 <listitem> 46 <para>Number of custom fields is not restricted.</para> 47 </listitem> 48 <listitem> 49 <para>Users can define filters that include custom fields.</para> 50 </listitem> 51 <listitem> 52 <para>Custom fields can be included in View Issues, Print 53 Issues, and CSV exports.</para> 54 </listitem> 55 <listitem> 56 <para>Enumeration custom fields can have a set of static 57 values or values that are calculated dynamically based on 58 a custom function.</para> 59 </listitem> 60 </itemizedlist> 61 </para> 62 </section> 63 64 <section id="admin.customize.customfields.definitions"> 65 <title>Custom Field Definition</title> 66 67 <para> 68 The definition of a custom field includes the following logical 69 attributes: 70 71 <itemizedlist> 72 <listitem> 73 <para>Caption variable name (eg: This is the value that is 74 supplied to lang_get() API, or displayed as-is if not found in 75 language file). This should not include any space or 76 any character that would be an invalid PHP identifier. 77 </para> 78 </listitem> 79 <listitem> 80 <para>Custom field type (string, numeric, float, 81 enumeration, email, checkbox, radio, list, multi-selection list, date). 82 </para> 83 <para>Type 'string' is used for strings of up to 255 characters.</para> 84 <para>Type 'numeric' is used for numerical integer values.</para> 85 <para>Type 'float' is used for real (float / double) numbers.</para> 86 <para>Type 'enumeration' is used when a user selects one entry from a list. The user interface for such type is a combo-box.</para> 87 <para>Type 'email' is used for storing email addresses.</para> 88 <para>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).</para> 89 <para>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.</para> 90 <para>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.</para> 91 <para>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.</para> 92 <para>Type 'date' is for date values. The default value can be empty, or {tomorrow}, {yesterday}, {next week}, {last week}, {+3 days}, {-2 days}.</para> 93 </listitem> 94 <listitem> 95 <para>Enumeration possible values (eg: RED|YELLOW|BLUE). 96 Use the pipe ('|') character to separate possible values for an 97 enumeration. One of the possible values can be an 98 empty string. The set of possible values can also be 99 calculated at runtime. For example, "=versions" would 100 automatically resolve into all the versions defined 101 for the current project. 102 </para> 103 </listitem> 104 <listitem> 105 <para>Default value - see details above for a sample default value for each type.</para> 106 </listitem> 107 <listitem> 108 <para>Minimum/maximum length for the custom field value (use 0 109 to disable). Note that these metrics are not really relevant to custom fields that are based on an enumeration of possible values. 110 </para> 111 </listitem> 112 <listitem> 113 <para>Regular expression to use for validating user input (use <ulink url="http://www.php.net/manual/en/reference.pcre.pattern.syntax.php">PCRE syntax</ulink>). 114 </para> 115 </listitem> 116 <listitem> 117 <para>Read Access level: Minimum access level for users to be 118 able to see the value of the custom field. 119 </para> 120 </listitem> 121 <listitem> 122 <para>Write Access level: Minimum access level for users to be 123 able to edit the value of the custom field. 124 </para> 125 </listitem> 126 <listitem> 127 <para>Display when reporting issues? - If this custom 128 field should be shown on the Report Issue page. 129 </para> 130 </listitem> 131 <listitem> 132 <para>Display when updating issues? - If this custom 133 field should be shown on the Update Issue page. 134 </para> 135 </listitem> 136 <listitem> 137 <para>Display when resolving issues? - If this custom 138 field should be shown when resolving an issue. For 139 example, a "root cause" custom field would make sense to 140 set when resolving the issue. 141 </para> 142 </listitem> 143 <listitem> 144 <para>Display when closing issues? - If this custom 145 field should be shown when closing an issue. 146 </para> 147 </listitem> 148 <listitem> 149 <para>Required on Report - If this custom 150 field is a mandatory field on the Report Issue page. 151 </para> 152 </listitem> 153 <listitem> 154 <para>Required on Update - If this custom 155 field is a mandatory field on the Update Issue page. 156 </para> 157 </listitem> 158 <listitem> 159 <para>Required on Resolve - If this custom 160 field is a mandatory field when resolving an issue. 161 </para> 162 </listitem> 163 <listitem> 164 <para>Required on Close - If this custom 165 field is a mandatory field when closing an issue. 166 </para> 167 </listitem> 168 </itemizedlist> 169 </para> 170 171 <para>All custom fields are currently saved to a field of type 172 VARCHAR(255) in the database. However, in future releases, it is 173 possible to support custom fields of different types (eg: memo, 174 file).</para> 175 176 <para> 177 If the value of a custom field for a certain defect is not found, 178 the default value is assumed. 179 </para> 180 </section> 181 182 <section id="admin.customize.customfields.editing"> 183 <title>Adding/Editing Custom Fields</title> 184 185 <para> 186 <itemizedlist> 187 <listitem> 188 <para>The logged in user needs $g_manage_custom_fields_threshold 189 access level. 190 </para> 191 </listitem> 192 <listitem> 193 <para>Select "Manage" from the main menu.</para> 194 </listitem> 195 <listitem> 196 <para>Select "Manage Custom Fields" from the management 197 menu. 198 </para> 199 </listitem> 200 <listitem> 201 <para>In case of edit, click on the name of an existing 202 custom field to edit its information. 203 </para> 204 </listitem> 205 <listitem> 206 <para>In case of adding a new one, enter the name of the 207 new custom field then click "New Custom Field". 208 </para> 209 </listitem> 210 </itemizedlist> 211 </para> 212 213 <note><para>Added custom fields will not show up in any of the issues 214 until the added custom field is linked to the appropriate 215 projects.</para></note> 216 </section> 217 218 <section id="admin.customize.customfields.linking"> 219 <title>Linking/Unlinking/Ordering Existing Custom Fields in Projects</title> 220 221 <para> 222 <itemizedlist> 223 <listitem> 224 <para>The logged in user needs to have access level that is 225 greater than or equal to $g_custom_field_link_threshold and 226 $g_manage_project_threshold. 227 </para> 228 </listitem> 229 <listitem> 230 <para>Select "Manage" from the main menu.</para> 231 </listitem> 232 <listitem> 233 <para>Select "Manage Projects". 234 </para> 235 </listitem> 236 <listitem> 237 <para>Select the name of the project to manage.</para> 238 </listitem> 239 <listitem> 240 <para>Scroll down to the "Custom Fields" box.</para> 241 </listitem> 242 <listitem> 243 <para>Select the field to add from the list, then click "Add 244 This Existing Custom Field". 245 </para> 246 </listitem> 247 <listitem> 248 <para>To change the order of the custom fields, edit the 249 "Sequence" value and click update. Custom fields with smaller 250 values are displayed first. 251 </para> 252 </listitem> 253 <listitem> 254 <para>To unlink a custom field, click on "Remove" link next to 255 the field. 256 Unlinking a custom field will not delete the values that are 257 associated with the issues for this field. These values are only 258 deleted if the custom field definition is removed (not unlinked!) 259 from the database. This is useful if you decide to re-link the 260 custom field. These values may also re-appear if issues are moved to 261 another project which has this field linked. 262 </para> 263 </listitem> 264 </itemizedlist> 265 </para> 266 267 <formalpara> 268 <title>Moving Issues</title> 269 <para> 270 When an issue is moved from one project to another, custom 271 fields that are not defined for the new project are not deleted. 272 These fields will re-appear with their correct values if the issue is 273 moved back to the original project, or if these custom fields are 274 linked to the new project. 275 </para> 276 </formalpara> 277 </section> 278 279 <section id="admin.customize.customfields.localize"> 280 <title>Localizing Custom Field Names</title> 281 282 <para>It is possible to localize the label for the custom fields. 283 This can be as follows: 284 285 <itemizedlist> 286 <listitem><para>Give the custom field a valid variable name 287 (i.e. start with an alpha character, no spaces, etc) - For 288 example, we will use "my_start_date" for a custom field of 289 type "Date" which stores the "Start Date" for working on an 290 issue.</para></listitem> 291 <listitem><para>Add the localized string for "my_start_date" 292 - This can be done by creating custom_strings_inc.php in the 293 MantisBT root folder and adding the following code to it: 294 <programlisting> 295 <?php 296 if ( lang_get_current() == 'german' ) { 297 $s_my_start_date = 'Start Date XX'; // German translation of Start Date 298 } else { 299 # Default (use your preferred language as the default) 300 $s_my_start_date = 'Start Date'; 301 } 302 ?></programlisting></para></listitem> 303 </itemizedlist> 304 </para> 305 306 <note><para>If we would have decided to use start_date as the 307 name of the custom field, then we have used an already localized 308 string from MantisBT standard strings. In this case, there is no 309 need to create the custom_strings_inc.php or to add any strings to 310 it. To check for standard strings, inspect 311 lang/strings_english.txt.</para></note> 312 </section> 313 314 <section id="admin.customize.customfields.defaults"> 315 <title>Dynamic default values</title> 316 317 <section id="admin.customize.customfields.defaults.date"> 318 <title>Dynamic defaults for Date fields</title> 319 320 <para>Custom fields of type date can be defaulted to a specific dates or to relative dates. Typically relative dates is the scenario that makes sense in most of the cases. The format for specific dates is an integer which indicates the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT), which is the format consumed by the PHP <ulink url="http://www.php.net/date">date()</ulink> method. The relative scenario expects default values like {tomorrow}, {yesterday}, {+2 days}, {-3 days}, {next week}, etc. The curly brackets indicate that this is a logical value which is then evaluated using the PHP <ulink url="http://www.php.net/strtotime">strtotime()</ulink> function.</para> 321 </section> 322 </section> 323 324 <section id="admin.customize.customfields.dynamic"> 325 <title>Dynamic values for Enumeration Custom Fields</title> 326 327 <para>As discussed earlier, one of the possible types of a custom 328 field is "enumeration". This type of custom field allows the user 329 to select one value from a provided list of possible values. The 330 standard way of defining such custom fields is to provide a '|' 331 separated list of possible values. However, this approach has two 332 limitations: the list is static, and the maximum length of the list 333 must be no longer than 255 characters. Hence, the need for the 334 ability to construct the list of possible values dynamically.</para> 335 336 337 <section id="admin.customize.customfields.dynamic.default"> 338 <title>Dynamic possible values included by default</title> 339 340 <para>MantisBT ships with some dynamic possible values, these 341 include the following: 342 343 <itemizedlist> 344 <listitem><para>=categories - a list of categories defined 345 in the current project (or the project to which the issue 346 belongs).</para></listitem> 347 <listitem><para>=versions - a list of all versions defined 348 in the current project (or the project to which the issue 349 belongs).</para></listitem> 350 <listitem><para>=future_versions - a list of all versions that 351 belong to the current project with 352 released flag set to false.</para></listitem> 353 <listitem><para>=released_versions - a list of all versions 354 that belong to the current project with released flag set to 355 true.</para></listitem> 356 </itemizedlist> 357 </para> 358 359 <note><para>The '=' before the name of the dynamic list of options is used 360 to tell MantisBT that this is a dynamic list, rather than a static 361 list with just one option.</para></note> 362 363 </section> 364 365 <section id="admin.customize.customfields.dynamic.custom"> 366 <title>Defining Custom Dynamic Possible Values</title> 367 368 <para>If the user selects =versions, the actual custom function 369 that is executed is custom_function_*_enum_versions(). The reason 370 why the "enum_" is not included is to have a fixed prefix for all 371 custom functions used for this purpose and protect against users 372 using custom functions that were not intended for this purpose. 373 For example, you don't want the user to use 374 custom_function_*_issue_delete_notify() which may be overridden 375 by the web master to delete associated data in other 376 databases.</para> 377 378 <para>Following is a sample custom function that is used to 379 populate a field with the categories belonging to the currently 380 selected project: 381 382 <programlisting># -------------------- 383 # Construct an enumeration for all categories for the current project. 384 # The enumeration will be empty if current project is ALL PROJECTS. 385 # Enumerations format is: "abc|lmn|xyz" 386 # To use this in a custom field type "=categories" in the possible values field. 387 function custom_function_override_enum_categories() { 388 $t_categories = category_get_all_rows( helper_get_current_project() ); 389 390 $t_enum = array(); 391 foreach( $t_categories as $t_category ) { 392 $t_enum[] = $t_category['category']; 393 } 394 395 $t_possible_values = implode( '|', $t_enum ); 396 397 return $t_possible_values; 398 }</programlisting> 399 </para> 400 401 <para>Notice the following: 402 403 <itemizedlist> 404 <listitem><para>The custom function doesn't take any 405 parameters.</para></listitem> 406 <listitem><para>The custom function returns the possible values in the 407 format (A|B|C).</para></listitem> 408 <listitem><para>The custom function uses the current 409 project.</para></listitem> 410 <listitem><para>The custom function builds on top of the already 411 existing APIs.</para></listitem> 412 </itemizedlist> 413 </para> 414 415 <para>To define your own function \u201c=mine\u201d, you will have to define it 416 with the following signature: 417 418 <programlisting> 419 # -------------------- 420 # To use this in a custom field type "=mine" in the possible values field. 421 function custom_function_override_enum_mine() { 422 $t_enum = array(); 423 424 : 425 426 $t_possible_values = implode( '|', $t_enum ); 427 428 return $t_possible_values; 429 } 430 </programlisting> 431 </para> 432 433 <para>Notice "override" in the function name. This is because this method is 434 defined by the MantisBT administrator/webmaster and not part of the MantisBT source. 435 It is OK to override a method that doesn't exist.</para> 436 437 <para>As usual, when MantisBT is upgraded to future releases, the custom functions 438 will not be overwritten. The difference between the "default" implementation and 439 the "override" implementation is explained in more details in the custom 440 functions section.</para> 441 442 </section> 443 444 </section> 445 446 </section> 447 <section id="admin.customize.enums"> 448 <title>Enumerations</title> 449 450 451 <para>Enumerations are used in MantisBT to represent a set of 452 possible values for an attribute. Enumerations are used for access 453 levels, severities, priorities, project statuses, project view 454 state, reproducibility, resolution, ETA, and projection. MantisBT 455 provides the administrator with the flexibility of altering the 456 values in these enumerations. The rest of this topic explains how 457 enumerations work, and then how they can be customised. 458 </para> 459 460 <formalpara> 461 <title>How enumerations work?</title> 462 463 <para> 464 <filename>core/constant_inc.php</filename> defines the 465 constants that correspond to those in the enumeration. These are 466 useful to refer to these enumerations in the configs and the code. 467 <programlisting> 468 define( 'VIEWER', 10 ) 469 define( 'REPORTER', 25 ) 470 define( 'UPDATER', 40 ) 471 define( 'DEVELOPER', 55 ) 472 define( 'MANAGER', 70 ) 473 define( 'ADMINISTRATOR', 90 ) 474 </programlisting> 475 </para> 476 </formalpara> 477 478 <para> 479 <filename>config_defaults_inc.php</filename> includes the defaults for the 480 enumerations. The configuration options that are defaulted here are 481 used in specifying which enumerations are active and should be used 482 in MantisBT. However, the strings included in the enumerations here 483 are just for documentation purpose, they are not shown to the user 484 (due to the need for localisation). Hence, if an entry in this 485 enumeration is not found in the corresponding localised enumeration 486 (i.e. 70:manager), then it will be printed to the user as @70@. 487 488 <programlisting> 489 $g_access_levels_enum_string = 490 '10:viewer,25:reporter,40:updater,55:developer,70:manager,90:administrator'; 491 </programlisting> 492 </para> 493 <para> 494 <filename>lang/strings_german.txt</filename> provide the 495 localised strings (in this case, in german) for enumerations. But again, the master list is 496 the enumeration in the configs, the ones in the language files are 497 just used for finding the localised equivalent for an entry. Hence, 498 if a user changes the config to have only two types of users 499 developers and administrators, then only those will be prompted to 500 the users even if the enumerations in the language files still 501 includes the full list. 502 <programlisting> 503 504 $s_access_levels_enum_string = 505 '10:Betrachter,25:Reporter,40:Updater,55:Entwickler,70:Manager,90:Administrator'; 506 </programlisting> 507 </para> 508 509 <formalpara> 510 <title>How can they be customised?</title> <para>Let say we want to remove access level 511 "Updater" and add access level "Senior 512 Developer". 513 </para> 514 </formalpara> 515 <para> 516 The file <filename>custom_constants_inc.php</filename> is supported for the 517 exclusive purpose of allowing administrators to define their own 518 constants while maintaining a simple upgrade path for future 519 releases of MantisBT. Note that this file is not distributed with 520 MantisBT and you will need to create it if you need such 521 customisation. In our example, we need to define a constant for the 522 new access level. 523 <programlisting> 524 define ( 'SENIOR_DEVELOPER', 60 ); 525 </programlisting> 526 </para> 527 528 <para> 529 In <filename>config_inc.php</filename> 530 <programlisting> 531 // Remove Updater and add Senior Developer 532 $g_access_levels_enum_string = 533 '10:viewer,25:reporter,55:developer,60:senior_developer,70:manager,90:administrator'; 534 // Give access to Senior developers to create/delete custom field. 535 $g_manage_custom_fields_threshold = SENIOR_DEVELOPER; 536 </programlisting> 537 </para> 538 539 <para> 540 The file <filename>custom_strings_inc.php</filename> is introduced for a similar reason 541 to that of custom_constants_inc.php, which is to define custom 542 strings. The advantage of defining them here is to provide a simple 543 upgrade path, and avoid having to re-do the changes when upgrading 544 to the next MantisBT release. Note that you will need to create this 545 file if you need such customisation. The file is automatically 546 detected and included by MantisBT code. 547 <programlisting> 548 # Note that we don't have to remove the Updater entry from the 549 localisation file if ( lang_get_current() === 'english' ) { 550 $s_access_levels_enum_string = 551 '10:Betrachter,25:Reporter,40:Updater,55:Entwickler,60:Senior 552 Developer,70:Manager,90:Administrator'; } 553 </programlisting> 554 </para> 555 556 <formalpara> 557 <title>Conclusion</title><para>We have covered how enumerations work in general, and how 558 to customise one of them. If you are interested in customising 559 other enumerations, a good starting point would be to go to "MantisBT 560 Enum Strings" section in config_defaults_inc.php. This section 561 defines all enumerations that are used by MantisBT. 562 For versions that are older than 0.18.0, custom_*_inc.php files are 563 not supported, and hence you will need to change in the actual 564 constants / language files directly. 565 </para> 566 </formalpara> 567 568 </section> 569 570 571 <section id="admin.customize.email"> 572 <title>Email Notifications</title> 573 574 <para>See Email in the Configuration section.</para> 575 576 <para>Examples: 577 <itemizedlist> 578 <listitem> 579 <para>Notify only managers of new issues. 580 <programlisting> 581 $g_notify_flags['new']['threshold_min'] = MANAGER; 582 $g_notify_flags['new']['threshold_max'] = MANAGER; 583 </programlisting> 584 </para> 585 </listitem> 586 <listitem> 587 <para>Notify Developers and managers of all project events, 588 except, exclude developers from the 'closed' events. 589 <programlisting>$g_default_notify_flags['threshold_min'] = DEVELOPER; 590 $g_default_notify_flags['threshold_max'] = MANAGER; 591 $g_notify_flags['closed']['threshold_max'] = MANAGER; 592 $g_notify_flags['closed']['threshold_max'] = MANAGER; 593 </programlisting> 594 </para> 595 </listitem> 596 <listitem> 597 <para>Exclude those who contributed issue notes from getting 598 messages about other changes in the issue. 599 <programlisting>$g_default_notify_flags['bugnotes'] = OFF;</programlisting> 600 </para> 601 </listitem> 602 <listitem> 603 <para>Exclude those monitoring issues from seeing the 'closed' 604 message 605 <programlisting>$g_notify_flags['closed']['monitor'] = OFF;</programlisting> 606 </para> 607 </listitem> 608 <listitem> 609 <para>Only notify developers when issue notes are added. 610 <programlisting>$g_notify_flags['bugnote']['threshold_min'] = DEVELOPER; 611 $g_notify_flags['bugnote']['threshold_max'] = DEVELOPER; 612 </programlisting> 613 </para> 614 </listitem> 615 <listitem> 616 <para>Notify managers of changes in sponsorship. 617 <programlisting>$g_notify_flags['sponsor']['threshold_max'] = MANAGER; 618 $g_notify_flags['sponsor']['threshold_max'] = MANAGER; 619 </programlisting> 620 </para> 621 </listitem> 622 <listitem> 623 <para>Notify originator and managers of changes in ownership 624 ("Assigned To:"). 625 <programlisting>$g_notify_flags['owner']['threshold_max'] = MANAGER; 626 $g_notify_flags['owner']['threshold_max'] = MANAGER; 627 $g_notify_flags['owner']['reporter'] = ON; 628 </programlisting> 629 </para> 630 </listitem> 631 <listitem> 632 <para>I'm paranoid about mail. Only send information on issues 633 to those involved in them. Don't send mail people already know 634 about. Also send new issue notifications to managers so they can 635 screen them. 636 <programlisting>$g_mail_receive_own = OFF; 637 $g_default_notify_flags = 638 array('reporter' => ON, 'handler' => ON, 'monitor' => ON, 639 'bugnotes' => ON, 'threshold_min' => NOBODY, 'threshold_max' 640 => NOBODY); 641 $g_notify_flags['new']['threshold_min'] = MANAGER; 642 $g_notify_flags['new']['threshold_max'] = MANAGER; 643 </programlisting> 644 </para> 645 </listitem> 646 <listitem> 647 <para>How do I replace the $g_to_email configuration variable 648 to log all messages to an email logger. 649 </para> 650 <para>You will need to create a 651 dummy user with the appropriate access level for the notices you 652 want to log. Once this user is added to projects, they will receive 653 mail using the appropriate rules. 654 </para> 655 </listitem> 656 </itemizedlist> 657 </para> 658 </section> 659 660 <section id="admin.customize.status"> 661 <title>Customizing Status Values</title> 662 <para>The default is no workflow, where all states 663 are accessible from any others. The following example can be 664 transferred to config_inc.php. The workflow needs to have a path 665 from the statuses greater than or equal to the resolved state back 666 to the feedback state. Otherwise, the re-open operation won't work. 667 <programlisting>$g_status_enum_workflow[NEW_]= 668 '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned,80:resolved'; 669 $g_status_enum_workflow[FEEDBACK] = 670 '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned,80:resolved'; 671 $g_status_enum_workflow[ACKNOWLEDGED] = 672 '20:feedback,30:acknowledged,40:confirmed,50:assigned,80:resolved'; 673 $g_status_enum_workflow[CONFIRMED] = 674 '20:feedback,40:confirmed,50:assigned,80:resolved'; 675 $g_status_enum_workflow[ASSIGNED] = 676 '20:feedback,50:assigned,80:resolved,90:closed'; 677 $g_status_enum_workflow[RESOLVED] = 678 '50:assigned,80:resolved,90:closed'; 679 $g_status_enum_workflow[CLOSED] = '50:assigned'; 680 </programlisting> 681 </para> 682 683 <para>To add a status: 684 <orderedlist> 685 <listitem> 686 <para>Define a constant to map the new status to.In a new file 687 custom_constants_inc.php in the main mantisbt directory: 688 <programlisting><?php define ( 'TEST', 60 ); ?></programlisting> 689 </para> 690 </listitem> 691 <listitem> 692 <para>Define the language strings required. This may need to be 693 defined in several languages.In a new file custom_strings_inc.php 694 in the main mantisbt directory: 695 <programlisting language="PHP (HTML)"><?php if ( lang_get_current() == 'german' ) { 696 $s_status_enum_string = '10:neu,20:Rückmeldung,30:anerkannt,40:bestätigt,50:zugewiesen,60:zu testen,80:behoben,90:geschlossen'; 697 } else { 698 $s_status_enum_string = '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned, 60:to be tested,80:resolved,90:closed'; 699 $s_to_be_tested_bug_button = "Issue Ready to Test"; 700 $s_to_be_tested_bug_title = "Set Issue Ready to Test"; 701 $s_email_notification_title_for_status_bug_to_be_tested = "The following issue is ready TO BE TESTED."; 702 } 703 ?> 704 </programlisting> 705 </para> 706 </listitem> 707 <listitem> 708 <para>Define any configurations required.In the existing file 709 config_inc.php in the main mantisbt directory: 710 <programlisting>$g_status_enum_string = 711 '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned, 60:to 712 be tested,80:resolved,90:closed'; # Status color additions 713 $g_status_colors['to be tested'] = '#ACE7AE'; 714 </programlisting> 715 </para> 716 </listitem> 717 <listitem> 718 <para>Add the status to any workflow defined.In config_inc.php: 719 <programlisting>$g_status_enum_workflow[NEW_]= 720 '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned,60:to 721 be tested'; $g_status_enum_workflow[FEEDBACK] = 722 '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned,60:to 723 be tested'; $g_status_enum_workflow[ACKNOWLEDGED] = 724 '20:feedback,30:acknowledged,40:confi rmed,50:assigned,60:to be 725 tested'; $g_status_enum_workflow[CONFIRMED] = 726 '20:feedback,40:confirmed,50:assigned,60:to be tested'; 727 $g_status_enum_workflow[ASSIGNED] = '20:feedback,50:assigned,60:to 728 be tested,90:closed'; $g_status_enum_workflow[TEST] = 729 '10:new,20:feedback,50:assigned,60:to be 730 tested,80:resolved,90:closed'; $g_status_enum_workflow[RESOLVED] = 731 '50:assigned,60:to be tested,80:resolved,90:closed'; 732 $g_status_enum_workflow[CLOSED] = '50:assigned,90:closed'; 733 </programlisting> 734 </para> 735 </listitem> 736 </orderedlist> 737 </para> 738 </section> 739 740 <section id="admin.customize.customfuncs"> 741 <title>Custom Functions</title> 742 743 <para>Custom functions are used to extend the functionality of 744 MantisBT by integrating user written functions into the issue 745 processing at strategic places. This allows the system 746 administrator to change the functionality without re-writing parts 747 of the internals of the code. 748 </para> 749 <para>User versions of these functions are 750 placed in a file called custom_functions_inc.php in the 751 root directory of MantisBT. This is the same place that the 752 "config_inc.php" file modifying MantisBT defaults is placed. In normal 753 processing, MantisBT will look for override functions and execute 754 them instead of the provided default functions.</para> 755 <para>Custom functions have 756 names like custom_function_override_descriptive_name where 757 descriptive name described the particular function. The specific 758 functions are described below. The simplest way to create a custom 759 function is to copy the default function, named 760 custom_function_default_descriptive_namefrom the 761 core/custom_function_api.php file to your override file 762 (custom_functions_inc.php), and rename it. The specific 763 functionality you need can then be coded into the override 764 function. 765 </para> 766 767 <section id="admin.customize.customfuncs.defined"> 768 <title>Defined Functions</title> 769 770 <para>custom_function_default_changelog_include_issue( $p_issue_id 771 ) returns true or false if the issue if to be included in the 772 Changelog. custom_function_default_changelog_print_issue( $p_issue_id 773 ) returns a formatted string to be included for the issue in the 774 Changelog. custom_function_default_issue_update_validate( $p_issue_id, 775 $p_new_bug, $p_bug_note_text ) validate issue field settings before 776 an update occurs. It returns true or fails with an 777 error. custom_function_default_issue_update_notify( $p_issue_id ) 778 notify after an issue has been 779 updated. custom_function_default_issue_create_validate( $p_new_bug ) 780 validate issue field settings before an issue is created. It returns 781 true or fails with an 782 error. custom_function_default_issue_create_notify( $p_issue_id ) 783 notify after an issue has been 784 opened. custom_function_default_issue_delete_validate( $p_issue_id ) 785 validate issue field settings before an issue can be deleted. It 786 returns true or fails with an 787 error. custom_function_default_issue_delete_notify( $p_issue_id ) 788 notify after an issue has been deleted 789 </para> 790 </section> 791 792 <section id="admin.customize.customfuncs.example"> 793 <title>Example Custom Function</title> 794 795 <para>The following function is used to validate an issue before 796 it is resolved. 797 <programlisting width="102"><![CDATA[<?php 798 # -------------------- 799 # Hook to validate Validate field settings before resolving 800 # verify that the resolution is not set to OPEN 801 # verify that the fixed in version is set (if versions of the product exist) 802 803 function custom_function_override_issue_update_validate( $p_issue_id, $p_bug_data, $p_bugnote_text ) { 804 if ( $p_bug_data->status == RESOLVED ) { 805 if ( $p_bug_data->resolution == OPEN ) { 806 error_parameters( 'the resolution cannot be open to resolve the issue' ); 807 trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR ); 808 } 809 $t_version_count = count( version_get_all_rows( $p_bug_data->project_id ) ); 810 if ( ( $t_version_count > 0 ) && ( $p_bug_data->fixed_in_version == '' ) ) { 811 error_parameters( 'fixed in version must be set to resolve the issue' ); 812 trigger_error( ERROR_BUG_VALIDATE_FAILURE, ERROR ); 813 } 814 } 815 } 816 ?>]]> 817 </programlisting> 818 The errors will also need to be defined by adding the following to <filename>custom_constants_inc.php</filename> 819 <programlisting> 820 define ( 'ERROR_VALIDATE_FAILURE', 2000 ); 821 To custom_strings_inc.php 822 $MANTIS_ERROR['ERROR_VALIDATE_FAILURE'] = 'This change cannot be made because %s'; 823 </programlisting> 824 </para> 825 </section> 826 </section> 827 </chapter>
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Thu Jul 28 15:48:31 2011 | Cross-referenced by PHPXref 0.7 |