/ 
OpenInteract-1.99_06
River stage zero No dependents
/ OpenInteract2::SPOPS

NAME

OpenInteract2::SPOPS - Define common behaviors for all SPOPS objects in the OpenInteract Framework

SYNOPSIS

# In the server configuration ($WEBSITE_DIR/conf/server.ini)

# First define the datasource type ('DBI') and associate that type
# with an OI2::SPOPS subclass...

[datasource_type DBI]
connection_manager = OpenInteract2::Datasource::DBI
spops_config       = OpenInteract2::SPOPS::DBI

# Then declare a datasource and associate it with that type; SPOPS
# objects associated with this datasource will have 'OI2::SPOPS::DBI'
# automatically placed in the 'isa'.

[datasource main]
type          = DBI
...

DESCRIPTION

Here we provide some common operations within OpenInteract that are not implmented within the data abstraction layer itself. Since we want to continue using both separately we cannot embed ideas like a configuration object or a particular cache implementation within SPOPS. Think of this class as a bridge between the two.

Note that while most of the functionality is in this class, you will always want to use one of the implementations-specific child classes -- see OpenInteract2::SPOPS::DBI and OpenInteract2::SPOPS::LDAP.

DESCRIBING AN OBJECT

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 SPOPS, returning a hashref of information with the keys:

class

Class of the object.

object_id

ID of this particular object.

id_field

ID field for this object.

name

General type of this object: 'News', 'Document', etc.

title

Title of this specific object: 'Weather tomorrow to be scorching', 'Recipe: Franks and Beans', etc.

date

Date associated with this object, typically a created-on or updated-on date and usually a DateTime object.

security

Security set on this object, matches one of the SEC_LEVEL_ constants exported from SPOPS::Secure.

url

URL to display the object.

url_edit

URL to display an editable form of the object.

Some of these values you can control from your SPOPS configuration:

id_field

Matches whatever you set in your id_field key.

name

Matches whatever you set in your object_name key.

title

Use title (or 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 );
}

date

If you want a date to be associated with your object, put its field/method here. You're strongly encouraged to return a DateTime object.

url and 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 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 create*() methods in 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

OBJECT TRACKING METHODS

There are a number of methods for dealing with object tracking -- when a create/update/remove action is taken on an object and by whom.

log_action( $action, $id )

Wrapper for the log_action_enter method below, decides whether it gets called. (Wrapper exists so subclasses can call log_action_enter directly and not deal with this step.)

Parameters:

  • action ($)

    Should be 'create', 'update', 'remove'.

    id ($)

    ID of the object.

Returns undef on failure, true value on success.

log_action_enter( $action, $id )

Makes an entry into the 'object_track' table, which logs all object creations, updates and deletions. We do not note the content that changes, but we do note who did the action and when it was done.

Parameters:

  • action ($)

    Should be 'create', 'update', 'remove'.

    id ($)

    ID of the object.

Returns undef on failure, true value on success.

fetch_creator()

Retrieve an arrayref of all user objects who have 'creator' rights to a particular object.

is_creator( $uid )

Parameters:

  • uid ($)

    User ID to check and see if that user created this object.

Returns 1 if the object was created by $uid, undef if not.

fetch_updates()

Returns an arrayref of arrayrefs, each formatted:

[ uid of updater, date of update ]

METHODS

notify()

Either call from an object or from a class passing an arrayref of objects to send to a user. Calls the as_string() method of the object, which (if you look in the SPOPS docs), defaults to being a simple property -> value listing. You can override this with information in your class configuration which specifies the fields you want to use in the listing along with associated labels.

Parameters:

  • email ($)

    Address to which we should send the notification.

  • email_from ($) (optional)

    Address from which the email should be sent. If not specified this defaults to the 'admin_email' setting in your server configuration (under 'mail').

  • subject ($) (optional)

    Subject of email. If not specified the subject will be 'Object notification # objects in mail'.

  • object (\@) (optional if called from an object)

    If not called from an object, this should be an arrayref of objects to notify someone about.

  • notes ($) (optional)

    Notes that lead off an email.

COPYRIGHT

Copyright (c) 2002-2005 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>