--- loncom/interface/lonhelper.pm	2003/03/27 20:58:16	1.3
+++ loncom/interface/lonhelper.pm	2003/03/28 20:25:19	1.4
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # .helper XML handler to implement the LON-CAPA helper
 #
-# $Id: lonhelper.pm,v 1.3 2003/03/27 20:58:16 bowersj2 Exp $
+# $Id: lonhelper.pm,v 1.4 2003/03/28 20:25:19 bowersj2 Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -105,7 +105,7 @@ use Apache::lonxml;
 
 BEGIN {
     &Apache::lonxml::register('Apache::lonhelper', 
-                              ('helper', 'state', 'message'));
+                              ('helper', 'state'));
 }
 
 # Since all wizards are only three levels deep (wizard tag, state tag, 
@@ -115,6 +115,10 @@ BEGIN {
 my $helper;
 my $state;
 my $substate;
+# To collect parameters, the contents of the subtags are collected
+# into this paramHash, then passed to the element object when the 
+# end of the element tag is located.
+my $paramHash; 
 
 sub handler {
     my $r = shift;
@@ -160,7 +164,7 @@ sub start_helper {
     }
     
     $helper = Apache::lonhelper::helper->new($token->[2]{'title'});
-    return 'helper made';
+    return '';
 }
 
 sub end_helper {
@@ -170,7 +174,7 @@ sub end_helper {
         return '';
     }
     
-    return 'Helper ended.';
+    return '';
 }
 
 sub start_state {
@@ -190,26 +194,6 @@ sub end_state {
     return '';
 }
 
-sub start_message {
-    my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
-
-    if ($target ne 'helper') {
-        return '';
-    }
-    
-    return &Apache::lonxml::get_all_text("/message", $parser);
-}
-
-sub end_message {
-    my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
-
-    if ($target ne 'helper') {
-        return '';
-    }
-    
-    return '';
-}
-
 1;
 
 package Apache::lonhelper::helper;
@@ -430,7 +414,11 @@ FOOTER
 package Apache::lonhelper::state;
 
 # States bundle things together and are responsible for compositing the
-# various elements together
+# various elements together. It is not generally necessary for users to
+# use the state object directly, so it is not perldoc'ed.
+
+# Basically, all the states do is pass calls to the elements and aggregate
+# the results.
 
 sub new {
     my $proto = shift;
@@ -458,6 +446,99 @@ sub title {
     return $self->{TITLE};
 }
 
+sub preprocess {
+    my $self = shift;
+    for my $element (@{$self->{ELEMENTS}}) {
+        $element->preprocess();
+    }
+}
+
+sub postprocess {
+    my $self = shift;
+    
+    for my $element (@{$self->{ELEMENTS}}) {
+        $element->postprocess();
+    }
+}
+
+sub overrideForm {
+    return 0;
+}
+
+sub addElement {
+    my $self = shift;
+    my $element = shift;
+    
+    push @{$self->{ELEMENTS}}, $element;
+}
+
+sub render {
+    my $self = shift;
+    my @results = ();
+
+    for my $element (@{$self->{ELEMENTS}}) {
+        push @results, $element->render();
+    }
+    return join("\n", @results);
+}
+
+1;
+
+package Apache::lonhelper::element;
+# Support code for elements
+
+=pod
+
+=head2 Element Base Class
+
+The Apache::lonhelper::element base class provides support methods for
+the elements to use, such as a multiple value processer.
+
+B<Methods>:
+
+=over 4
+
+=item * process_multiple_choices(formName, varName): Process the form 
+element named "formName" and place the selected items into the helper 
+variable named varName. This is for things like checkboxes or 
+multiple-selection listboxes where the user can select more then 
+one entry. The selected entries are delimited by triple pipes in 
+the helper variables, like this:  CHOICE_1|||CHOICE_2|||CHOICE_3
+
+=back
+
+=cut
+
+# Because we use the param hash, this is often a sufficent
+# constructor
+sub new {
+    my $proto = shift;
+    my $class = ref($proto) || $proto;
+    my $self = $paramHash;
+    bless($self, $class);
+
+    $self->{PARAMS} = $paramHash;
+    $self->{STATE} = $state;
+    $state->addElement($self);
+    
+    # Ensure param hash is not reused
+    $paramHash = {};
+
+    return $self;
+}   
+
+sub preprocess {
+    return 1;
+}
+
+sub postprocess {
+    return 1;
+}
+
+sub render {
+    return '';
+}
+
 sub process_multiple_choices {
     my $self = shift;
     my $formname = shift;
@@ -483,35 +564,99 @@ sub process_multiple_choices {
     return;
 }
 
-sub preprocess {
-    return 1;
+1;
+
+package Apache::lonhelper::message;
+
+=pod
+
+=head2 Element: message
+
+Message elements display the contents of their <message_text> tags, and
+transition directly to the state in the <next_state> tag. Example:
+
+ <message>
+   <next_state>GET_NAME</next_state>
+   <message_text>This is the <b>message</b> the user will see, 
+                 <i>HTML allowed</i>.</message_text>
+   </message>
+
+This will display the HTML message and transition to the <next_state> if
+given. The HTML will be directly inserted into the wizard, so if you don't
+want text to run together, you'll need to manually wrap the <message_text>
+in <p> tags, or whatever is appropriate for your HTML.
+
+This is also a good template for creating your own new states, as it has
+very little code beyond the state template.
+
+=cut
+
+no strict;
+@ISA = ("Apache::lonhelper::element");
+use strict;
+
+BEGIN {
+    &Apache::lonxml::register('Apache::lonhelper::message',
+                              ('message', 'next_state', 'message_text'));
 }
 
-sub postprocess {
-    return 1;
+# Don't need to override the "new" from element
+
+# CONSTRUCTION: Construct the message element from the XML
+sub start_message {
+    return '';
 }
 
-sub overrideForm {
-    return 1;
+sub end_message {
+    my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
+
+    if ($target ne 'helper') {
+        return '';
+    }
+    Apache::lonhelper::message->new();
+    return '';
 }
 
-sub addElement {
-    my $self = shift;
-    my $element = shift;
+sub start_next_state {
+    my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
+
+    if ($target ne 'helper') {
+        return '';
+    }
     
-    push @{$self->{ELEMENTS}}, $element;
+    $paramHash->{NEXT_STATE} = &Apache::lonxml::get_all_text('/next_state',
+                                                             $parser);
+    return '';
 }
 
+sub end_next_state { return ''; }
+
+sub start_message_text {
+    my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
+
+    if ($target ne 'helper') {
+        return '';
+    }
+
+    $paramHash->{MESSAGE_TEXT} = &Apache::lonxml::get_all_text('/message_text',
+                                                               $parser);
+}
+    
+sub end_message_text { return 1; }
+
 sub render {
     my $self = shift;
-    my @results = ();
 
-    for my $element (@{$self->{ELEMENTS}}) {
-        push @results, $element->render();
+    return $self->{MESSAGE_TEXT};
+}
+# If a NEXT_STATE was given, switch to it
+sub postprocess {
+    my $self = shift;
+    if (defined($self->{NEXT_STATE})) {
+        $helper->changeState($self->{NEXT_STATE});
     }
-    push @results, $self->title();
-    return join("\n", @results);
 }
+1;
 
 __END__