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 options - For checkbox-multiple and select, a list reference of available option values.
  89
  90 =item option_labels - For select, a hash reference of availble option values and labels.
  91
  92 =item value - for checkbox, fixed, hidden
  93
  94 =item table - for select-table
  95
  96 =item name_col - for select-table
  97
  98 =item NOTE: See httemplate/elements/select-table.html for a full list of the optinal options for the select-table type
  99
 100 =back
 101
 102 NOTE: A database connection is B<not> yet available when this subroutine is
 103 executed.
 104
 105 Example:
 106
 107   sub option_fields {
 108     (
 109       'field'         => 'description',
 110
 111       'another_field' => { 'label'=>'Amount', 'type'=>'money', },
 112
 113       'third_field'   => { 'label'         => 'Types',
 114                            'type'          => 'select',
 115                            'options'       => [ 'h', 's' ],
 116                            'option_labels' => { 'h' => 'Happy',
 117                                                 's' => 'Sad',
 118                                               },
 119     );
 120   }
 121
 122 =cut
 123
 124 #fallback
 125 sub option_fields {
 126   ();
 127 }
 128
 129 =item default_weight
 130
 131 Action classes may define a default weighting.  Weights control execution order
 132 relative to other actions (that are triggered at the same time).
 133
 134 =cut
 135
 136 #fallback
 137 sub default_weight {
 138   100;
 139 }
 140
 141 =item deprecated
 142
 143 Action classes may define a deprecated method that returns true, indicating
 144 that this action is deprecated.
 145
 146 =cut
 147
 148 #default
 149 sub deprecated {
 150   0;
 151 }
 152
 153 =item do_action CUSTOMER_EVENT_OBJECT
 154
 155 Action classes must define an action method.  This method is triggered if
 156 all conditions have been met.
 157
 158 The object which triggered the event (an FS::cust_main, FS::cust_bill or
 159 FS::cust_pkg object) is passed as an argument.
 160
 161 To retreive option values, call the option method on the desired option, i.e.:
 162
 163   my( $self, $cust_object ) = @_;
 164   $value_of_field = $self->option('field');
 165
 166 To indicate sucessful completion, simply return.  Optionally, you can return a
 167 string of information status information about the sucessful completion, or
 168 simply return the empty string.
 169
 170 To indicate a failure and that this event should retry, die with the desired
 171 error message.
 172
 173 =back
 174
 175 =head1 BASE METHODS
 176
 177 These methods are defined in the base class for use in action classes.
 178
 179 =over 4
 180
 181 =item cust_main CUST_OBJECT
 182
 183 Return the customer object (see L<FS::cust_main>) associated with the provided
 184 object (the object itself if it is already a customer object).
 185
 186 =cut
 187
 188 sub cust_main {
 189   my( $self, $cust_object ) = @_;
 190
 191   $cust_object->isa('FS::cust_main') ? $cust_object : $cust_object->cust_main;
 192
 193 }
 194
 195 =item cust_pkg OBJECT
 196
 197 Return the package object (L<FS::cust_pkg>) associated with the provided
 198 object.  The object must be either a service (L<FS::svc_Common>) or a
 199 package.
 200
 201 =cut
 202
 203 sub cust_pkg {
 204   my( $self, $object ) = @_;
 205   $object->isa('FS::cust_pkg')      ? $object :
 206   $object->isa('FS::svc_Common')    ? $object->cust_svc->cust_pkg :
 207   undef;
 208 }
 209
 210 =item option_label OPTIONNAME
 211
 212 Returns the label for the specified option name.
 213
 214 =cut
 215
 216 sub option_label {
 217   my( $self, $optionname ) = @_;
 218
 219   my %option_fields = $self->option_fields;
 220
 221   ref( $option_fields{$optionname} )
 222     ? $option_fields{$optionname}->{'label'}
 223     : $option_fields{$optionname}
 224   or $optionname;
 225 }
 226
 227 =item option_fields_hashref
 228
 229 Returns the option fields as an (ordered) hash reference.
 230
 231 =cut
 232
 233 sub option_fields_hashref {
 234   my $self = shift;
 235   tie my %hash, 'Tie::IxHash', $self->option_fields;
 236   \%hash;
 237 }
 238
 239 =item option_fields_listref
 240
 241 Returns just the option field names as a list reference.
 242
 243 =cut
 244
 245 sub option_fields_listref {
 246   my $self = shift;
 247   my $hashref = $self->option_fields_hashref;
 248   [ keys %$hashref ];
 249 }
 250
 251 =back
 252
 253 =cut
 254
 255 1;
 256