1 package FS::part_event::Condition;
4 use base qw( FS::part_event_condition );
8 FS::part_event::Condition - Base class for event conditions
12 package FS::part_event::Condition::mycondition;
14 use base FS::part_event::Condition;
18 FS::part_event::Condition is a base class for event conditions classes.
22 These methods are implemented in each condition class.
28 Condition classes must define a description method. This method should return
29 a scalar description of the condition.
31 =item eventtable_hashref
33 Condition classes must define an eventtable_hashref method if they can only be
34 tested against some kinds of tables. This method should return a hash reference
35 of eventtables (values set true indicate the condition can be tested):
37 sub eventtable_hashref {
41 'cust_pay_batch' => 0,
48 sub eventtable_hashref {
52 'cust_pay_batch' => 1,
58 Condition classes may define an option_fields method to indicate that they
59 accept one or more options.
61 This method should return a list of option names and option descriptions.
62 Each option description can be a scalar description, for simple options, or a
63 hashref with the following values:
67 =item label - Description
69 =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 =item options - For checkbox-multiple and select, a list reference of available option values.
73 =item option_labels - For checkbox-multiple (and select?), a hash reference of availble option values and labels.
75 =item value - for checkbox, fixed, hidden (also a default for text, money, more?)
77 =item table - for select-table
79 =item name_col - for select-table
81 =item NOTE: See httemplate/elements/select-table.html for a full list of the optinal options for the select-table type
85 NOTE: A database connection is B<not> yet available when this subroutine is
92 'field' => 'description',
94 'another_field' => { 'label'=>'Amount', 'type'=>'money', },
96 'third_field' => { 'label' => 'Types',
97 'type' => 'checkbox-multiple',
98 'options' => [ 'h', 's' ],
99 'option_labels' => { 'h' => 'Happy',
112 =item condition CUSTOMER_EVENT_OBJECT
114 Condition classes must define a condition method. This method is evaluated
115 to determine if the condition has been met. The object which triggered the
116 event (an FS::cust_main, FS::cust_bill or FS::cust_pkg object) is passed as
117 the first argument. Additional arguments are list of key-value pairs.
119 To retreive option values, call the option method on the desired option, i.e.:
121 my( $self, $cust_object, %opts ) = @_;
122 $value_of_field = $self->option('field');
124 Available additional arguments:
126 $time = $opt{'time'}; #use this instead of time or $^T
128 $cust_event = $opt{'cust_event'}; #to retreive the cust_event object being tested
130 Return a true value if the condition has been met, and a false value if it has
133 =item condition_sql EVENTTABLE
135 Condition classes may optionally define a condition_sql method. This B<class>
136 method should return an SQL fragment that tests for this condition. The
137 fragment is evaluated and a true value of this expression indicates that the
138 condition has been met. The event table (cust_main, cust_bill or cust_pkg) is
139 passed as an argument.
141 This method is used for optimizing event queries. You may want to add indices
142 for any columns referenced. It is acceptable to return an SQL fragment which
143 partially tests the condition; doing so will still reduce the number of
144 records which much be returned and tested with the B<condition> method.
150 my( $class, $eventtable ) = @_;
157 Condition classes may optionally define a disabled method. Returning a true
158 value disbles the condition entirely.
168 This is used internally by the I<once> and I<balance> conditions. You probably
169 do B<not> want to define this method for new custom conditions, unless you're
170 sure you want B<every> new action to start with your condition.
172 Condition classes may define an implicit_flag method that returns true to
173 indicate that all new events should start with this condition. (Currently,
174 condition classes which do so should be applicable to all kinds of
175 I<eventtable>s.) The numeric value of the flag also defines the ordering of
181 sub implicit_flag { 0; }
185 Again, used internally by the I<once> and I<balance> conditions; probably not
186 a good idea for new custom conditions.
188 Condition classes may define a remove_warning method containing a string
189 warning message to enable a confirmation dialog triggered when the condition
190 is removed from an event.
195 sub remove_warning { ''; }
199 This is used internally by the I<balance_age> and I<cust_bill_age> conditions
200 to declare ordering; probably not of general use for new custom conditions.
202 =item order_sql_weight
204 In conjunction with order_sql, this defines which order the ordering fragments
205 supplied by different B<order_sql> should be used.
209 sub order_sql_weight { ''; }
215 These methods are defined in the base class for use in condition classes.
219 =item cust_main CUST_OBJECT
221 Return the customer object (see L<FS::cust_main>) associated with the provided
222 object (the object itself if it is already a customer object).
227 my( $self, $cust_object ) = @_;
229 $cust_object->isa('FS::cust_main') ? $cust_object : $cust_object->cust_main;
233 =item option_label OPTIONNAME
235 Returns the label for the specified option name.
240 my( $self, $optionname ) = @_;
242 my %option_fields = $self->option_fields;
244 ref( $option_fields{$optionname} )
245 ? $option_fields{$optionname}->{'label'}
246 : $option_fields{$optionname}
252 =item condition_sql_option
254 This is a class method that returns an SQL fragment for retreiving a condition
255 option. It is primarily intended for use in B<condition_sql>.
258 sub condition_sql_option {
259 my( $class, $option ) = @_;
261 ( my $condname = $class ) =~ s/^.*:://;
263 "( SELECT optionvalue FROM part_event_condition_option
264 WHERE part_event_condition_option.eventconditionnum =
265 cond_$condname.eventconditionnum
266 AND part_event_condition_option.optionname = '$option'
271 =head1 NEW CONDITION CLASSES
273 A module should be added in FS/FS/part_event/Condition/ which implements the
274 methods desribed above in L</METHODS>. An example may be found in the
275 eg/part_event-Condition-template.pm file.