--- loncom/interface/lonhelper.pm 2003/09/02 20:58:31 1.44 +++ loncom/interface/lonhelper.pm 2007/07/25 23:20:38 1.161 @@ -1,7 +1,7 @@ # The LearningOnline Network with CAPA # .helper XML handler to implement the LON-CAPA helper # -# $Id: lonhelper.pm,v 1.44 2003/09/02 20:58:31 bowersj2 Exp $ +# $Id: lonhelper.pm,v 1.161 2007/07/25 23:20:38 albertel Exp $ # # Copyright Michigan State University Board of Trustees # @@ -25,10 +25,6 @@ # # http://www.lon-capa.org/ # -# (Page Handler -# -# (.helper handler -# =pod @@ -85,25 +81,28 @@ State tags are also required to have an human name of the state, and will be displayed as the header on top of the screen for the user. +State tags may also optionally have an attribute "help" which should be +the filename of a help file, this will add a blue ? to the title. + =head2 Example Helper Skeleton An example of the tags so far: - + -Of course this does nothing. In order for the wizard to do something, it is -necessary to put actual elements into the wizard. Documentation for each +Of course this does nothing. In order for the helper to do something, it is +necessary to put actual elements into the helper. Documentation for each of these elements follows. =head1 Creating a Helper With Code, Not XML -In some situations, such as the printing wizard (see lonprintout.pm), +In some situations, such as the printing helper (see lonprintout.pm), writing the helper in XML would be too complicated, because of scope issues or the fact that the code actually outweighs the XML. It is possible to create a helper via code, though it is a little odd. @@ -172,12 +171,24 @@ before parsing XML fragments and B # mod_perl connection. In this code, it was manifesting itself in the existence -# of two seperate file-scoped $helper variables, one set to the value of the +# of two separate file-scoped $helper variables, one set to the value of the # helper in the helper constructor, and one referenced by the handler on the # "$helper->process()" line. Using the debugger, one could actually # see the two different $helper variables, as hashes at completely @@ -247,7 +258,7 @@ sub real_handler { my $r = shift; my $uri = shift; if (!defined($uri)) { $uri = $r->uri(); } - $ENV{'request.uri'} = $uri; + $env{'request.uri'} = $uri; my $filename = '/home/httpd/html' . $uri; my $fh = Apache::File->new($filename); my $file; @@ -255,21 +266,13 @@ sub real_handler { # Send header, don't cache this page - if ($r->header_only) { - if ($ENV{'browser.mathml'}) { - $r->content_type('text/xml'); - } else { - $r->content_type('text/html'); - } - $r->send_http_header; - return OK; - } - if ($ENV{'browser.mathml'}) { - $r->content_type('text/xml'); + if ($env{'browser.mathml'}) { + &Apache::loncommon::content_type($r,'text/xml'); } else { - $r->content_type('text/html'); + &Apache::loncommon::content_type($r,'text/html'); } $r->send_http_header; + return OK if $r->header_only; $r->rflush(); # Discard result, we just want the objects that get created by the @@ -278,7 +281,7 @@ sub real_handler { my $allowed = $helper->allowedCheck(); if (!$allowed) { - $ENV{'user.error.msg'} = $ENV{'request.uri'}.':'.$helper->{REQUIRED_PRIV}. + $env{'user.error.msg'} = $env{'request.uri'}.':'.$helper->{REQUIRED_PRIV}. ":0:0:Permission denied to access this helper."; return HTTP_NOT_ACCEPTABLE; } @@ -334,7 +337,8 @@ sub start_state { } Apache::lonhelper::state->new($token->[2]{'name'}, - $token->[2]{'title'}); + $token->[2]{'title'}, + $token->[2]{'help'}); return ''; } @@ -359,9 +363,12 @@ sub end_state { package Apache::lonhelper::helper; use Digest::MD5 qw(md5_hex); -use HTML::Entities; +use HTML::Entities(); use Apache::loncommon; use Apache::File; +use Apache::lonlocal; +use Apache::lonnet; +use LONCAPA; sub new { my $proto = shift; @@ -373,16 +380,16 @@ sub new { # If there is a state from the previous form, use that. If there is no # state, use the start state parameter. - if (defined $ENV{"form.CURRENT_STATE"}) + if (defined $env{"form.CURRENT_STATE"}) { - $self->{STATE} = $ENV{"form.CURRENT_STATE"}; + $self->{STATE} = $env{"form.CURRENT_STATE"}; } else { $self->{STATE} = "START"; } - $self->{TOKEN} = $ENV{'form.TOKEN'}; + $self->{TOKEN} = $env{'form.TOKEN'}; # If a token was passed, we load that in. Otherwise, we need to create a # new storage file # Tried to use standard Tie'd hashes, but you can't seem to take a @@ -415,16 +422,16 @@ sub new { return undef; } # Must create the storage - $self->{TOKEN} = md5_hex($ENV{'user.name'} . $ENV{'user.domain'} . + $self->{TOKEN} = md5_hex($env{'user.name'} . $env{'user.domain'} . time() . rand()); $self->{FILENAME} = $Apache::lonnet::tmpdir . md5_hex($self->{TOKEN}); } # OK, we now have our persistent storage. - if (defined $ENV{"form.RETURN_PAGE"}) + if (defined $env{"form.RETURN_PAGE"}) { - $self->{RETURN_PAGE} = $ENV{"form.RETURN_PAGE"}; + $self->{RETURN_PAGE} = $env{"form.RETURN_PAGE"}; } else { @@ -453,11 +460,11 @@ sub _saveVars { my $self = shift; my $result = ""; $result .= '\n"; + HTML::Entities::encode($self->{STATE},'<>&"') . "\" />\n"; $result .= '\n"; $result .= '\n"; + HTML::Entities::encode($self->{RETURN_PAGE},'<>&"') . "\" />\n"; return $result; } @@ -467,9 +474,8 @@ sub _saveVars { sub _varsInFile { my $self = shift; my @vars = (); - for my $key (keys %{$self->{VARS}}) { - push @vars, &Apache::lonnet::escape($key) . '=' . - &Apache::lonnet::escape($self->{VARS}->{$key}); + for my $key (keys(%{$self->{VARS}})) { + push(@vars, &escape($key) . '=' . &escape($self->{VARS}->{$key})); } return join ('&', @vars); } @@ -484,12 +490,12 @@ sub declareVar { $self->{VARS}->{$var} = ''; } - my $envname = 'form.' . $var . '.forminput'; - if (defined($ENV{$envname})) { - if (ref($ENV{$envname})) { - $self->{VARS}->{$var} = join('|||', @{$ENV{$envname}}); + my $envname = 'form.' . $var . '_forminput'; + if (defined($env{$envname})) { + if (ref($env{$envname})) { + $self->{VARS}->{$var} = join('|||', @{$env{$envname}}); } else { - $self->{VARS}->{$var} = $ENV{$envname}; + $self->{VARS}->{$var} = $env{$envname}; } } } @@ -501,7 +507,7 @@ sub allowedCheck { return 1; } - return Apache::lonnet::allowed($self->{REQUIRED_PRIV}, $ENV{'request.course.id'}); + return Apache::lonnet::allowed($self->{REQUIRED_PRIV}, $env{'request.course.id'}); } sub changeState { @@ -523,7 +529,7 @@ sub process { # Phase 1: Post processing for state of previous screen (which is actually # the "current state" in terms of the helper variables), if it wasn't the # beginning state. - if ($self->{STATE} ne "START" || $ENV{"form.SUBMIT"} eq "Next ->") { + if ($self->{STATE} ne "START" || $env{"form.SUBMIT"} eq &mt("Next ->")) { my $prevState = $self->{STATES}{$self->{STATE}}; $prevState->postprocess(); } @@ -574,20 +580,28 @@ sub display { } # Phase 4: Display. - my $stateTitle = $state->title(); - my $bodytag = &Apache::loncommon::bodytag("$self->{TITLE}",'',''); + my $stateTitle=&mt($state->title()); + my $stateHelp= $state->help(); + my $browser_searcher_js = + ''; + + $result .= &Apache::loncommon::start_page($self->{TITLE}, + $browser_searcher_js); + + my $previous = HTML::Entities::encode(&mt("<- Previous"), '<>&"'); + my $next = HTML::Entities::encode(&mt("Next ->"), '<>&"'); + # FIXME: This should be parameterized, not concatenated - Jeremy + - $result .= < - - LON-CAPA Helper: $self->{TITLE} - - $bodytag -HEADER if (!$state->overrideForm()) { $result.="
"; } + if ($stateHelp) { + $stateHelp = &Apache::loncommon::help_open_topic($stateHelp); + } $result .= < -

$stateTitle

+

$stateTitle$stateHelp

HEADER $result .= "
"; @@ -607,12 +621,12 @@ HEADER } if ($self->{DONE}) { my $returnPage = $self->{RETURN_PAGE}; - $result .= "End Helper"; + $result .= "" . &mt("End Helper") . ""; } else { $result .= ' '; + $result .= ''; } } @@ -626,12 +640,12 @@ HEADER } if ($self->{DONE}) { my $returnPage = $self->{RETURN_PAGE}; - $result .= "End Helper"; + $result .= "" . &mt('End Helper') . ""; } else { $result .= ' '; + $result .= ''; } } @@ -646,10 +660,9 @@ HEADER
- - FOOTER + $result .= &Apache::loncommon::end_page(); # Handle writing out the vars to the file my $file = Apache::File->new('>'.$self->{FILENAME}); print $file $self->_varsInFile(); @@ -675,6 +688,7 @@ sub new { $self->{NAME} = shift; $self->{TITLE} = shift; + $self->{HELP} = shift; $self->{ELEMENTS} = []; bless($self, $class); @@ -696,6 +710,11 @@ sub title { return $self->{TITLE}; } +sub help { + my $self = shift; + return $self->{HELP}; +} + sub preprocess { my $self = shift; for my $element (@{$self->{ELEMENTS}}) { @@ -787,7 +806,7 @@ the element. How this value is interpret the element itself, and possibly the settings the element has (such as multichoice vs. single choice for tags). -This is also intended for things like the course initialization wizard, where the +This is also intended for things like the course initialization helper, where the user is setting various parameters. By correctly grabbing current settings and including them into the helper, it allows the user to come back to the helper later and re-execute it, without needing to worry about overwriting @@ -883,6 +902,7 @@ sub start_defaultvalue { sub end_defaultvalue { return ''; } +# Validators may need to take language specifications sub start_validator { my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_; @@ -926,7 +946,9 @@ package Apache::lonhelper::message; =pod -=head1 Element: messageX +=head1 Elements + +=head2 Element: messageX Message elements display their contents, and transition directly to the state in the attribute. Example: @@ -950,11 +972,17 @@ within each other.) This is also a good template for creating your own new states, as it has very little code beyond the state template. +=head3 Localization + +The contents of the message tag will be run through the +normalize_string function and that will be used as a call to &mt. + =cut no strict; @ISA = ("Apache::lonhelper::element"); use strict; +use Apache::lonlocal; BEGIN { &Apache::lonhelper::register('Apache::lonhelper::message', @@ -974,8 +1002,8 @@ sub start_message { return ''; } - $paramHash->{MESSAGE_TEXT} = &Apache::lonxml::get_all_text('/message', - $parser); + $paramHash->{MESSAGE_TEXT} = &mtn(&Apache::lonxml::get_all_text('/message', + $parser)); if (defined($token->[2]{'nextstate'})) { $paramHash->{NEXTSTATE} = $token->[2]{'nextstate'}; @@ -1009,6 +1037,175 @@ sub postprocess { } 1; +package Apache::lonhelper::helpicon; + +=pod + +=head1 Elements + +=head2 Element: helpiconX + +Helpicon elements add a help icon at the current location. +Example: + + + General Help + + +In this example will generate a help icon to the Help.hlp url with a +description of 'General Help'. The description is not required and if +left out (Example: only the icon will be +added.) + +=head3 Localization + +The description text will be run through the normalize_string function +and that will be used as a call to &mt. + +=cut + +no strict; +@ISA = ("Apache::lonhelper::element"); +use strict; +use Apache::lonlocal; + +BEGIN { + &Apache::lonhelper::register('Apache::lonhelper::helpicon', + ('helpicon')); +} + +sub new { + my $ref = Apache::lonhelper::element->new(); + bless($ref); +} + +# CONSTRUCTION: Construct the message element from the XML +sub start_helpicon { + my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_; + + if ($target ne 'helper') { + return ''; + } + + $paramHash->{HELP_TEXT} = &mtn(&Apache::lonxml::get_all_text('/helpicon', + $parser)); + + $paramHash->{HELP_TEXT} =~s/^\s+//; + $paramHash->{HELP_TEXT} =~s/\s+$//; + + if (defined($token->[2]{'file'})) { + $paramHash->{HELP_FILE} = $token->[2]{'file'}; + } + return ''; +} + +sub end_helpicon { + my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_; + + if ($target ne 'helper') { + return ''; + } + Apache::lonhelper::helpicon->new(); + return ''; +} + +sub render { + my $self = shift; + + my $text; + if ( $self->{HELP_TEXT} ne '') { + $text=&mtn($self->{HELP_TEXT}); + } + + return &Apache::loncommon::help_open_topic($self->{HELP_FILE}, + $text); +} +sub postprocess { + my $self = shift; + if (defined($self->{NEXTSTATE})) { + $helper->changeState($self->{NEXTSTATE}); + } + + return 1; +} + +1; + +package Apache::lonhelper::skip; + +=pod + +=head1 Elements + +=head2 Element: skipX + +The tag allows you define conditions under which the current state +should be skipped over and define what state to skip to. + + + + + #some code that decides whether to skip the state or not + + FINISH + + A possibly skipped state + + +=cut + +no strict; +@ISA = ("Apache::lonhelper::element"); +use strict; + +BEGIN { + &Apache::lonhelper::register('Apache::lonhelper::skip', + ('skip')); +} + +sub new { + my $ref = Apache::lonhelper::element->new(); + bless($ref); +} + +sub start_skip { + my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_; + + if ($target ne 'helper') { + return ''; + } + # let know what text to skip to + $paramHash->{SKIPTAG}='/skip'; + return ''; +} + +sub end_skip { + my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_; + + if ($target ne 'helper') { + return ''; + } + Apache::lonhelper::skip->new(); + return ''; +} + +sub render { + my $self = shift; + return ''; +} +# If a NEXTSTATE is set, switch to it +sub preprocess { + my ($self) = @_; + + if (defined($self->{NEXTSTATE})) { + $helper->changeState($self->{NEXTSTATE}); + } + + return 1; +} + +1; + package Apache::lonhelper::choices; =pod @@ -1058,6 +1255,16 @@ will be the state transistioned to if th the choice is not multichoice. This will override the nextstate passed to the parent C tag. + may optionally contain a 'relatedvalue' attribute, which +if present will cause a text entry to appear to the right of the +selection. The value of the relatedvalue attribute is a variable +into which the text entry will be stored e.g.: +[2]{'computer'}; - my $human = &Apache::lonxml::get_all_text('/choice', - $parser); - my $nextstate = $token->[2]{'nextstate'}; - my $evalFlag = $token->[2]{'eval'}; - push @{$paramHash->{CHOICES}}, [$human, $computer, $nextstate, - $evalFlag]; + my $human = &mt(&Apache::lonxml::get_all_text('/choice', + $parser)); + my $nextstate = $token->[2]{'nextstate'}; + my $evalFlag = $token->[2]{'eval'}; + my $relatedVar = $token->[2]{'relatedvalue'}; + my $relatedDefault = $token->[2]{'relateddefault'}; + push @{$paramHash->{CHOICES}}, [&mtn($human), $computer, $nextstate, + $evalFlag, $relatedVar, $relatedDefault]; return ''; } @@ -1157,6 +1368,13 @@ sub end_choice { return ''; } +{ + # used to generate unique id attributes for tags. + # internal use only. + my $id = 0; + sub new_id { return $id++; } +} + sub render { my $self = shift; my $var = $self->{'variable'}; @@ -1165,15 +1383,17 @@ sub render { if ($self->{'multichoice'}) { $result .= < + SCRIPT } @@ -1181,10 +1401,13 @@ SCRIPT # Only print "select all" and "unselect all" if there are five or # more choices; fewer then that and it looks silly. if ($self->{'multichoice'} && scalar(@{$self->{CHOICES}}) > 4) { + my %lt=&Apache::lonlocal::texthash( + 'sa' => "Select All", + 'ua' => "Unselect All"); $buttons = < - - + +
  BUTTONS } @@ -1236,22 +1459,31 @@ BUTTONS my $type = "radio"; if ($self->{'multichoice'}) { $type = 'checkbox'; } foreach my $choice (@{$self->{CHOICES}}) { + my $id = &new_id(); $result .= "\n \n"; - $result .= "[1]}) { - $result .= " checked "; + $result .= " checked='checked' "; } + $result .= qq{id="id$id"}; my $choiceLabel = $choice->[0]; - if ($choice->[4]) { # if we need to evaluate this choice + if ($choice->[3]) { # if we need to evaluate this choice $choiceLabel = "sub { my $helper = shift; my $state = shift;" . $choiceLabel . "}"; $choiceLabel = eval($choiceLabel); $choiceLabel = &$choiceLabel($helper, $self); } - $result .= "/> " . $choiceLabel . "\n"; + $result .= "/> ".qq{"; + if ($choice->[4]) { + $result .=''; + } + $result .= "\n"; } $result .= "\n\n\n"; $result .= $buttons; @@ -1263,11 +1495,11 @@ BUTTONS # given, switch to it sub postprocess { my $self = shift; - my $chosenValue = $ENV{'form.' . $self->{'variable'} . '.forminput'}; + my $chosenValue = $env{'form.' . $self->{'variable'} . '_forminput'}; if (!defined($chosenValue) && !$self->{'allowempty'}) { - $self->{ERROR_MSG} = "You must choose one or more choices to" . - " continue."; + $self->{ERROR_MSG} = + &mt("You must choose one or more choices to continue."); return 0; } @@ -1285,6 +1517,10 @@ sub postprocess { $helper->changeState($choice->[2]); } } + if ($choice->[4]) { + my $varname = $choice->[4]; + $helper->{'VARS'}->{$varname} = $env{'form.'."${varname}_forminput"}; + } } return 1; } @@ -1310,9 +1546,14 @@ the result is stored in. =cut +# This really ought to be a sibling class to "choice" which is itself +# a child of some abstract class.... *shrug* + no strict; @ISA = ("Apache::lonhelper::element"); use strict; +use Apache::lonlocal; +use Apache::lonnet; BEGIN { &Apache::lonhelper::register('Apache::lonhelper::dropdown', @@ -1387,13 +1628,13 @@ sub render { $checkedChoices{$self->{CHOICES}->[0]->[1]} = 1; } - $result .= "\n"; foreach my $choice (@{$self->{CHOICES}}) { $result .= "\n"; } $result .= "\n"; @@ -1413,7 +1654,7 @@ sub render { # given, switch to it sub postprocess { my $self = shift; - my $chosenValue = $ENV{'form.' . $self->{'variable'} . '.forminput'}; + my $chosenValue = $env{'form.' . $self->{'variable'} . '_forminput'}; if (!defined($chosenValue) && !$self->{'allowempty'}) { $self->{ERROR_MSG} = "You must choose one or more choices to" . @@ -1471,7 +1712,8 @@ Example: no strict; @ISA = ("Apache::lonhelper::element"); use strict; - +use Apache::lonlocal; # A localization nightmare +use Apache::lonnet; use Time::localtime; BEGIN { @@ -1499,6 +1741,7 @@ sub start_date { $paramHash->{'variable'} = $token->[2]{'variable'}; $helper->declareVar($paramHash->{'variable'}); $paramHash->{'hoursminutes'} = $token->[2]{'hoursminutes'}; + $paramHash->{'anytime'} = $token->[2]{'anytime'}; } sub end_date { @@ -1517,10 +1760,43 @@ sub render { my $var = $self->{'variable'}; my $date; - + + my $time=time; + my ($anytime,$onclick); + + + # first check VARS for a valid new value from the user + # then check DEFAULT_VALUE for a valid default time value + # otherwise pick now as reasonably good time + + if (defined($helper->{VARS}{$var}) + && $helper->{VARS}{$var} > 0) { + $date = localtime($helper->{VARS}{$var}); + } elsif (defined($self->{DEFAULT_VALUE})) { + my $valueFunc = eval($self->{DEFAULT_VALUE}); + die('Error in default value code for variable ' . + $self->{'variable'} . ', Perl said: ' . $@) if $@; + $time = &$valueFunc($helper, $self); + if (lc($time) eq 'anytime') { + $anytime=1; + $date = localtime(time); + $date->min(0); + } elsif (defined($time) && $time ne 0) { + $date = localtime($time); + } else { + # leave date undefined so it'll default to now + } + } + + if (!defined($date)) { + $date = localtime(time); + $date->min(0); + } + + if ($anytime) { + $onclick = "onclick=\"javascript:updateCheck(this.form,'${var}anytime',false)\""; + } # Default date: The current hour. - $date = localtime(); - $date->min(0); if (defined $self->{ERROR_MSG}) { $result .= '' . $self->{ERROR_MSG} . '

'; @@ -1528,22 +1804,22 @@ sub render { # Month my $i; - $result .= "\n"; for ($i = 0; $i < 12; $i++) { if ($i == $date->mon) { - $result .= "\n"; + $result .= &mt($months[$i]) . "\n"; } $result .= "\n"; # Day - $result .= "\n"; for ($i = 1; $i < 32; $i++) { if ($i == $date->mday) { - $result .= '\n"; for ($i = 1; $i < 12; $i++) { if ($date->hour == $i) { - $result .= "\n"; + $result .= "\n"; } else { - $result .= "\n"; + $result .= "\n"; } } - $result .= "\n"; + $result .= "\n"; for ($i = 13; $i < 24; $i++) { my $printedHour = $i - 12; if ($date->hour == $i) { - $result .= "\n"; + $result .= "\n"; } else { - $result .= "\n"; + $result .= "\n"; } } $result .= " :\n"; - $result .= "\n"; + my $selected=0; + for my $i ((0,15,30,45,59,undef,0..59)) { my $printedMinute = $i; - if ($i < 10) { + if (defined($i) && $i < 10) { $printedMinute = "0" . $printedMinute; } - if ($date->min == $i) { - $result .= "