FS/FS/cust_location.pm

   1 package FS::cust_location;
   2
   3 use strict;
   4 use base qw( FS::Record );
   5 use Locale::Country;
   6 use FS::Record qw( qsearch ); #qsearchs );
   7 use FS::cust_main;
   8 use FS::cust_main_county;
   9
  10 =head1 NAME
  11
  12 FS::cust_location - Object methods for cust_location records
  13
  14 =head1 SYNOPSIS
  15
  16   use FS::cust_location;
  17
  18   $record = new FS::cust_location \%hash;
  19   $record = new FS::cust_location { 'column' => 'value' };
  20
  21   $error = $record->insert;
  22
  23   $error = $new_record->replace($old_record);
  24
  25   $error = $record->delete;
  26
  27   $error = $record->check;
  28
  29 =head1 DESCRIPTION
  30
  31 An FS::cust_location object represents a customer location.  FS::cust_location
  32 inherits from FS::Record.  The following fields are currently supported:
  33
  34 =over 4
  35
  36 =item locationnum
  37
  38 primary key
  39
  40 =item custnum
  41
  42 custnum
  43
  44 =item address1
  45
  46 Address line one (required)
  47
  48 =item address2
  49
  50 Address line two (optional)
  51
  52 =item city
  53
  54 City
  55
  56 =item county
  57
  58 County (optional, see L<FS::cust_main_county>)
  59
  60 =item state
  61
  62 State (see L<FS::cust_main_county>)
  63
  64 =item zip
  65
  66 Zip
  67
  68 =item country
  69
  70 Country (see L<FS::cust_main_county>)
  71
  72 =item geocode
  73
  74 Geocode
  75
  76 =back
  77
  78 =head1 METHODS
  79
  80 =over 4
  81
  82 =item new HASHREF
  83
  84 Creates a new location.  To add the location to the database, see L<"insert">.
  85
  86 Note that this stores the hash reference, not a distinct copy of the hash it
  87 points to.  You can ask the object for a copy with the I<hash> method.
  88
  89 =cut
  90
  91 sub table { 'cust_location'; }
  92
  93 =item insert
  94
  95 Adds this record to the database.  If there is an error, returns the error,
  96 otherwise returns false.
  97
  98 =item delete
  99
 100 Delete this record from the database.
 101
 102 =item replace OLD_RECORD
 103
 104 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 105 returns the error, otherwise returns false.
 106
 107 =item check
 108
 109 Checks all fields to make sure this is a valid location.  If there is
 110 an error, returns the error, otherwise returns false.  Called by the insert
 111 and replace methods.
 112
 113 =cut
 114
 115 #some false laziness w/cust_main, but since it should eventually lose these
 116 #fields anyway...
 117 sub check {
 118   my $self = shift;
 119
 120   my $error =
 121     $self->ut_numbern('locationnum')
 122     || $self->ut_foreign_key('custnum', 'cust_main', 'custnum')
 123     || $self->ut_text('address1')
 124     || $self->ut_textn('address2')
 125     || $self->ut_text('city')
 126     || $self->ut_textn('county')
 127     || $self->ut_textn('state')
 128     || $self->ut_country('country')
 129     || $self->ut_zip('zip', $self->country)
 130     || $self->ut_alphan('geocode')
 131   ;
 132   return $error if $error;
 133
 134   unless ( qsearch('cust_main_county', {
 135     'country' => $self->country,
 136     'state'   => '',
 137    } ) ) {
 138     return "Unknown state/county/country: ".
 139       $self->state. "/". $self->county. "/". $self->country
 140       unless qsearch('cust_main_county',{
 141         'state'   => $self->state,
 142         'county'  => $self->county,
 143         'country' => $self->country,
 144       } );
 145   }
 146
 147   $self->SUPER::check;
 148 }
 149
 150 =item country_full
 151
 152 Returns this locations's full country name
 153
 154 =cut
 155
 156 sub country_full {
 157   my $self = shift;
 158   code2country($self->country);
 159 }
 160
 161 =item location_label [ OPTION => VALUE ... ]
 162
 163 Returns the label of the service location for this customer.
 164
 165 Options are
 166
 167 =over 4
 168
 169 =item join_string
 170
 171 used to separate the address elements (defaults to ', ')
 172
 173 =item escape_function
 174
 175
 176 a callback used for escaping the text of the address elements
 177
 178 =back
 179
 180 =cut
 181
 182 # false laziness with FS::cust_main::location_label
 183
 184 sub location_label {
 185   my $self = shift;
 186   my %opt = @_;
 187
 188   my $separator = $opt{join_string} || ', ';
 189   my $escape = $opt{escape_function} || sub{ shift };
 190   my $line = '';
 191   my $cydefault = FS::conf->new->config('countrydefault') || 'US';
 192   my $prefix = '';
 193
 194   my $notfirst = 0;
 195   foreach (qw ( address1 address2 ) ) {
 196     my $method = "$prefix$_";
 197     $line .= ($notfirst ? $separator : ''). &$escape($self->$method)
 198       if $self->$method;
 199     $notfirst++;
 200   }
 201   $notfirst = 0;
 202   foreach (qw ( city county state zip ) ) {
 203     my $method = "$prefix$_";
 204     if ( $self->$method ) {
 205       $line .= '(' if $method eq 'county';
 206       $line .= ($notfirst ? ' ' : $separator). &$escape($self->$method);
 207       $line .= ')' if $method eq 'county';
 208       $notfirst++;
 209     }
 210   }
 211   $line .= $separator. &$escape(code2country($self->country))
 212     if $self->country ne $cydefault;
 213
 214   $line;
 215 }
 216
 217 =item line
 218
 219 Synonym for location_label
 220
 221 =cut
 222
 223 sub line {
 224   my $self = shift;
 225   $self->location_label;
 226 }
 227
 228 =back
 229
 230 =head1 BUGS
 231
 232 Not yet used for cust_main billing and shipping addresses.
 233
 234 =head1 SEE ALSO
 235
 236 L<FS::cust_main_county>, L<FS::cust_pkg>, L<FS::Record>,
 237 schema.html from the base documentation.
 238
 239 =cut
 240
 241 1;
 242