From 4f758064d9dd6962105860710217473af9407e8f Mon Sep 17 00:00:00 2001
From: Sean Harvey <sean@silverstripe.com>
Date: Tue, 27 May 2008 04:49:16 +0000
Subject: [PATCH] FEATURE Allow setting a flag (true, by default) so that you
 can't use the "back" form action for a step.

---
 code/MultiForm.php     | 35 ++++++++++++++++++++---------------
 code/MultiFormStep.php | 18 ++++++++++++++++++
 2 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/code/MultiForm.php b/code/MultiForm.php
index 3c4fbfd..4c5ab72 100644
--- a/code/MultiForm.php
+++ b/code/MultiForm.php
@@ -83,18 +83,21 @@ abstract class MultiForm extends Form {
 	 * takes the fields, actions and validation (if any) for the step, setting up the form.
 	 */
 	public function init() {
-		// Set up the session
+		// Set up the session for this MultiForm instance
 		$this->setSession();
 		
-		// Get the current step, and set it
+		// Get the current step available (Note: either returns an existing
+		// step or creates a new one if none available)
 		$currentStep = $this->getCurrentStep();
+		
+		// Set the step returned above as the current step
 		$this->setCurrentStep($currentStep);
 		
-		// Set up the fields from the current step
+		// Set up the fields for the current step
 		$this->setFields($currentStep->getFields());
 		
-		// Set up the actions from the current step
-		$this->setActions();
+		// Set up the actions for the current step
+		$this->setActions($currentStep);
 		
 		// Set a hidden field in the form to identify this session.
 		// Depending on what has been configured for $url_type, we
@@ -102,7 +105,7 @@ abstract class MultiForm extends Form {
 		$urlMethod = $this->stat('url_type');
 		$this->fields->push(new HiddenField('MultiFormSessionID', false, $this->session->$urlMethod));
 		
-		// Set up validator from the form step class
+		// Set up validator for the step
 		$this->setValidator();
 		
 		// If there is form data, we populate it here (CAUTION: loadData() MUST unserialize first!)
@@ -282,32 +285,34 @@ abstract class MultiForm extends Form {
 	 * If there are any extra actions defined in MultiFormStep->getExtraActions()
 	 * then that set of actions is appended to the end of the actions FieldSet we
 	 * have created in this method.
+	 * 
+	 * @param $currentStep Subclass of MultiFormStep to set actions for
 	 */
-	function setActions() {
+	function setActions($currentStep) {
 		// Create default multi step actions (next, prev), and merge with extra actions, if any
 		$this->actions = new FieldSet();
 		
 		// If the form is at final step, create a submit button to perform final actions
 		// The last step doesn't have a next button, so add that action to any step that isn't the final one
-		if($this->getCurrentStep()->isFinalStep()) {
+		if($currentStep->isFinalStep()) {
 			$this->actions->push(new FormAction('finish', _t('MultiForm.SUBMIT', 'Submit')));
 		} else {
 			$this->actions->push(new FormAction('next', _t('MultiForm.NEXT', 'Next')));
 		}
 
 		// If there is a previous step defined, add the back button
-		if($this->getCurrentStep()->getPreviousStep()) {
-			if($this->actions->fieldByName('action_next')) {
+		if($currentStep->getPreviousStep() && $currentStep->canGoBack()) {
+			// If there is a next step, insert the action before the next action
+			if($currentStep->getNextStep()) {
 				$this->actions->insertBefore(new FormAction('prev', _t('MultiForm.BACK', 'Back')), 'action_next');
-			} elseif($this->actions->fieldByName('action_finish')) {
-				$this->actions->insertBefore(new FormAction('prev', _t('MultiForm.BACK', 'Back')), 'action_finish');
+			// Assume that this is the last step, insert the action before the finish action
 			} else {
-				$this->actions->push(new FormAction('prev', _t('MultiForm.BACK', 'Back')));
+				$this->actions->insertBefore(new FormAction('prev', _t('MultiForm.BACK', 'Back')), 'action_finish');
 			}
 		}
 
 		// Merge any extra action fields defined on the step
-		$this->actions->merge($this->getCurrentStep()->getExtraActions());
+		$this->actions->merge($currentStep->getExtraActions());
 	}
 	
 	/**
@@ -395,7 +400,7 @@ abstract class MultiForm extends Form {
 	 * @param object $form The form that the action was called on
 	 */
 	public function prev($data, $form) {
-		if(!$this->getCurrentStep()->getPreviousStep()) {
+		if(!$this->getCurrentStep()->getPreviousStep() && !$this->getCurrentStep()->canGoBack()) {
 			Director::redirectBack();
 			return false;
 		}
diff --git a/code/MultiFormStep.php b/code/MultiFormStep.php
index 5eec4f7..ffb2303 100644
--- a/code/MultiFormStep.php
+++ b/code/MultiFormStep.php
@@ -42,6 +42,14 @@ class MultiFormStep extends DataObject {
 	 */
 	protected static $is_final_step = false;
 
+	/**
+	 * This variable determines whether a user can use
+	 * the "back" action from this step.
+	 *
+	 * @var boolean
+	 */
+	protected static $can_go_back = true;
+	
 	/**
 	 * Title of this step.
 	 * 
@@ -232,6 +240,16 @@ class MultiFormStep extends DataObject {
 	
 	// ##################### Utility ####################
 	
+	/**
+	 * Determines whether the user is able to go back using the "action_back"
+	 * form action, based on the boolean value of $can_go_back.
+	 * 
+	 * @return boolean
+	 */
+	public function canGoBack() {
+		return $this->stat('can_go_back');
+	}
+	
 	/**
 	 * Determines whether this step is the final step in the multi-step process or not,
 	 * based on the variable $is_final_step - which must be defined on at least one step.