FS/FS/part_event/Action.pm

   1 package FS::part_event::Action;
   2
   3 use strict;
   4 use base qw( FS::part_event );
   5 use Tie::IxHash;
   6
   7 =head1 NAME
   8
   9 FS::part_event::Action - Base class for event actions
  10
  11 =head1 SYNOPSIS
  12
  13 package FS::part_event::Action::myaction;
  14
  15 use base FS::part_event::Action;
  16
  17 =head1 DESCRIPTION
  18
  19 FS::part_event::Action is a base class for event action classes.
  20
  21 =head1 METHODS
  22
  23 These methods are implemented in each action class.
  24
  25 =over 4
  26
  27 =item description
  28
  29 Action classes must define a description method.  This method should return a
  30 scalar description of the action.
  31
  32 =item eventtable_hashref
  33
  34 Action classes must define a eventtable_hashref method if they can only be
  35 triggered against some kinds of tables.  This method should return a hash
  36 reference of eventtables (values set true indicate the action can be performed):
  37
  38   sub eventtable_hashref {
  39     { 'cust_main'      => 1,
  40       'cust_bill'      => 1,
  41       'cust_pkg'       => 0,
  42       'cust_pay_batch' => 0,
  43     };
  44   }
  45
  46 =cut
  47
  48 #fallback
  49 sub eventtable_hashref {
  50     { 'cust_main'      => 1,
  51       'cust_bill'      => 1,
  52       'cust_pkg'       => 1,
  53       'cust_pay_batch' => 1,
  54       'svc_acct'       => 1,
  55     };
  56 }
  57
  58 =item event_stage
  59
  60 Action classes may define an event_stage method to indicate a preference
  61 for being run at a non-standard stage of the billing and collection process.
  62
  63 This method may currently return "collect" (the default) or "pre-bill".
  64
  65 =cut
  66
  67 sub event_stage {
  68   'collect';
  69 }
  70
  71 =item option_fields
  72
  73 Action classes may define an option_fields method to indicate that they
  74 accept one or more options.
  75
  76 This method should return a list of option names and option descriptions.
  77 Each option description can be a scalar description, for simple options, or a
  78 hashref with the following values:
  79
  80 =over 4
  81
  82 =item label - Description
  83
  84 =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.
  85
  86 =item size - Size for text fields
  87
  88 =item validation - (optional) Validate optionvalue using the given object method, such as ut_textn, ut_email
  89
  90 =item options - For checkbox-multiple and select, a list reference of available option values.
  91
  92 =item option_labels - For select, a hash reference of availble option values and labels.
  93
  94 =item value - for checkbox, fixed, hidden
  95
  96 =item table - for select-table
  97
  98 =item name_col - for select-table
  99
 100 =item NOTE: See httemplate/elements/select-table.html for a full list of the optinal options for the select-table type
 101
 102 =back
 103
 104 NOTE: A database connection is B<not> yet available when this subroutine is
 105 executed.
 106
 107 Example:
 108
 109   sub option_fields {
 110     (
 111       'field'         => 'description',
 112
 113       'another_field' => { 'label'=>'Amount', 'type'=>'money', },
 114
 115       'third_field'   => { 'label'         => 'Types',
 116                            'type'          => 'select',
 117                            'options'       => [ 'h', 's' ],
 118                            'option_labels' => { 'h' => 'Happy',
 119                                                 's' => 'Sad',
 120                                               },
 121     );
 122   }
 123
 124 =cut
 125
 126 #fallback
 127 sub option_fields {
 128   ();
 129 }
 130
 131 =item default_weight
 132
 133 Action classes may define a default weighting.  Weights control execution order
 134 relative to other actions (that are triggered at the same time).
 135
 136 =cut
 137
 138 #fallback
 139 sub default_weight {
 140   100;
 141 }
 142
 143 =item deprecated
 144
 145 Action classes may define a deprecated method that returns true, indicating
 146 that this action is deprecated.
 147
 148 =cut
 149
 150 #default
 151 sub deprecated {
 152   0;
 153 }
 154
 155 =item will_send_invoice
 156
 157 Action classes may define a will_send_invoice method that returns true, indicating
 158 that this action is sending out an invoice.
 159
 160 =cut
 161
 162 #default
 163 sub will_send_invoice {
 164   0;
 165 }
 166
 167 =item do_action CUSTOMER_EVENT_OBJECT
 168
 169 Action classes must define an action method.  This method is triggered if
 170 all conditions have been met.
 171
 172 The object which triggered the event (an FS::cust_main, FS::cust_bill or
 173 FS::cust_pkg object) is passed as an argument.
 174
 175 To retreive option values, call the option method on the desired option, i.e.:
 176
 177   my( $self, $cust_object ) = @_;
 178   $value_of_field = $self->option('field');
 179
 180 To indicate sucessful completion, simply return.  Optionally, you can return a
 181 string of information status information about the sucessful completion, or
 182 simply return the empty string.
 183
 184 To indicate a failure and that this event should retry, die with the desired
 185 error message.
 186
 187 =back
 188
 189 =head1 BASE METHODS
 190
 191 These methods are defined in the base class for use in action classes.
 192
 193 =over 4
 194
 195 =item cust_main CUST_OBJECT
 196
 197 Return the customer object (see L<FS::cust_main>) associated with the provided
 198 object (the object itself if it is already a customer object).
 199
 200 =cut
 201
 202 sub cust_main {
 203   my( $self, $cust_object ) = @_;
 204
 205   $cust_object->isa('FS::cust_main') ? $cust_object : $cust_object->cust_main;
 206
 207 }
 208
 209 =item cust_pkg OBJECT
 210
 211 Return the package object (L<FS::cust_pkg>) associated with the provided
 212 object.  The object must be either a service (L<FS::svc_Common>) or a
 213 package.
 214
 215 =cut
 216
 217 sub cust_pkg {
 218   my( $self, $object ) = @_;
 219   $object->isa('FS::cust_pkg')      ? $object :
 220   $object->isa('FS::svc_Common')    ? $object->cust_svc->cust_pkg :
 221   undef;
 222 }
 223
 224 =item option_label OPTIONNAME
 225
 226 Returns the label for the specified option name.
 227
 228 =cut
 229
 230 sub option_label {
 231   my( $self, $optionname ) = @_;
 232
 233   my %option_fields = $self->option_fields;
 234
 235   ref( $option_fields{$optionname} )
 236     ? $option_fields{$optionname}->{'label'}
 237     : $option_fields{$optionname}
 238   or $optionname;
 239 }
 240
 241 =item option_fields_hashref
 242
 243 Returns the option fields as an (ordered) hash reference.
 244
 245 =cut
 246
 247 sub option_fields_hashref {
 248   my $self = shift;
 249   tie my %hash, 'Tie::IxHash', $self->option_fields;
 250   \%hash;
 251 }
 252
 253 =item option_fields_listref
 254
 255 Returns just the option field names as a list reference.
 256
 257 =cut
 258
 259 sub option_fields_listref {
 260   my $self = shift;
 261   my $hashref = $self->option_fields_hashref;
 262   [ keys %$hashref ];
 263 }
 264
 265 =back
 266
 267 =cut
 268
 269 1;
 270