384 lines
9.0 KiB
Perl
384 lines
9.0 KiB
Perl
# -*- Mode: perl; indent-tabs-mode: nil -*-
|
|
#
|
|
# The contents of this file are subject to the Mozilla Public
|
|
# License Version 1.1 (the "License"); you may not use this file
|
|
# except in compliance with the License. You may obtain a copy of
|
|
# the License at http://www.mozilla.org/MPL/
|
|
#
|
|
# Software distributed under the License is distributed on an "AS
|
|
# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
|
# implied. See the License for the specific language governing
|
|
# rights and limitations under the License.
|
|
#
|
|
# The Original Code is the Bugzilla Bug Tracking System.
|
|
#
|
|
# Contributor(s): Dan Mosedale <dmose@mozilla.org>
|
|
# Frédéric Buclin <LpSolit@gmail.com>
|
|
# Myk Melez <myk@mozilla.org>
|
|
|
|
=head1 NAME
|
|
|
|
Bugzilla::Field - a particular piece of information about bugs
|
|
and useful routines for form field manipulation
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Bugzilla;
|
|
use Data::Dumper;
|
|
|
|
# Display information about all fields.
|
|
print Dumper(Bugzilla->get_fields());
|
|
|
|
# Display information about non-obsolete custom fields.
|
|
print Dumper(Bugzilla->get_fields({ obsolete => 1, custom => 1 }));
|
|
|
|
# Display a list of the names of non-obsolete custom fields.
|
|
print Bugzilla->custom_field_names;
|
|
|
|
use Bugzilla::Field;
|
|
|
|
# Display information about non-obsolete custom fields.
|
|
# Bugzilla->get_fields() is a wrapper around Bugzilla::Field::match(),
|
|
# so both methods take the same arguments.
|
|
print Dumper(Bugzilla::Field::match({ obsolete => 1, custom => 1 }));
|
|
|
|
# Create a custom field.
|
|
my $field = Bugzilla::Field::create("hilarity", "Hilarity");
|
|
print "$field->{description} is a custom field\n";
|
|
|
|
# Instantiate a Field object for an existing field.
|
|
my $field = new Bugzilla::Field('qacontact_accessible');
|
|
if ($field->{obsolete}) {
|
|
print "$field->{description} is obsolete\n";
|
|
}
|
|
|
|
# Validation Routines
|
|
check_form_field($cgi, $fieldname, \@legal_values);
|
|
check_form_field_defined($cgi, $fieldname);
|
|
$fieldid = get_field_id($fieldname);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Field.pm defines field objects, which represent the particular pieces
|
|
of information that Bugzilla stores about bugs.
|
|
|
|
This package also provides functions for dealing with CGI form fields.
|
|
|
|
=cut
|
|
|
|
package Bugzilla::Field;
|
|
|
|
use strict;
|
|
|
|
use base qw(Exporter);
|
|
@Bugzilla::Field::EXPORT = qw(check_form_field check_form_field_defined
|
|
get_field_id);
|
|
|
|
use Bugzilla::Util;
|
|
use Bugzilla::Constants;
|
|
use Bugzilla::Error;
|
|
|
|
use constant DB_COLUMNS => (
|
|
'fieldid AS id',
|
|
'name',
|
|
'description',
|
|
'type',
|
|
'custom',
|
|
'obsolete'
|
|
);
|
|
|
|
our $columns = join(", ", DB_COLUMNS);
|
|
|
|
sub new {
|
|
my $invocant = shift;
|
|
my $name = shift;
|
|
my $self = shift || Bugzilla->dbh->selectrow_hashref(
|
|
"SELECT $columns FROM fielddefs WHERE name = ?",
|
|
undef,
|
|
$name
|
|
);
|
|
bless($self, $invocant);
|
|
return $self;
|
|
}
|
|
|
|
=pod
|
|
|
|
=head2 Instance Properties
|
|
|
|
=over
|
|
|
|
=item C<id>
|
|
|
|
the unique identifier for the field;
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub id { return $_[0]->{id} }
|
|
|
|
=over
|
|
|
|
=item C<name>
|
|
|
|
the name of the field in the database; begins with "cf_" if field
|
|
is a custom field, but test the value of the boolean "custom" property
|
|
to determine if a given field is a custom field;
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub name { return $_[0]->{name} }
|
|
|
|
=over
|
|
|
|
=item C<description>
|
|
|
|
a short string describing the field; displayed to Bugzilla users
|
|
in several places within Bugzilla's UI, f.e. as the form field label
|
|
on the "show bug" page;
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub description { return $_[0]->{description} }
|
|
|
|
=over
|
|
|
|
=item C<type>
|
|
|
|
an integer specifying the kind of field this is; values correspond to
|
|
the FIELD_TYPE_* constants in Constants.pm
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub type { return $_[0]->{type} }
|
|
|
|
=over
|
|
|
|
=item C<custom>
|
|
|
|
a boolean specifying whether or not the field is a custom field;
|
|
if true, field name should start "cf_", but use this property to determine
|
|
which fields are custom fields;
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub custom { return $_[0]->{custom} }
|
|
|
|
=over
|
|
|
|
=item C<obsolete>
|
|
|
|
a boolean specifying whether or not the field is obsolete;
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub obsolete { return $_[0]->{obsolete} }
|
|
|
|
|
|
=pod
|
|
|
|
=head2 Class Methods
|
|
|
|
=over
|
|
|
|
=item C<create($name, $desc)>
|
|
|
|
Description: creates a new custom field.
|
|
|
|
Params: C<$name> - string - the name of the field;
|
|
C<$desc> - string - the field label to display in the UI.
|
|
|
|
Returns: a field object.
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub create {
|
|
my ($name, $desc, $custom) = @_;
|
|
|
|
# Convert the $custom argument into a DB-compatible value.
|
|
$custom = $custom ? 1 : 0;
|
|
|
|
my $dbh = Bugzilla->dbh;
|
|
|
|
# Some day we'll allow invocants to specify the sort key.
|
|
my ($sortkey) =
|
|
$dbh->selectrow_array("SELECT MAX(sortkey) + 1 FROM fielddefs");
|
|
|
|
# Some day we'll require invocants to specify the field type.
|
|
my $type = FIELD_TYPE_FREETEXT;
|
|
|
|
# Create the database column that stores the data for this field.
|
|
$dbh->bz_add_column("bugs", $name, { TYPE => 'varchar(255)' });
|
|
|
|
# Add the field to the list of fields at this Bugzilla installation.
|
|
my $sth = $dbh->prepare(
|
|
"INSERT INTO fielddefs (name, description, sortkey, type,
|
|
custom, mailhead)
|
|
VALUES (?, ?, ?, ?, ?, 1)"
|
|
);
|
|
$sth->execute($name, $desc, $sortkey, $type, $custom);
|
|
|
|
return new Bugzilla::Field($name);
|
|
}
|
|
|
|
|
|
=pod
|
|
|
|
=over
|
|
|
|
=item C<match($criteria)>
|
|
|
|
Description: returns a list of fields that match the specified criteria.
|
|
|
|
Params: C<$criteria> - hash reference - the criteria to match against.
|
|
Hash keys represent field properties; hash values represent
|
|
their values. All criteria are optional. Valid criteria are
|
|
"custom" and "obsolete", and both take boolean values.
|
|
|
|
Note: Bugzilla->get_fields() and Bugzilla->custom_field_names
|
|
wrap this method for most callers.
|
|
|
|
Returns: a list of field objects.
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub match {
|
|
my ($criteria) = @_;
|
|
|
|
my @terms;
|
|
if (defined $criteria->{name}) {
|
|
push(@terms, "name=" . Bugzilla->dbh->quote($criteria->{name}));
|
|
}
|
|
if (defined $criteria->{custom}) {
|
|
push(@terms, "custom=" . ($criteria->{custom} ? "1" : "0"));
|
|
}
|
|
if (defined $criteria->{obsolete}) {
|
|
push(@terms, "obsolete=" . ($criteria->{obsolete} ? "1" : "0"));
|
|
}
|
|
my $where = (scalar(@terms) > 0) ? "WHERE " . join(" AND ", @terms) : "";
|
|
|
|
my $records = Bugzilla->dbh->selectall_arrayref(
|
|
"SELECT $columns FROM fielddefs $where ORDER BY sortkey",
|
|
{ Slice => {}}
|
|
);
|
|
# Generate a array of field objects from the array of field records.
|
|
my @fields = map( new Bugzilla::Field(undef, $_), @$records );
|
|
return @fields;
|
|
}
|
|
|
|
=pod
|
|
|
|
=head2 Data Validation
|
|
|
|
=over
|
|
|
|
=item C<check_form_field($cgi, $fieldname, \@legal_values)>
|
|
|
|
Description: Makes sure the field $fieldname is defined and its value
|
|
is non empty. If @legal_values is defined, this routine
|
|
also checks whether its value is one of the legal values
|
|
associated with this field. If the test fails, an error
|
|
is thrown.
|
|
|
|
Params: $cgi - a CGI object
|
|
$fieldname - the field name to check
|
|
@legal_values - (optional) ref to a list of legal values
|
|
|
|
Returns: nothing
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub check_form_field {
|
|
my ($cgi, $fieldname, $legalsRef) = @_;
|
|
my $dbh = Bugzilla->dbh;
|
|
|
|
if (!defined $cgi->param($fieldname)
|
|
|| trim($cgi->param($fieldname)) eq ""
|
|
|| (defined($legalsRef)
|
|
&& lsearch($legalsRef, $cgi->param($fieldname)) < 0))
|
|
{
|
|
trick_taint($fieldname);
|
|
my ($result) = $dbh->selectrow_array("SELECT description FROM fielddefs
|
|
WHERE name = ?", undef, $fieldname);
|
|
|
|
my $field = $result || $fieldname;
|
|
ThrowCodeError("illegal_field", { field => $field });
|
|
}
|
|
}
|
|
|
|
=pod
|
|
|
|
=over
|
|
|
|
=item C<check_form_field_defined($cgi, $fieldname)>
|
|
|
|
Description: Makes sure the field $fieldname is defined and its value
|
|
is non empty. Else an error is thrown.
|
|
|
|
Params: $cgi - a CGI object
|
|
$fieldname - the field name to check
|
|
|
|
Returns: nothing
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub check_form_field_defined {
|
|
my ($cgi, $fieldname) = @_;
|
|
|
|
if (!defined $cgi->param($fieldname)) {
|
|
ThrowCodeError("undefined_field", { field => $fieldname });
|
|
}
|
|
}
|
|
|
|
=pod
|
|
|
|
=over
|
|
|
|
=item C<get_field_id($fieldname)>
|
|
|
|
Description: Returns the ID of the specified field name and throws
|
|
an error if this field does not exist.
|
|
|
|
Params: $name - a field name
|
|
|
|
Returns: the corresponding field ID or an error if the field name
|
|
does not exist.
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
sub get_field_id {
|
|
my ($name) = @_;
|
|
my $dbh = Bugzilla->dbh;
|
|
|
|
trick_taint($name);
|
|
my $id = $dbh->selectrow_array('SELECT fieldid FROM fielddefs
|
|
WHERE name = ?', undef, $name);
|
|
|
|
ThrowCodeError('invalid_field_name', {field => $name}) unless $id;
|
|
return $id
|
|
}
|
|
|
|
1;
|
|
|
|
__END__
|