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 option_label OPTIONNAME
 196
 197 Returns the label for the specified option name.
 198
 199 =cut
 200
 201 sub option_label {
 202   my( $self, $optionname ) = @_;
 203
 204   my %option_fields = $self->option_fields;
 205
 206   ref( $option_fields{$optionname} )
 207     ? $option_fields{$optionname}->{'label'}
 208     : $option_fields{$optionname}
 209   or $optionname;
 210 }
 211
 212 =item option_fields_hashref
 213
 214 Returns the option fields as an (ordered) hash reference.
 215
 216 =cut
 217
 218 sub option_fields_hashref {
 219   my $self = shift;
 220   tie my %hash, 'Tie::IxHash', $self->option_fields;
 221   \%hash;
 222 }
 223
 224 =item option_fields_listref
 225
 226 Returns just the option field names as a list reference.
 227
 228 =cut
 229
 230 sub option_fields_listref {
 231   my $self = shift;
 232   my $hashref = $self->option_fields_hashref;
 233   [ keys %$hashref ];
 234 }
 235
 236 =back
 237
 238 =cut
 239
 240 1;
 241