User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:dynamic_enum_custom_fields

Enumeration Custom Fields with Dynamic Possible Values

Introduction

Starting with Mantis 1.1.0rc1, it is possible to define enumeration custom fields that have a dynamic set of possible values. The possible values are constructed via a custom function. The implementation of the custom function can depend on the context (current project, current user, current user's access level).

Usually when an enumeration custom field is defined, the possible values are defined as “A|B|C” (without the quotes). For dynamic possible values, an identifier is specified that specifies to Mantis which custom function to use. The ones that are already defined are “=categories”, “=versions”, “=future_versions”, “=released_versions” (again without the quotes).

How to do it?

If the user selects “=versions”, the actual method that is used 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:

# --------------------
# custom_function_api.php
# 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 name "=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;
}

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 for custom field (name = “mine”), you will have to define it with the following signature:

# --------------------
# To use this in a custom field name = "mine" in the possible values field.
function custom_function_override_enum_mine() {
    $t_enum = array();
 
    :
 
    $t_possible_values = implode( '|', $t_enum );
 
    return $t_possible_values;
}

Notice “override” in the function name. This is because this method is defined by the Mantis adminstrator/webmaster and not part of the Mantis source. It is OK to override a method that doesn't exist.

As usual, when you upgrade Mantis to future releases, your custom functions will not be overwritten. The difference between the “default” implementation and the “override” implementation is explained in more details in the manual.

mantisbt/dynamic_enum_custom_fields.txt · Last modified: 2009/04/21 03:36 by ckchan