FS/FS/part_event/Condition.pm

   1 package FS::part_event::Condition;
   2
   3 use strict;
   4 use base qw( FS::part_event_condition );
   5
   6 =head1 NAME
   7
   8 FS::part_event::Condition - Base class for event conditions
   9
  10 =head1 SYNOPSIS
  11
  12 package FS::part_event::Condition::mycondition;
  13
  14 use base FS::part_event::Condition;
  15
  16 =head1 DESCRIPTION
  17
  18 FS::part_event::Condition is a base class for event conditions classes.
  19
  20 =head1 METHODS
  21
  22 These methods are implemented in each condition class.
  23
  24 =over 4
  25
  26 =item description
  27
  28 Condition classes must define a description method.  This method should return
  29 a scalar description of the condition.
  30
  31 =item eventtable_hashref
  32
  33 Condition classes must define an eventtable_hashref method if they can only be
  34 tested against some kinds of tables. This method should return a hash reference
  35 of eventtables (values set true indicate the condition can be tested):
  36
  37   sub eventtable_hashref {
  38     { 'cust_main'      => 1,
  39       'cust_bill'      => 1,
  40       'cust_pkg'       => 0,
  41       'cust_pay_batch' => 0,
  42     };
  43   }
  44
  45 =cut
  46
  47 #fallback
  48 sub eventtable_hashref {
  49     { 'cust_main'      => 1,
  50       'cust_bill'      => 1,
  51       'cust_pkg'       => 1,
  52       'cust_pay_batch' => 1,
  53     };
  54 }
  55
  56 =item option_fields
  57
  58 Condition classes may define an option_fields method to indicate that they
  59 accept one or more options.
  60
  61 This method should return a list of option names and option descriptions.
  62 Each option description can be a scalar description, for simple options, or a
  63 hashref with the following values:
  64
  65 =over 4
  66
  67 =item label - Description
  68
  69 =item type - Currently text, money, checkbox, checkbox-multiple, select, select-agent, select-pkg_class, select-part_referral, select-table, fixed, hidden, (others can be implemented as httemplate/elements/tr-TYPE.html mason components).  Defaults to text.
  70
  71 =item options - For checkbox-multiple and select, a list reference of available option values.
  72
  73 =item option_labels - For checkbox-multiple (and select?), a hash reference of availble option values and labels.
  74
  75 =item value - for checkbox, fixed, hidden (also a default for text, money, more?)
  76
  77 =item table - for select-table
  78
  79 =item name_col - for select-table
  80
  81 =item NOTE: See httemplate/elements/select-table.html for a full list of the optinal options for the select-table type
  82
  83 =back
  84
  85 NOTE: A database connection is B<not> yet available when this subroutine is
  86 executed.
  87
  88 Example:
  89
  90   sub option_fields {
  91     (
  92       'field'         => 'description',
  93
  94       'another_field' => { 'label'=>'Amount', 'type'=>'money', },
  95
  96       'third_field'   => { 'label'         => 'Types',
  97                            'type'          => 'checkbox-multiple',
  98                            'options'       => [ 'h', 's' ],
  99                            'option_labels' => { 'h' => 'Happy',
 100                                                 's' => 'Sad',
 101                                               },
 102     );
 103   }
 104
 105 =cut
 106
 107 #fallback
 108 sub option_fields {
 109   ();
 110 }
 111
 112 =item condition CUSTOMER_EVENT_OBJECT
 113
 114 Condition classes must define a condition method.  This method is evaluated
 115 to determine if the condition has been met.  The object which triggered the
 116 event (an FS::cust_main, FS::cust_bill or FS::cust_pkg object) is passed as
 117 the first argument.  Additional arguments are list of key-value pairs.
 118
 119 To retreive option values, call the option method on the desired option, i.e.:
 120
 121   my( $self, $cust_object, %opts ) = @_;
 122   $value_of_field = $self->option('field');
 123
 124 Available additional arguments:
 125
 126   $time = $opt{'time'}; #use this instead of time or $^T
 127
 128   $cust_event = $opt{'cust_event'}; #to retreive the cust_event object being tested
 129
 130 Return a true value if the condition has been met, and a false value if it has
 131 not.
 132
 133 =item condition_sql EVENTTABLE
 134
 135 Condition classes may optionally define a condition_sql method.  This B<class>
 136 method should return an SQL fragment that tests for this condition.  The
 137 fragment is evaluated and a true value of this expression indicates that the
 138 condition has been met.  The event table (cust_main, cust_bill or cust_pkg) is
 139 passed as an argument.
 140
 141 This method is used for optimizing event queries.  You may want to add indices
 142 for any columns referenced.  It is acceptable to return an SQL fragment which
 143 partially tests the condition; doing so will still reduce the number of
 144 records which much be returned and tested with the B<condition> method.
 145
 146 =cut
 147
 148 # fallback.
 149 sub condition_sql {
 150   my( $class, $eventtable ) = @_;
 151   #...
 152   'true';
 153 }
 154
 155 =item disabled
 156
 157 Condition classes may optionally define a disabled method.  Returning a true
 158 value disbles the condition entirely.
 159
 160 =cut
 161
 162 sub disabled {
 163   0;
 164 }
 165
 166 =item implicit_flag
 167
 168 This is used internally by the I<once> and I<balance> conditions.  You probably
 169 do B<not> want to define this method for new custom conditions, unless you're
 170 sure you want B<every> new action to start with your condition.
 171
 172 Condition classes may define an implicit_flag method that returns true to
 173 indicate that all new events should start with this condition.  (Currently,
 174 condition classes which do so should be applicable to all kinds of
 175 I<eventtable>s.)  The numeric value of the flag also defines the ordering of
 176 implicit conditions.
 177
 178 =cut
 179
 180 #fallback
 181 sub implicit_flag { 0; }
 182
 183 =item remove_warning
 184
 185 Again, used internally by the I<once> and I<balance> conditions; probably not
 186 a good idea for new custom conditions.
 187
 188 Condition classes may define a remove_warning method containing a string
 189 warning message to enable a confirmation dialog triggered when the condition
 190 is removed from an event.
 191
 192 =cut
 193
 194 #fallback
 195 sub remove_warning { ''; }
 196
 197 =item order_sql
 198
 199 This is used internally by the I<balance_age> and I<cust_bill_age> conditions
 200 to declare ordering; probably not of general use for new custom conditions.
 201
 202 =item order_sql_weight
 203
 204 In conjunction with order_sql, this defines which order the ordering fragments
 205 supplied by different B<order_sql> should be used.
 206
 207 =cut
 208
 209 sub order_sql_weight { ''; }
 210
 211 =back
 212
 213 =head1 BASE METHODS
 214
 215 These methods are defined in the base class for use in condition classes.
 216
 217 =over 4
 218
 219 =item cust_main CUST_OBJECT
 220
 221 Return the customer object (see L<FS::cust_main>) associated with the provided
 222 object (the object itself if it is already a customer object).
 223
 224 =cut
 225
 226 sub cust_main {
 227   my( $self, $cust_object ) = @_;
 228
 229   $cust_object->isa('FS::cust_main') ? $cust_object : $cust_object->cust_main;
 230
 231 }
 232
 233 =item option_label OPTIONNAME
 234
 235 Returns the label for the specified option name.
 236
 237 =cut
 238
 239 sub option_label {
 240   my( $self, $optionname ) = @_;
 241
 242   my %option_fields = $self->option_fields;
 243
 244   ref( $option_fields{$optionname} )
 245     ? $option_fields{$optionname}->{'label'}
 246     : $option_fields{$optionname}
 247   or $optionname;
 248 }
 249
 250 =back
 251
 252 =item condition_sql_option
 253
 254 This is a class method that returns an SQL fragment for retreiving a condition
 255 option.  It is primarily intended for use in B<condition_sql>.
 256 =cut
 257
 258 sub condition_sql_option {
 259   my( $class, $option ) = @_;
 260
 261   ( my $condname = $class ) =~ s/^.*:://;
 262
 263   "( SELECT optionvalue FROM part_event_condition_option
 264       WHERE part_event_condition_option.eventconditionnum =
 265             cond_$condname.eventconditionnum
 266         AND part_event_condition_option.optionname = '$option'
 267    )";
 268 }
 269
 270
 271 =head1 NEW CONDITION CLASSES
 272
 273 A module should be added in FS/FS/part_event/Condition/ which implements the
 274 methods desribed above in L</METHODS>.  An example may be found in the
 275 eg/part_event-Condition-template.pm file.
 276
 277 =cut
 278
 279 1;
 280
 281