Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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:

<code php>
# --------------------
# 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;
}
</code>

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:

<code php>
# --------------------
# 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;
}
</code>

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.