[Openinteract-commits] CVS: OpenInteract2/lib/OpenInteract2 SPOPS.pm,1.29,1.30

[Chris W. <la...@us...>]

Update of /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21363/OpenInteract2

Modified Files:
	SPOPS.pm 
Log Message:
OIN-154: add data to object_description and make it a runtime process rather than a mostly-startup-time one

Index: SPOPS.pm
===================================================================
RCS file: /cvsroot/openinteract/OpenInteract2/lib/OpenInteract2/SPOPS.pm,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -d -r1.29 -r1.30
*** SPOPS.pm	17 Mar 2005 14:57:58 -0000	1.29
--- SPOPS.pm	17 Mar 2005 20:30:44 -0000	1.30
***************
*** 9,14 ****
  use OpenInteract2::Context   qw( CTX );
  use OpenInteract2::Exception qw( oi_error );
  use OpenInteract2::Util;
- use SPOPS::ClassFactory      qw( OK NOTIFY );
  
  $OpenInteract2::SPOPS::VERSION = sprintf("%d.%02d", q$Revision$ =~ /(\d+)\.(\d+)/);
--- 9,14 ----
  use OpenInteract2::Context   qw( CTX );
  use OpenInteract2::Exception qw( oi_error );
+ use OpenInteract2::URL;
  use OpenInteract2::Util;
  
  $OpenInteract2::SPOPS::VERSION = sprintf("%d.%02d", q$Revision$ =~ /(\d+)\.(\d+)/);
***************
*** 20,23 ****
--- 20,103 ----
  
  ########################################
+ # OBJECT DESCRIPTION
+ 
+ # overrides implementation from SPOPS.pm
+ 
+ sub object_description {
+     my ( $self ) = @_;
+     my $config = $self->CONFIG;
+     my $object_type = $config->{object_name};
+     my $title_info  = $config->{title} || $config->{name};
+     my $title = '';
+     if ( exists $self->{ $title_info } ) {
+         $title = $self->{ $title_info };
+     }
+     elsif ( $title_info ) {
+         $title = eval { $self->$title_info() };
+     }
+     $title ||= 'Cannot find name';
+ 
+     my $u = OpenInteract2::URL->new();
+     my $oid       = $self->id;
+     my $id_field  = $self->id_field;
+     my ( $url, $url_edit );
+     my $inf = $config->{display};
+     my @url_param_values = ();
+     if ( $inf->{URL_PARAMS} ) {
+         my @url_params = ( ref $inf->{URL_PARAMS} )
+                            ? @{ $inf->{URL_PARAMS} }
+                            : ( $inf->{URL_PARAMS} );
+         @url_param_values = map { eval { $self->$_() } } @url_params;
+     }
+     if ( $inf->{ACTION} ) {
+         if ( $inf->{TASK} and @url_param_values ) {
+             $url = $u->create( $inf->{ACTION}, $inf->{TASK},
+                                { URL_PARAMS => \@url_param_values } );
+         }
+         elsif ( $inf->{TASK} ) {
+             $url = $u->create( $inf->{ACTION}, $inf->{TASK},
+                                { $id_field => $oid } );
+         }
+         if ( $inf->{TASK_EDIT} and @url_param_values ) {
+             $url_edit = $u->create( $inf->{ACTION}, $inf->{TASK_EDIT},
+                                     { URL_PARAMS => \@url_param_values } );
+         }
+         elsif ( $inf->{TASK_EDIT} ) {
+             $url_edit = $u->create( $inf->{ACTION}, $inf->{TASK_EDIT},
+                                     { $id_field => $oid } );
+         }
+ 
+     }
+     else {
+         if ( $inf->{url} ) {
+             $url = "$inf->{url}?" . $id_field . '=' . $oid;
+         }
+         if ( $inf->{url_edit} ) {
+             $url_edit = "$inf->{url_edit}?" . $id_field . '=' . $oid;
+         }
+         else {
+             $url_edit = "$inf->{url}?edit=1;" . $id_field . '=' . $oid;
+         }
+     }
+     my ( $object_date );
+     if ( my $date_field = $inf->{date} ) {
+         $object_date = $self->$date_field();
+     }
+     return {
+         class       => ref $self,
+         object_id   => $oid,
+         security    => $self->{tmp_security_level},
+         oid         => $oid, # backwards compatibility
+         id_field    => $id_field,
+         name        => $object_type,
+         title       => $title,
+         date        => $object_date,
+         url         => $url,
+         url_edit    => $url_edit,
+     };
+ }
+ 
+ 
+ ########################################
  # OBJECT TRACK METHODS
  
***************
*** 315,318 ****
--- 395,543 ----
  L<OpenInteract2::SPOPS::LDAP|OpenInteract2::SPOPS::LDAP>.
  
+ =head1 DESCRIBING AN OBJECT
+ 
+ B<object_description()>
+ 
+ Very useful method you can call on any SPOPS object to get general
+ information about it. It's particularly useful when you're dealing
+ with an object of an unknown type -- such as when you're doing
+ fulltext searching or object tagging -- and need summary information
+ about it.
+ 
+ The method overrides the implementation found in L<SPOPS>, returning a
+ hashref of information with the keys:
+ 
+ =over 4
+ 
+ =item B<class>
+ 
+ Class of the object.
+ 
+ =item B<object_id>
+ 
+ ID of this particular object.
+ 
+ =item B<id_field>
+ 
+ ID field for this object.
+ 
+ =item B<name>
+ 
+ General type of this object: 'News', 'Document', etc.
+ 
+ =item B<title>
+ 
+ Title of this specific object: 'Weather tomorrow to be scorching',
+ 'Recipe: Franks and Beans', etc.
+ 
+ =item B<date>
+ 
+ Date associated with this object, typically a created-on or updated-on
+ date and usually a L<DateTime> object.
+ 
+ =item B<security>
+ 
+ Security set on this object, matches one of the C<SEC_LEVEL_>
+ constants exported from L<SPOPS::Secure>.
+ 
+ =item B<url>
+ 
+ URL to display the object.
+ 
+ =item B<url_edit>
+ 
+ URL to display an editable form of the object.
+ 
+ =back
+ 
+ Some of these values you can control from your SPOPS configuration:
+ 
+ B<id_field>
+ 
+ Matches whatever you set in your C<id_field> key.
+ 
+ B<name>
+ 
+ Matches whatever you set in your C<object_name> key.
+ 
+ B<title>
+ 
+ Use C<title> (or C<name> as the method to call to retrieve the
+ title. So say you had an object representing a contact in your address
+ book. That contact may have 'first_name' and 'last_name' defined, but
+ when you display the object you want the contact's full name. So in
+ your configuration:
+ 
+  [contact]
+  title = full_name
+ 
+ And in your implementation you might have the naive:
+ 
+  sub full_name {
+      my ( $self ) = @_;
+      return join( ' ', $self->first_name, $self->last_name );
+  }
+ 
+ B<date>
+ 
+ If you want a date to be associated with your object, put its
+ field/method here. You're strongly encouraged to return a L<DateTime>
+ object.
+ 
+ B<url> and B<url_edit>
+ 
+ These can take a little more configuration. All configuration is in
+ the 'display' section of your SPOPS configuration, such as:
+ 
+  [news display]
+  ACTION     = news
+  TASK       = display
+  TASK_EDIT  = display_form
+  URL_PARAMS = news_id
+ 
+ Most often you'll use the keys 'ACTION', 'TASK', and
+ 'TASK_EDIT'. Similar to other areas of OI2, 'ACTION' and 'TASK' are
+ used in conjunction with L<OpenInteract2::URL> to create portable
+ URLs. We add 'TASK_EDIT' here because you typically not only want to
+ generate a URL for displaying an object but also one for editing it.
+ 
+ If you don't specify any 'URL_PARAMS' then we'll generate a URL with
+ the given action/task path and a GET param mapping your object's ID
+ field to its ID value. So the following:
+ 
+  [news]
+  ...
+  id_field = news_id
+  ...
+  [news display]
+  ACTION    = news
+  TASK      = display
+  TASK_EDIT = display_form
+ 
+ will generate the following for an object with ID 99:
+ 
+  url:      /news/display/?news_id=99
+  url_edit: /news/display_form/?news_id=99
+ 
+ However, you can also generate REST-style parameters using the
+ 'URL_PARAMS' key. (This maps to the 'URL_PARAMS' argument passed to
+ all the C<create*()> methods in L<OpenInteract2::URL>.) So if we
+ change the above to:
+ 
+  [news]
+  ...
+  id_field = news_id
+  ...
+  [news display]
+  ACTION     = news
+  TASK       = display
+  TASK_EDIT  = display_form
+  URL_PARAMS = news_id
+ 
+ Then you'll generate the following URLs with ID 99:
+ 
+  url:      /news/display/99
+  url_edit: /news/display_form/99
+ 
  =head1 OBJECT TRACKING METHODS