NAME

Krang::Trash - data broker for TrashBin CGI

SYNOPSIS

  use Krang::ClassLoader 'Trash';

  # get a list of objects on the current user's workspace
  @objects = pkg('Trash')->find();

  # get just the first 10, sorting by url:
  @objects = pkg('Trash')->find(limit    => 10,
                                offset   => 0,
                                order_by => 'url');

DESCRIPTION

This module provides a find() method which returns all objects living in the trashbin. These are not full-fledged Story/Media/Template objects, just hashes containing what we need to fill the trashbin's pager view.

INTERFACE

• @objects = Krang::Trash->find()
  
• $count = Krang::Trash->find(count => 1)
  
Finds stories, media and templates currently living the trashbin. The returned array will contain Krang::Story, Krang::Media and Krang::Template objects slimmed down to Trash objects. Custom objects may also be listed (see the class method register_find_sql()).

Since the returned objects do not share single ID-space, the standard ids_only mode is not supported.

Available search options are:

• count
  
Return just a count of the results for this query.
• limit
  
Return no more than this many results.
• offset
  
Start return results at this offset into the result set.
• order_by
  
Output field to sort by. Defaults to 'type' which sorts stories first, then media and finally templates. Other available settings are 'date', 'title', 'url' and 'id'.
• order_desc
  
Results will be in sorted in ascending order unless this is set to 1 (making them descending).

• pkg('Trash')->register_find_sql(object => $moniker, user_sensitive => 0, sql => $sql)
  
This class method allows custom objects other than Krang's core objects Story, Media and Template to register with the trashbin's find() method. It should be called in a BEGIN block!

ARGUMENTS

• object
  
This should be the lowercase moniker of your object's class, e.g. 'mailing' for Krang::Mailing.
• sql
  
This should be the SQL query used to find those objects in the trashbin.
• user_sensitive
  
Set this flag to true if the sql argument includes a placeholder for the logged in user's ID. Defaults to 0.

Example: A custom object class named ``Krang::Mailing''

The SQL select command forms a fassade, mapping asset fields to trash object fields. Order matters! All fields must be present, though they might contain the empty string (as the 'class' field in the example below.

Also assumed in the custom objects' database table is the presence of a boolean column named 'trashed', which is supposed to be set to true if the object currently lives in the trashbin.

 Class:   Krang::Mailing
 Table:   mailing

 BEGIN {

     pkg('Trash')->register_find_sql(object => 'mailing', user_sensitive => 0, sql => <<SQL);
 SELECT mailing_id   AS id,
        'mailing'    AS type,
        subject      AS title,
        ''           AS class,
        url          AS url,
        mailing_date AS date,
        ''           AS version,
        someperm     AS may_see,
        otherperm    AS may_edit,
        1            AS linkto      # format the URL as a link
 FROM mailing
 WHERE trashed = 1
 SQL

 }

• pkg('Trash')->store(object => $story)
  
• pkg('Trash')->store(object => $media)
  
• pkg('Trash')->store(object => $template)
  
• pkg('Trash')->store(object => $other)
  
This method moves the specified object to the trash on the database level. It must be called by the object's trash() method.
• pkg('Trash')->prune()
  
Prune the trash, deleting the oldest entries, leaving TrashMaxItems.

This class method is currently called at the end of each object delete (i.e. when moving an object into the trash).

• Potential Security Hole
  
Users without admin_delete permission may delete assets by creating bogus objects and pushing them into the trash, thus causing prune() to permanently delete trashed objects!

• pkg('Trash')->delete(object => $story)
  
• pkg('Trash')->delete(object => $media)
  
• pkg('Trash')->delete(object => $template)
  
• pkg('Trash')->delete(object => $other)
  
Deletes the specified object from the trashbin, i.e. deletes it permanently from the database. The object must implement a method named delete().
• pkg('Trash')->restore(object => $story)
  
• pkg('Trash')->restore(object => $media)
  
• pkg('Trash')->restore(object => $template)
  
• pkg('Trash')->restore(object => $other)
  
Restores the specified object from the trashbin back to live or to the retired section (depending from where it has been deleted). The object must implement a method named untrash() that does the heavy lifting.
• pkg('Trash')->remove(object => $object)
  
This method removes an object from the trash table. Objects wishing to implement the trash functionality should call this method in their untrash() and delete() methods.