--- loncom/auth/lonroles.pm	2009/01/05 16:50:02	1.209.2.1
+++ loncom/auth/lonroles.pm	2008/11/12 20:01:09	1.210
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # User Roles Screen
 #
-# $Id: lonroles.pm,v 1.209.2.1 2009/01/05 16:50:02 raeburn Exp $
+# $Id: lonroles.pm,v 1.210 2008/11/12 20:01:09 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -27,6 +27,103 @@
 #
 ###
 
+=pod
+
+=head1 NAME
+
+Apache::lonroles - User Roles Screen
+
+=head1 SYNOPSIS
+
+Invoked by /etc/httpd/conf/srm.conf:
+
+ <Location /adm/roles>
+ PerlAccessHandler       Apache::lonacc
+ SetHandler perl-script
+ PerlHandler Apache::lonroles
+ ErrorDocument     403 /adm/login
+ ErrorDocument	  500 /adm/errorhandler
+ </Location>
+
+=head1 OVERVIEW
+
+=head2 Choosing Roles
+
+C<lonroles> is a handler that allows a user to switch roles in
+mid-session. LON-CAPA attempts to work with "No Role Specified", the
+default role that a user has before selecting a role, as widely as
+possible, but certain handlers for example need specification which
+course they should act on, etc. Both in this scenario, and when the
+handler determines via C<lonnet>'s C<&allowed> function that a certain
+action is not allowed, C<lonroles> is used as error handler. This
+allows the user to select another role which may have permission to do
+what they were trying to do. C<lonroles> can also be accessed via the
+B<CRS> button in the Remote Control. 
+
+=begin latex
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.45\paperwidth,keepaspectratio]{Sample_Roles_Screen}
+  \caption{\label{Sample_Roles_Screen}Sample Roles Screen} 
+\end{center}
+\end{figure}
+
+=end latex
+
+=head2 Role Initialization
+
+The privileges for a user are established at login time and stored in the session environment. As a consequence, a new role does not become active till the next login. Handlers are able to query for privileges using C<lonnet>'s C<&allowed> function. When a user first logs in, their role is the "common" role, which means that they have the sum of all of their privileges. During a session it might become necessary to choose a particular role, which as a consequence also limits the user to only the privileges in that particular role.
+
+=head1 INTRODUCTION
+
+This module enables a user to select what role he wishes to
+operate under (instructor, student, teaching assistant, course
+coordinator, etc).  These roles are pre-established by the actions
+of upper-level users.
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+=head1 HANDLER SUBROUTINE
+
+This routine is called by Apache and mod_perl.
+
+=over 4
+
+=item *
+
+Roles Initialization (yes/no)
+
+=item *
+
+Get Error Message from Environment
+
+=item *
+
+Who is this?
+
+=item *
+
+Generate Page Output
+
+=item *
+
+Choice or no choice
+
+=item *
+
+Table
+
+=item *
+
+Privileges
+
+=back
+
+=cut
+
+
 package Apache::lonroles;
 
 use strict;
@@ -548,7 +645,6 @@ ENDHEADER
     my $possiblerole='';
     my %futureroles;
     my %roles_nextlogin;
-    my %timezones;
     foreach $envkey (sort keys %env) {
         my $button = 1;
         my $switchserver='';
@@ -558,16 +654,15 @@ ENDHEADER
             my ($role,$where,$trolecode,$tstart,$tend,$tremark,$tstatus,$tpstart,$tpend,$tfont);
             &role_status($envkey,$then,$now,\$role,\$where,\$trolecode,\$tstatus,\$tstart,\$tend);
             next if (!defined($role) || $role eq '' || $role =~ /^gr/);
-            my $timezone = &role_timezone($where,\%timezones);
             $tremark='';
             $tpstart='&nbsp;';
             $tpend='&nbsp;';
             $tfont='#000000';
             if ($tstart) {
-                $tpstart=&Apache::lonlocal::locallocaltime($tstart,$timezone);
+                $tpstart=&Apache::lonlocal::locallocaltime($tstart);
             }
             if ($tend) {
-                $tpend=&Apache::lonlocal::locallocaltime($tend,$timezone);
+                $tpend=&Apache::lonlocal::locallocaltime($tend);
             }
             if ($env{'request.role'} eq $trolecode) {
 		$tstatus='selected';
@@ -835,56 +930,6 @@ ENDHEADER
     return OK;
 }
 
-sub role_timezone {
-    my ($where,$timezones) = @_;
-    my $timezone;
-    if (ref($timezones) eq 'HASH') {
-        if ($where =~ m{^/($match_domain)/($match_courseid)}) {
-            my $cdom = $1;
-            my $cnum = $2;
-            if ($cdom && $cnum) {
-                if (!exists($timezones->{$cdom.'_'.$cnum})) {
-                    my %timehash =
-                        &Apache::lonnet::get('environment',['timezone'],$cdom,$cnum);
-                    if ($timehash{'timezone'} eq '') {
-                        if (!exists($timezones->{$cdom})) {
-                            my %domdefaults =
-                                &Apache::lonnet::get_domain_defaults($cdom);
-                            if ($domdefaults{'timezone_def'} eq '') {
-                                $timezones->{$cdom} = 'local';
-                            } else {
-                                $timezones->{$cdom} = $domdefaults{'timezone_def'};
-                            }
-                        }
-                        $timezones->{$cdom.'_'.$cnum} = $timezones->{$cdom};
-                    } else {
-                        $timezones->{$cdom.'_'.$cnum} =
-                            &Apache::lonlocal::gettimezone($timehash{'timezone'});
-                    }
-                }
-                $timezone = $timezones->{$cdom.'_'.$cnum};
-            }
-        } else {
-            my ($tdom) = ($where =~ m{^/($match_domain)});
-            if ($tdom) {
-                if (!exists($timezones->{$tdom})) {
-                    my %domdefaults = &Apache::lonnet::get_domain_defaults($tdom);
-                    if ($domdefaults{'timezone_def'} eq '') {
-                        $timezones->{$tdom} = 'local';
-                    } else {
-                        $timezones->{$tdom} = $domdefaults{'timezone_def'};
-                    }
-                }
-                $timezone = $timezones->{$tdom};
-            }
-        }
-        if ($timezone eq 'local') {
-            $timezone = undef;
-        }
-    }
-    return $timezone;
-}
-
 sub roletable_headers {
     my ($r,$roleclass,$sortrole,$nochoose) = @_;
     my $doheaders;