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

Status: RESOLVED FIXED

(Bugzilla :: Administration, task)

Description

[rojanu]

Bugzilla UI should have the means to add tooltips to custom fields instead of the default standard tooltip for all custom fields

Comment 1

[Antoine "hashar" Musso]

Looks like there is some code on http://code.google.com/p/bugzilla-field-help/ to implements this feature request.

Comment 2

[David Lawrence [:dkl]]

(In reply to Antoine "hashar" Musso from comment #1)
> Looks like there is some code on
> http://code.google.com/p/bugzilla-field-help/ to implements this feature
> request.

Didn't see anything yet in the extension that does anything. Think they just submitted as a placeholder at the moment.

dkl

Comment 3

[rojanu]

I was thinking of putting some code together but to save the text I would need to add a column to fielddefs table and that means, the text cannot be localised.

If that's acceptable I will create a patch


> Didn't see anything yet in the extension that does anything. Think they just
> submitted as a placeholder at the moment.
The FieldHelp extension works. Just add element to vars.help_html hash in file extensions/FieldHelp/template/en/default/hook/bug/field-help-end.none.tmpl

like the example in the file but with correct field name

Comment 4

[rojanu]

Attachment: Field Help tooltip

Further to my comments in comment 3. Text in DB are not localised and there are other examples for it as well. e.g. Product, component descriptions.

Anyways, I created a simple patch for this bug.

Comment 5

[Frédéric Buclin]

I agree that we need to be able to specify a better description for custom fields, but I don't like "helptext" as field name. Maybe "long_desc" would be better? Also, the description should be limited to 255 characters. No need for longer strings.

Comment 6

[Frédéric Buclin]

Comment on attachment 599929 [details] [diff] [review]
Field Help tooltip

>=== modified file 'Bugzilla/DB/Schema.pm'

>+            helptext   => {TYPE => 'MEDIUMTEXT', NOTNULL => 0},


>=== modified file 'Bugzilla/Install/DB.pm'

>+    $dbh->bz_add_column('fielddefs', 'helptext',{TYPE => 'MEDIUMTEXT', NOTNULL => 1}, '');


The definition is inconsistent. IMO, it's fine for this field to be NULL. In that case, we fall back to the default definition of the custom field. So r- for this and per my previous comment. Also, in the validator, make sure that the length of the description is shorter than 255 characters.

Comment 7

[rojanu]

Attachment: Field Long Description v2

Comment 8

[Frédéric Buclin]

Comment on attachment 613898 [details] [diff] [review]
Field Long Description v2

Looks like you didn't fix all parts of your patch. :)


>=== modified file 'Bugzilla/DB/Schema.pm'

>+            long_desc   => {TYPE => 'MEDIUMTEXT', NOTNULL => 1},

Must be TYPE => 'varchar(255)'. MEDIUMTEXT is way too long.


>=== modified file 'Bugzilla/Field.pm'

>+    $long_desc = clean_text($long_desc);
>+    if (length($long_desc) > MAX_FIELD_LONG_DESC_LENTGH) {

You must make sure that $long_desc is defined, else Perl is going to complain.


> sub set_description    { $_[0]->set('description', $_[1]); }
>+sub set_long_desc       { $_[0]->set('long_desc',    $_[1]); }

Fix the indentation.



>=== modified file 'Bugzilla/Install/DB.pm'

>+    $dbh->bz_add_column('fielddefs', 'long_desc',{TYPE => 'MEDIUMTEXT', NOTNULL => 1}, '');

Here too, use varchar(255).



>=== modified file 'editfields.cgi'

>     $vars->{'field'} = Bugzilla::Field->create({
>         name        => scalar $cgi->param('name'),
>         description => scalar $cgi->param('desc'),
>+        long_desc    => scalar $cgi->param('long_desc'),

Fix the indentation.



>=== modified file 'template/en/default/admin/custom_fields/create.html.tmpl'

>+      <th align="right" valign="top">Lond Description:</th>

s/Lond/Long/



>=== modified file 'template/en/default/bug/field-help.none.tmpl'

>+    [% IF bug_fields.${help_field}.long_desc %]
>+        [% vars.help_html.${help_field} = bug_fields.${help_field}.long_desc %]
>+      [% ELSE %]

Fix the indentation (ELSE is not aligned with IF). In templates, the indentation is 2 whitespaces only, not 4.


Otherwise looks good.

Comment 9

[rojanu]

Attachment: Field Long Description v2.1

Comment 10

[Frédéric Buclin]

Comment on attachment 613945 [details] [diff] [review]
Field Long Description v2.1

This looks good. Still a few things to fix, though.


>=== modified file 'Bugzilla/Constants.pm'

>+    MAX_FIELD_LONG_DESC_LENTGH

s/LENTGH/LENGTH/ and everywhere else where this constant is used.


>+# The maximum length for the long description of fields

Nit: add a period at the end of the sentence.


>=== modified file 'Bugzilla/Install/DB.pm'

>+    # Add long_desc to fielddefs for tooltips
>+    $dbh->bz_add_column('fielddefs', 'long_desc',{TYPE => 'varchar(255)', NOTNULL => 1}, '');

New code is added chronologically, so please add it at the end of update_fielddefs_definition(), with a reference to this bug ID.


>=== modified file 'template/en/default/admin/custom_fields/create.html.tmpl'

>+      <th align="right" valign="top">Long Description:</th>

Instead of align="right" valign="top", use the same class as all other table headers, i.e. narrow_label. This will make the label to be displayed correctly.


>+      <td>
>+        [% INCLUDE global/textarea.html.tmpl
>+         name           = 'long_desc'
>+         id             = 'long_desc'
>+         minrows        = 1
>+         maxrows        = 2
>+         cols           = constants.COMMENT_COLS

The UI doesn't look good. This field is too large and make the right column to move out of the window. I played with it a bit, and these values give good results: minrows = 3, maxrows = 5, cols = 46. This way, the field will look as wide as other fields.

Also, here and in edit.html.tmpl, move this field above the "Reverse Relationship Description" one. When editing fields which are not of type "Bug ID", you get an ugly empty space between the sortkey and the long desc.



>=== modified file 'template/en/default/global/user-error.html.tmpl'

>+    The long description you have provided for this field is longer than 
>+    [% constants.MAX_FIELD_LONG_DESC_LENTGH FILTER html %] characters allowed.

remove "allowed".

Comment 11

[rojanu]

Attachment: Field Long Description v2.2

>New code is added chronologically, so please add it at the end of >update_fielddefs_definition()
it already is the last item before the hook


Also, is it a good idea to use MAX_FIELD_LONG_DESC_LENGTH constant in DB.pm and Schema.pm

Comment 12

[rojanu]

>Also, is it a good idea to use MAX_FIELD_LONG_DESC_LENGTH constant in DB.pm and Schema.pm

By that I mean, to do 
long_desc   => {TYPE => 'varchar('.MAX_FIELD_LONG_DESC_LENGTH.')', NOTNULL => 1}

Comment 13

[Frédéric Buclin]

(In reply to rojanu from comment #12)
> >Also, is it a good idea to use MAX_FIELD_LONG_DESC_LENGTH constant in DB.pm and Schema.pm
> 
> By that I mean, to do 
> long_desc   => {TYPE => 'varchar('.MAX_FIELD_LONG_DESC_LENGTH.')', NOTNULL
> => 1}

Ah no, it's not. If someone edits this constant multiple times, this is going to make the DB inconsistent.

Comment 14

[Frédéric Buclin]

Comment on attachment 614293 [details] [diff] [review]
Field Long Description v2.2

>=== modified file 'Bugzilla/DB/Schema.pm'

>+            long_desc   => {TYPE => 'varchar(255)', NOTNULL => 1},

To work correctly with PostgreSQL, it must have a DEFAULT value, see bug 711925.	



>=== modified file 'Bugzilla/Install/DB.pm'

>+    $dbh->bz_add_column('fielddefs', 'long_desc',{TYPE => 'varchar(255)', NOTNULL => 1}, '');

Same here.


Otherwise, this looks good and works fine. r=LpSolit
I will fix the comments above on checkin. Thanks for the patch! :)

Comment 15

[Frédéric Buclin]

Committing to: bzr+ssh://[e-mail]/bugzilla/trunk/
modified editfields.cgi
modified Bugzilla/Constants.pm
modified Bugzilla/Field.pm
modified Bugzilla/DB/Schema.pm
modified Bugzilla/Install/DB.pm
modified template/en/default/admin/custom_fields/create.html.tmpl
modified template/en/default/admin/custom_fields/edit.html.tmpl
modified template/en/default/bug/field-help.none.tmpl
modified template/en/default/global/user-error.html.tmpl
Committed revision 8226.

Comment 16

[Frédéric Buclin]

Added to relnotes for 4.4.