[LON-CAPA-cvs] cvs: loncom /interface lonparmset.pm
damieng
damieng at source.lon-capa.org
Tue Jul 19 17:55:13 EDT 2016
damieng Tue Jul 19 21:55:13 2016 EDT
Modified files:
/loncom/interface lonparmset.pm
Log:
finished adding comments
-------------- next part --------------
Index: loncom/interface/lonparmset.pm
diff -u loncom/interface/lonparmset.pm:1.562 loncom/interface/lonparmset.pm:1.563
--- loncom/interface/lonparmset.pm:1.562 Fri Jul 15 22:24:37 2016
+++ loncom/interface/lonparmset.pm Tue Jul 19 21:55:12 2016
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# Handler to set parameters for assessments
#
-# $Id: lonparmset.pm,v 1.562 2016/07/15 22:24:37 damieng Exp $
+# $Id: lonparmset.pm,v 1.563 2016/07/19 21:55:12 damieng Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -367,7 +367,7 @@
##################################################
-# TABLE MODE
+# (mostly) TABLE MODE
# (parmval is also used for the log of parameter changes)
##################################################
@@ -2416,8 +2416,12 @@
}
}
-# Build up the select Box to choose if your parameter specification should work for the resource, map/folder or the course level
-# The value of default selection in the select box is set by the value that is given by the argument in $parmlev.
+# Prints HTML to select the parameter level (resource, map/folder or course).
+# Used by table and overview modes.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $alllevs - all parameter levels, hash English title -> value
+# @param {string} $parmlev - selected level value (full|map|general), or ''
sub levelmenu {
my ($r,$alllevs,$parmlev)=@_;
@@ -2435,6 +2439,11 @@
}
+# Returns HTML to select a section (with a select HTML element).
+# Used by overview mode.
+#
+# @param {array reference} $selectedsections - list of selected section ids
+# @returns {string}
sub sectionmenu {
my ($selectedsections)=@_;
my %sectionhash = &Apache::loncommon::get_sections();
@@ -2460,6 +2469,11 @@
return $output;
}
+# Returns HTML to select a group (with a select HTML element).
+# Used by overview mode.
+#
+# @param {array reference} $selectedgroups - list of selected group names
+# @returns {string}
sub groupmenu {
my ($selectedgroups)=@_;
my %grouphash;
@@ -2482,11 +2496,23 @@
return $output;
}
+# Returns an array with the given parameter split by comma.
+# Used by assessparms (table mode).
+#
+# @param {string} $keyp - the string to split
+# @returns {Array<string>}
sub keysplit {
my $keyp=shift;
return (split(/\,/,$keyp));
}
+# Returns the keys in $name, sorted using $keyorder.
+# Parameters are sorted by key, which means they are sorted by part first, then by name.
+# Used by assessparms (table mode) for resource level.
+#
+# @param {hash reference} $name - parameter key -> parameter name
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array<string>}
sub keysinorder {
my ($name,$keyorder)=@_;
return sort {
@@ -2494,10 +2520,16 @@
} (keys(%{$name}));
}
+# Returns the keys in $name, sorted using $keyorder to sort parameters by name first, then by part.
+# Used by assessparms (table mode) for map and general levels.
+#
+# @param {hash reference} $name - parameter key -> parameter name
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array<string>}
sub keysinorder_bytype {
my ($name,$keyorder)=@_;
return sort {
- my $ta=(split('_',$a))[-1];
+ my $ta=(split('_',$a))[-1]; # parameter name
my $tb=(split('_',$b))[-1];
if ($$keyorder{'parameter_0_'.$ta} == $$keyorder{'parameter_0_'.$tb}) {
return ($a cmp $b);
@@ -2506,6 +2538,12 @@
} (keys(%{$name}));
}
+# Returns the keys in $name, sorted using $keyorder to sort parameters by name.
+# Used by defaultsetter (parameter settings default actions).
+#
+# @param {hash reference} $name - hash parameter name -> parameter title
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array<string>}
sub keysindisplayorder {
my ($name,$keyorder)=@_;
return sort {
@@ -2513,6 +2551,11 @@
} (keys(%{$name}));
}
+# Prints HTML with a choice to sort results by realm or student first.
+# Used by overview mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $sortorder - realmstudent|studentrealm
sub sortmenu {
my ($r,$sortorder)=@_;
$r->print('<br /><label><input type="radio" name="sortorder" value="realmstudent"');
@@ -2528,6 +2571,9 @@
'</label>');
}
+# Returns a hash parameter key -> order (integer) giving the order for some parameters.
+#
+# @returns {hash}
sub standardkeyorder {
return ('parameter_0_opendate' => 1,
'parameter_0_duedate' => 2,
@@ -2556,28 +2602,56 @@
# Table mode UI.
+# If nothing is selected, prints HTML forms to select resources, parts, parameters, user, group and section.
+# Otherwise, prints the parameter table, with a link to change the selection unless a single resource is selected.
+#
+# Parameters used from the request:
+# action - handler action (see handler), usermenu is checking for value 'settable'
+# cgroup - selected group
+# command - 'set': direct access to table mode for a resource
+# csec - selected section
+# dis - set when the "Update Display" button was used, used only to discard command 'set'
+# hideparmsel - can be 'hidden' to hide the parameter selection div initially and display the "Change Parameter Selection" link instead (which displays the div)
+# id - student/employee ID
+# parmlev - selected level (full|map|general)
+# part - selected part (unused ?)
+# pres_marker - &&&-separated parameter identifiers, "resource id&part_parameter name&level"
+# pres_type - &&&-separated parameter types
+# pres_value - &&&-separated parameter values
+# prevvisit - '1' if the user has submitted the form before
+# pscat (multiple values) - selected parameter names
+# pschp - selected map id, or 'all'
+# psprt (multiple values) - list of selected parameter parts
+# filter - part of or whole parameter name, to be filtered out when parameters are displayed (unused ?)
+# recent_* (* = parameter type) - recent values entered by the user for parameter types
+# symb - resource symb (when a single resource is selected)
+# udom - selected user domain
+# uname - selected user name
+# url - used only with command 'set', the resource url
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub assessparms {
my $r=shift;
# -------------------------------------------------------- Variable declaration
- my @ids=();
- my %symbp=();
- my %mapp=();
- my %typep=();
- my %keyp=();
- my %uris=();
- my %maptitles=();
- my %allmaps=();
- my %alllevs=();
-
- my $uname;
- my $udom;
- my $uhome;
- my $csec;
- my $cgroup;
- my @usersgroups = ();
+ my @ids=(); # resource ids
+ my %symbp=(); # hash map id or resource id -> map src.'___(all)' for a map or resource symb for a resource
+ my %mapp=(); # hash resource id -> enclosing map src
+ my %typep=(); # hash resource id (from big hash) -> resource type (file extension)
+ my %keyp=(); # hash resource id -> comma-separated list of parameter keys
+ my %uris=(); # hash resource id -> resource src
+ my %maptitles=(); # hash map id or src -> map title
+ my %allmaps=(); # hash map id (from big hash) -> map src
+ my %alllevs=(); # hash English level title -> value
+
+ my $uname; # selected user name
+ my $udom; # selected user domain
+ my $uhome; # server with the user's files, or 'no_host'
+ my $csec; # selected section name
+ my $cgroup; # selected group name
+ my @usersgroups = (); # list of the user groups
my $coursename=$env{'course.'.$env{'request.course.id'}.'.description'};
@@ -2585,8 +2659,8 @@
$alllevs{'Map/Folder Level'}='map';
$alllevs{'Course Level'}='general';
- my %allparms;
- my %allparts;
+ my %allparms; # hash parameter name -> parameter title
+ my %allparts; # hash parameter part -> part title
# ------------------------------------------------------------------------------
#
@@ -2890,19 +2964,25 @@
}
}
#----------------------------------------------- if all selected, fill in array
- if ($pscat[0] eq "all") {@pscat = (keys(%allparms));}
- if (!@pscat) { @pscat=('duedate','opendate','answerdate','weight','maxtries','type','problemstatus') };
- if ($psprt[0] eq "all" || !@psprt) {@psprt = (keys(%allparts));}
+ if ($pscat[0] eq "all") {
+ @pscat = (keys(%allparms));
+ }
+ if (!@pscat) {
+ @pscat=('duedate','opendate','answerdate','weight','maxtries','type','problemstatus')
+ };
+ if ($psprt[0] eq "all" || !@psprt) {
+ @psprt = (keys(%allparts));
+ }
# ------------------------------------------------------------------ Start page
my $crstype = &Apache::loncommon::course_type();
&startpage($r,$pssymb,$crstype);
foreach my $item ('tolerance','date_default','date_start','date_end',
- 'date_interval','int','float','string') {
+ 'date_interval','int','float','string') {
$r->print('<input type="hidden" value="'.
- &HTML::Entities::encode($env{'form.recent_'.$item},'"&<>').
- '" name="recent_'.$item.'" />');
+ &HTML::Entities::encode($env{'form.recent_'.$item},'"&<>').
+ '" name="recent_'.$item.'" />');
}
# ----- Start Parameter Selection
@@ -2920,6 +3000,7 @@
ENDPARMSELSCRIPT
if (!$pssymb) {
+ # No single resource selected, print forms to select things (hidden after first selection)
my $parmselhiddenstyle=' style="display:none"';
if($env{'form.hideparmsel'} eq 'hidden') {
$r->print('<div id="parmsel"'.$parmselhiddenstyle.'>');
@@ -3429,8 +3510,12 @@
##################################################
# OVERVIEW MODE
##################################################
-my $tableopen;
+my $tableopen; # boolean, true if HTML table is already opened
+
+# Returns HTML with the HTML table start tag and header, unless the table is already opened.
+# @param {boolean} $readonly - true if values cannot be edited (otherwise more columns are added)
+# @returns {string}
sub tablestart {
my ($readonly) = @_;
if ($tableopen) {
@@ -3448,6 +3533,8 @@
}
}
+# Returns HTML with the HTML table end tag, unless the table is not opened.
+# @returns {string}
sub tableend {
if ($tableopen) {
$tableopen=0;
@@ -3457,6 +3544,13 @@
}
}
+# Reads course and user information.
+# If the context is looking for a scalar, returns the course parameters hash (result of lonnet::get_courseresdata, dump of course's resourcedata.db) with added student data from lonnet::get_userresdata (which reads the user's resourcedata.db).
+# The key for student data is modified with '[useropt:'.username.':'.userdomain.'].'.
+# If the context is looking for a list, returns a list with the scalar data and the class list.
+# @param {string} $crs - course number
+# @param {string} $dom - course domain
+# @returns {hash reference|Array}
sub readdata {
my ($crs,$dom)=@_;
# Read coursedata
@@ -3485,8 +3579,24 @@
}
-# Setting
-
+# Stores parameter data, using form parameters directly.
+#
+# Uses the following form parameters. The variable part in the names is a resourcedata key (except for a modification for user data).
+# set_* (except settext, setipallow, setipdeny) - set a parameter value
+# del_* - remove a parameter
+# datepointer_* - set a date parameter (value is key_* refering to a set of other form parameters)
+# dateinterval_* - set a date interval parameter (value refers to more form parameters)
+# key_* - date values
+# days_* - for date intervals
+# hours_* - for date intervals
+# minutes_* - for date intervals
+# seconds_* - for date intervals
+# done_* - for date intervals
+# typeof_* - parameter type
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $crs - course number
+# @param {string} $dom - course domain
sub storedata {
my ($r,$crs,$dom)=@_;
# Set userlevel immediately
@@ -3509,151 +3619,152 @@
$tkey=~s/\.\[useropt\:$tuname\:$tudom\]\./\./;
}
if ($cmd eq 'set' || $cmd eq 'datepointer' || $cmd eq 'dateinterval') {
- my ($data, $typeof, $text, $name, $valchk, $valmatch, $namematch);
- if ($cmd eq 'set') {
- $data=$env{$key};
- $valmatch = '';
- $valchk = $data;
- $typeof=$env{'form.typeof_'.$thiskey};
- $text = &mt('Saved modified parameter for');
- if ($typeof eq 'string_questiontype') {
- $name = 'type';
- } elsif ($typeof eq 'string_lenient') {
- $name = 'lenient';
- my $stringmatch = &standard_string_matches($typeof);
- if (ref($stringmatch) eq 'ARRAY') {
- foreach my $item (@{$stringmatch}) {
- if (ref($item) eq 'ARRAY') {
- my ($regexpname,$pattern) = @{$item};
- if ($pattern ne '') {
- if ($data =~ /$pattern/) {
- $valmatch = $regexpname;
- $valchk = '';
- last;
+ my ($data, $typeof, $text, $name, $valchk, $valmatch, $namematch);
+ if ($cmd eq 'set') {
+ $data=$env{$key};
+ $valmatch = '';
+ $valchk = $data;
+ $typeof=$env{'form.typeof_'.$thiskey};
+ $text = &mt('Saved modified parameter for');
+ if ($typeof eq 'string_questiontype') {
+ $name = 'type';
+ } elsif ($typeof eq 'string_lenient') {
+ $name = 'lenient';
+ my $stringmatch = &standard_string_matches($typeof);
+ if (ref($stringmatch) eq 'ARRAY') {
+ foreach my $item (@{$stringmatch}) {
+ if (ref($item) eq 'ARRAY') {
+ my ($regexpname,$pattern) = @{$item};
+ if ($pattern ne '') {
+ if ($data =~ /$pattern/) {
+ $valmatch = $regexpname;
+ $valchk = '';
+ last;
+ }
}
}
}
}
- }
- } elsif ($typeof eq 'string_discussvote') {
- $name = 'discussvote';
- } elsif ($typeof eq 'string_examcode') {
- $name = 'examcode';
- if (&Apache::lonnet::validCODE($data)) {
- $valchk = 'valid';
- }
- } elsif ($typeof eq 'string_yesno') {
- if ($thiskey =~ /\.retrypartial$/) {
- $name = 'retrypartial';
- }
- }
- } elsif ($cmd eq 'datepointer') {
- $data=&Apache::lonhtmlcommon::get_date_from_form($env{$key});
- $typeof=$env{'form.typeof_'.$thiskey};
- $text = &mt('Saved modified date for');
- if ($typeof eq 'date_start') {
- if ($thiskey =~ /\.printstartdate$/) {
- $name = 'printstartdate';
- if (($data) && ($data > $now)) {
- $valchk = 'future';
+ } elsif ($typeof eq 'string_discussvote') {
+ $name = 'discussvote';
+ } elsif ($typeof eq 'string_examcode') {
+ $name = 'examcode';
+ if (&Apache::lonnet::validCODE($data)) {
+ $valchk = 'valid';
+ }
+ } elsif ($typeof eq 'string_yesno') {
+ if ($thiskey =~ /\.retrypartial$/) {
+ $name = 'retrypartial';
}
}
- } elsif ($typeof eq 'date_end') {
- if ($thiskey =~ /\.printenddate$/) {
- $name = 'printenddate';
- if (($data) && ($data < $now)) {
- $valchk = 'past';
+ } elsif ($cmd eq 'datepointer') {
+ $data=&Apache::lonhtmlcommon::get_date_from_form($env{$key});
+ $typeof=$env{'form.typeof_'.$thiskey};
+ $text = &mt('Saved modified date for');
+ if ($typeof eq 'date_start') {
+ if ($thiskey =~ /\.printstartdate$/) {
+ $name = 'printstartdate';
+ if (($data) && ($data > $now)) {
+ $valchk = 'future';
+ }
+ }
+ } elsif ($typeof eq 'date_end') {
+ if ($thiskey =~ /\.printenddate$/) {
+ $name = 'printenddate';
+ if (($data) && ($data < $now)) {
+ $valchk = 'past';
+ }
}
}
- }
- } elsif ($cmd eq 'dateinterval') {
- $data=&get_date_interval_from_form($thiskey);
- if ($thiskey =~ /\.interval$/) {
- $name = 'interval';
- my $intervaltype = &get_intervaltype($name);
- my $intervalmatch = &standard_interval_matches($intervaltype);
- if (ref($intervalmatch) eq 'ARRAY') {
- foreach my $item (@{$intervalmatch}) {
- if (ref($item) eq 'ARRAY') {
- my ($regexpname,$pattern) = @{$item};
- if ($pattern ne '') {
- if ($data =~ /$pattern/) {
- $valmatch = $regexpname;
- $valchk = '';
- last;
+ } elsif ($cmd eq 'dateinterval') {
+ $data=&get_date_interval_from_form($thiskey);
+ if ($thiskey =~ /\.interval$/) {
+ $name = 'interval';
+ my $intervaltype = &get_intervaltype($name);
+ my $intervalmatch = &standard_interval_matches($intervaltype);
+ if (ref($intervalmatch) eq 'ARRAY') {
+ foreach my $item (@{$intervalmatch}) {
+ if (ref($item) eq 'ARRAY') {
+ my ($regexpname,$pattern) = @{$item};
+ if ($pattern ne '') {
+ if ($data =~ /$pattern/) {
+ $valmatch = $regexpname;
+ $valchk = '';
+ last;
+ }
}
}
}
}
}
+ $typeof=$env{'form.typeof_'.$thiskey};
+ $text = &mt('Saved modified date for');
}
- $typeof=$env{'form.typeof_'.$thiskey};
- $text = &mt('Saved modified date for');
- }
- if ($thiskey =~ m{\.(?:sequence|page)___\(rec\)}) {
- $namematch = 'maplevelrecurse';
- }
- if (($name ne '') || ($namematch ne '')) {
- my ($needsrelease,$needsnewer);
- if ($name ne '') {
- $needsrelease = $Apache::lonnet::needsrelease{"parameter:$name:$valchk:$valmatch:"};
- if ($needsrelease) {
- unless ($got_chostname) {
- ($chostname,$cmajor,$cminor)=¶meter_release_vars();
- $got_chostname = 1;
- }
- $needsnewer = ¶meter_releasecheck($name,$valchk,$valmatch,undef,
- $needsrelease,
- $cmajor,$cminor);
- }
+ if ($thiskey =~ m{\.(?:sequence|page)___\(rec\)}) {
+ $namematch = 'maplevelrecurse';
}
- if ($namematch ne '') {
- if ($needsnewer) {
- undef($namematch);
- } else {
- my $currneeded;
+ if (($name ne '') || ($namematch ne '')) {
+ my ($needsrelease,$needsnewer);
+ if ($name ne '') {
+ $needsrelease = $Apache::lonnet::needsrelease{"parameter:$name:$valchk:$valmatch:"};
if ($needsrelease) {
- $currneeded = $needsrelease;
- }
- $needsrelease =
- $Apache::lonnet::needsrelease{"parameter::::$namematch"};
- if (($needsrelease) && (($currneeded eq '') || ($needsrelease < $currneeded))) {
unless ($got_chostname) {
- ($chostname,$cmajor,$cminor) = ¶meter_release_vars();
+ ($chostname,$cmajor,$cminor)=¶meter_release_vars();
$got_chostname = 1;
}
- $needsnewer = ¶meter_releasecheck(undef,$valchk,$valmatch,$namematch,
- $needsrelease,$cmajor,$cminor);
- } else {
+ $needsnewer = ¶meter_releasecheck($name,$valchk,$valmatch,undef,
+ $needsrelease,
+ $cmajor,$cminor);
+ }
+ }
+ if ($namematch ne '') {
+ if ($needsnewer) {
undef($namematch);
+ } else {
+ my $currneeded;
+ if ($needsrelease) {
+ $currneeded = $needsrelease;
+ }
+ $needsrelease =
+ $Apache::lonnet::needsrelease{"parameter::::$namematch"};
+ if (($needsrelease) &&
+ (($currneeded eq '') || ($needsrelease < $currneeded))) {
+ unless ($got_chostname) {
+ ($chostname,$cmajor,$cminor) = ¶meter_release_vars();
+ $got_chostname = 1;
+ }
+ $needsnewer = ¶meter_releasecheck(undef,$valchk,$valmatch,
+ $namematch, $needsrelease,$cmajor,$cminor);
+ } else {
+ undef($namematch);
+ }
}
}
+ if ($needsnewer) {
+ $r->print('<br />'.&oldversion_warning($name,$namematch,$data,
+ $chostname,$cmajor,
+ $cminor,$needsrelease));
+ next;
+ }
}
- if ($needsnewer) {
- $r->print('<br />'.&oldversion_warning($name,$namematch,$data,
- $chostname,$cmajor,
- $cminor,$needsrelease));
- next;
- }
- }
- if (defined($data) and $$olddata{$thiskey} ne $data) {
- if ($tuname) {
- if (&Apache::lonnet::put('resourcedata',{$tkey=>$data,
- $tkey.'.type' => $typeof},
- $tudom,$tuname) eq 'ok') {
- &log_parmset({$tkey=>$data,$tkey.'.type' => $typeof},0,$tuname,$tudom);
- $r->print('<br />'.$text.' '.
- &Apache::loncommon::plainname($tuname,$tudom));
+ if (defined($data) and $$olddata{$thiskey} ne $data) {
+ if ($tuname) {
+ if (&Apache::lonnet::put('resourcedata',{$tkey=>$data,
+ $tkey.'.type' => $typeof},
+ $tudom,$tuname) eq 'ok') {
+ &log_parmset({$tkey=>$data,$tkey.'.type' => $typeof},0,$tuname,$tudom);
+ $r->print('<br />'.$text.' '.
+ &Apache::loncommon::plainname($tuname,$tudom));
+ } else {
+ $r->print('<div class="LC_error">'.
+ &mt('Error saving parameters').'</div>');
+ }
+ &Apache::lonnet::devalidateuserresdata($tuname,$tudom);
} else {
- $r->print('<div class="LC_error">'.
- &mt('Error saving parameters').'</div>');
+ $newdata{$thiskey}=$data;
+ $newdata{$thiskey.'.type'}=$typeof;
}
- &Apache::lonnet::devalidateuserresdata($tuname,$tudom);
- } else {
- $newdata{$thiskey}=$data;
- $newdata{$thiskey.'.type'}=$typeof;
}
- }
} elsif ($cmd eq 'del') {
if ($tuname) {
if (&Apache::lonnet::del('resourcedata',[$tkey],$tudom,$tuname) eq 'ok') {
@@ -3697,11 +3808,20 @@
}
}
+# Returns the username and domain from a key created in readdata from a resourcedata key.
+#
+# @param {string} $key - the key
+# @returns {Array}
sub extractuser {
my $key=shift;
return ($key=~/^$env{'request.course.id'}.\[useropt\:($match_username)\:($match_domain)\]\./);
}
+# Parses a parameter key and returns the components.
+#
+# @param {string} $key -
+# @param {hash reference} $listdata -
+# @return {Array} - (student, resource, part, parameter)
sub parse_listdata_key {
my ($key,$listdata) = @_;
# split into student/section affected, and
@@ -3722,7 +3842,15 @@
return ($student,$res,$part,$parm);
}
-# Displays forms for the given data in overview mode (newoverview or overview).
+# Prints HTML with forms for the given parameter data in overview mode (newoverview or overview).
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $resourcedata - parameter data returned by readdata
+# @param {hash reference} $listdata - data created in secgroup_lister, course id.[section id].part.name -> 1 or course id.[section id].part.name.type -> parameter type
+# @param {string} $sortorder - realmstudent|studentrealm
+# @param {string} $caller - name of the calling sub (overview|newoverview)
+# @param {hash reference} $classlist - from loncoursedata::get_classlist
+# @returns{integer} - number of $listdata parameters processed
sub listdata {
my ($r,$resourcedata,$listdata,$sortorder,$caller,$classlist)=@_;
@@ -3925,6 +4053,12 @@
return $foundkeys;
}
+# Returns a string representing the interval, directly using form data matching the given key.
+# The returned string may also include information related to proctored exams.
+# Format: seconds['_done'[':'done button title':']['_proctor'['_'proctor key]]]
+#
+# @param {string} $key - suffix for form fields related to the interval
+# @returns {string}
sub get_date_interval_from_form {
my ($key) = @_;
my $seconds = 0;
@@ -3957,6 +4091,12 @@
}
+# Returns HTML to enter a text value for a parameter.
+#
+# @param {string} $thiskey - parameter key
+# @param {string} $showval - the current value
+# @param {boolean} $readonly - true if the field should not be made editable
+# @returns {string}
sub default_selector {
my ($thiskey, $showval, $readonly) = @_;
my $disabled;
@@ -3966,6 +4106,12 @@
return '<input type="text" name="set_'.$thiskey.'" value="'.$showval.'"'.$disabled.' />';
}
+# Returns HTML to enter allow/deny rules related to IP addresses.
+#
+# @param {string} $thiskey - parameter key
+# @param {string} $showval - the current value
+# @param {boolean} $readonly - true if the fields should not be made editable
+# @returns {string}
sub string_ip_selector {
my ($thiskey, $showval, $readonly) = @_;
my %access = (
@@ -4079,6 +4225,11 @@
acc => 'string_ip',
);
+# Returns the possible values and titles for a given string type, or undef if there are none.
+# Used by courseprefs.
+#
+# @param {string} $string_type - a parameter type for strings
+# @returns {array reference} - 2D array, containing values and English titles
sub standard_string_options {
my ($string_type) = @_;
if (ref($strings{$string_type}) eq 'ARRAY') {
@@ -4087,6 +4238,10 @@
return;
}
+# Returns regular expressions to match kinds of string types, or undef if there are none.
+#
+# @param {string} $string_type - a parameter type for strings
+# @returns {array reference} - 2D array, containing regular expression names and regular expressions
sub standard_string_matches {
my ($string_type) = @_;
if (ref($stringmatches{$string_type}) eq 'ARRAY') {
@@ -4095,6 +4250,10 @@
return;
}
+# Returns a parameter type for a given parameter with a string type, or undef if not known.
+#
+# @param {string} $name - parameter name
+# @returns {string}
sub get_stringtype {
my ($name) = @_;
if (exists($stringtypes{$name})) {
@@ -4103,6 +4262,14 @@
return;
}
+# Returns HTML to edit a string parameter.
+#
+# @param {string} $thistype - parameter type
+# @param {string} $thiskey - parameter key
+# @param {string} $showval - parameter current value
+# @param {string} $name - parameter name
+# @param {boolean} $readonly - true if the values should not be made editable
+# @returns {string}
sub string_selector {
my ($thistype, $thiskey, $showval, $name, $readonly) = @_;
@@ -4268,6 +4435,10 @@
interval => 'date_interval',
);
+# Returns regular expressions to match kinds of interval type, or undef if there are none.
+#
+# @param {string} $interval_type - a parameter type for intervals
+# @returns {array reference} - 2D array, containing regular expression names and regular expressions
sub standard_interval_matches {
my ($interval_type) = @_;
if (ref($intervalmatches{$interval_type}) eq 'ARRAY') {
@@ -4276,6 +4447,10 @@
return;
}
+# Returns a parameter type for a given parameter with an interval type, or undef if not known.
+#
+# @param {string} $name - parameter name
+# @returns {string}
sub get_intervaltype {
my ($name) = @_;
if (exists($intervaltypes{$name})) {
@@ -4284,6 +4459,11 @@
return;
}
+# Returns the possible values and titles for a given interval type, or undef if there are none.
+# Used by courseprefs.
+#
+# @param {string} $interval_type - a parameter type for intervals
+# @returns {array reference} - 2D array, containing values and English titles
sub standard_interval_options {
my ($interval_type) = @_;
if (ref($intervals{$interval_type}) eq 'ARRAY') {
@@ -4292,6 +4472,13 @@
return;
}
+# Returns HTML to edit a date interval parameter.
+#
+# @param {string} $thiskey - parameter key
+# @param {string} $name - parameter name
+# @param {string} $showval - parameter current value
+# @param {boolean} $readonly - true if the values should not be made editable
+# @returns {string}
sub date_interval_selector {
my ($thiskey, $name, $showval, $readonly) = @_;
my ($result,%skipval);
@@ -4393,6 +4580,16 @@
return $result;
}
+# Returns HTML with a warning if a parameter requires a more recent version of LON-CAPA.
+#
+# @param {string} $name - parameter name
+# @param {string} $namematch - parameter level name (recognized: resourcelevel|maplevel|maplevelrecurse|courselevel)
+# @param {string} $value - parameter value
+# @param {string} $chostname - course server name
+# @param {integer} $cmajor - major version number
+# @param {integer} $cminor - minor version number
+# @param {string} $needsrelease - release version needed (major.minor)
+# @returns {string}
sub oldversion_warning {
my ($name,$namematch,$value,$chostname,$cmajor,$cminor,$needsrelease) = @_;
my $standard_name = &standard_parameter_names($name);
@@ -4468,10 +4665,11 @@
} # end of block using some constants related to parameter types
-#
-# Shift all start and end dates by $shift
-#
+# Shifts all start and end dates in the current course by $shift.
+#
+# @param {integer} $shift - time to shift, in seconds
+# @returns {string} - error name or 'ok'
sub dateshift {
my ($shift)=@_;
my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4503,6 +4701,9 @@
return $reply;
}
+# Overview mode UI to edit course parameters.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub newoverview {
my ($r) = @_;
@@ -4676,6 +4877,20 @@
$r->print(&Apache::loncommon::end_page());
}
+# Fills $listdata with parameter information.
+# Keys use the format course id.[section id].part.name and course id.[section id].part.name.type.
+# The non-type value is always 1.
+#
+# @param {string} $cat - parameter name
+# @param {string} $pschp - selected map id, or 'all'
+# @param {string} $parmlev - selected level value (full|map|general), or ''
+# @param {hash reference} $listdata - the parameter data that will be modified
+# @param {array reference} $psprt - selected parts
+# @param {array reference} $selections - selected sections
+# @param {hash reference} $defkeytype - hash parameter name -> parameter type
+# @param {hash reference} $allmaps - hash map id -> map src
+# @param {array reference} $ids - resource ids
+# @param {hash reference} $symbp - hash map id or resource id -> map src.'___(all)' for a map or resource symb for a resource
sub secgroup_lister {
my ($cat,$pschp,$parmlev,$listdata,$psprt,$selections,$defkeytype,$allmaps,$ids,$symbp) = @_;
foreach my $item (@{$selections}) {
@@ -4714,7 +4929,10 @@
}
}
-# Display all existing parameter settings.
+# UI to edit parameter settings starting with a list of all existing parameters.
+# (called by setoverview action)
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub overview {
my ($r) = @_;
my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4762,6 +4980,8 @@
}
# Unused sub.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub clean_parameters {
my ($r) = @_;
my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4850,7 +5070,10 @@
$r->print(&Apache::loncommon::end_page());
}
-# Overview mode, UI to shift all dates.
+# UI to shift all dates (called by dateshift1 action).
+# Used by overview mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub date_shift_one {
my ($r) = @_;
my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4879,7 +5102,9 @@
$r->print(&Apache::loncommon::end_page());
}
-# Overview mode, UI to shift all dates (second form).
+# UI to shift all dates (second form).
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub date_shift_two {
my ($r) = @_;
my $dom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -4907,6 +5132,13 @@
$r->print(&Apache::loncommon::end_page());
}
+# Returns the different components of a resourcedata key.
+# Keys: scope_type, scope, realm_type, realm, realm_title,
+# realm_exists, parameter_part, parameter_name.
+# Was used by clean_parameters (which is unused).
+#
+# @param {string} $key - the parameter key
+# @returns {hash}
sub parse_key {
my ($key) = @_;
my %data;
@@ -4947,6 +5179,7 @@
}
+# Calls loncommon::start_page with the "Settings" title.
sub header {
return &Apache::loncommon::start_page('Settings');
}
@@ -4957,6 +5190,10 @@
# MAIN MENU
##################################################
+# Content and problem settings main menu.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {boolean} $parm_permission - true if the user has permission to edit the current course or section
sub print_main_menu {
my ($r,$parm_permission)=@_;
#
@@ -5060,6 +5297,13 @@
# PORTFOLIO METADATA
##################################################
+# Prints HTML to edit an item of portfolio metadata. The HTML contains several td elements (no tr).
+# It looks like field titles are not localized.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $field_name - metadata field name
+# @param {string} $field_text - metadata field title, in English unless manually added
+# @param {boolean} $added_flag - true if the field was manually added
sub output_row {
my ($r, $field_name, $field_text, $added_flag) = @_;
my $output;
@@ -5117,6 +5361,9 @@
# UI to order portfolio metadata fields.
+# Currently useless because addmetafield does not work.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub order_meta_fields {
my ($r)=@_;
my $idx = 1;
@@ -5207,6 +5454,8 @@
}
+# Returns HTML with a Continue button redirecting to the initial portfolio metadata screen.
+# @returns {string}
sub continue {
my $output;
$output .= '<form action="" method="post">';
@@ -5216,6 +5465,10 @@
}
+# UI to add a metadata field.
+# Currenly does not work because of an HTML error (the field is not visible).
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub addmetafield {
my ($r)=@_;
&Apache::lonhtmlcommon::add_breadcrumb({href=>'/adm/parmset?action=addmetadata',
@@ -5260,7 +5513,7 @@
$r->print('<input type="submit" name="undelete" value="Undelete" />');
$r->print('</form>');
}
- $r->print('<hr /><strong>Or</strong> you may enter a new metadata field name.<form method="post" action="/adm/parmset?action=addmetadata"');
+ $r->print('<hr /><strong>Or</strong> you may enter a new metadata field name.<form method="post" action="/adm/parmset?action=addmetadata"'); # FIXME: HTML error, input will not be displayed !
$r->print('<input type="text" name="fieldname" /><br />');
$r->print('<input type="submit" value="Add Metadata Field" />');
}
@@ -5271,6 +5524,8 @@
# Display or save portfolio metadata.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub setrestrictmeta {
my ($r)=@_;
my $next_meta;
@@ -5346,7 +5601,7 @@
my $added_flag = 1;
foreach my $field (sort(keys(%$added_metadata_fields))) {
$row_alt = $row_alt ? 0 : 1;
- $output.= &output_row($r, $field, $$added_metadata_fields{$field},$added_flag, $row_alt);
+ $output.= &output_row($r, $field, $$added_metadata_fields{$field},$added_flag, $row_alt); # FIXME: wrong parameters
}
$output .= &Apache::loncommon::end_data_table();
$r->print(<<ENDenv);
@@ -5361,6 +5616,10 @@
}
+# Returns metadata fields that have been manually added.
+#
+# @param {string} $cid - course id
+# @returns {hash reference} - hash field name -> field title (not localized)
sub get_added_meta_fieldnames {
my ($cid) = @_;
my %fields;
@@ -5375,6 +5634,10 @@
}
+# Returns metadata fields that have been manually added and deleted.
+#
+# @param {string} $cid - course id
+# @returns {hash reference} - hash field name -> field title (not localized)
sub get_deleted_meta_fieldnames {
my ($cid) = @_;
my %fields;
@@ -5396,6 +5659,8 @@
##################################################
# UI to change parameter setting default actions
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub defaultsetter {
my ($r) = @_;
@@ -5489,8 +5754,8 @@
push @datedisplay,&mt('Automatically set earlier than ').$tempkey;
}
}
-$r->print(&mt('Manual setting rules apply to all interfaces.').'<br />'.
- &mt('Automatic setting rules apply to table mode interfaces only.'));
+ $r->print(&mt('Manual setting rules apply to all interfaces.').'<br />'.
+ &mt('Automatic setting rules apply to table mode interfaces only.'));
$r->print("\n".&Apache::loncommon::start_data_table().
&Apache::loncommon::start_data_table_header_row().
"<th>".&mt('Rule for parameter').'</th><th>'.
@@ -5562,6 +5827,28 @@
# PARAMETER CHANGES LOG
##################################################
+# Returns some info for a parameter log entry.
+# Returned entries:
+# $realm - HTML title for the parameter level and resource
+# $section - parameter section
+# $name - parameter name
+# $part - parameter part
+# $what - $part.'.'.$name
+# $middle - resource symb ?
+# $uname - user name (same as given)
+# $udom - user domain (same as given)
+# $issection - section or group name
+# $realmdescription - title for the parameter level and resource (without using HTML)
+#
+# FIXME: remove unused fields.
+#
+# @param {string} $key - parameter log key
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @param {string} $exeuser - unused
+# @param {string} $exedomain - unused
+# @param {boolean} $typeflag - .type log entry
+# @returns {Array}
sub components {
my ($key,$uname,$udom,$exeuser,$exedomain,$typeflag)=@_;
@@ -5610,9 +5897,10 @@
$what,$middle,$uname,$udom,$issection,$realmdescription);
}
-my %standard_parms;
-my %standard_parms_types;
+my %standard_parms; # hash parameter name -> parameter title (not localized)
+my %standard_parms_types; # hash parameter name -> parameter type
+# Reads parameter info from packages.tab into %standard_parms.
sub load_parameter_names {
open(my $config,"<$Apache::lonnet::perlvar{'lonTabDir'}/packages.tab");
while (my $configline=<$config>) {
@@ -5631,6 +5919,10 @@
$standard_parms{'int_zero_pos'} = 'Positive Integer or Zero';
}
+# Returns a parameter title for standard parameters, the name for others.
+#
+# @param {string} $name - parameter name
+# @returns {string}
sub standard_parameter_names {
my ($name)=@_;
if (!%standard_parms) {
@@ -5643,6 +5935,10 @@
}
}
+# Returns a parameter type for standard parameters, undef for others.
+#
+# @param {string} $name - parameter name
+# @returns {string}
sub standard_parameter_types {
my ($name)=@_;
if (!%standard_parms_types) {
@@ -5654,6 +5950,10 @@
return;
}
+# Returns a parameter level title (not localized) from the parameter level name.
+#
+# @param {string} $name - parameter level name (recognized: resourcelevel|maplevel|maplevelrecurse|courselevel)
+# @returns {string}
sub standard_parameter_levels {
my ($name)=@_;
my %levels = (
@@ -5669,6 +5969,8 @@
}
# Display log for parameter changes, blog postings, user notification changes.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
sub parm_change_log {
my ($r)=@_;
my $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
@@ -5863,7 +6165,17 @@
# MISC !
##################################################
+# Stores slot information.
# Used by table UI
+# FIXME: I don't understand how this can work when the symb is not defined (if only a map was selected)
+#
+# @param {string} $slot_name - slot name
+# @param {string} $cdom - course domain
+# @param {string} $cnum - course number
+# @param {string} $symb - resource symb
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @returns {string} - 'ok' or error name
sub update_slots {
my ($slot_name,$cdom,$cnum,$symb,$uname,$udom) = @_;
my %slot=&Apache::lonnet::get_slot($slot_name);
@@ -5917,7 +6229,17 @@
return $success;
}
+# Deletes a slot reservation.
# Used by table UI
+# FIXME: I don't understand how this can work when the symb is not defined (if only a map was selected)
+#
+# @param {string} $slot_name - slot name
+# @param {string} $cdom - course domain
+# @param {string} $cnum - course number
+# @param {string} $uname - user name
+# @param {string} $udom - user domain
+# @param {string} $symb - resource symb
+# @returns {string} - 'ok' or error name
sub delete_slots {
my ($slot_name,$cdom,$cnum,$uname,$udom,$symb) = @_;
my $delresult;
@@ -5953,13 +6275,19 @@
return $delresult;
}
+# Returns true if there is a current course.
# Used by handler
+#
+# @returns {boolean}
sub check_for_course_info {
my $navmap = Apache::lonnavmaps::navmap->new();
return 1 if ($navmap);
return 0;
}
+# Returns the current course host and host LON-CAPA version.
+#
+# @returns {Array} - (course hostname, major version number, minor version number)
sub parameter_release_vars {
my $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
my $chome = $env{'course.'.$env{'request.course.id'}.'.home'};
@@ -5969,6 +6297,17 @@
return ($chostname,$cmajor,$cminor);
}
+# Checks if the course host version can handle a parameter required version,
+# and if it does, stores the release needed for the course.
+#
+# @param {string} $name - parameter name
+# @param {string} $value - parameter value
+# @param {string} $valmatch - name of the test used for checking the value
+# @param {string} $namematch - name of the test used for checking the name
+# @param {string} $needsrelease - version needed by the parameter, major.minor
+# @param {integer} $cmajor - course major version number
+# @param {integer} $cminor - course minor version number
+# @returns {boolean} - true if a newer version is needed
sub parameter_releasecheck {
my ($name,$value,$valmatch,$namematch,$needsrelease,$cmajor,$cminor) = @_;
my $needsnewer;
More information about the LON-CAPA-cvs
mailing list