/
Customizing.xml
1287 lines (1181 loc) · 43.3 KB
/
Customizing.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<chapter id="admin.customize">
<title>Customizing MantisBT</title>
<section id="admin.customize.strings">
<title>Strings / Translations</title>
<para>All strings used in MantisBT, including those defined in
plugins, can be customized or translated differently.
This is achieved by overriding them in the
<emphasis>Custom Strings File</emphasis>
(<filename>config/custom_strings_inc.php</filename>),
which is automatically detected and included by MantisBT code.
</para>
<para>Defining custom strings here provides a simple upgrade path,
and avoids having to re-do the changes when upgrading to the
next release.
</para>
<note><para>The standard MantisBT language strings are sometimes reused
in different contexts.
If you are planning to override some strings to meet your specific
requirements, make sure to analyze where they are used to avoids
unexpected issues.
</para></note>
<para>Format
<programlisting>
$s_CODE = STRING;
</programlisting>
</para>
<para>Where
<itemizedlist>
<listitem>
<para>CODE = string code, as called by
lang_get() function.
Search in lang/strings_english.txt for existing codes.
</para>
</listitem>
<listitem>
<para>STRING = string value / translation
</para>
</listitem>
</itemizedlist>
</para>
<warning><para>NEVER call <emphasis>lang_get_current()</emphasis>
from the <filename>custom_strings_inc.php</filename>, as doing so
will reset the active_language, causing the code to return
incorrect translations if the default language is different
from English.
Always use the <emphasis>$g_active_language</emphasis>
global variable instead.
</para></warning>
</section>
<section id="admin.customize.customfields">
<title>Custom Fields</title>
<section id="admin.customize.customfields.overview">
<title>Overview</title>
<para>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:
</para>
<itemizedlist>
<listitem>
<para>Custom fields are defined system wide.</para>
</listitem>
<listitem>
<para>Custom fields can be linked to multiple
projects.
</para>
</listitem>
<listitem>
<para>The sequence of displaying custom fields can be different
per project.
</para>
</listitem>
<listitem>
<para>Custom fields must be defined by users with access level
ADMINISTRATOR.
</para>
</listitem>
<listitem>
<para>Custom fields can be linked to projects by users with
access level MANAGER or above (by default, this can be
configurable).
</para>
</listitem>
<listitem>
<para>Number of custom fields is not restricted.</para>
</listitem>
<listitem>
<para>Users can define filters that include custom fields.</para>
</listitem>
<listitem>
<para>Custom fields can be included in View Issues, Print
Issues, and CSV exports.</para>
</listitem>
<listitem>
<para>Enumeration custom fields can have a set of static
values or values that are calculated dynamically based on
a custom function.</para>
</listitem>
</itemizedlist>
</section>
<section id="admin.customize.customfields.definitions">
<title>Custom Field Definition</title>
<para>
The definition of a custom field includes the following logical
attributes:
<itemizedlist>
<listitem>
<para>Caption variable name.
This value is supplied to the lang_get() API; it is
therefore mandatory to set this to a
<ulink url="https://www.php.net/manual/en/language.variables.basics.php">valid PHP identifier</ulink>
(i.e. only letters, numbers and underscores; no spaces)
if you intend to translate the field label
(see <xref linkend="admin.customize.customfields.localize" />).
</para>
<note><para>If the specified variable is not found in the
language files or in
<filename>custom_strings_inc.php</filename>,
then it will be displayed as-is.
</para></note>
</listitem>
<listitem>
<para>Custom field type, can be one of:
</para>
<itemizedlist>
<listitem>
<para><literal>string</literal>,
for strings of up to 255 characters.
</para>
</listitem>
<listitem>
<para>
<literal>numeric</literal>,
for numerical integer values.
</para>
</listitem>
<listitem>
<para><literal>float</literal>,
for real (float / double) numbers.
</para>
</listitem>
<listitem>
<para>
<literal>email</literal>,
for storing email addresses.
</para>
</listitem>
<listitem>
<para>
<literal>enumeration</literal>
is used when a user selects one entry from a list.
The user interface for this type is a combo-box.
</para>
</listitem>
<listitem>
<para>
<literal>checkbox</literal>
is like enumeration, but the options are shown as checkboxes
and the user is allowed to tick more than one item.
</para>
<para>The default value and the possible value can contain multiple
values like <userinput>RED|YELLOW|BLUE</userinput>.
</para>
</listitem>
<listitem>
<para>
<literal>radio</literal>
is like enumeration, but the list is shown as radio buttons
and the user is only allowed to tick a single option.
</para>
<para>The possible values can be <userinput>RED|YELLOW|BLUE</userinput>,
and default <userinput>YELLOW</userinput>.
</para>
<note><para>The default value can't contain multiple values.</para></note>
</listitem>
<listitem>
<para>
<literal>list</literal>
is like enumeration but the list is shown as a list box
where the user is only allowed to select one option.
</para>
<para>The possible values can be <userinput>RED|YELLOW|BLUE</userinput>,
and default <userinput>YELLOW</userinput>.
</para>
<note><para>The default value can't contain multiple values.</para></note>
</listitem>
<listitem>
<para>
<literal>multi-selection list</literal>
is like enumeration, but the list is shown as a list box
where the user is allowed to select multiple options.
</para>
<para>The possible values can be <userinput>RED|YELLOW|BLUE</userinput>,
and default <userinput>RED|BLUE</userinput>.
</para>
<note><para>Multiple values are allowed as default.</para></note>
</listitem>
<listitem>
<para>
<literal>date</literal>,
for date values.
</para>
<para>The default value can be <emphasis>empty</emphasis>,
a numeric <emphasis>UNIX timestamp</emphasis>,
or a date in a
<ulink url="https://www.php.net/manual/en/datetime.formats.php">valid format</ulink>,
including relative indications such as
<userinput>tomorrow</userinput>,
<userinput>next week</userinput>,
<userinput>last month</userinput>,
<userinput>+3 days</userinput>,
<userinput>last day of this month</userinput>, etc.
</para>
<note>
<para>The legacy format where the dynamic date had to be
wrapped in curly brackets (e.g. <literal>{tomorrow}</literal>)
is still supported for backwards-compatibility,
but no longer necessary.
</para>
</note>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Possible values for the Custom Field
(e.g. <userinput>RED|YELLOW|BLUE</userinput>).
Use the pipe (<literal>|</literal>) character to separate
the enumeration's values.
It is possible for one of the values to be empty
(e.g. <userinput>|RED|YELLOW|BLUE</userinput>, note the
leading <literal>|</literal>).
</para>
<para>The set of values can also be calculated at runtime.
For example, <literal>=versions</literal> would
automatically resolve into all the versions defined
for the current project.
See <xref linkend="admin.customize.customfields.dynamic" />
for more information.
</para>
</listitem>
<listitem>
<para>Default value - see details above for a sample default value for each type.</para>
</listitem>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>Regular expression to use for validating user input (use
<ulink url="https://www.php.net/manual/en/reference.pcre.pattern.syntax.php">PCRE syntax</ulink>).
</para>
</listitem>
<listitem>
<para>Read Access level: Minimum access level for users to be
able to <emphasis>see</emphasis> the value of the custom field.
</para>
</listitem>
<listitem>
<para>Write Access level: Minimum access level for users to be
able to <emphasis>edit</emphasis> the value of the custom field.
</para>
</listitem>
<listitem>
<para>Display when reporting issues? - If this custom
field should be shown on the Report Issue page.
</para>
</listitem>
<listitem>
<para>Display when updating issues? - If this custom
field should be shown on the Update Issue page.
</para>
</listitem>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>Display when closing issues? - If this custom
field should be shown when closing an issue.
</para>
</listitem>
<listitem>
<para>Required on Report - If this custom
field is a mandatory field on the Report Issue page.
</para>
</listitem>
<listitem>
<para>Required on Update - If this custom
field is a mandatory field on the Update Issue page.
</para>
</listitem>
<listitem>
<para>Required on Resolve - If this custom
field is a mandatory field when resolving an issue.
</para>
</listitem>
<listitem>
<para>Required on Close - If this custom
field is a mandatory field when closing an issue.
</para>
</listitem>
</itemizedlist>
</para>
<para>
If the value of a custom field for a certain defect is not found,
the default value is assumed.
</para>
</section>
<section id="admin.customize.customfields.editing">
<title>Adding/Editing Custom Fields</title>
<para>
<itemizedlist>
<listitem>
<para>The logged in user needs $g_manage_custom_fields_threshold
access level.
</para>
</listitem>
<listitem>
<para>Select "Manage" from the main menu.</para>
</listitem>
<listitem>
<para>Select "Manage Custom Fields" from the management
menu.
</para>
</listitem>
<listitem>
<para>In case of edit, click on the name of an existing
custom field to edit its information.
</para>
</listitem>
<listitem>
<para>In case of adding a new one, enter the name of the
new custom field then click "New Custom Field".
</para>
</listitem>
</itemizedlist>
</para>
<note><para>Added custom fields will not show up in any of the issues
until the added custom field is linked to the appropriate
projects.</para></note>
</section>
<section id="admin.customize.customfields.linking">
<title>Linking/Unlinking/Ordering Existing Custom Fields in Projects</title>
<para>
<itemizedlist>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>Select "Manage" from the main menu.</para>
</listitem>
<listitem>
<para>Select "Manage Projects".
</para>
</listitem>
<listitem>
<para>Select the name of the project to manage.</para>
</listitem>
<listitem>
<para>Scroll down to the "Custom Fields" box.</para>
</listitem>
<listitem>
<para>Select the field to add from the list, then click "Add
This Existing Custom Field".
</para>
</listitem>
<listitem>
<para>To change the order of the custom fields, edit the
"Sequence" value and click update. Custom fields with smaller
values are displayed first.
</para>
</listitem>
<listitem>
<para>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.
</para>
</listitem>
</itemizedlist>
</para>
<formalpara>
<title>Moving Issues</title>
<para>
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.
</para>
</formalpara>
</section>
<section id="admin.customize.customfields.localize">
<title>Localizing Custom Field Names</title>
<para>It is possible to localize the custom fields' labels.
This can be done as follows:
<orderedlist>
<listitem>
<para>Define the custom field
(see <xref linkend="admin.customize.customfields.definitions" />),
keeping in mind that its name must be a
<ulink url="https://www.php.net/en/language.variables.basics.php">valid PHP identifier</ulink>.
</para>
<para>As an example, we will use
<emphasis>my_start_date</emphasis>
for a custom field of type "Date", storing the date when
work on an issue was initiated.
</para>
</listitem>
<listitem>
<para>Set the localization strings
<itemizedlist>
<listitem><para>In the MantisBT <filename>config</filename>
directory, locate and edit
<filename>custom_strings_inc.php</filename>
(see <xref linkend="admin.customize.strings"/>),
create it if it does not exist.
</para></listitem>
<listitem><para>Localize the custom field's label
<emphasis>my_start_date</emphasis> by adding
the following code
<programlisting>
<?php
switch( $g_active_language ) {
case 'french':
$s_my_start_date = 'Date de début';
break;
default:
# Default language, as defined in config/config_inc.php
# ($g_default_language, English in this case)
$s_my_start_date = 'Start Date';
break;
}
</programlisting>
</para></listitem>
</itemizedlist>
</para>
</listitem>
</orderedlist>
</para>
<note><para>Had we decided to use <emphasis>start_date</emphasis>
as the custom field's name, then it would not have been necessary
to modify <filename>custom_strings_inc.php</filename>
(see <xref linkend="admin.customize.strings"/>),
since MantisBT would have used the
existing, already localized string from the standard language files.
To check for standard strings, inspect
<filename>lang/strings_english.txt</filename>.
</para></note>
</section>
<section id="admin.customize.customfields.defaults">
<title>Dynamic default values</title>
<section id="admin.customize.customfields.defaults.date">
<title>Dynamic defaults for Date fields</title>
<para>Custom fields of type date can be defaulted to
either specific or relative dates.
Typically, relative dates is the scenario that makes
sense in most of the cases.
</para>
<para>The format for specific dates is an integer which
indicates the number of seconds since the
<ulink url="https://en.wikipedia.org/wiki/Unix_time">
Unix Epoch</ulink> (January 1 1970 00:00:00 UTC),
which is the format consumed by the PHP
<ulink url="https://www.php.net/date">date()</ulink> method.
</para>
<para>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="https://www.php.net/strtotime">strtotime()</ulink>
function.
</para>
</section>
</section>
<section id="admin.customize.customfields.dynamic">
<title>Dynamic values for Enumeration Custom Fields</title>
<para>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.
</para>
<section id="admin.customize.customfields.dynamic.default">
<title>Dynamic possible values included by default</title>
<para>MantisBT ships with some dynamic possible values, these
include the following:
</para>
<itemizedlist>
<listitem>
<para>
<literal>=categories</literal>
a list of categories defined in the current project
(or the project to which the issue belongs).
</para>
</listitem>
<listitem>
<para>
<literal>=versions</literal>
a list of all versions defined in the current project
(or the project to which the issue belongs).
</para>
</listitem>
<listitem>
<para>
<literal>=future_versions</literal>
a list of all versions that belong to the current project
with <emphasis>released</emphasis> flag set to false.
</para>
</listitem>
<listitem>
<para>
<literal>=released_versions</literal>
a list of all versions that belong to the current project
with <emphasis>released</emphasis> flag set to true.
</para>
</listitem>
</itemizedlist>
<note>
<para>The <literal>=</literal> before the list of options
tells MantisBT that this is a dynamic list,
rather than a static one with a single option.
</para>
</note>
</section>
<section id="admin.customize.customfields.dynamic.custom">
<title>Defining Custom Dynamic Possible Values</title>
<para>If the user selects <literal>=versions</literal>, the actual
custom function that is executed is
<emphasis>custom_function_*_enum_versions()</emphasis>.
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.
</para>
<para>For example, you would not want the user to use
<emphasis>custom_function_*_issue_delete_notify()</emphasis>
which may be overridden by the web master to delete associated data
in other databases.
</para>
<para>Following is a sample custom function that is used to
populate a field with the categories belonging to the currently
selected project:
</para>
<programlisting>
/**
* Construct an enumeration for all categories for the current project.
*
* The enumeration will be empty if current project is ALL PROJECTS.
* 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_enum = array();
foreach( $t_categories as $t_category ) {
$t_enum[] = $t_category['category'];
}
$t_possible_values = implode( '|', $t_enum );
return $t_possible_values;
}
</programlisting>
<note>
<itemizedlist>
<listitem>
<para>The custom function doesn't take any parameters.
</para>
</listitem>
<listitem>
<para>The custom function returns the possible values in the
format (A|B|C).
</para>
</listitem>
<listitem>
<para>The custom function uses the current project.
</para>
</listitem>
<listitem>
<para>The custom function builds on top of the already
existing APIs.
</para>
</listitem>
</itemizedlist>
</note>
<para>To define your own function <literal>mine</literal>,
you will have to define it with the following signature:
</para>
<programlisting>
/**
* Use this in a custom field type "=mine" in the possible values field.
*/
function custom_function_override_enum_mine() {
# Populate $t_enum values as appropriate here
$t_enum = array();
$t_possible_values = implode( '|', $t_enum );
return $t_possible_values;
}
</programlisting>
<note>
<para>Notice the <emphasis>override</emphasis> in the function name.
This is because this method is defined by the MantisBT administrator
and not part of the MantisBT source.
It is OK to override a method that doesn't exist.
</para>
</note>
<para>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
<xref linkend="admin.customize.customfuncs" />.
</para>
</section>
</section>
</section>
<section id="admin.customize.enums">
<title>Enumerations</title>
<para>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.
</para>
<formalpara>
<title>How do enumerations work?</title>
<para>
<filename>core/constant_inc.php</filename> defines the
constants that correspond to those in the enumeration. These are
useful to refer to these enumerations in the configs and the code.
<programlisting>
define( 'VIEWER', 10 );
define( 'REPORTER', 25 );
define( 'UPDATER', 40 );
define( 'DEVELOPER', 55 );
define( 'MANAGER', 70 );
define( 'ADMINISTRATOR', 90 );
</programlisting>
</para>
</formalpara>
<para>
<filename>config_defaults_inc.php</filename> 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.
<programlisting>
$g_access_levels_enum_string =
'10:viewer,25:reporter,40:updater,55:developer,70:manager,90:administrator';
</programlisting>
<note><para>The strings included in the enumerations here are just for
documentation purposes, they are not actually shown to the user
(due to the need for localisation). Hence, if an entry in this
enumeration is not found in the corresponding localised string
(i.e. 70:manager), then it will be printed to the user as @70@.
</para></note>
</para>
<para>
The Language Files (e.g. <filename>lang/strings_german.txt</filename>)
provide the localised strings (German in this case) for enumerations.
But again, the <emphasis>master list</emphasis> 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.
<programlisting>
$s_access_levels_enum_string =
'10:Betrachter,25:Reporter,40:Updater,55:Entwickler,70:Manager,90:Administrator';
</programlisting>
</para>
<formalpara>
<title>How can they be customised?</title>
<para>Let say we want to remove access level
"Updater" and add access level "Senior
Developer".
</para>
</formalpara>
<para>
The file <filename>config/custom_constants_inc.php</filename> 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.
<programlisting>
define( 'SENIOR_DEVELOPER', 60 );
</programlisting>
</para>
<para>
In <filename>config/config_inc.php</filename>
<programlisting>
// Remove Updater and add Senior Developer
$g_access_levels_enum_string =
'10:viewer,25:reporter,55:developer,60:senior_developer,70:manager,90:administrator';
// Give access to Senior developers to create/delete custom field.
$g_manage_custom_fields_threshold = SENIOR_DEVELOPER;
</programlisting>
</para>
<para>
Update <filename>custom_strings_inc.php</filename>
(see <xref linkend="admin.customize.strings"/>)
<programlisting>
$s_access_levels_enum_string =
'10:Betrachter,25:Reporter,40:Updater,55:Entwickler,60:Senior Developer,70:Manager,90:Administrator';
</programlisting>
<note><para>We don't need to remove the <emphasis>Updater</emphasis>
entry from the localisation file if the current language
is 'English'.
</para></note>
</para>
<formalpara>
<title>Conclusion</title>
<para>We have covered how enumerations work in general, and how
to customise one of them. If you are interested in customising
other enumerations, a good starting point would be to go to
<emphasis>MantisBT Enum Strings</emphasis> section in
<filename>config_defaults_inc.php</filename>. This section
defines all enumerations that are used by MantisBT.
</para>
</formalpara>
</section>
<section id="admin.customize.email">
<title>Email Notifications</title>
<para>See <xref linkend="admin.config.email" />
in the Configuration section.
</para>
<para>Examples:
<itemizedlist>
<listitem>
<para>Notify only managers of new issues.
<programlisting>
$g_notify_flags['new'] = array(
'threshold_min' => MANAGER,
'threshold_max' => MANAGER,
);
</programlisting>
</para>
</listitem>
<listitem>
<para>Notify Developers and managers of all project events,
except, exclude developers from the 'closed' events.
<programlisting>
$g_default_notify_flags = array(
'threshold_min' => DEVELOPER,
'threshold_max' => MANAGER,
);
$g_notify_flags['closed'] = array(
'threshold_min' => MANAGER,
'threshold_max' => MANAGER,
);
</programlisting>
</para>
</listitem>
<listitem>
<para>Exclude those who contributed issue notes from getting
messages about other changes in the issue.
<programlisting>
$g_default_notify_flags['bugnotes'] = OFF;
</programlisting>
</para>
</listitem>
<listitem>
<para>Exclude those monitoring issues from seeing the 'closed'
message
<programlisting>
$g_notify_flags['closed']['monitor'] = OFF;
</programlisting>
</para>
</listitem>
<listitem>
<para>Only notify developers when issue notes are added.
<programlisting>
$g_notify_flags['bugnote'] = array(
'threshold_min' => DEVELOPER,
'threshold_max' => DEVELOPER,
);
</programlisting>
</para>
</listitem>
<listitem>
<para>Notify managers of changes in sponsorship.
<programlisting>
$g_notify_flags['sponsor'] = array(
'threshold_min' => MANAGER,
'threshold_max' => MANAGER,
);
</programlisting>
</para>
</listitem>
<listitem>
<para>Notify originator and managers of changes in ownership
("Assigned To:").
<programlisting>
$g_notify_flags['owner'] = array(
'threshold_min' => MANAGER,
'threshold_max' => MANAGER,
'reporter' => ON,
);
</programlisting>
</para>
</listitem>
<listitem>
<para>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.
<programlisting>
$g_email_receive_own = OFF;
$g_default_notify_flags = array(
'reporter' => ON,
'handler' => ON,
'monitor' => ON,
'bugnotes' => ON,
'category' => ON,
'threshold_min' => NOBODY,
'threshold_max' => NOBODY
);
$g_notify_flags['new'] = array(
'threshold_min' => MANAGER,
'threshold_max' => MANAGER,
);
</programlisting>
</para>
</listitem>
<listitem>
<para>How do I send all messages to an email logger.
</para>
<para>You will need to create a dummy user with the
appropriate access level for the notices you want to log.
Once this user is added to projects, they will receive
mail using the appropriate rules.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="admin.customize.status">
<title>Customizing Status Values</title>
<para>This section describes how to add a custom status.
<orderedlist>
<listitem>
<para>Define a constant to map the new status to.</para>
<para>In subfolder config, locate and edit file
<emphasis>custom_constants_inc.php</emphasis>;
(create it if it does not exist)
<programlisting>
<?php
# Custom status code
define( 'TESTING', 60 );
</programlisting>
</para>
</listitem>
<listitem>
<para>Define the new status in the enumeration, as well as
the corresponding color code.
</para>
<para>In subfolder config, edit your
<emphasis>config_inc.php</emphasis>
<programlisting>
# Revised enum string with new 'testing' status
$g_status_enum_string = '10:new,20:feedback,30:acknowledged,40:confirmed,50:assigned,<emphasis>60:testing,</emphasis>80:resolved,90:closed';
# Status color additions
$g_status_colors['<emphasis>testing</emphasis>'] = '#ACE7AE';
</programlisting>
Note that the key in the $g_status_colors array must be
equal to the value defined for the new status code in
$g_status_enum_string.
</para>
</listitem>
<listitem>
<para>Define the required translation strings for
the new status, for each language used in
the installation.
<itemizedlist>
<listitem><para><emphasis>s_status_enum_string</emphasis>:
status codes translation (refer to the original
language strings for standard values)
</para></listitem>
<listitem><para><emphasis>s_XXXX_bug_title</emphasis>:
title displayed in the change status page
</para></listitem>
<listitem><para><emphasis>s_XXXX_bug_button</emphasis>:
label for the submit button in the change status page
</para></listitem>
<listitem><para><emphasis>s_email_notification_title_for_status_bug_XXXX</emphasis>:
title for notification e-mails
</para></listitem>
</itemizedlist>
where XXXX is the name of the new status as it was defined
in <emphasis>g_status_enum_string</emphasis> above. If
XXXX contains spaces, they should be replaced by
underscores in the language strings names (e.g.
for '35:pending user', use '$s_pending_user_bug_button')
</para>
<para>In the <filename>config</filename> subfolder, locate and edit
<filename>custom_strings_inc.php</filename>
(see <xref linkend="admin.customize.strings"/>),
create it if it does not exist
<programlisting>
<?php
# Translation for Custom Status Code: <emphasis>testing</emphasis>
switch( $g_active_language ) {