Master to 4.2.8
[usit-rt.git] / lib / RT / CustomFieldValues / External.pm
1 # BEGIN BPS TAGGED BLOCK {{{
2 #
3 # COPYRIGHT:
4 #
5 # This software is Copyright (c) 1996-2014 Best Practical Solutions, LLC
6 #                                          <sales@bestpractical.com>
7 #
8 # (Except where explicitly superseded by other copyright notices)
9 #
10 #
11 # LICENSE:
12 #
13 # This work is made available to you under the terms of Version 2 of
14 # the GNU General Public License. A copy of that license should have
15 # been provided with this software, but in any event can be snarfed
16 # from www.gnu.org.
17 #
18 # This work is distributed in the hope that it will be useful, but
19 # WITHOUT ANY WARRANTY; without even the implied warranty of
20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21 # General Public License for more details.
22 #
23 # You should have received a copy of the GNU General Public License
24 # along with this program; if not, write to the Free Software
25 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
26 # 02110-1301 or visit their web page on the internet at
27 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
28 #
29 #
30 # CONTRIBUTION SUBMISSION POLICY:
31 #
32 # (The following paragraph is not intended to limit the rights granted
33 # to you to modify and distribute this software under the terms of
34 # the GNU General Public License and is only of importance to you if
35 # you choose to contribute your changes and enhancements to the
36 # community by submitting them to Best Practical Solutions, LLC.)
37 #
38 # By intentionally submitting any modifications, corrections or
39 # derivatives to this work, or any other work intended for use with
40 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
41 # you are the copyright holder for those contributions and you grant
42 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
43 # royalty-free, perpetual, license to use, copy, create derivative
44 # works based on those contributions, and sublicense and distribute
45 # those contributions and any derivatives thereof.
46 #
47 # END BPS TAGGED BLOCK }}}
48
49 package RT::CustomFieldValues::External;
50
51 use strict;
52 use warnings;
53
54 use base qw(RT::CustomFieldValues);
55
56 =head1 NAME
57
58 RT::CustomFieldValues::External - Pull possible values for a custom
59 field from an arbitrary external data source.
60
61 =head1 SYNOPSIS
62
63 Custom field value lists can be produced by creating a class that
64 inherits from C<RT::CustomFieldValues::External>, and overloading
65 C<SourceDescription> and C<ExternalValues>.  See
66 L<RT::CustomFieldValues::Groups> for a simple example.
67
68 =head1 DESCRIPTION
69
70 Subclasses should implement the following methods:
71
72 =head2 SourceDescription
73
74 This method should return a string describing the data source; this is
75 the identifier by which the user will see the dropdown.
76
77 =head2 ExternalValues
78
79 This method should return an array reference of hash references.  The
80 hash references must contain a key for C<name> and can optionally contain
81 keys for C<description>, C<sortorder>, and C<category>. If supplying a
82 category, you must also set the category the custom field is based on in
83 the custom field configuration page.
84
85 =head1 SEE ALSO
86
87 F<docs/extending/external_custom_fields.pod>
88
89 =cut
90
91 sub _Init {
92     my $self = shift;
93     $self->Table( '' );
94     return ( $self->SUPER::_Init(@_) );
95 }
96
97 sub CleanSlate {
98     my $self = shift;
99     delete $self->{ $_ } foreach qw(
100         __external_cf
101         __external_cf_limits
102     );
103     return $self->SUPER::CleanSlate(@_);
104 }
105
106 sub _ClonedAttributes {
107     my $self = shift;
108     return qw(
109         __external_cf
110         __external_cf_limits
111     ), $self->SUPER::_ClonedAttributes;
112 }
113
114 sub Limit {
115     my $self = shift;
116     my %args = (@_);
117     push @{ $self->{'__external_cf_limits'} ||= [] }, {
118         %args,
119         CALLBACK => $self->__BuildLimitCheck( %args ),
120     };
121     return $self->SUPER::Limit( %args );
122 }
123
124 sub __BuildLimitCheck {
125     my ($self, %args) = (@_);
126     return undef unless $args{'FIELD'} =~ /^(?:Name|Description)$/;
127
128     my $condition = $args{VALUE};
129     my $op = $args{'OPERATOR'} || '=';
130     my $field = $args{FIELD};
131
132     return sub {
133         my $record = shift;
134         my $value = $record->$field;
135         return 0 unless defined $value;
136         if ($op eq "=") {
137             return 0 unless $value eq $condition;
138         } elsif ($op eq "!=" or $op eq "<>") {
139             return 0 unless $value ne $condition;
140         } elsif (uc($op) eq "LIKE") {
141             return 0 unless $value =~ /\Q$condition\E/i;
142         } elsif (uc($op) eq "NOT LIKE") {
143             return 0 unless $value !~ /\Q$condition\E/i;
144         } else {
145             return 0;
146         }
147         return 1;
148     };
149 }
150
151 sub __BuildAggregatorsCheck {
152     my $self = shift;
153     my @cbs = grep {$_->{CALLBACK}} @{ $self->{'__external_cf_limits'} };
154     return undef unless @cbs;
155
156     my %h = (
157         OR  => sub { defined $_[0] ? ($_[0] || $_[1]) : $_[1] },
158         AND => sub { defined $_[0] ? ($_[0] && $_[1]) : $_[1] },
159     );
160
161     return sub {
162         my ($sb, $record) = @_;
163         my $ok;
164         for my $limit ( @cbs ) {
165             $ok = $h{$limit->{ENTRYAGGREGATOR} || 'OR'}->(
166                 $ok, $limit->{CALLBACK}->($record),
167             );
168         }
169         return $ok;
170     };
171 }
172
173 sub _DoSearch {
174     my $self = shift;
175
176     delete $self->{'items'};
177
178     my %defaults = (
179             id => 1,
180             name => '',
181             customfield => $self->{'__external_cf'},
182             sortorder => 0,
183             description => '',
184             category => undef,
185             creator => RT->SystemUser->id,
186             created => undef,
187             lastupdatedby => RT->SystemUser->id,
188             lastupdated => undef,
189     );
190
191     my $i = 0;
192
193     my $check = $self->__BuildAggregatorsCheck;
194     foreach( @{ $self->ExternalValues } ) {
195         my $value = $self->NewItem;
196         $value->LoadFromHash( { %defaults, %$_ } );
197         next if $check && !$check->( $self, $value );
198         $self->AddRecord( $value );
199     }
200     $self->{'must_redo_search'} = 0;
201     return $self->_RecordCount;
202 }
203
204 sub _DoCount {
205     my $self = shift;
206
207     my $count;
208     $count = $self->_DoSearch if $self->{'must_redo_search'};
209     $count = $self->_RecordCount unless defined $count;
210
211     return $self->{'count_all'} = $self->{'raw_rows'} = $count;
212 }
213
214 sub LimitToCustomField {
215     my $self = shift;
216     $self->{'__external_cf'} = $_[0];
217     return $self->SUPER::LimitToCustomField( @_ );
218 }
219
220 sub _SingularClass {
221     "RT::CustomFieldValue"
222 }
223
224 RT::Base->_ImportOverlays();
225
226 1;