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