--- loncom/auth/lonroles.pm	2008/10/20 03:25:48	1.209
+++ loncom/auth/lonroles.pm	2008/12/10 21:46:50	1.213
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # User Roles Screen
 #
-# $Id: lonroles.pm,v 1.209 2008/10/20 03:25:48 raeburn Exp $
+# $Id: lonroles.pm,v 1.213 2008/12/10 21:46:50 kaisler 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;
@@ -272,7 +369,7 @@ $swinfo
 <form method="post">
 <input type="hidden" name="selectrole" value="1" />
 <input type="hidden" name="$trolecode" value="1" />
-<font size="+2">$message</font><br />
+<span class="LC_fontsize_large">$message</span><br />
 <input type="submit" value="$buttontext" />
 </form>
 $end_page
@@ -438,8 +535,9 @@ ENDENTERKEY
     $r->send_http_header;
     return OK if $r->header_only;
 
+	my @brcrum =[{href=>"/admmm/roles",text=>"User Roles"}];
     my $swinfo=&Apache::lonmenu::rawconfig();
-    my $start_page=&Apache::loncommon::start_page('User Roles');
+    my $start_page=&Apache::loncommon::start_page('User Roles',undef,{bread_crumbs=>@brcrum});
     my $standby=&mt('Role selected. Please stand by.');
     $standby=~s/\n/\\n/g;
     my $noscript='<span class="LC_error">'.&mt('Use of LON-CAPA requires Javascript to be enabled in your web browser.').'<br />'.&mt('As this is not the case, most functionality in the system will be unavailable.').'</span><br />';
@@ -554,13 +652,12 @@ ENDHEADER
 	my $roletext;
 	my $sortkey;
         if ($envkey=~/^user\.role\./) {
-            my ($role,$where,$trolecode,$tstart,$tend,$tremark,$tstatus,$tpstart,$tpend,$tfont);
+            my ($role,$where,$trolecode,$tstart,$tend,$tremark,$tstatus,$tpstart,$tpend);
             &role_status($envkey,$then,$now,\$role,\$where,\$trolecode,\$tstatus,\$tstart,\$tend);
             next if (!defined($role) || $role eq '' || $role =~ /^gr/);
             $tremark='';
             $tpstart='&nbsp;';
             $tpend='&nbsp;';
-            $tfont='#000000';
             if ($tstart) {
                 $tpstart=&Apache::lonlocal::locallocaltime($tstart);
             }
@@ -577,30 +674,27 @@ ENDHEADER
 		|| ($tstatus eq 'future') 
                 || ($env{'form.showall'})) {
                 if ($tstatus eq 'is') {
-                    $tbg='#77FF77';
-                    $tfont='#003300';
+                    $tbg='LC_roles_is';
 		    $possiblerole=$trolecode;
 		    $countactive++;
                 } elsif ($tstatus eq 'future') {
-                    $tbg='#FFFF77';
+                    $tbg='LC_roles_future';
                     $button=0;
                     $futureroles{$trolecode} = $tstart.':'.$tend;
                     $countfuture ++;
                 } elsif ($tstatus eq 'will') {
-                    $tbg='#FFAA77';
+                    $tbg='LC_roles_will';
                     $tremark.=&mt('Active at next login.').' ';
                     $roles_nextlogin{$trolecode} = $tstart.':'.$tend;
                     $countwill ++;
                 } elsif ($tstatus eq 'expired') {
-                    $tbg='#FF7777';
-                    $tfont='#330000';
+                    $tbg='LC_roles_expired';
                     $button=0;
                 } elsif ($tstatus eq 'will_not') {
-                    $tbg='#AAFF77';
+                    $tbg='LC_roles_will_not';
                     $tremark.=&mt('Expired after logout.').' ';
                 } elsif ($tstatus eq 'selected') {
-                    $tbg='#11CC55';
-                    $tfont='#002200';
+                    $tbg='LC_roles_selected';
 		    $inrole=1;
 		    $countactive++;
                     $tremark.=&mt('Currently selected.').' ';
@@ -662,9 +756,9 @@ ENDHEADER
                         $twhere=$env{'course.'.$tcourseid.'.description'};
 			$sortkey=$role."\0".$tdom."\0".$twhere."\0".$envkey;
                         unless ($twhere eq &mt('Currently not available')) {
-			    $twhere.=' <font size="-2">'.
-        &Apache::loncommon::syllabuswrapper(&mt('Syllabus'),$trest,$tdom,$tfont).
-                                    '</font>';
+			    $twhere.=' <span class="LC_fontsize_small">'.
+        &Apache::loncommon::syllabuswrapper(&mt('Syllabus'),$trest,$tdom).
+                                    '</span>';
 			}
                     } else {
                         my %newhash=&Apache::lonnet::coursedescription($tcourseid);
@@ -672,9 +766,9 @@ ENDHEADER
 			    $sortkey=$role."\0".$tdom."\0".$newhash{'description'}.
 				"\0".$envkey;
                             $twhere=$newhash{'description'}.
-                              ' <font size="-2">'.
-        &Apache::loncommon::syllabuswrapper(&mt('Syllabus'),$trest,$tdom,$tfont).
-                              '</font>';
+                              ' <span class="LC_fontsize_small">'.
+        &Apache::loncommon::syllabuswrapper(&mt('Syllabus'),$trest,$tdom).
+                              '</span>';
                             $ttype = $newhash{'type'};
                             $trole = &Apache::lonnet::plaintext($role,$ttype);
                         } else {
@@ -697,7 +791,7 @@ ENDHEADER
                     $twhere=&mt('system wide');
 		    $sortkey=$role.$twhere;
                 }
-                $roletext.=&build_roletext($trolecode,$tdom,$trest,$tstatus,$tryagain,$advanced,$tremark,$tbg,$tfont,$trole,$twhere,$tpstart,$tpend,$nochoose,$button,$switchserver,$reinit);
+                $roletext.=&build_roletext($trolecode,$tdom,$trest,$tstatus,$tryagain,$advanced,$tremark,$tbg,$trole,$twhere,$tpstart,$tpend,$nochoose,$button,$switchserver,$reinit);
 		$roletext{$envkey}=$roletext;
 		if (!$sortkey) {$sortkey=$twhere."\0".$envkey;}
 		$sortrole{$sortkey}=$envkey;
@@ -707,9 +801,9 @@ ENDHEADER
     }
     if ($env{'user.adv'}) {
         $r->print(
-              '<br /><span class="LC_rolesinfo"><label>'.&mt('Show all roles').': <input type="checkbox" name="showall"');
+              '<p><label>'.&mt('Show all roles').': <input type="checkbox" name="showall"');
         if ($env{'form.showall'}) { $r->print(' checked="checked" '); }
-        $r->print(' /></label><input type="submit" value="'.&mt('Display').'" /></span>');
+        $r->print(' /></label><input type="submit" value="'.&mt('Display').'" /></p>');
     } else {
         if ($countactive > 0) {
             my $domdesc = &Apache::lonnet::domain($env{'user.domain'},'description');
@@ -734,19 +828,23 @@ ENDHEADER
             &print_rolerows($r,$doheaders,\%roleclass,\%sortrole,\%dcroles,
                             \%roletext);
             my $tremark='';
-            my $tfont='#003300';
+            my $tbg;
             if ($env{'request.role'} eq 'cm') {
-                $r->print('<tr bgcolor="#11CC55">');
+                $tbg="LC_roles_selected";
                 $tremark=&mt('Currently selected.').' ';
-                $tfont='#002200';
             } else {
-                $r->print('<tr bgcolor="#77FF77">');
+                $tbg="LC_roles_is";
             }
-            $r->print('<td></td><td colspan="3"><font color="'.$tfont.'"><span class="LC_rolesinfo">'.&mt('No role specified').
-                      '</span></font></td><td><font color="'.$tfont.'">'.$tremark.
-                      '&nbsp;</font></td></tr>'."\n");
+            $r->print(&Apache::loncommon::start_data_table_row()
+                     .'<td class="'.$tbg.'">&nbsp;</td>'
+                     .'<td colspan="3">'
+                     .&mt('No role specified')
+                     .'</td>'
+                     .'<td>'.$tremark.'&nbsp;</td>'
+                     .&Apache::loncommon::end_data_table_row()
+            );
 
-            $r->print('</table>');
+            $r->print(&Apache::loncommon::end_data_table());
         }
         $r->print(&Apache::loncommon::end_page());
 	return OK;
@@ -774,8 +872,12 @@ ENDHEADER
             } 
 	}
 	if ($output) {
-	    $r->print("<tr><td align='center' colspan='5'><font face='arial'>".
-		      &mt('Recent Roles')."</font></td></tr>");
+	    $r->print(&Apache::loncommon::start_data_table_empty_row()
+                     .'<td align="center" colspan="5">'
+                     .&mt('Recent Roles')
+                     .'</td>'
+                     .&Apache::loncommon::end_data_table_empty_row()
+            );
 	    $r->print($output);
             $doheaders ++;
 	}
@@ -789,33 +891,36 @@ ENDHEADER
     &print_rolerows($r,$doheaders,\%roleclass,\%sortrole,\%dcroles,\%roletext);
     if ($countactive > 1) {
         my $tremark='';
-        my $tfont='#003300';
+        my $tbg;
         if ($env{'request.role'} eq 'cm') {
-	    $r->print('<tr bgcolor="#11CC55">');
+            $tbg="LC_roles_selected";
             $tremark=&mt('Currently selected.').' ';
-            $tfont='#002200';
         } else {
-            $r->print('<tr bgcolor="#77FF77">');
+                $tbg="LC_roles_is";
         }
+        $r->print(&Apache::loncommon::start_data_table_row());
         unless ($nochoose) {
 	    if ($env{'request.role'} ne 'cm') {
-	        $r->print('<td><input type="submit" value="'.
+	        $r->print('<td class="'.$tbg.'"><input type="submit" value="'.
 		          &mt('Select').'" name="cm" /></td>');
 	    } else {
-	        $r->print('<td>&nbsp;</td>');
+	        $r->print('<td class="'.$tbg.'">&nbsp;</td>');
 	    }
         }
-        $r->print('<td colspan="3"><font color="'.$tfont.'"><span class="LC_rolesinfo">'.&mt('No role specified').
-                  '</span></font></td><td><font color="'.$tfont.'">'.$tremark.
-                  '&nbsp;</font></td></tr>'."\n");
+        $r->print('<td colspan="3">'
+                 .&mt('No role specified')
+                 .'</td>'
+                 .'<td>'.$tremark.'&nbsp;</td>'
+                 .&Apache::loncommon::end_data_table_row()
+        );
     } 
-    $r->print('</table>');
+    $r->print(&Apache::loncommon::end_data_table());
     unless ($nochoose) {
 	$r->print("</form>\n");
     }
 # ------------------------------------------------------------ Privileges Info
     if (($advanced) && (($env{'user.error.msg'}) || ($error))) {
-	$r->print('<hr /><h2>Current Privileges</h2>');
+	$r->print('<hr /><h2>'.&mt('Current Privileges').'</h2>');
 	$r->print(&privileges_info());
     }
     $r->print(&Apache::lonnet::getannounce());
@@ -837,11 +942,17 @@ sub roletable_headers {
     my ($r,$roleclass,$sortrole,$nochoose) = @_;
     my $doheaders;
     if ((ref($sortrole) eq 'HASH') && (ref($roleclass) eq 'HASH')) {
-        $r->print('<br /><table id="LC_rolesmenu"><tr>');
+        $r->print('<br />'
+                 .&Apache::loncommon::start_data_table()
+                 .&Apache::loncommon::start_data_table_header_row()
+        );
         if (!$nochoose) { $r->print('<th>&nbsp;</th>'); }
-        $r->print('<th>'.&mt('User Role').'</th><th>'.&mt('Extent')
-                  .'</th><th>'.&mt('Start').'</th><th>'.&mt('End')
-                  .'</th></tr>'."\n");
+        $r->print('<th>'.&mt('User Role').'</th>'
+                 .'<th>'.&mt('Extent').'</th>'
+                 .'<th>'.&mt('Start').'</th>'
+                 .'<th>'.&mt('End').'</th>'
+                 .&Apache::loncommon::end_data_table_header_row()
+        );
         $doheaders=-1;
         my @roletypes = &roletypes();
         foreach my $type (@roletypes) {
@@ -884,9 +995,12 @@ sub print_rolerows {
             }
             if ($output) {
                 if ($doheaders > 0) {
-                    $r->print("<tr>".
-                              "<td align='center' colspan='5'><font face='arial'>".
-                              &mt($type)."</font></td></tr>");
+                    $r->print(&Apache::loncommon::start_data_table_empty_row()
+                             .'<td align="center" colspan="5">'
+                             .&mt($type)
+                             .'</td>'
+                             .&Apache::loncommon::end_data_table_empty_row()
+                    );
                 }
                 $r->print($output);
             }
@@ -996,8 +1110,8 @@ sub role_status {
 }
 
 sub build_roletext {
-    my ($trolecode,$tdom,$trest,$tstatus,$tryagain,$advanced,$tremark,$tbg,$tfont,$trole,$twhere,$tpstart,$tpend,$nochoose,$button,$switchserver,$reinit) = @_;
-    my $roletext='<tr bgcolor="'.$tbg.'" class="LC_rolesmenu_'.$tstatus.'">';
+    my ($trolecode,$tdom,$trest,$tstatus,$tryagain,$advanced,$tremark,$tbg,$trole,$twhere,$tpstart,$tpend,$nochoose,$button,$switchserver,$reinit) = @_;
+    my $roletext=&Apache::loncommon::start_data_table_row();
     my $is_dc=($trolecode =~ m/^dc\./);
     my $rowspan=($is_dc) ? ''
                          : ' rowspan="2" ';
@@ -1007,33 +1121,40 @@ sub build_roletext {
         $buttonname=~s/\W//g;
         if (!$button) {
             if ($switchserver) {
-                $roletext.='<td'.$rowspan.'><span class="LC_rolesinfo"><a href="/adm/switchserver?'.
-                $switchserver.'">'.&mt('Switch Server').'</a></span></td>';
+                $roletext.='<td'.$rowspan.' class="'.$tbg.'">'
+                          .'<a href="/adm/switchserver?'.$switchserver.'">'
+                          .&mt('Switch Server')
+                          .'</a></td>';
             } else {
-                $roletext.=('<td'.$rowspan.'>&nbsp;</td>');
+                $roletext.=('<td'.$rowspan.' class="'.$tbg.'">&nbsp;</td>');
             }
         } elsif ($tstatus eq 'is') {
-            $roletext.='<td'.$rowspan.'><input name="'.$buttonname.'" type="button" value="'.
+            $roletext.='<td'.$rowspan.' class="'.$tbg.'">'.
+                        '<input name="'.$buttonname.'" type="button" value="'.
                         &mt('Select').'" onClick="javascript:enterrole(this.form,\''.
                         $trolecode."','".$buttonname.'\');" /></td>';
         } elsif ($tryagain) {
             $roletext.=
-                '<td'.$rowspan.'><input name="'.$buttonname.'" type="button" value="'.
+                '<td'.$rowspan.' class="'.$tbg.'">'.
+                '<input name="'.$buttonname.'" type="button" value="'.
                 &mt('Try Selecting Again').'" onClick="javascript:enterrole(this.form,\''.
                         $trolecode."','".$buttonname.'\');" /></td>';
         } elsif ($advanced) {
             $roletext.=
-                '<td'.$rowspan.'><input name="'.$buttonname.'" type="button" value="'.
+                '<td'.$rowspan.' class="'.$tbg.'">'.
+                '<input name="'.$buttonname.'" type="button" value="'.
                 &mt('Re-Initialize').'" onClick="javascript:enterrole(this.form,\''.
                         $trolecode."','".$buttonname.'\');" /></td>';
         } elsif ($reinit) {
             $roletext.= 
-                '<td'.$rowspan.'><input name="'.$buttonname.'" type="button" value="'.
+                '<td'.$rowspan.' class="'.$tbg.'">'.
+                '<input name="'.$buttonname.'" type="button" value="'.
                 &mt('Re-Select').'" onClick="javascript:enterrole(this.form,\''.
                         $trolecode."','".$buttonname.'\');" /></td>';
         } else {
             $roletext.=
-                '<td'.$rowspan.'><input name="'.$buttonname.'" type="button" value="'.
+                '<td'.$rowspan.' class="'.$tbg.'">'.
+                '<input name="'.$buttonname.'" type="button" value="'.
                 &mt('Re-Initialize').'" onClick="javascript:enterrole(this.form,\''.
                         $trolecode."','".$buttonname.'\');" /></td>';
         }
@@ -1042,14 +1163,17 @@ sub build_roletext {
 	$tremark.=&Apache::lonannounce::showday(time,1,
 			 &Apache::lonannounce::readcalendar($tdom.'_'.$trest));
     }
-    $roletext.='<td><font color="'.$tfont.'">'.$trole.
-	       '</font></td><td><font color="'.$tfont.'">'.$twhere.
-               '</font></td><td><font color="'.$tfont.'">'.$tpstart.
-               '</font></td><td><font color="'.$tfont.'">'.$tpend.
-               '</font></td></tr>';
+    $roletext.='<td>'.$trole.'</td>'
+              .'<td>'.$twhere.'</td>'
+              .'<td>'.$tpstart.'</td>'
+              .'<td>'.$tpend.'</td>'
+              .&Apache::loncommon::end_data_table_row();
     if (!$is_dc) {
-	$roletext.='<tr bgcolor="'.$tbg.'"><td colspan="4"><font color="'.$tfont.'"><span class="LC_rolesinfo">'.$tremark.
-	    '</span>&nbsp;</font></td></tr><tr><td colspan="5" height="3"></td></tr>'."\n";
+        $roletext.=&Apache::loncommon::continue_data_table_row()
+                  .'<td colspan="4">'
+                  .$tremark.'&nbsp;'
+                  .'</td>'
+                  .&Apache::loncommon::end_data_table_row();
     }
     return $roletext;
 }
@@ -1093,7 +1217,7 @@ sub check_privs {
     my ($cdom,$cnum,$then,$now,$checkrole) = @_;
     my $cckey = 'user.role.'.$checkrole.'./'.$cdom.'/'.$cnum; 
     if ($env{$cckey}) {
-        my ($role,$where,$trolecode,$tstart,$tend,$tremark,$tstatus,$tpstart,$tpend,$tfont);
+        my ($role,$where,$trolecode,$tstart,$tend,$tremark,$tstatus,$tpstart,$tpend);
         &role_status($cckey,$then,$now,\$role,\$where,\$trolecode,\$tstatus,\$tstart,\$tend);
         unless (($tstatus eq 'is') || ($tstatus eq 'will_not')) {
             &set_privileges($cdom,$cnum,$checkrole);
@@ -1266,14 +1390,13 @@ sub display_cc_role {
             my $trolecode = 'cc./'.$1.'/'.$2;
             my $twhere;
             my $ttype;
-            my $tbg='#77FF77';
-            my $tfont='#003300';
+            my $tbg='LC_roles_is';
             my %newhash=&Apache::lonnet::coursedescription($tcourseid);
             if (%newhash) {
                 $twhere=$newhash{'description'}.
-                        ' <font size="-2">'.
-                        &Apache::loncommon::syllabuswrapper(&mt('Syllabus'),$2,$1,$tfont).
-                        '</font>';
+                        ' <span style="LC_fontsize_small">'.
+                        &Apache::loncommon::syllabuswrapper(&mt('Syllabus'),$2,$1).
+                        '</span>';
                 $ttype = $newhash{'type'};
             } else {
                 $twhere=&mt('Currently not available');
@@ -1281,7 +1404,7 @@ sub display_cc_role {
             }
             my $trole = &Apache::lonnet::plaintext('cc',$ttype);
             $twhere.="<br />".&mt('Domain').":".$1;
-            $roletext = &build_roletext($trolecode,$1,$2,'is',$tryagain,$advanced,'',$tbg,$tfont,$trole,$twhere,'','','',1,'');
+            $roletext = &build_roletext($trolecode,$1,$2,'is',$tryagain,$advanced,'',$tbg,$trole,$twhere,'','','',1,'');
         }
     }
     return ($roletext);
@@ -1289,20 +1412,24 @@ sub display_cc_role {
 
 sub adhoc_roles_row {
     my ($dcdom,$rowtype) = @_;
-    my $output = '<tr bgcolor="#77FF77">'.
-                 ' <td colspan="5"><table><tr><td><span class="LC_rolesinfo">'
-                 .&mt('[_1]Ad hoc[_2] roles in domain [_3] --',
-                 '<span class="LC_cusr_emph">','</span>',$dcdom).'</span></td><td>';
+    my $output = &Apache::loncommon::continue_data_table_row()
+                 .' <td colspan="5">'
+                 .'<table><tr><td>'
+                 .&mt('[_1]Ad hoc[_2] roles in domain [_3] --'
+                     ,'<span class="LC_cusr_emph">','</span>',$dcdom)
+                 .'</td>'
+                 .'<td>';
     my $selectcclink = &courselink($dcdom,$rowtype);
     my $ccrole = &Apache::lonnet::plaintext('cc');
     my $carole = &Apache::lonnet::plaintext('ca');
     my $selectcalink = &coauthorlink($dcdom,$rowtype);
-    $output.= '<span class="LC_rolesinfo">'.
-            &mt('[_1]: [_2]',$ccrole,$selectcclink).
-            '</span><br /></td><td>&nbsp;&nbsp;</td><td><span class="LC_rolesinfo">'.
-            &mt('[_1]: [_2]',$carole,$selectcalink).
-            '</span><br /></td></tr></table></td></tr>'.
-            '<tr><td colspan="5" height="3"></td></tr>'."\n";
+    $output.=&mt('[_1]: [_2]',$ccrole,$selectcclink)
+            .'<br /></td>'
+            .'<td>&nbsp;&nbsp;</td>'
+            .'<td>'.&mt('[_1]: [_2]',$carole,$selectcalink).'<br /></td>'
+            .'</tr></table>'
+            .'</td>'
+            .&Apache::loncommon::end_data_table_row();
     return $output;
 }