Adding new relationship types

[kratib]

This is a record of how I added new relationship types to Mantis 1.0.1. Specifically, we needed a new pair "is origin of"/"originates from" to enable the traceability of requirements/test cases/etc that we store in Mantis.

Reverse engineering was easy, even for a Mantis n00b like me:
* grep -r "has duplicate" yields lang/strings_english.txt with variable $s_has_duplicate
* grep -r "$s_has_duplicate" yields nothing but the same file, which does not make sense
* grep -r "has_duplicate" yields core/relationship_api.php, with a function lang_get() that appends the 's_' and chooses the right language
* Examining relationship_api.php reveals the usage of constants BUG_XXX to define relationship types
* grep -r 'BUG_DUPLICATE' yields core/constant_inc.php

That's it for reverse engineering! Now for the new code:
* Define new constants for relationship types BUG_IS_ORIGIN_OF and BUG_ORIGINATES_FROM in core/constant_inc.php
* Define new strings corresponding to these constants in lang/strings_*.txt:

Code: Select all

$s_is_origin_of = 'is origin of';
$s_originates_from = 'originates from';

* Edit core/relationship_api.php to process and display new types:

function relationship_get_complementary_type() enables relationship reflexivity, so add two cases:

Code: Select all

                        case BUG_IS_ORIGIN_FOR:
                                return BUG_ORIGINATES_FROM;
                                break;
                        case BUG_ORIGINATES_FROM:
                                return BUG_IS_ORIGIN_FOR;
                                break;

function relationship_get_description_src_side() associates a relationship type ID with its string:

Code: Select all

                        case BUG_IS_ORIGIN_FOR:
                                return lang_get('is_origin_for');
                                break;
                        case BUG_ORIGINATES_FROM:
                                return lang_get('originates_from');
                                break;

relationship_get_description_dest_side() does the opposite it seems:

Code: Select all

                        case BUG_IS_ORIGIN_FOR:
                                return lang_get('originates_from');
                                break;
                        case BUG_ORIGINATES_FROM:
                                return lang_get('is_origin_for');
                                break;

relationship_get_description_for_history() also needs editing, I made it like relationship_get_description_src_side().

relationship_list_box() displays the relationship types on the bug editing page:

Code: Select all

<option value="<?php echo BUG_IS_ORIGIN_FOR ?>"<?php echo ( $p_default_rel_type == BUG_IS_ORIGIN_FOR ? ' selected' : '' ) ?>><?php echo lang_get( 'is_origin_for' ) ?></option>
<option value="<?php echo BUG_ORIGINATES_FROM ?>"<?php echo ( $p_default_rel_type == BUG_ORIGINATES_FROM ? ' selected' : '' ) ?>><?php echo lang_get( 'originates_from' ) ?></option>

That's it!
Hope somebody finds this useful.
K.

[kratib]

Being a Mantis n00b, I made some mistakes. Here are the ones I caught:

1. Custom strings should go into ./custom_strings_inc.php
2. Custom constants should go into ./custom_constant_inc.php
3. core/email_api.php should be modified to send notifications upon addition and deletion of the two new relationships, in the functions:
email_relationship_added(), email_relationship_deleted

I am currently preparing a more generic way to handle relationships, I hope to send the patch soon.

Cheers,
K.

[kratib]

I just submitted a patch for custom relationships. You can find it at http://www.mantisbugtracker.com/bugs/view.php?id=8130. Your feedback is appreciated.