Bug 728138: Custom fields should have a "Long Description" attribute to better understand what they are used for

r/a=LpSolit

Bugzilla/Constants.pm

@@ -156,6 +156,7 @@ use Memoize;
     MAX_MILESTONE_SIZE
     MAX_COMPONENT_SIZE
     MAX_FIELD_VALUE_SIZE
+    MAX_FIELD_LONG_DESC_LENGTH
     MAX_FREETEXT_LENGTH
     MAX_BUG_URL_LENGTH
     MAX_POSSIBLE_DUPLICATES
@@ -537,6 +538,9 @@ use constant MAX_COMPONENT_SIZE => 64;
 # The maximum length for values of <select> fields.
 use constant MAX_FIELD_VALUE_SIZE => 64;
 
+# The maximum length for the long description of fields.
+use constant MAX_FIELD_LONG_DESC_LENGTH => 255;
+
 # Maximum length allowed for free text fields.
 use constant MAX_FREETEXT_LENGTH => 255;
 

Bugzilla/DB/Schema.pm

@@ -670,6 +670,7 @@ use constant ABSTRACT_SCHEMA => {
             custom      => {TYPE => 'BOOLEAN', NOTNULL => 1,
                             DEFAULT => 'FALSE'},
             description => {TYPE => 'TINYTEXT', NOTNULL => 1},
+            long_desc   => {TYPE => 'varchar(255)', NOTNULL => 1, DEFAULT => "''"},
             mailhead    => {TYPE => 'BOOLEAN', NOTNULL => 1,
                             DEFAULT => 'FALSE'},
             sortkey     => {TYPE => 'INT2', NOTNULL => 1},

Bugzilla/Field.pm

@@ -80,6 +80,7 @@ use constant DB_COLUMNS => qw(
     id
     name
     description
+    long_desc
     type
     custom
     mailhead
@@ -97,6 +98,7 @@ use constant DB_COLUMNS => qw(
 use constant VALIDATORS => {
     custom       => \&_check_custom,
     description  => \&_check_description,
+    long_desc    => \&_check_long_desc,
     enter_bug    => \&_check_enter_bug,
     buglist      => \&Bugzilla::Object::check_boolean,
     mailhead     => \&_check_mailhead,
@@ -123,6 +125,7 @@ use constant VALIDATOR_DEPENDENCIES => {
 
 use constant UPDATE_COLUMNS => qw(
     description
+    long_desc
     mailhead
     sortkey
     obsolete
@@ -279,6 +282,15 @@ sub _check_description {
     return $desc;
 }
 
+sub _check_long_desc {
+    my ($invocant, $long_desc) = @_;
+    $long_desc = clean_text($long_desc || '');
+    if (length($long_desc) > MAX_FIELD_LONG_DESC_LENGTH) {
+        ThrowUserError('field_long_desc_too_long');
+    }
+    return $long_desc;
+}
+
 sub _check_enter_bug { return $_[1] ? 1 : 0; }
 
 sub _check_is_numeric {
@@ -441,6 +453,17 @@ sub description { return $_[0]->{description} }
 
 =over
 
+=item C<long_desc>
+
+A string providing detailed info about the field;
+
+=back
+=cut
+
+sub long_desc { return $_[0]->{long_desc} }
+
+=over
+
 =item C<type>
 
 an integer specifying the kind of field this is; values correspond to
@@ -824,6 +847,8 @@ They will throw an error if you try to set the values to something invalid.
 
 =item C<set_description>
 
+=item C<set_long_desc>
+
 =item C<set_enter_bug>
 
 =item C<set_obsolete>
@@ -850,6 +875,7 @@ They will throw an error if you try to set the values to something invalid.
 =cut
 
 sub set_description    { $_[0]->set('description', $_[1]); }
+sub set_long_desc      { $_[0]->set('long_desc',   $_[1]); }
 sub set_enter_bug      { $_[0]->set('enter_bug',   $_[1]); }
 sub set_is_numeric     { $_[0]->set('is_numeric',  $_[1]); }
 sub set_obsolete       { $_[0]->set('obsolete',    $_[1]); }
@@ -972,6 +998,8 @@ Just like L<Bugzilla::Object/create>. Takes the following parameters:
 
 =item C<description> B<Required> - The field label to display in the UI.
 
+=item C<long_desc> - A longer description of the field.
+
 =item C<mailhead> - boolean - Whether this field appears at the
 top of the bugmail for a newly-filed bug. Defaults to 0.
 

Bugzilla/Install/DB.pm

@@ -114,7 +114,11 @@ sub update_fielddefs_definition {
         {TYPE => 'BOOLEAN', NOTNULL => 1, DEFAULT => 'FALSE'});
     $dbh->do('UPDATE fielddefs SET is_numeric = 1 WHERE type = '
              . FIELD_TYPE_BUG_ID);
-             
+
+    # 2012-04-12 aliustek@gmail.com - Bug 728138
+    $dbh->bz_add_column('fielddefs', 'long_desc',
+                        {TYPE => 'varchar(255)', NOTNULL => 1, DEFAULT => "''"}, '');
+
     Bugzilla::Hook::process('install_update_db_fielddefs');
 
     # Remember, this is not the function for adding general table changes.

editfields.cgi

@@ -49,6 +49,7 @@ elsif ($action eq 'new') {
     $vars->{'field'} = Bugzilla::Field->create({
         name        => scalar $cgi->param('name'),
         description => scalar $cgi->param('desc'),
+        long_desc   => scalar $cgi->param('long_desc'),
         type        => scalar $cgi->param('type'),
         sortkey     => scalar $cgi->param('sortkey'),
         mailhead    => scalar $cgi->param('new_bugmail'),
@@ -99,6 +100,7 @@ elsif ($action eq 'update') {
     $field || ThrowUserError('customfield_nonexistent', {'name' => $name});
 
     $field->set_description($cgi->param('desc'));
+    $field->set_long_desc($cgi->param('long_desc'));
     $field->set_sortkey($cgi->param('sortkey'));
     $field->set_in_new_bugmail($cgi->param('new_bugmail'));
     $field->set_enter_bug($cgi->param('enter_bug'));

template/en/default/admin/custom_fields/create.html.tmpl

@@ -96,18 +96,16 @@ YAHOO.util.Event.onDOMReady(function() {onChangeType(document.getElementById('ty
     </tr>
 
     <tr>
-      <th class="narrow_label">
-        <label for="reverse_desc">Reverse Relationship Description:</label>
-      </th>
+      <th class="narrow_label">Long Description:</th>
       <td>
-        <input type="text" id="reverse_desc" name="reverse_desc" value="" size="40" disabled="disabled">
-        <br/>
-        Use this label for the list of [% terms.bugs %] that link to
-        [%+ terms.abug %] with this 
-        [%+ field_types.${constants.FIELD_TYPE_BUG_ID} FILTER html %]
-        field. For example, if the description is "Is a duplicate of",
-        the reverse description would be "Duplicates of this [% terms.bug %]".
-        Leave blank to disable the list for this field.
+         [% INCLUDE global/textarea.html.tmpl
+          name           = 'long_desc'
+          id             = 'long_desc'
+          minrows        = 3
+          maxrows        = 5
+          cols           = 46
+          defaultcontent = defaultcontent
+        %]
       </td>
       <th>
         <label for="visibility_field_id">Field only appears when:</label>
@@ -134,7 +132,19 @@ YAHOO.util.Event.onDOMReady(function() {onChangeType(document.getElementById('ty
     </tr>
 
     <tr>
-      <td colspan="2">&nbsp;</td>
+      <th class="narrow_label">
+        <label for="reverse_desc">Reverse Relationship Description:</label>
+      </th>
+      <td>
+        <input type="text" id="reverse_desc" name="reverse_desc" value="" size="40" disabled="disabled">
+        <br/>
+        Use this label for the list of [% terms.bugs %] that link to
+        [%+ terms.abug %] with this 
+        [%+ field_types.${constants.FIELD_TYPE_BUG_ID} FILTER html %]
+        field. For example, if the description is "Is a duplicate of",
+        the reverse description would be "Duplicates of this [% terms.bug %]".
+        Leave blank to disable the list for this field.
+      </td>
       <th>
         <label for="value_field_id">
           Field that controls the values<br>

template/en/default/admin/custom_fields/edit.html.tmpl

@@ -76,24 +76,17 @@
                  [%- ' checked="checked"' IF field.is_mandatory %]></td>
     </tr>
     <tr>
-      [% IF field.type == constants.FIELD_TYPE_BUG_ID %]
-        <th class="narrow_label">
-          <label for="reverse_desc">Reverse Relationship Description:</label>
-        </th>
-        <td>
-          <input type="text" id="reverse_desc" name="reverse_desc" size="40"
-                 value="[% field.reverse_desc FILTER html %]">
-          <br/>
-          Use this label for the list of [% terms.bugs %] that link to
-          [%+ terms.abug %] with this 
-          [%+ field_types.${constants.FIELD_TYPE_BUG_ID} FILTER html %] field.
-          For example, if the description is "Is a duplicate of",
-          the reverse description would be "Duplicates of this [% terms.bug %]".
-          Leave blank to disable the list for this field.
-        </td>
-      [% ELSE %]
-        <td colspan="2">&nbsp;</td>
-      [% END %]
+      <th class="narrow_label">Long Description:</th>
+      <td>
+        [% INCLUDE global/textarea.html.tmpl
+         name           = 'long_desc'
+         id             = 'long_desc'
+         minrows        = 3
+         maxrows        = 5
+         cols           = 46
+         defaultcontent = field.long_desc
+       %]
+      </td>
       <th>
         <label for="visibility_field_id">Field only appears when:</label>
       </th>
@@ -128,6 +121,25 @@
         </select>
       </td>
     </tr>
+    [% IF field.type == constants.FIELD_TYPE_BUG_ID %]
+      <tr>
+        <th class="narrow_label">
+          <label for="reverse_desc">Reverse Relationship Description:</label>
+        </th>
+        <td>
+          <input type="text" id="reverse_desc" name="reverse_desc" size="40"
+                 value="[% field.reverse_desc FILTER html %]">
+          <br/>
+          Use this label for the list of [% terms.bugs %] that link to
+          [%+ terms.abug %] with this 
+          [%+ field_types.${constants.FIELD_TYPE_BUG_ID} FILTER html %] field.
+          For example, if the description is "Is a duplicate of",
+          the reverse description would be "Duplicates of this [% terms.bug %]".
+          Leave blank to disable the list for this field.
+        </td>
+        <td colspan="2">&nbsp;</td>
+      </tr>
+    [% END %]
     [% IF field.is_select %]
       <tr>
         <th>&nbsp;</th>

template/en/default/bug/field-help.none.tmpl

@@ -214,13 +214,17 @@ email1 =>
 
   [%# Add help for custom fields. %]
   [% IF !vars.help_html.${help_field}.defined %]
-    [% SET field_type = bug_fields.${help_field}.type %]
-    [% field_type_desc = BLOCK -%]
-      [% field_types.$field_type FILTER html %]
-    [%- END %]
-    [% vars.help_html.${help_field} = 
-      "A custom $field_type_desc field in this installation"
-      _ " of ${terms.Bugzilla}." %]
+    [% IF bug_fields.${help_field}.long_desc %]
+      [% vars.help_html.${help_field} = bug_fields.${help_field}.long_desc %]
+    [% ELSE %]
+      [% SET field_type = bug_fields.${help_field}.type %]
+      [% field_type_desc = BLOCK -%]
+        [% field_types.$field_type FILTER html %]
+      [%- END %]
+      [% vars.help_html.${help_field} = 
+        "A custom $field_type_desc field in this installation"
+        _ " of ${terms.Bugzilla}." %]
+    [% END %]
   [% END %]
 
   [%# Add help for the search types, for query.cgi. %]

template/en/default/global/user-error.html.tmpl

@@ -491,6 +491,11 @@
     [% title = "Missing Description for Field" %]
     You must enter a description for this field.
 
+  [% ELSIF error == "field_long_desc_too_long" %]
+    [% title = "Long Description for Field too long" %]
+    The long description you have provided for this field is longer than 
+    [% constants.MAX_FIELD_LONG_DESC_LENGTH FILTER html %] characters.
+
   [% ELSIF error == "field_missing_name" %]
     [% title = "Missing Name for Field" %]
     You must enter a name for this field.