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