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