-package FS::part_sb_field;
-
-use strict;
-use vars qw( @ISA );
-use FS::Record qw( qsearchs );
-
-@ISA = qw( FS::Record );
-
-=head1 NAME
-
-FS::part_sb_field - Object methods for part_sb_field records
-
-=head1 SYNOPSIS
-
- use FS::part_sb_field;
-
- $record = new FS::part_sb_field \%hash;
- $record = new FS::part_sb_field { 'column' => 'value' };
-
- $error = $record->insert;
-
- $error = $new_record->replace($old_record);
-
- $error = $record->delete;
-
- $error = $record->check;
-
-=head1 DESCRIPTION
-
-An FS::part_sb_field object represents an extended field (xfield) definition
-for svc_broadband's sb_field mechanism (see L<FS::svc_broadband>).
-FS::part_sb_field inherits from FS::Record. The following fields are
-currently supported:
-
-=over 2
-
-=item sbfieldpart - primary key (assigned automatically)
-
-=item name - name of the field
-
-=item svcpart - service type for which this field is available (see L<FS::part_svc>)
-
-=item length - length of the contents of the field (see note #1)
-
-=item check_block - validation routine (see note #2)
-
-=item list_source - enumeration routine (see note #3)
-
-=back
-
-=head1 BACKGROUND
-
-Broadband services, unlike dialup services, are provided over a wide
-variety of physical media (DSL, wireless, cable modems, digital circuits)
-and network architectures (Ethernet, PPP, ATM). For many of these access
-mechanisms, adding a new customer requires knowledge of some properties
-of the physical connection (circuit number, the type of CPE in use, etc.).
-It is unreasonable to expect ISPs to alter Freeside's schema (and the
-associated library and UI code) to make each of these parameters a field in
-svc_broadband.
-
-Hence sb_field and part_sb_field. They allow the Freeside administrator to
-define 'extended fields' ('xfields') associated with svc_broadband records.
-These are I<not> processed in any way by Freeside itself; they exist solely for
-use by exports (see L<FS::part_export>) and technical support staff.
-
-For a parallel mechanism (at the per-router level rather than per-service),
-see L<FS::part_router_field>.
-
-=head1 METHODS
-
-=over 4
-
-=item new HASHREF
-
-Create a new record. To add the record to the database, see "insert".
-
-=cut
-
-sub table { 'part_sb_field'; }
-
-=item insert
-
-Adds this record to the database. If there is an error, returns the error,
-otherwise returns false.
-
-=item delete
-
-Deletes this record from the database. If there is an error, returns the
-error, otherwise returns false.
-
-=item replace OLD_RECORD
-
-Replaces OLD_RECORD with this one in the database. If there is an error,
-returns the error, otherwise returns false.
-
-=item check
-
-Checks all fields to make sure this is a valid record. If there is an error,
-returns the error, otherwise returns false. Called by the insert and replace
-methods.
-
-=cut
-
-sub check {
- my $self = shift;
- my $error = '';
-
- $error = $self->ut_numbern('svcpart');
- return $error if $error;
-
- unless (qsearchs('part_svc', { svcpart => $self->svcpart }))
- { return "Unknown svcpart: " . $self->svcpart;}
-
- $self->name =~ /^([a-z0-9_\-\.]{1,15})$/i
- or return "Invalid field name for part_sb_field";
-
- #How to check input_block, display_block, and check_block?
-
- ''; #no error
-}
-
-=item list_values
-
-If the I<list_source> field is set, this method eval()s it and
-returns its output. If the field is empty, list_values returns
-an empty list.
-
-Any arguments passed to this method will be received by the list_source
-code, but this behavior is a fortuitous accident and may be removed in
-the future.
-
-=cut
-
-sub list_values {
- my $self = shift;
- return () unless $self->list_source;
-
- my @opts = eval($self->list_source);
- if($@) {
- warn $@;
- return ();
- } else {
- return @opts;
- }
-}
-
-=item part_svc
-
-Returns the FS::part_svc object associated with this field definition.
-
-=cut
-
-sub part_svc {
- my $self = shift;
- return qsearchs('part_svc', { svcpart => $self->svcpart });
-}
-
-=back
-
-=head1 VERSION
-
-$Id:
-
-=head1 NOTES
-
-=over
-
-=item 1.
-
-The I<length> field is not enforced. It provides a hint to UI
-code about how to display the field on a form. If you want to enforce a
-minimum or maximum length for a field, use a I<check_block>.
-
-=item 2.
-
-The check_block mechanism used here as well as in
-FS::part_router_field allows the user to define validation rules.
-
-When FS::sb_field::check is called, the proposed value of the xfield is
-assigned to $_. The check_block is then eval()'d and its return value
-captured. If the return value is false (empty/zero/undef), $_ is then assigned
-back into the field and stored in the database.
-
-Therefore a check_block can do three different things with the value: allow
-it, allow it with a modification, or reject it. This is very flexible, but
-somewhat dangerous. Some warnings:
-
-=over 2
-
-=item *
-
-Assume that $_ has had I<no> error checking prior to the
-check_block. That's what the check_block is for, after all. It could
-contain I<anything>: evil shell commands in backquotes, 100kb JPEG images,
-the Klez virus, whatever.
-
-=item *
-
-If your check_block modifies the input value, it should probably
-produce a value that wouldn't be modified by going through the same
-check_block again. (That is, it should map input values into its own
-eigenspace.) The reason is that if someone calls $new->replace($old),
-where $new and $old contain the same value for the field, they probably
-want the field to keep its old value, not to get transformed by the
-check_block again. So don't do silly things like '$_++' or
-'tr/A-Za-z/a-zA-Z/'.
-
-=item *
-
-Don't alter the contents of the database. I<Reading> the database
-is perfectly reasonable, but writing to it is a bad idea. Remember that
-check() might get called more than once, as described above.
-
-=item *
-
-The check_block probably won't even get called if the user submits
-an I<empty> sb_field. So at present, you can't set up a default value with
-something like 's/^$/foo/'. Conversely, don't replace the submitted value
-with an empty string. It probably will get stored, but might be deleted at
-any time.
-
-=back
-
-=item 3.
-
-The list_source mechanism is a UI hint (like length) to generate
-drop-down or list boxes. If list_source contains a value, the UI code can
-eval() it and use the results as the options on the list.
-
-Note 'can'. This is not a substitute for check_block. The HTML interface
-currently requires that the user pick one of the options on the list
-because that's the way HTML drop-down boxes work, but in the future the UI
-code might add an 'Other (please specify)' option and a text box so that
-the user can enter something else. Or it might ignore list_source and just
-generate a text box. Or the interface might be rewritten in MS Access,
-where drop-down boxes have text boxes built in. Data validation is the job
-of check(), not the front end.
-
-Note also that a list of literals evaluates to itself, so a list_source
-like
-
-C<('Windows', 'MacOS', 'Linux')>
-
-or
-
-C<qw(Windows MacOS Linux)>
-
-means exactly what you'd think.
-
-=head1 BUGS
-
-The lack of any way to do default values. We might add this as another UI
-hint (since, for the most part, it's the UI's job to figure out which fields
-have had values entered into them). In fact, there are lots of things we
-should add as UI hints.
-
-Oh, and the documentation is probably full of lies.
-
-=head1 SEE ALSO
-
-FS::svc_broadband, FS::sb_field, schema.html from the base documentation.
-
-=cut
-
-1;
-
projects / freeside.git / commitdiff