AJAX Combo Edit Control Requirements

Author: Victor Boctor

Introduction

It is common in Mantis to have a form where the user must enter a valid user name, category, platform, OS, etc. The aim of this task is to implement an AJAX control and wrapping PHP code which allows the use of this control to replace edit boxes and combo boxes in the scenarios that are mentioned later in the document.

Use Case 1: Reporter Name

In the case of “reporter name”, the user has to select a name from the list of defined users. The normal way to do this is to use a combobox and pre-populate it with all reporter names in the system. This can blow out the size of the page, hence time to send it over the wire and prepare it. In the mean time, the combobox doesn't provide a very easy way to navigate from such a big list of options.

It should be possible to use the AJAX control to do this. The AJAX control will consistent of three UI components: a textbox, a drop down button and a listbox (or a div) that pops up when the user is selecting from a list of options. For each option, there will be a label and a value as per the normal combo box.

If the user writes in the text box, then auto-complete functionality will be activated. The user can continue writing or select a suggested entry. It should be configurable whether the user can write an entry which is not in the list or not. In the case where the user types a label that is not in the list and that is not allowed, then the color of the text box should change to reflect the error state.

The other option is for the user to click on the drop down button, in this case the user will get ALL entries independent of the contents of the text box. This will be very useful in the case where the control is pre-populated by a user name and the user wants to select a different entry (rather than using the current content as a prefix).

Use Case 2: Platform

In this case the list of possible values should be pretty small. The user can elect to select from the list using the drop down button or use the auto-complete feature. However, the unique part here is that the user can write an entry that doesn't exist in the list. Hence, the control will support this mode as well. In this case, the value of the user's selection will be the same as the label that the user typed.

Migration to the Control

It should be very easy to migrate a current text box or combobox to this AJAX control. The AJAX control should have a corresponding function that returns back the list of options, providing for each option a label and a value. Such functions will take a context and a prefix as a parameter.

Design Constraints

   /***
    * This function inserts the necessary HTML and Javascript within the HTML form.
    *
    * @param $p_name     The name of the control on the form.
    * @param $p_results_function The name of the function to be used to retrieve the results.
    * @param $p_error_div  A div to insert the error message in, if the current value of the control is invalid.  If empty, then this feature is disabled.
    * @param $p_context  The context string that will be sent to the function.  In addition to the prefix.
    * @param $p_allow_new_entries true to allow the user to enter values not in the list without indicating errors, false otherwise.
    *
    * @returns string to be echoed.
    */
   function comboedit_insert( $p_name, $p_results_function, $p_error_div, $p_context, $p_allow_new_entries );
   /**
    * A function that returns the list of reporter names based on a context and a prefix.  This will
    *
    * @param $p_context - The context to be used by the function.  For example, the project id.
    * @param $p_prefix - The prefix typed by the user. For example, "vb" which will match "vboctor".
    *
    * @returns An array of entries where the array key is the form value and the array value is the label.
    *          Returns an empty array if case of no matches.
    *          Returns a localized string in case of an error that should be displayed to the user (will only be visible if div was supplied)
    */
   function xmlhttprequest_reporter_comboedit_results( $p_context, $p_prefix );

Usage in Mantis

Feedback

Please provide feedback in this section.