# This is the LON-CAPA HTML Wizard framework, for wrapping easy
# functionality easily.

package Apache::lonwizard;

use Apache::Constants qw(:common :http);
use Apache::loncommon;

=head1 lonwizard - HTML "Wizard" framework for LON-CAPA

I know how most developers feel about Wizards, but the fact is they are a well-established UI widget that users feel comfortable with. It can take a complicated multi-dimensional problem the user has (such as the canonical Course Parameter example) and turn in into a series of bite-sized one-dimensional questions. Or take the some four-question form and put it in a Wizard, and present the same user with the same form outside of the Wizard, and the user will *think* the Wizard is easier.

For the developer, wizards do provide an easy way to bundle easy bits of functionality for the user. It can be easier to write a Wizard then provide another custom interface.

All classes are in the Apache::lonwizard namespace.

(For a perldoc'ed example of a wizard you can use as an example, see loncourseparmwizard.pm.)

=cut

# To prevent runaway file counts, this file has lonwizard,
# lonwizstate, and other wizard classes.
use strict;

use HTML::Entities;

=pod

=head1 Class: lonwizard

=head2 lonwizard Attributes

=over 4

=item B<STATE>: The string name of the current state.

=item B<TITLE>: The human-readable title of the wizard

=item B<STATES>: A hash mapping the string names of states to references to the actual states.

=item B<VARS>: Hash that maintains the persistent variable values.

=item B<HISTORY>: An array containing the names of the previous states. Used for "back" functionality.

=item B<DONE>: A boolean value, true if the wizard has completed.

=back

=cut

sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;
    my $self = {};

    # 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"})
    {
	$self->{STATE} = $ENV{"form.CURRENT_STATE"};
    }
    else
    {
	$self->{STATE} = "START";
    }

    # set up return URL: Return the user to the referer page, unless the
    # form has stored a value.
    if (defined $ENV{"form.RETURN_PAGE"})
    {
	$self->{RETURN_PAGE} = $ENV{"form.RETURN_PAGE"};
    }
    else
    {
	$self->{RETURN_PAGE} = $ENV{REFERER};
    }

    $self->{TITLE} = shift;
    $self->{STATES} = {};
    $self->{VARS} = {};
    $self->{HISTORY} = {};
    $self->{DONE} = 0;
    bless($self, $class);
    return $self;
}

=pod

=head2 lonwizard methods

=over 2

=item B<new>(title): Returns a new instance of the given wizard type. "title" is the human-readable name of the wizard. A new wizard always starts on the B<START> state name.

=item B<declareVars>(varList): Call this function to declare the var names you want the wizard to maintain for you. The wizard will automatically output the hidden form fields and parse the values for you on the next call.

=over 2

=item Note that these variables are reserved for the wizard; if you output other form values in your state, you must use other names. For example, declaring "student" will cause the wizard to emit a form value with the name "student"; if your state emits form entries, do not name them "student".

=back

=cut

sub declareVars {
    my $self = shift;
    my $varlist = shift;

    # for each string in the passed in list,
    foreach my $element ( @{$varlist} )
    {
	# assign the var the default of ""
	$self->{VARS}{$element} = "";

	# if there's a form in the env, use that instead
	my $envname = "form." . $element;
	if (defined ($ENV{$envname}))
	{
	    $self->{VARS}->{$element} = $ENV{$envname};
	}
    }
}

# Private function; takes all of the declared vars and returns a string
# corresponding to the hidden input fields that will re-construct the 
# variables.
sub _saveVars {
    my $self = shift;
    my $result = "";
    print $self->{VARS}{VAR1};
    foreach my $varname (keys %{$self->{VARS}})
    {
	$result .= '<input type="hidden" name="' .
	           HTML::Entities::encode($varname) . '" value="' .
		   HTML::Entities::encode($self->{VARS}{$varname}) . 
		   "\" />\n";
    }

    # also save state & return page
    $result .= '<input type="hidden" name="CURRENT_STATE" value="' .
               HTML::Entities::encode($self->{STATE}) . '" />' . "\n";
    $result .= '<input type="hidden" name="RETURN_PAGE" value="' .
               HTML::Entities::encode($self->{RETURN_PAGE}) . '" />' . "\n";

    return $result;
}

=pod

=item B<registerState>(referenceToStateObj): Registers a state as part of the wizard, so the wizard can use it. The 'referenceToStateObj' should be a reference to an instantiated lonwizstate object. This is normally called at the end of the lonwizstate constructor.

=cut

sub registerState {
    my $self = shift;
    my $state = shift;

    my $stateName = $state->name();
    $self->{STATES}{$stateName} = $state;
}

=pod

=item B<changeState>(stateName): Given a string representing the name of some registered state, this causes the wizard to change to that state. Generally, states will call this.

=cut

sub changeState {
    my $self = shift;
    $self->{STATE} = shift;
}

=pod

=item B<display>(): This is the main method that the handler using the wizard calls.

=cut

# Done in five phases
# 1: Do the post processing for the previous state.
# 2: Do the preprocessing for the current state.
# 3: Check to see if state changed, if so, postprocess current and move to next.
#    Repeat until state stays stable.
# 4: Render the current state to the screen as an HTML page.
sub display {
    my $self = shift;

    my $result = "";

    # Phase 1: Post processing for state of previous screen (which is actually
    # the current state), if it wasn't the beginning state.
    if ($self->{STATE} ne "START" || $ENV{"form.SUBMIT"} eq "Next ->")
    {
	my $prevState = $self->{STATES}{$self->{STATE}};
	$prevState->postprocess();
    }
    
    # Note, to handle errors in a state's input that a user must correct,
    # do not transition in the postprocess, and force the user to correct
    # the error.

    # Phase 2: Preprocess current state
    my $startState = $self->{STATE};
    my $state = $self->{STATES}{$startState};
    $state->preprocess();

    # Phase 3: While the current state is different from the previous state,
    # keep processing.
    while ( $startState ne $self->{STATE} )
    {
	$startState = $self->{STATE};
	$state = $self->{STATES}{$startState};
	$state->preprocess();
    }

    # Phase 4: Display.
    my $stateTitle = $state->title();

    $result .= <<HEADER;
<html>
    <head>
        <title>LON-CAPA Wizard: $self->{NAME}</title>
    </head>
    <body bgcolor="#FFFFFF">
        <h1 style="font: Ariel">LON-CAPA Wizard: $self->{TITLE}</h1>
	
	<h2><i>$stateTitle</i></h2>

	<form method="GET">
HEADER

    $result .= $self->_saveVars();
    $result .= $state->render() . "<p>&nbsp;</p>";

    if ($self->{STATE} ne $self->{START_STATE})
    {
	$result .= '<input name="SUBMIT" type="submit" value="&lt;- Previous" />&nbsp;&nbsp;';
    }
    if ($self->{DONE})
    {
	my $returnPage = $self->{RETURN_PAGE};
	$result .= "<a href=\"$returnPage\">End Wizard</a>";
    }
    else
    {
	$result .= '<input name="SUBMIT" type="submit" value="Next -&gt;" />';
    }
    

    $result .= <<FOOTER;
        </form>
    </body>
</html>
FOOTER
}

=pod

=item B<name>([name]): Returns the name of the wizard. If a parameter is passed, that will be saved as the name.

=cut

# Returns/sets the name of this wizard, i.e., "Assignment Parameter"
sub title {
    my $self = shift;
    if (@_) { $self->{TITLE} = shift};
    return $self->{TITLE};
}

=pod

=item B<getVars>(): Returns a hash reference containing the stored vars for this wizard. The states use this for variables maintained across states. Example: C<my %vars = %{$wizard-E<gt>getVars()};> This provides read-only access, apparently.

=cut

sub getVars {
    my $self = shift;
    return ($self->{VARS});
}

=pod

=item B<setVar>(key, val): Sets the var named "key" to "val" in the wizard's form array.

=cut

sub setVar {
    my $self = shift;
    my $key = shift;
    my $val = shift;
    $self->{VARS}{$key} = $val;
    print "set $key to $val<br>";
}

=pod

=item B<setDone>(): If a state calls this, the wizard will consider itself completed. The state should display a friendly "Done" message, and the wizard will display a link returning the user to the invoking page, rather then a "Next" button.

=cut


# A temp function for debugging
sub handler {
    my $r = shift;

    Apache::loncommon::get_unprocessed_cgi($ENV{QUERY_STRING});
    
    my $mes = "Using this wizard, you can <ul><li>change the due date of an assignment</li><li>change the due date for a whole map of assignments</li><li>change the due date for just one person</li></ul>";

    my $wizard = Apache::lonwizard->new("Test Wizard");

    my $mesState = Apache::lonwizard::message_state->new($wizard, "START", "Welcome to the Assignment Parameter Wizard", $mes, "NEXT");
    my $mesState2 = Apache::lonwizard::choice_state->new($wizard, "NEXT", "Fucking the Cow", "How should the cow be fucked?", "Wow, with so many wonderful choices, how will you choose!?!", "START", "VAR1", {'standing & dildoated','standing & didldoated', 'rotten','rotten', 'sitting','sitting'});
    $wizard->declareVars( ["VAR1", "VAR2", "VAR3"] );
    
    $r->print($wizard->display());

    return OK;
}



1;

=head1 Class: lonwizstate

A "lonwizstate" object represents a lonwizard state. A "state" is basically what is visible on the screen. For instance, a state may display a radio button dialog with three buttons, and wait for the user to choose one.

Several pre-prepared child classes are include in lonwizard. If you create a new wizard type, be sure to add it to lonwizard.pm so others can use it too.

=head2 lonwizstate methods

These methods should be overridden in derived states, except B<new> which may be sufficient.

=over 2

=item B<new> (parentLonWizReference, stateName, stateTitle): Creates a new state and returns it. The first argument is a reference to the parent wizard. The second is the name of the state, which I<must> be unique. The third is the title, which will be displayed on the screen to the human.

=item B<preprocess>(): preprocess sets up all of the information the state needs to do its job, such as querying data bases to obtain lists of choices, and sets up data for the render method. If preprocess decides to jump to a new state, it is responsible for manually running post-process, if it so desires.

=over 2

=item If this method calls the parent lonwizard's B<changeState> method to another state, then the state will never be rendered on the screen, and the wizard will move to the specified state. This is useful if the state may only be necessary to clarify an ambiguous input, such as selecting a part from a multi-part problem, which isn't necessary if the problem only has one state.

=back

=item B<render>(): render returns a string of itself to be rendered to the screen, which the wizard will display.

=back

=cut 

package Apache::lonwizard::state;

use strict;

sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;
    my $self = {};
    $self->{WIZARD} = shift;
    $self->{NAME} = shift;
    $self->{TITLE} = shift;

    bless($self);

    $self->{WIZARD}->registerState($self);
    return $self;
}

sub name {
    my $self = shift;
    if (@_) { $self->{NAME} = shift};
    return $self->{NAME};
}

sub title {
    my $self = shift;
    if (@_) { $self->{TITLE} = shift};
    return $self->{TITLE};
}

sub preprocess {
    return 1;
}

sub render {
    return "This is the empty state. If you can see this, it's a bug.\n"
}

sub postprocess {
    return 1;
}

1;

=pod

=back

=head1 Prepackaged States

lonwizard provides several pre-packaged states that you can drop into your Wizard and obtain common functionality.

=head2 Class: message_state

message_state is a state the simply displays a message. It does not do any pre- or postprocessing. It makes a good initial state, which traditionally is a short message telling the user what they are about to accomplish, and may contain warnings or preconditions that should be fulfilled before using the wizard.

=over 4

=item overridden method B<new>(parentLonWizReference, stateName, message, nextState): Two new parameters "message" will be the HTML message displayed to the user, and "nextState" is the name of the next state.

=back

=cut

package Apache::lonwizard::message_state;

no strict;
@ISA = ("Apache::lonwizard::state");
use strict;

sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;

    my $self = bless $proto->SUPER::new(shift, shift, shift);

    $self->{MESSAGE} = shift;
    $self->{NEXT_STATE} = shift;

    return $self;
}

sub postprocess {
    my $self = shift;
    $self->{WIZARD}->changeState($self->{NEXT_STATE});
    return 1;
}

sub render {
    my $self = shift;
    return $self->{MESSAGE};
}

1;

package Apache::lonwizard::choice_state;

no strict;
@ISA = ("Apache::lonwizard::state");
use strict;

sub new {
    my $proto = shift;
    my $class = ref($proto) || $proto;
    my $self = bless $proto->SUPER::new(shift, shift, shift);

    $self->{MESSAGE_BEFORE} = shift;
    $self->{MESSAGE_AFTER} = shift;
    $self->{NEXT_STATE} = shift;
    $self->{VAR_NAME} = shift;
    $self->{CHOICE_HASH} = shift;
    $self->{NO_CHOICES} = 0;
}

=pod

=head2 Class: choice_state

Choice state provides a single choice to the user as a text selection box. You pass it a message and hash containing [human_name] -> [computer_name] entries, and it will display the choices and store the result in the provided variable.

If there is only one choice, the state will automatically make it and go to the next state.

=over 4

=item overridden method B<new>(parentLonWizReference, stateName, stateTitle, messageBefore, messageAfter, nextState, varName, choiceHash): messageBefore is the HTML text that will be displayed before the choice display, messageAfter will display after. Keys will be sorted according to human name. nextState is the state to proceed to after the choice. varName is the name of the wizard var to store the computer_name answer in. choiceHash is the hash described above. It is optional because you may override it.

=cut

sub preprocess {
    my $self = shift;
    my %choices = %{$self->{CHOICE_HASH}};
    my %wizvars = %{$self->{WIZARD}->getVars()};

    my @keys = keys(%choices);
    @keys = sort @keys;

    if (scalar(@keys) == 0)
    {
	# No choices... so prepare to display error message and cancel further execution.
	$self->{NO_CHOICES} = 1;
	$self->{WIZARD}->setDone();
	return;
    }
    if (scalar(@keys) == 1)
    {
	# If there is only one choice, pick it and move on.
	$wizvars{$self->{VAR_NAME}} = $choices{$keys[0]};
	$self->{WIZARD}->changeState($self->{NEXT_STATE});
	return;
    }

    # Otherwise, do normal processing in the render routine.

    return;
}

sub determineChoices {
    return {"NO_CHOICE" => "No choices were given."};
}

sub render { 
    my $self = shift;
    my $result = "";
    my $var = $self->{VAR_NAME};
    my %choices = %{$self->{CHOICE_HASH}};

    if (!defined ($self->{CHOICE_HASH}))
    {
	$self->determineChoices();
    }

    my %choices = %{$self->{CHOICE_HASH}};
    my @keys = keys (%choices);

    $result .= "<select name=\"${var}.forminput\" size=\"10\">\n";

    foreach (@keys)
    {
	$result .= "<option value=\"" . HTML::Entities::encode($choices{$_}) .
	    "\">" . HTML::Entities::encode($_) . "\n";
    }

    $result .= "</select>\n\n";
    return $result;
}

sub postprocess {
    my $self = shift;
    my $wizard = $self->{WIZARD};
    $wizard->setVar($self->{VAR_NAME}, $ENV{"form." . $self->{VAR_NAME} . ".forminput"});
    $wizard->changeState($self->{NEXT_STATE});
    return 1;
}

package Apache::lonwizard::switch_state;

no strict;
@ISA = ("Apache::lonwizard::state");
use strict;