1 package FS::part_virtual_field;
5 use FS::Record qw( qsearchs qsearch dbdef );
7 @ISA = qw( FS::Record );
11 FS::part_virtual_field - Object methods for part_virtual_field records
15 use FS::part_virtual_field;
17 $record = new FS::part_virtual_field \%hash;
18 $record = new FS::part_virtual_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_virtual_field object represents the definition of a virtual field
31 (see the BACKGROUND section). FS::part_virtual_field contains the name and
32 base table of the field, as well as validation rules and UI hints about the
33 display of the field. The actual data is stored in FS::virtual_field; see
34 its manpage for details.
36 FS::part_virtual_field inherits from FS::Record. The following fields are
41 =item vfieldpart - primary key (assigned automatically)
43 =item name - name of the field
45 =item dbtable - table for which this virtual field is defined
47 =item check_block - Perl code to validate/normalize data
49 =item list_source - Perl code to generate a list of values (UI hint)
51 =item length - expected length of the value (UI hint)
53 =item label - descriptive label for the field (UI hint)
55 =item sequence - sort key (UI hint; unimplemented)
61 "Form is none other than emptiness,
62 and emptiness is none other than form."
65 The virtual field mechanism allows site admins to make trivial changes to
66 the Freeside database schema without modifying the code. Specifically, the
67 user can add custom-defined 'fields' to the set of data tracked by Freeside
68 about objects such as customers and services. These fields are not associated
69 with any logic in the core Freeside system, but may be referenced in peripheral
70 code such as exports, price calculations, or alternate interfaces, or may just
71 be stored in the database for future reference.
73 This system was originally devised for svc_broadband, which (by necessity)
74 comprises such a wide range of access technologies that no static set of fields
75 could contain all the information needed by the exports. In an appalling
76 display of False Laziness, a parallel mechanism was implemented for the
77 router table, to store properties such as passwords to configure routers.
79 The original system treated svc_broadband custom fields (sb_fields) as records
80 in a completely separate table. Any code that accessed or manipulated these
81 fields had to be aware that they were I<not> fields in svc_broadband, but
82 records in sb_field. For example, code that inserted a svc_broadband with
83 several custom fields had to create an FS::svc_broadband object, call its
84 insert() method, and then create several FS::sb_field objects and call I<their>
87 This created a problem for exports. The insert method on any FS::svc_Common
88 object (including svc_broadband) automatically triggers exports after the
89 record has been inserted. However, at this point, the sb_fields had not yet
90 been inserted, so the export could not rely on their presence, which was the
91 original purpose of sb_fields.
93 Hence the new system. Virtual fields are appended to the field list of every
94 record at the FS::Record level, whether the object is created ex nihilo with
95 new() or fetched with qsearch(). The fields() method now returns a list of
96 both real and virtual fields. The insert(), replace(), and delete() methods
97 now update both the base table and the virtual fields, in a single transaction.
99 A new method is provided, virtual_fields(), which gives only the virtual
100 fields. UI code that dynamically generates form widgets to edit virtual field
101 data should use this to figure out what fields are defined. (See below.)
103 Subclasses may override virtual_fields() to restrict the set of virtual
104 fields available. Some discipline and sanity on the part of the programmer
105 are required; in particular, this function should probably not depend on any
106 fields in the record other than the primary key, since the others may change
107 after the object is instantiated. (Making it depend on I<virtual> fields is
108 just asking for pain.) One use of this is seen in FS::svc_Common; another
109 possibility is field-level access control based on FS::UID::getotaker().
111 As a trivial case, a subclass may opt out of supporting virtual fields with
114 sub virtual_fields { () }
122 Create a new record. To add the record to the database, see "insert".
126 sub table { 'part_virtual_field'; }
127 sub virtual_fields { () }
131 Adds this record to the database. If there is an error, returns the error,
132 otherwise returns false.
136 Deletes this record from the database. If there is an error, returns the
137 error, otherwise returns false.
139 =item replace OLD_RECORD
141 Replaces OLD_RECORD with this one in the database. If there is an error,
142 returns the error, otherwise returns false.
146 If there is an error, returns the error, otherwise returns false.
147 Called by the insert and replace methods.
156 my $error = $self->ut_text('name') ||
157 $self->ut_text('dbtable') ||
158 $self->ut_number('length')
160 return $error if $error;
162 # Make sure it's a real table with a numeric primary key
164 if($table = $FS::Record::dbdef->table($self->dbtable)) {
165 if($pkey = $table->primary_key) {
166 if($table->column($pkey)->type =~ /int/i) {
167 # this is what it should be
169 $error = "$table.$pkey is not an integer";
172 $error = "$table does not have a single-field primary key";
175 $error = "$table does not exist in the schema";
177 return $error if $error;
179 # Possibly some sanity checks for check_block and list_source?
186 Evaluates list_source.
192 return () unless $self->list_source;
194 my @opts = eval($self->list_source);
203 =item widget UI_TYPE MODE [ VALUE ]
205 Generates UI code for a widget suitable for editing/viewing the field, based on
206 list_source and length.
208 The only UI_TYPE currently supported is 'HTML', and the only MODE is 'view'.
209 Others will be added later.
211 In HTML, all widgets are assumed to be table rows. View widgets look like
212 <TR><TD ALIGN="right">Label</TD><TD BGCOLOR="#ffffff">Value</TD></TR>
214 (Most of the display style stuff, such as the colors, should probably go into
215 a separate module specific to the UI. That can wait, though. The API for
216 this function won't change.)
218 VALUE (optional) is the current value of the field.
224 my ($ui_type, $mode, $value) = @_;
226 my $label = $self->label || $self->name;
228 if ($ui_type eq 'HTML') {
229 if ($mode eq 'view') {
230 $text = q!<TR><TD ALIGN="right">! . $label .
231 q!</TD><TD BGCOLOR="#ffffff">! . $value .
232 q!</TD></TR>! . "\n";
233 } elsif ($mode eq 'edit') {
234 $text = q!<TR><TD ALIGN="right">! . $label .
236 if ($self->list_source) {
237 $text .= q!<SELECT NAME="! . $self->name .
239 foreach ($self->list) {
240 $text .= q!<OPTION VALUE="! . $_ . q!"!;
241 $text .= ' SELECTED' if ($_ eq $value);
242 $text .= '>' . $_ . '</OPTION>' . "\n";
245 $text .= q!<INPUT NAME="! . $self->name .
246 q!" VALUE="! . $value . q!"!;
248 $text .= q! SIZE="! . $self->length . q!"!;
252 $text .= q!</TD></TR>! . "\n";
264 =head2 Semantics of check_block:
266 This has been changed from the sb_field implementation to make check_blocks
267 simpler and more natural to Perl programmers who work on things other than
270 The check_block is eval'd with the (proposed) new value of the field in $_,
271 and the object to be updated in $self. Its return value is ignored. The
272 check_block may change the value of $_ to override the proposed value, or
273 call die() (with an appropriate error message) to reject the update entirely;
274 the error string will be returned as the output of the check() method.
276 This makes check_blocks like
282 The check_block is expected NOT to do anything freaky to $self, like modifying
283 other fields or calling $self->check(). You have been warned.
285 (FIXME: Rewrite some of the warnings from part_sb_field and insert here.)
289 None. It's absolutely falwless.
293 L<FS::Record>, L<FS::virtual_field>