1 package FS::part_sb_field;
5 use FS::Record qw( qsearchs );
7 @ISA = qw( FS::Record );
11 FS::part_sb_field - Object methods for part_sb_field records
15 use FS::part_sb_field;
17 $record = new FS::part_sb_field \%hash;
18 $record = new FS::part_sb_field { 'column' => 'value' };
20 $error = $record->insert;
22 $error = $new_record->replace($old_record);
24 $error = $record->delete;
26 $error = $record->check;
30 An FS::part_sb_field object represents an extended field (xfield) definition
31 for svc_broadband's sb_field mechanism (see L<FS::svc_broadband>).
32 FS::part_sb_field inherits from FS::Record. The following fields are
37 =item sbfieldpart - primary key (assigned automatically)
39 =item name - name of the field
41 =item svcpart - service type for which this field is available (see L<FS::part_svc>)
43 =item length - length of the contents of the field (see note #1)
45 =item check_block - validation routine (see note #2)
47 =item list_source - enumeration routine (see note #3)
53 Broadband services, unlike dialup services, are provided over a wide
54 variety of physical media (DSL, wireless, cable modems, digital circuits)
55 and network architectures (Ethernet, PPP, ATM). For many of these access
56 mechanisms, adding a new customer requires knowledge of some properties
57 of the physical connection (circuit number, the type of CPE in use, etc.).
58 It is unreasonable to expect ISPs to alter Freeside's schema (and the
59 associated library and UI code) to make each of these parameters a field in
62 Hence sb_field and part_sb_field. They allow the Freeside administrator to
63 define 'extended fields' ('xfields') associated with svc_broadband records.
64 These are I<not> processed in any way by Freeside itself; they exist solely for
65 use by exports (see L<FS::part_export>) and technical support staff.
67 For a parallel mechanism (at the per-router level rather than per-service),
68 see L<FS::part_router_field>.
76 Create a new record. To add the record to the database, see "insert".
80 sub table { 'part_sb_field'; }
84 Adds this record to the database. If there is an error, returns the error,
85 otherwise returns false.
89 Deletes this record from the database. If there is an error, returns the
90 error, otherwise returns false.
92 =item replace OLD_RECORD
94 Replaces OLD_RECORD with this one in the database. If there is an error,
95 returns the error, otherwise returns false.
99 Checks all fields to make sure this is a valid record. If there is an error,
100 returns the error, otherwise returns false. Called by the insert and replace
109 $error = $self->ut_numbern('svcpart');
110 return $error if $error;
112 unless (qsearchs('part_svc', { svcpart => $self->svcpart }))
113 { return "Unknown svcpart: " . $self->svcpart;}
115 $self->name =~ /^([a-z0-9_\-\.]{1,15})$/i
116 or return "Invalid field name for part_sb_field";
118 #How to check input_block, display_block, and check_block?
125 If the I<list_source> field is set, this method eval()s it and
126 returns its output. If the field is empty, list_values returns
129 Any arguments passed to this method will be received by the list_source
130 code, but this behavior is a fortuitous accident and may be removed in
137 return () unless $self->list_source;
139 my @opts = eval($self->list_source);
150 Returns the FS::part_svc object associated with this field definition.
156 return qsearchs('part_svc', { svcpart => $self->svcpart });
171 The I<length> field is not enforced. It provides a hint to UI
172 code about how to display the field on a form. If you want to enforce a
173 minimum or maximum length for a field, use a I<check_block>.
177 The check_block mechanism used here as well as in
178 FS::part_router_field allows the user to define validation rules.
180 When FS::sb_field::check is called, the proposed value of the xfield is
181 assigned to $_. The check_block is then eval()'d and its return value
182 captured. If the return value is false (empty/zero/undef), $_ is then assigned
183 back into the field and stored in the database.
185 Therefore a check_block can do three different things with the value: allow
186 it, allow it with a modification, or reject it. This is very flexible, but
187 somewhat dangerous. Some warnings:
193 Assume that $_ has had I<no> error checking prior to the
194 check_block. That's what the check_block is for, after all. It could
195 contain I<anything>: evil shell commands in backquotes, 100kb JPEG images,
196 the Klez virus, whatever.
200 If your check_block modifies the input value, it should probably
201 produce a value that wouldn't be modified by going through the same
202 check_block again. (That is, it should map input values into its own
203 eigenspace.) The reason is that if someone calls $new->replace($old),
204 where $new and $old contain the same value for the field, they probably
205 want the field to keep its old value, not to get transformed by the
206 check_block again. So don't do silly things like '$_++' or
211 Don't alter the contents of the database. I<Reading> the database
212 is perfectly reasonable, but writing to it is a bad idea. Remember that
213 check() might get called more than once, as described above.
217 The check_block probably won't even get called if the user submits
218 an I<empty> sb_field. So at present, you can't set up a default value with
219 something like 's/^$/foo/'. Conversely, don't replace the submitted value
220 with an empty string. It probably will get stored, but might be deleted at
227 The list_source mechanism is a UI hint (like length) to generate
228 drop-down or list boxes. If list_source contains a value, the UI code can
229 eval() it and use the results as the options on the list.
231 Note 'can'. This is not a substitute for check_block. The HTML interface
232 currently requires that the user pick one of the options on the list
233 because that's the way HTML drop-down boxes work, but in the future the UI
234 code might add an 'Other (please specify)' option and a text box so that
235 the user can enter something else. Or it might ignore list_source and just
236 generate a text box. Or the interface might be rewritten in MS Access,
237 where drop-down boxes have text boxes built in. Data validation is the job
238 of check(), not the front end.
240 Note also that a list of literals evaluates to itself, so a list_source
243 C<('Windows', 'MacOS', 'Linux')>
247 C<qw(Windows MacOS Linux)>
249 means exactly what you'd think.
253 The lack of any way to do default values. We might add this as another UI
254 hint (since, for the most part, it's the UI's job to figure out which fields
255 have had values entered into them). In fact, there are lots of things we
256 should add as UI hints.
258 Oh, and the documentation is probably full of lies.
262 FS::svc_broadband, FS::sb_field, schema.html from the base documentation.