More custom field revisions

[Sean McAfee]

First, a quick note to let everyone know where I'm coming from:

Our current incident-tracking system is administered by someone in
Human Resources--ie, a non-programmer.  Ideally I'd like for Bugzilla
administration to be turned over to the same person after our migration.
Therefore, one of my aims (which I haven't stated directly before now)
has been to make custom field administration as simple as possible.
Some groups within my company have expressed an interest in having me
do more advanced work, like auto-populating certain form elements based
on a query against a local database, but IMHO, everyday administrative
tasks--like renaming or rearranging fields--shouldn't require a grounding
in the Template Toolkit to achieve.

Gervase Markham <gerv at mozilla.org> wrote:
>> Each custom field has a name, consisting of up to 255 characters.  A
>> field's name may not contain any vertical whitespace characters
>> (carriage return, newline, and vertical tab), nor may it begin or end
>> with whitespace. 

>There are two things we need - a name to refer to it internally, and a 
>display name. The display name should be solely the preserve of 
>templates (with the internal name used if none is defined) and the 
>internal name should be suitable for use as a form field name and 
>database table/column name. This means that, for max compatibility, it 
>should be alphanumeric only, with no whitespace.

My design doesn't call for any database entities (tables or columns)
to share names with fields, so that reason's moot.  I hadn't given any
thought yet to how custom field form elements should be named, but surely
it's straightforward to name them with either the corresponding field's
name or its numeric ID, right?

I discuss the template issue a bit later in this message.

>> Each field also has a type: one of Integer, String,
>> Date, or Selection.  The Integer, String, and Date types are
>> collectively referred to as "scalar" types.

>I still think we should have single-select (a scalar type) and 
>multi-select. This prevents the need for "sub-types" for the Selection type.
>
><later>Well, I suppose other types have sub-types too...</later>

It can be argued either way.  I had them unified because they're
administered similarly, and are represented similarly in the database.

>Did we decide to leave Email Address until version 2?

It was only mentioned once, briefly, that I recall.  Would this be a
string-like field that is checked for RFC822 validity when submitted,
or one which offers a choice of all known users?

>> If the users enters no text at all (including whitespace) into a
>> String form element, the field will be set to the undefined value.

>Is this right? Surely the empty string is a better representation in 
>this case?

I wasn't making a statement on representations; I meant that the field would
be conceptually undefined, from the user's POV.

>> A Date field describes a particular moment of time.  It is represented
>> on Bugzilla's web interface as a single-line text form element.

>I don't think you should specify this explicitly. It should be possible 
>to have a variety of representations for Date fields - i.e. you do
>[% INCLUDE date_field date = "10035356674" type="date-time" %]
>or similar and the template defines the representation.

Sure, template-twiddling should be possible, but I think I've described a
reasonable default.

>> Each Date field is flagged as belonging to one of two varieties:
>> date-only and date/time.  A date-only Date field is represented using
>> the format 'YYYY-MM-DD'; a date/time Date field is represented using
>> the format 'YYYY-MM-DD HH24:MM:SS'.  (Arbitrary whitespace may
>> separate the two components in the latter case.)  When a user enters
>> text into a Date form element, it must conform to the appropriate
>> format, or Bugzilla will signal an error condition.

>I think that dates should always be displayed as above, but dates should 
>be able to be input in any format which can be unambiguously understood 
>by Date::Parse. Let's not enforce restrictions we don't need.

That's reasonable.

>> A multiselection field's value is an arbitrary subset of the field's
>> value set.  It is represented on Bugzilla's web interface as a
>> multiline listbox in which multiple simultaneous selections are
>> allowed.  The listbox's vertical size is equal to the value set's size
>> or five, whichever is smaller.

>The current ones on query.cgi are 7, which seems like a nice size to me. 
>  And they are all the same size even if some have less than seven 
>elements, which looks better. But this is a minor display issue.

7 is fine with me.

>> Whenever a user edits a bug and changes one or more custom fields, the
>> changes must be logged. 
><snip>

>Are all these requirements met by the existing Bug Activity system?

I hadn't considered the existing system, since I've been attempting to keep
the custom field implementation as orthogonal as possible to the core.  Are
you suggesting that the existing activity system could be leveraged to hold
custom field activity data?

>> On "enter_bug.cgi" and "long_list.cgi", the custom fields will be
>> shown just after the "Description" text box.

>It's not an automatic given that the custom field will be needed on 
>enter_bug. In fact, an argument could be made for not including any of 
>them by default.

This seems a bit counterintuitive to me.  What is the argument for not
including any of them?

>> Here is an alternate approach.  Global custom fields are always
>> displayed.  A button is to be added to the query page, to the right of
>> the "Product", "Component", and "Version" listboxes, labelled "Show
>> custom fields for these projects".  If the user clicks it, the query
>> form is redisplayed, augmented with all custom fields in all of the
>> selected projects.  

>_Any_ of the selected projects?

Er, no.  All of them.

>> If no projects were selected, or if no selected
>> project has any custom fields, the page is simply redisplayed as it
>> was before.

>The button should never appear if there are no product-specific custom 
>fields. Helper JS should disable the button if the selected products 
>have no custom fields.

OK, makes sense.

>Remember to display all possible custom fields if 
>no products are selected. :-)

Why?

>The appearing/disappearing should be done using JS and CSS without a 
>page reload if the browser supports JS, by having an onsubmit="doIt(); 
>return false" on the button.

>> When custom fields are being shown, a second button is to be added
>> below the "Show custom fields" button, labelled "Hide custom fields".
>> When it is clicked, the query page is redisplayed as it was
>> originally, showing only custom fields in the global scope (if any).

>Why is this needed? They can always just ignore them.

Because there may be a lot of fields, and they may be distracting.

>> It is an error for the user to select one or more target projects,
>> show the custom fields for those components, change the target
>> projects, and begin a search.  In this case Bugzilla will redisplay
>> the query page with an appropriate error message at the top.

>It should not be an error unless the user has set search values for 
>custom fields which apply to none of the products concerned - and even 
>then, the message is more informational than error.

OK.

>> Different projects may define different custom fields with the same
>> name.
>
>No; this is an error. That's fine, because the display name is separated 
>from the internal name. They could define the same display name for two 
>fields, but any confusion caused is their fault :-)
>
>Hmm... there's a bit of info missing in my mind. Is it possible to have 
>a custom field which is part of projects A, B and C but not D or E?

Definitely not, at least according to my proposal.  We seem to have stumbled
onto a fundamental difference in our two conceptions of how custom fields
should work.  In my view, each product *contains* zero or more custom
fields, which are not shared with any other product.  There's no concept
of "hard linking" between products.  It may be that two different products
both want a date field called (say) "Date Received", and they can have them,
just as two distinct fields.

>> Administration
>> ==============
>> 
>> A new CGI program for managing custom fields, cdadmin.cgi, will be
>> created.  The program is only accessible to the Bugzilla
>> administrator.

>editcustomfields.cgi would be a name fitting with the rest of our admin 
>CGIs.

OK.

>A critique of the editing UI will follow.
>
>> Editing a custom field
>> ----------------------
>> The only aspect of a string, integer, and date field that may be
>> edited (other than its name, handled by a separate Rename operation)
>> is its default value.

>And which products it belongs to?

Again, my custom field concept calls for a field to belong to exactly one
parent product.  Since creating scalar fields is so trivial, it's not
necessary to provide an interface to copy or move them between products.

>> For a new String field, the first page presented includes only a pair
>> of radiobuttons, labelled "Long string (multiline, up to 64K
>> characters)" 

>Remind me again why we need this long string type?

First, to provide two different form elements, single-line and multiline.
Second, because I can easily imagine needing to enter a detailed report of
some kind that could run over 255 characters.  I occasionally do so with my
company's current issue-tracking system.

>> Moving a field to a different position
>> --------------------------------------
>> This action is performed immediately.  The field ordering for the
>> selected project (or for the global scope) is rearranged so that the
>> fields appear in the new order specified by the administrator.  The
>> initial cfadmin.cgi page is redisplayed, showing the fields in their
>> new order.

>What does this ordering affect? If it's display ordering, this is the 
>wrong place for it - such configuration belongs in templates.

Templates are static; field ordering is dynamic.  I can't think of any
way of putting field ordering into a template that isn't clearly the
Wrong Thing.  I'm still a newbie with the Template Toolkit, but this is the
only way I can think of to do this:

[% IF product == 'Product Foo';
      ordering = [ 'Foo Field One', 'Foo Field Two', 'Foo Field Three' ];
   ELSIF product == 'Product Bar';
      ordering = [ 'Bar Field One', 'Bar Field Two' ];
   ELSIF ...;
      ...;
   #  previous two lines repeated N times
   END
%]

[% FOREACH field = ordering %]
( generate HTML for field )
[% END %]

Not only does this require the administrator to regularly edit templates--
which, as I said, I'm trying to avoid--but it unnecessarily duplicates
information from the database and creates the potential for typos.

>> custom_fields
>> -------------
>> project tinytext primary key,
>> field_id integer not null,
>> field_index integer not null

>You should be using product_ids here, not "project" strings.

Yeah, I changed that in the latest revision.  I was unconsciously using our
existing system's lingo ("project" instead of "product").

>> custom_field_defs
>> -----------------

>> The field_type column is 'I' for integer fields, 'C' for string
>> fields, 'D' for date fields, and 'S' for selection fields.
>> 
>> Field type | extended is "true"  | extended is "false"
>> -----------+---------------------+------------------------
>> String     | long string (text)  | short string (tinytext)
>> Date       | date/time           | date only
>> Selection  | multiselection      | single-selection

>This looks like a hack to me. Even if you expose it in the UI as types 
>and subtypes, it seems that in the database, it makes sense to have a 
>single field_type field with seven values.

Yeah, maybe so.  A MySQL enum would be good here, but I seem to recall
reading somewhere that developers are supposed to avoid MySQL-specific
features to make it easier to port Bugzilla to other databases in the
future.  Is this right?

>> cf_selection_defs
>> -----------------
>> selection_id integer primary key,
>> unset tinytext not null
>> 
>> The unset column is the text which represents the "empty set" value of
>> single-selection fields.

>Again, this should be decided in UI templates.

The idea of putting dynamic data in a static template is one which leaves me
scratching my head in puzzlement.  I honestly can't figure out why this is a
good thing.


-- 
Sean McAfee -- etzwane at schwag.org