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 do_action CUSTOMER_EVENT_OBJECT
 156
 157 Action classes must define an action method.  This method is triggered if
 158 all conditions have been met.
 159
 160 The object which triggered the event (an FS::cust_main, FS::cust_bill or
 161 FS::cust_pkg object) is passed as an argument.
 162
 163 To retreive option values, call the option method on the desired option, i.e.:
 164
 165   my( $self, $cust_object ) = @_;
 166   $value_of_field = $self->option('field');
 167
 168 To indicate sucessful completion, simply return.  Optionally, you can return a
 169 string of information status information about the sucessful completion, or
 170 simply return the empty string.
 171
 172 To indicate a failure and that this event should retry, die with the desired
 173 error message.
 174
 175 =back
 176
 177 =head1 BASE METHODS
 178
 179 These methods are defined in the base class for use in action classes.
 180
 181 =over 4
 182
 183 =item cust_main CUST_OBJECT
 184
 185 Return the customer object (see L<FS::cust_main>) associated with the provided
 186 object (the object itself if it is already a customer object).
 187
 188 =cut
 189
 190 sub cust_main {
 191   my( $self, $cust_object ) = @_;
 192
 193   $cust_object->isa('FS::cust_main') ? $cust_object : $cust_object->cust_main;
 194
 195 }
 196
 197 =item cust_pkg OBJECT
 198
 199 Return the package object (L<FS::cust_pkg>) associated with the provided
 200 object.  The object must be either a service (L<FS::svc_Common>) or a
 201 package.
 202
 203 =cut
 204
 205 sub cust_pkg {
 206   my( $self, $object ) = @_;
 207   $object->isa('FS::cust_pkg')      ? $object :
 208   $object->isa('FS::svc_Common')    ? $object->cust_svc->cust_pkg :
 209   undef;
 210 }
 211
 212 =item option_label OPTIONNAME
 213
 214 Returns the label for the specified option name.
 215
 216 =cut
 217
 218 sub option_label {
 219   my( $self, $optionname ) = @_;
 220
 221   my %option_fields = $self->option_fields;
 222
 223   ref( $option_fields{$optionname} )
 224     ? $option_fields{$optionname}->{'label'}
 225     : $option_fields{$optionname}
 226   or $optionname;
 227 }
 228
 229 =item option_fields_hashref
 230
 231 Returns the option fields as an (ordered) hash reference.
 232
 233 =cut
 234
 235 sub option_fields_hashref {
 236   my $self = shift;
 237   tie my %hash, 'Tie::IxHash', $self->option_fields;
 238   \%hash;
 239 }
 240
 241 =item option_fields_listref
 242
 243 Returns just the option field names as a list reference.
 244
 245 =cut
 246
 247 sub option_fields_listref {
 248   my $self = shift;
 249   my $hashref = $self->option_fields_hashref;
 250   [ keys %$hashref ];
 251 }
 252
 253 =back
 254
 255 =cut
 256
 257 1;
 258