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