| 1 | # BingoX::Argon | ||
| 2 | # ----------------- | ||
| 3 | # $Revision: 2.9 $ | ||
| 4 | # $Date: 2001/11/20 19:11:14 $ | ||
| 5 | # --------------------------------------------------------- | ||
| 6 | |||
| 7 | =head1 NAME | ||
| 8 | |||
| 9 | Argon - Common methods used by many application classes. | ||
| 10 | |||
| 11 | =head1 SYNOPSIS | ||
| 12 | |||
| 13 | package MyApplication; | ||
| 14 | @MyApplication::ISA = qw(BingoX::Argon); | ||
| 15 | use BingoX::Argon; | ||
| 16 | |||
| 17 | # $BR - Blessed Reference | ||
| 18 | # $SV - Scalar Value | ||
| 19 | # @AV - Array Value | ||
| 20 | # $HR - Hash Ref | ||
| 21 | # $AR - Array Ref | ||
| 22 | # $SR - Stream Ref | ||
| 23 | |||
| 24 | # $proto - BingoX::Carbon object OR sub-class | ||
| 25 | # $object - BingoX::Carbon object | ||
| 26 | |||
| 27 | $BR = $proto->new() | ||
| 28 | $BR = $app->r() | ||
| 29 | $BR = $app->dbh() | ||
| 30 | $BR = $app->cgi() | ||
| 31 | $BR = $app->conf() | ||
| 32 | $app->include() | ||
| 33 | $app->xinclude() | ||
| 34 | $HR = $app->display_classes() | ||
| 35 | $BR = $app->get() | ||
| 36 | $AR = $app->list() | ||
| 37 | $SR = $app->stream() | ||
| 38 | |||
| 39 | =head1 REQUIRES | ||
| 40 | |||
| 41 | Apache::XPP | ||
| 42 | |||
| 43 | =head1 EXPORTS | ||
| 44 | |||
| 45 | Nothing | ||
| 46 | |||
| 47 | =head1 DESCRIPTION | ||
| 48 | |||
| 49 | BingoX::Argon is an application superclass that handles basic tasks like returning | ||
| 50 | display objects, handling xincludes, and caching request and cgi objects. | ||
| 51 | |||
| 52 | I'm hoping it won't do too much else: Display classes have to do SOMETHING, | ||
| 53 | don't they? | ||
| 54 | |||
| 55 | =head1 CLASS VARIABLES | ||
| 56 | |||
| 57 | =over 4 | ||
| 58 | |||
| 59 | =item * %display_classes | ||
| 60 | |||
| 61 | This is how Argon will know what classes it can call. | ||
| 62 | The keys are the name of the function and the value is the class name. | ||
| 63 | |||
| 64 | For example: | ||
| 65 | %display_classes = (thingees => 'Application::Display::Thingee'); | ||
| 66 | |||
| 67 | You can then call get_ , list_ , or stream_thingees(), passing a hashref | ||
| 68 | of the data fields by which you want to limit your search. | ||
| 69 | |||
| 70 | =back | ||
| 71 | |||
| 72 | =head1 METHODS | ||
| 73 | |||
| 74 | =head2 CONSTRUCTORS | ||
| 75 | |||
| 76 | =over 4 | ||
| 77 | |||
| 78 | =cut | ||
| 79 | |||
| 80 | package BingoX::Argon; | ||
| 81 | |||
| 82 | use Apache::XPP; | ||
| 83 | |||
| 84 | use strict; | ||
| 85 | use vars qw($debug $AUTOLOAD); | ||
| 86 | |||
| 87 | BEGIN { | ||
| 88 | $BingoX::Argon::REVISION = (qw$Revision: 2.9 $)[-1]; | ||
| 89 | $BingoX::Argon::VERSION = '1.92'; | ||
| 90 | |||
| 91 | $debug = undef; | ||
| 92 | |||
| 93 | if ($debug) { | ||
| 94 | eval 'use Data::Dumper'; | ||
| 95 | } | ||
| 96 | } | ||
| 97 | |||
| 98 | =item C<new> ( [ \%data ] ) | ||
| 99 | |||
| 100 | Creates a new Application object. | ||
| 101 | |||
| 102 | =cut | ||
| 103 | sub new { | ||
| 104 | my $self = shift; | ||
| 105 | my $class = ref($self) || $self; | ||
| 106 | ## backward compatibility: $r was traditionally the first arg passed. ## | ||
| 107 | my $r = (ref($_[0]) eq 'HASH') ? $class->r : shift; | ||
| 108 | ## Next comes the (optional) data ## | ||
| 109 | my $data = shift || { }; | ||
| 110 | $data->{'_r'} ||= $r; | ||
| 111 | bless $data, $class; | ||
| 112 | } # END of new | ||
| 113 | |||
| 114 | |||
| 115 | =back | ||
| 116 | |||
| 117 | =head2 OBJECT METHODS | ||
| 118 | |||
| 119 | =over 4 | ||
| 120 | |||
| 121 | =item C<r> ( ) | ||
| 122 | |||
| 123 | returns the Display object's Apache request object. Or if for some | ||
| 124 | reason the object doesn't have one, it creates a new one. | ||
| 125 | |||
| 126 | =cut | ||
| 127 | sub r { ref($_[0]) ? $_[0]->{'_r'} ||= Apache->request : Apache->request } | ||
| 128 | |||
| 129 | |||
| 130 | =item C<available_display_classes> ( ) | ||
| 131 | |||
| 132 | Static method returns the subclass's \%display_classes. | ||
| 133 | |||
| 134 | =cut | ||
| 135 | sub display_classes { | ||
| 136 | my $self = shift; | ||
| 137 | my $class = ref($self) || $self; | ||
| 138 | no strict 'refs'; | ||
| 139 | (defined %{"${class}::display_classes"}) ? \%{"${class}::display_classes"} : { }; | ||
| 140 | } # END of display_classes | ||
| 141 | |||
| 142 | |||
| 143 | =item C<data_class> ( ) | ||
| 144 | |||
| 145 | Static method returns data class defined for application subclass. | ||
| 146 | If none is assigned, guess. :-) | ||
| 147 | |||
| 148 | =cut | ||
| 149 | sub data_class { | ||
| 150 | my $self = shift; | ||
| 151 | my $class = ref($self) || $self; | ||
| 152 | no strict 'refs'; | ||
| 153 | ${"${class}::data_class"} || $class . '::Data'; | ||
| 154 | } # END of data_class | ||
| 155 | |||
| 156 | |||
| 157 | =item C<dbh> ( ) | ||
| 158 | |||
| 159 | Caches and returns a reference to the app's Data Class dbh. | ||
| 160 | |||
| 161 | =cut | ||
| 162 | sub dbh { | ||
| 163 | my $self = shift; | ||
| 164 | my $class = ref($self) || return undef; | ||
| 165 | return $self->{'_dbh'} if (ref $self->{'_dbh'}); | ||
| 166 | $self->{'_dbh'} = $self->data_class->dbh if ($self->data_class->can('dbh')); | ||
| 167 | warn "No data classes found for $class" unless (ref $self->{'_dbh'}); | ||
| 168 | return $self->{'_dbh'}; | ||
| 169 | } # END of dbh | ||
| 170 | |||
| 171 | |||
| 172 | =item C<cgi> ( ) | ||
| 173 | |||
| 174 | Returns the current CGI object or creates a new one. | ||
| 175 | |||
| 176 | =cut | ||
| 177 | sub cgi { ref($_[0]) ? $_[0]->{'_cgi'} ||= CGI->new : CGI->new } | ||
| 178 | |||
| 179 | |||
| 180 | =item C<conf> ( ) | ||
| 181 | |||
| 182 | Caches and returns a Conf object. | ||
| 183 | Overload this if you want to use a static Conf module. | ||
| 184 | |||
| 185 | =cut | ||
| 186 | sub conf { | ||
| 187 | ref($_[0]) | ||
| 188 | ? | ||
| 189 | $_[0]->{'_conf'} ||= Conf->new( $_[0]->r->dir_config('conf') ) | ||
| 190 | : | ||
| 191 | Conf->new( $_[0]->r->dir_config('conf') ) | ||
| 192 | } # END of conf | ||
| 193 | |||
| 194 | |||
| 195 | =item C<query_url> ( ) | ||
| 196 | |||
| 197 | Returns the path of the user's location. | ||
| 198 | |||
| 199 | =cut | ||
| 200 | sub query_url { | ||
| 201 | return $_[0]->cgi->url( -ABSOLUTE => 1); | ||
| 202 | } # END of query_url | ||
| 203 | |||
| 204 | |||
| 205 | =item C<param> ( $name ) | ||
| 206 | |||
| 207 | Returns cgi params. | ||
| 208 | |||
| 209 | =cut | ||
| 210 | sub param { | ||
| 211 | my $self = shift; | ||
| 212 | return $self->cgi->param( shift() ); | ||
| 213 | } # END of param | ||
| 214 | |||
| 215 | |||
| 216 | =item C<escape> ( $name ) | ||
| 217 | |||
| 218 | Returns cgi escape. | ||
| 219 | |||
| 220 | =cut | ||
| 221 | sub escape { | ||
| 222 | my $self = shift; | ||
| 223 | return $self->cgi->escape( shift() ); | ||
| 224 | } # END of escape | ||
| 225 | |||
| 226 | |||
| 227 | =item C<delete> ( $name ) | ||
| 228 | |||
| 229 | Deletes from the cgi params. | ||
| 230 | |||
| 231 | =cut | ||
| 232 | sub delete { | ||
| 233 | my $self = shift; | ||
| 234 | my $q = $self->cgi; | ||
| 235 | foreach (@_) { $q->delete( $_ ) } | ||
| 236 | return; | ||
| 237 | } # END of delete | ||
| 238 | |||
| 239 | |||
| 240 | =item C<include> ( $template ) | ||
| 241 | |||
| 242 | Forwarding method: | ||
| 243 | |||
| 244 | Calls L<Apache::XPP>->include() and passes it the $template. | ||
| 245 | |||
| 246 | =cut | ||
| 247 | sub include { Apache::XPP->include( $_[1] ) } | ||
| 248 | |||
| 249 | |||
| 250 | =item C<xinclude> ( $template [, $obj ] ) | ||
| 251 | |||
| 252 | Forwarding method: | ||
| 253 | |||
| 254 | Includes $obj in the $template. | ||
| 255 | Calls L<Apache::XPP->xinclude()> and passes it the default array. | ||
| 256 | |||
| 257 | =cut | ||
| 258 | sub xinclude { | ||
| 259 | my $self = shift; # shift it out 'cause we ain't passing it. | ||
| 260 | Apache::XPP->xinclude( @_ ); | ||
| 261 | } # END of xinclude | ||
| 262 | |||
| 263 | |||
| 264 | =item C<AUTOLOAD> ( ) | ||
| 265 | |||
| 266 | This will first look in instance data, then go through the sub class's | ||
| 267 | %display_classes field and see if it's in %display_classes reference. | ||
| 268 | If it is, it will try and get it using passed params. | ||
| 269 | |||
| 270 | Returns undef on error. | ||
| 271 | |||
| 272 | =cut | ||
| 273 | sub AUTOLOAD { | ||
| 274 | return if $AUTOLOAD =~ /::DESTROY$/o; | ||
| 275 | my $self = shift; | ||
| 276 | my $lname = $AUTOLOAD; | ||
| 277 | $lname =~ s/^.*://o; # strip fully-qualified portion | ||
| 278 | |||
| 279 | warn("AUTOLOADing ".(ref($self)||$self)."::${lname} in BingoX::Argon") | ||
| 280 | if $debug; | ||
| 281 | |||
| 282 | ## return instance data if it exists ## | ||
| 283 | return $self->{ $lname } if (ref($self) && defined($self->{ $lname })); | ||
| 284 | |||
| 285 | ## try the methods ## | ||
| 286 | my ($prefix,$name) = split(/_/, $lname, 2); # get the type and name | ||
| 287 | |||
| 288 | ## make sure it's a "get_", "list_", or "stream_" method ## | ||
| 289 | return unless ($prefix && $name); | ||
| 290 | return undef unless ($prefix eq 'stream' || $prefix eq 'list' || $prefix eq 'get'); | ||
| 291 | my $method = $prefix . (($prefix eq 'get') ? '' : '_obj'); | ||
| 292 | ## get the associated display class (and return if you can't find it) ## | ||
| 293 | my $displayclass = $self->display_classes->{ $name } || return undef; | ||
| 294 | if ($displayclass->data_class) { | ||
| 295 | ## limit it by any params they happen to pass. ## | ||
| 296 | my $params = shift || { }; | ||
| 297 | my $q = $self->cgi; | ||
| 298 | ## and by anything in the CGI object. ## | ||
| 299 | foreach (@{ $displayclass->data_class->fieldorder }) { | ||
| 300 | ## explicitly passed params override what's in the CGI object ## | ||
| 301 | unless (exists $params->{$_}) { | ||
| 302 | $params->{$_} = $q->param($_) if (defined $q->param($_)); | ||
| 303 | warn("$displayclass: $_ ==> $params->{$_}") if $debug > 1; | ||
| 304 | } | ||
| 305 | } | ||
| 306 | warn(Data::Dumper::Dumper($params)) if $debug > 1; | ||
| 307 | ## get methods should have params of some sort ## | ||
| 308 | return undef if ($prefix eq 'get' && !%{ $params }); | ||
| 309 | return $displayclass->$method( $self, $self->dbh, $params, @_ ); | ||
| 310 | } else { # some display classes don't have data classes | ||
| 311 | return $displayclass->new( @_ ); | ||
| 312 | } | ||
| 313 | } # END of AUTOLOAD | ||
| 314 | |||
| 315 | 1; | ||
| 316 | |||
| 317 | __END__ |