rt/lib/RT/CustomFields.pm

   1 # BEGIN BPS TAGGED BLOCK {{{
   2 #
   3 # COPYRIGHT:
   4 #
   5 # This software is Copyright (c) 1996-2015 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 =head1 NAME
  50
  51   RT::CustomFields - a collection of RT CustomField objects
  52
  53 =head1 SYNOPSIS
  54
  55   use RT::CustomFields;
  56
  57 =head1 DESCRIPTION
  58
  59 =head1 METHODS
  60
  61
  62
  63 =cut
  64
  65
  66 package RT::CustomFields;
  67
  68 use strict;
  69 use warnings;
  70
  71 use RT::CustomField;
  72
  73 use base 'RT::SearchBuilder';
  74
  75 sub Table { 'CustomFields'}
  76
  77 sub _Init {
  78     my $self = shift;
  79
  80   # By default, order by SortOrder
  81   $self->OrderByCols(
  82          { ALIAS => 'main',
  83            FIELD => 'SortOrder',
  84            ORDER => 'ASC' },
  85          { ALIAS => 'main',
  86            FIELD => 'Name',
  87            ORDER => 'ASC' },
  88          { ALIAS => 'main',
  89            FIELD => 'id',
  90            ORDER => 'ASC' },
  91      );
  92     $self->{'with_disabled_column'} = 1;
  93
  94     return ( $self->SUPER::_Init(@_) );
  95 }
  96
  97
  98 =head2 LimitToLookupType
  99
 100 Takes LookupType and limits collection.
 101
 102 =cut
 103
 104 sub LimitToLookupType  {
 105     my $self = shift;
 106     my $lookup = shift;
 107
 108     $self->Limit( FIELD => 'LookupType', VALUE => "$lookup" );
 109 }
 110
 111 =head2 LimitToChildType
 112
 113 Takes partial LookupType and limits collection to records
 114 where LookupType is equal or ends with the value.
 115
 116 =cut
 117
 118 sub LimitToChildType  {
 119     my $self = shift;
 120     my $lookup = shift;
 121
 122     $self->Limit( FIELD => 'LookupType', VALUE => "$lookup", OPERATOR => "ENDSWITH" );
 123 }
 124
 125
 126 =head2 LimitToParentType
 127
 128 Takes partial LookupType and limits collection to records
 129 where LookupType is equal or starts with the value.
 130
 131 =cut
 132
 133 sub LimitToParentType  {
 134     my $self = shift;
 135     my $lookup = shift;
 136
 137     $self->Limit( FIELD => 'LookupType', VALUE => "$lookup", OPERATOR => "STARTSWITH" );
 138 }
 139
 140 =head2 LimitToObjectId
 141
 142 Takes an ObjectId and limits the collection to CFs applied to said object.
 143
 144 When called multiple times the ObjectId limits are joined with OR.
 145
 146 =cut
 147
 148 sub LimitToObjectId {
 149     my $self = shift;
 150     my $id = shift;
 151     $self->Limit(
 152         ALIAS           => $self->_OCFAlias,
 153         FIELD           => 'ObjectId',
 154         OPERATOR        => '=',
 155         VALUE           => $id || 0,
 156         ENTRYAGGREGATOR => 'OR'
 157     );
 158 }
 159
 160 =head2 LimitToGlobalOrObjectId
 161
 162 Takes list of object IDs and limits collection to custom
 163 fields that are applied to these objects or globally.
 164
 165 =cut
 166
 167 sub LimitToGlobalOrObjectId {
 168     my $self = shift;
 169     my $global_only = 1;
 170
 171
 172     foreach my $id (@_) {
 173         $self->LimitToObjectId($id);
 174         $global_only = 0 if $id;
 175     }
 176
 177     $self->LimitToObjectId(0) unless $global_only;
 178 }
 179
 180 sub _LimitToOCFs {
 181     my $self = shift;
 182     my @ids = @_;
 183
 184     my $ocfs_alias = $self->_OCFAlias( New => 1, Left => 1 );
 185     if ( @ids ) {
 186         # XXX: we need different EA in join clause, but DBIx::SB
 187         # doesn't support them, use IN (X) instead
 188         my $dbh = $self->_Handle->dbh;
 189         $self->Limit(
 190             LEFTJOIN   => $ocfs_alias,
 191             ALIAS      => $ocfs_alias,
 192             FIELD      => 'ObjectId',
 193             OPERATOR   => 'IN',
 194             QUOTEVALUE => 0,
 195             VALUE      => "(". join( ',', map $dbh->quote($_), @ids ) .")",
 196         );
 197     }
 198
 199     return $ocfs_alias;
 200 }
 201
 202 =head2 LimitToNotApplied
 203
 204 Takes either list of object ids or nothing. Limits collection
 205 to custom fields to listed objects or any corespondingly. Use
 206 zero to mean global.
 207
 208 =cut
 209
 210 sub LimitToNotApplied {
 211     my $self = shift;
 212     my @ids = @_;
 213
 214     my $ocfs_alias = $self->_LimitToOCFs(@ids);
 215
 216     $self->Limit(
 217         ENTRYAGGREGATOR => 'AND',
 218         ALIAS    => $ocfs_alias,
 219         FIELD    => 'id',
 220         OPERATOR => 'IS',
 221         VALUE    => 'NULL',
 222     );
 223 }
 224
 225 =head2 LimitToApplied
 226
 227 Limits collection to custom fields to listed objects or any corespondingly. Use
 228 zero to mean global.
 229
 230 =cut
 231
 232 sub LimitToApplied {
 233     my $self = shift;
 234     my @ids = @_;
 235
 236     my $ocfs_alias = $self->_LimitToOCFs(@ids);
 237
 238     $self->Limit(
 239         ENTRYAGGREGATOR => 'AND',
 240         ALIAS    => $ocfs_alias,
 241         FIELD    => 'id',
 242         OPERATOR => 'IS NOT',
 243         VALUE    => 'NULL',
 244     );
 245 }
 246
 247 =head2 LimitToGlobalOrQueue QUEUEID
 248
 249 DEPRECATED since CFs are applicable not only to tickets these days.
 250
 251 Limits the set of custom fields found to global custom fields or those tied to the queue with ID QUEUEID
 252
 253 =cut
 254
 255 sub LimitToGlobalOrQueue {
 256     my $self = shift;
 257     my $queue = shift;
 258     $self->LimitToGlobalOrObjectId( $queue );
 259     $self->LimitToLookupType( 'RT::Queue-RT::Ticket' );
 260 }
 261
 262
 263 =head2 LimitToQueue QUEUEID
 264
 265 DEPRECATED since CFs are applicable not only to tickets these days.
 266
 267 Takes a queue id (numerical) as its only argument. Makes sure that
 268 Scopes it pulls out apply to this queue (or another that you've selected with
 269 another call to this method
 270
 271 =cut
 272
 273 sub LimitToQueue  {
 274    my $self = shift;
 275   my $queue = shift;
 276
 277   $self->Limit (ALIAS => $self->_OCFAlias,
 278                 ENTRYAGGREGATOR => 'OR',
 279                 FIELD => 'ObjectId',
 280                 VALUE => "$queue")
 281       if defined $queue;
 282   $self->LimitToLookupType( 'RT::Queue-RT::Ticket' );
 283 }
 284
 285
 286 =head2 LimitToGlobal
 287
 288 DEPRECATED since CFs are applicable not only to tickets these days.
 289
 290 Makes sure that Scopes it pulls out apply to all queues
 291 (or another that you've selected with
 292 another call to this method or LimitToQueue)
 293
 294 =cut
 295
 296 sub LimitToGlobal  {
 297    my $self = shift;
 298
 299   $self->Limit (ALIAS => $self->_OCFAlias,
 300                 ENTRYAGGREGATOR => 'OR',
 301                 FIELD => 'ObjectId',
 302                 VALUE => 0);
 303   $self->LimitToLookupType( 'RT::Queue-RT::Ticket' );
 304 }
 305
 306
 307 =head2 ApplySortOrder
 308
 309 Sort custom fields according to thier order application to objects. It's
 310 expected that collection contains only records of one
 311 L<RT::CustomField/LookupType> and applied to one object or globally
 312 (L</LimitToGlobalOrObjectId>), otherwise sorting makes no sense.
 313
 314 =cut
 315
 316 sub ApplySortOrder {
 317     my $self = shift;
 318     my $order = shift || 'ASC';
 319     $self->OrderByCols( {
 320         ALIAS => $self->_OCFAlias,
 321         FIELD => 'SortOrder',
 322         ORDER => $order,
 323     } );
 324 }
 325
 326
 327 =head2 ContextObject
 328
 329 Returns context object for this collection of custom fields,
 330 but only if it's defined.
 331
 332 =cut
 333
 334 sub ContextObject {
 335     my $self = shift;
 336     return $self->{'context_object'};
 337 }
 338
 339
 340 =head2 SetContextObject
 341
 342 Sets context object for this collection of custom fields.
 343
 344 =cut
 345
 346 sub SetContextObject {
 347     my $self = shift;
 348     return $self->{'context_object'} = shift;
 349 }
 350
 351
 352 sub _OCFAlias {
 353     my $self = shift;
 354     my %args = ( New => 0, Left => 0, @_ );
 355
 356     return $self->{'_sql_ocfalias'} if $self->{'_sql_ocfalias'} && !$args{'New'};
 357
 358     my $alias = $self->Join(
 359         $args{'Left'} ? (TYPE => 'LEFT') : (),
 360         ALIAS1 => 'main',
 361         FIELD1 => 'id',
 362         TABLE2 => 'ObjectCustomFields',
 363         FIELD2 => 'CustomField'
 364     );
 365     return $alias if $args{'New'};
 366     return $self->{'_sql_ocfalias'} = $alias;
 367 }
 368
 369
 370 =head2 AddRecord
 371
 372 Overrides the collection to ensure that only custom fields the user can
 373 see are returned; also propagates down the L</ContextObject>.
 374
 375 =cut
 376
 377 sub AddRecord {
 378     my $self = shift;
 379     my ($record) = @_;
 380
 381     $record->SetContextObject( $self->ContextObject );
 382     return unless $record->CurrentUserHasRight('SeeCustomField');
 383     return $self->SUPER::AddRecord( $record );
 384 }
 385
 386 =head2 NewItem
 387
 388 Returns an empty new RT::CustomField item
 389 Overrides <RT::SearchBuilder/NewItem> to make sure </ContextObject>
 390 is inherited.
 391
 392 =cut
 393
 394 sub NewItem {
 395     my $self = shift;
 396     my $res = RT::CustomField->new($self->CurrentUser);
 397     $res->SetContextObject($self->ContextObject);
 398     return $res;
 399 }
 400
 401 RT::Base->_ImportOverlays();
 402
 403 1;