# Copyright 2002-2008 Josh Clark and Global Moxie, LLC. This code cannot be 
# redistributed without permission from globalmoxie.com.  For more
# information, consult your Big Medium license.
#
# $Id: Priv.pm 3043 2008-03-31 14:00:38Z josh $

package BigMed::Priv;
use strict;
use utf8;
use Carp;

use base qw(BigMed::Data);


###########################################################
# SET PRIVILEGE DATA SCHEMA
###########################################################

my @data_schema = (
    {
        name  => 'user',
        type  => 'system_id',
        index => 1,
    },
    {
        name     => 'site',
        type     => 'system_id',
        index    => 1,
    },
    {
        name     => 'sections',
        type     => 'system_id',
        multiple     => 1,
        index    => 1,
    },
    {
        name     => 'level',
        type     => 'number_integer_positive',
    },
);

BigMed::Priv->set_schema(
    source   => 'privileges',
    label    => 'privilege',
    elements => \@data_schema,
    systemwide => 1,
);

BigMed::Priv->add_callback( 'after_copy', \&_after_priv_copy );

sub _after_priv_copy {
    my ( $orig, $clone, $rparam ) = @_;
    my $site = $rparam->{target_site};
    $clone->set_site( ref $site ? $site->id : $site ) if $site;
    return 1;
}

1;

=head1 NAME

BigMed::Priv - Big Medium privileges object

=head1 DESCRIPTION

A BigMed::Priv object stores the privileges level that an individual user has
at a site and whether that privilege level is limited only to certain sections.
Privilege objects are manipulated primarily by the BigMed::User class.

=head1 USAGE

BigMed::Priv is a subclass of BigMed::Data. In addition to the methods 
documented below, please see the BigMed::Data documentation for details about
topics including:

=over 4

=item Creating a new data object

=item Saving a data object

=item Finding and sorting saved data objects

=item Data access methods

=item Error handling

=back

=head1 METHODS

=head2 Data Access Methods

BigMed::Priv objects hold the following pieces of data. They can be
accessed and set using the standard data access methods described in the
BigMed::Data documentation. See the L<"Searching and Sorting"> section below
for details on the data columns available to search and sort BigMed::Site
objects.

=over 4

=item * id

The numeric ID of the privilege object

=item * user

The numeric ID of the user to which this privilege object applies.

=item * site

The museric ID of the site to which this privilege object applies.

=item * level

The numeric privilege level that the user has at the site. If not specified,
the privileges are the same as the user's default privilege level. The
privilege levels correspond to these values:

=over 4

=item * 1 = guest

=item * 2 = writer

=item * 3 = editor

=item * 4 = publisher

=item * 5 = webmaster

=item * 6 = administrator

=back

Note that the admin level should never be assigned to a privilege object.
Admin privileges may be enjoyed only by users who have admin privileges in
their BigMed::User object.

=item * sections

Array of IDs for the sections to which the user is limited. The user also
receives privileges to all child sections of the sections included in this
array. An empty array signifies no section limitations, and the user has the
full run of the site and all of its sections.

=item * mod_time

Timestamp for when the last time the object was saved.

=item * create_time

Timestamp for when the object was first created.

=back

=head2 Searching and Sorting

You can look up and sort records by any combination of the following fields.
See the C<fetch> and C<select> documentation in BigMed::Data for more info.

=over 4

=item * id

=item * mod_time

=item * user

=item * site

=item * sections

=back

=head1 SEE ALSO

=over 4

=item * BigMed::Data

=item * BigMed::User

=back

=head1 AUTHOR & COPYRIGHTS

This module and all Big Medium modules are copyright Josh Clark
and Global Moxie. All rights reserved.

Use of this module and the Big Medium content
management system are governed by Global Moxie's software licenses
and may not be used outside of the terms and conditions outlined
there.

For more information, visit the Global Moxie website at
L<http://globalmoxie.com/>.

Big Medium and Global Moxie are service marks of Global Moxie
and Josh Clark. All rights reserved.

=cut