mirror of
https://github.com/silverstripe/silverstripe-multiform
synced 2024-10-22 11:05:49 +02:00
Added phpdoc to methods and classes
This commit is contained in:
parent
ec747bc6c6
commit
6f07bf39b2
@ -1,8 +1,9 @@
|
||||
<?php
|
||||
|
||||
/**
|
||||
* Manages the loading of single form steps, and acts as a state machine
|
||||
* that connects to a {@link MultiFormSession} object as a persistence layer.
|
||||
* MultiForm manages the loading of single form steps, and acts as a state
|
||||
* machine that connects to a {@link MultiFormSession} object as a persistence
|
||||
* layer.
|
||||
*
|
||||
* CAUTION: If you're using controller permission control,
|
||||
* you have to allow the following methods:
|
||||
@ -10,8 +11,6 @@
|
||||
* static $allowed_actions = array('next','prev');
|
||||
* </code>
|
||||
*
|
||||
* @todo Deal with Form->securityID
|
||||
*
|
||||
* @package multiform
|
||||
*/
|
||||
abstract class MultiForm extends Form {
|
||||
@ -49,6 +48,11 @@ abstract class MultiForm extends Form {
|
||||
*/
|
||||
protected static $url_type = 'Hash';
|
||||
|
||||
/**
|
||||
* Set the casting for these fields.
|
||||
*
|
||||
* @var array
|
||||
*/
|
||||
static $casting = array(
|
||||
'CompletedStepCount' => 'Int',
|
||||
'TotalStepCount' => 'Int',
|
||||
@ -114,6 +118,12 @@ abstract class MultiForm extends Form {
|
||||
|
||||
/**
|
||||
* Get the current step.
|
||||
*
|
||||
* If StepID has been set in the URL, we attempt to get that record
|
||||
* by the ID. Otherwise, we check if there's a current step ID in
|
||||
* our session record. Failing those cases, we assume that the form has
|
||||
* just been started, and so we create the first step and return it.
|
||||
*
|
||||
* @return MultiFormStep subclass
|
||||
*/
|
||||
public function getCurrentStep() {
|
||||
@ -152,8 +162,18 @@ abstract class MultiForm extends Form {
|
||||
}
|
||||
|
||||
/**
|
||||
* Set up the session. There's a bit of logic to determine this, specifically
|
||||
* checking if there's a GET variable for a current session set.
|
||||
* Set up the session.
|
||||
*
|
||||
* First of all we check if MultiFormSessionID is set in the URL,
|
||||
* then we determine what URL type has been set (default is "Hash").
|
||||
* Knowing this, we can retrieve the session record from the database
|
||||
* by a particular method (getSessionRecordByHash, or getSessionRecordByID).
|
||||
*
|
||||
* If MultiFormSessionID isn't set, we assume that this is a new
|
||||
* multiform that requires a new session record to be created.
|
||||
*
|
||||
* @TODO Fix the fact you can continually refresh and create new records
|
||||
* if MultiFormSessionID isn't set.
|
||||
*/
|
||||
protected function setSession() {
|
||||
$urlType = $this->stat('url_type');
|
||||
@ -207,6 +227,9 @@ abstract class MultiForm extends Form {
|
||||
|
||||
/**
|
||||
* Set the fields for this form.
|
||||
*
|
||||
* To ensure that each field knows what form it's related to,
|
||||
* we call setForm($this) on each field.
|
||||
*
|
||||
* @param FieldSet $fields
|
||||
*/
|
||||
@ -217,8 +240,19 @@ abstract class MultiForm extends Form {
|
||||
|
||||
/**
|
||||
* Set the actions for this form.
|
||||
* @TODO is it appropriate to call it setActions?
|
||||
* @TODO should we put this on MultiFormStep, so it's easy to override on a per-step basis?
|
||||
*
|
||||
* If the current step is the final step, we push in a submit button, which
|
||||
* calls the action {@link finish()} to finalise the submission. Otherwise,
|
||||
* we push in a next button which calls the action {@link next()} to determine
|
||||
* where to go next in our step process, and save any form data collected.
|
||||
*
|
||||
* If there's a previous step (a step that has the current step as it's next
|
||||
* step class), then we allow a previous button, which calls the previous action
|
||||
* to determine which step to go back to.
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
function setActions() {
|
||||
// Create default multi step actions (next, prev), and merge with extra actions, if any
|
||||
@ -287,8 +321,9 @@ abstract class MultiForm extends Form {
|
||||
* Determine what to do when the next action is called.
|
||||
*
|
||||
* Saves the current step session data to the database, creates the
|
||||
* new step based on getNextStep() of the current step, resets the current
|
||||
* step to the next step, then redirects to the step.
|
||||
* new step based on getNextStep() of the current step (or fetches
|
||||
* an existing one), resets the current step to the next step,
|
||||
* then redirects to the newly set step.
|
||||
*
|
||||
* @param array $data The request data returned from the form
|
||||
* @param object $form The form that the action was called on
|
||||
@ -299,20 +334,20 @@ abstract class MultiForm extends Form {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Switch the step to the next!
|
||||
// Get the next step class
|
||||
$nextStepClass = $this->getCurrentStep()->getNextStep();
|
||||
|
||||
// Save the form data for the current step
|
||||
$this->save($data);
|
||||
|
||||
// Determine whether we can use a step already in the DB, or create a new one
|
||||
// Determine whether we can use a step already in the DB, or have to create a new one
|
||||
if(!$nextStep = DataObject::get_one($nextStepClass, "SessionID = {$this->session->ID}")) {
|
||||
$nextStep = new $nextStepClass();
|
||||
$nextStep->SessionID = $this->session->ID;
|
||||
$nextStep->write();
|
||||
}
|
||||
|
||||
// Set the next step to be the current step
|
||||
// Set the next step found as the current step
|
||||
$this->setCurrentStep($nextStep);
|
||||
|
||||
// Redirect to the next step
|
||||
@ -323,12 +358,9 @@ abstract class MultiForm extends Form {
|
||||
/**
|
||||
* Determine what to do when the previous action is called.
|
||||
*
|
||||
* Saves the current step session data to the database, retrieves the
|
||||
* previous step instance based on the classname returned by getPreviousStep()
|
||||
* on the current step instance, and resets the current step to the previous
|
||||
* step found, then redirects to the step.
|
||||
*
|
||||
* @TODO handle loading the data back into the previous step, from session.
|
||||
* Retrieves the previous step class, finds the record for that
|
||||
* class in the DB, and sets the current step to that step found.
|
||||
* Finally, it redirects to that step.
|
||||
*
|
||||
* @param array $data The request data returned from the form
|
||||
* @param object $form The form that the action was called on
|
||||
@ -356,9 +388,9 @@ abstract class MultiForm extends Form {
|
||||
/**
|
||||
* Save the raw data given back from the form into session.
|
||||
*
|
||||
* Harmful values provided from the internal form system will be unset from
|
||||
* the map as defined in self::$ignored_fields. It also unsets any fields
|
||||
* that look be be form action values, since they aren't required either.
|
||||
* Take the submitted form data for the current step, removing
|
||||
* any key => value pairs that shouldn't be saved, then saves
|
||||
* the data into the session.
|
||||
*
|
||||
* @param array $data An array of data to save
|
||||
*/
|
||||
@ -422,9 +454,6 @@ abstract class MultiForm extends Form {
|
||||
* to determine what the next step is, gathering each step along the way.
|
||||
* We stop on the last step, and return the results.
|
||||
*
|
||||
* @TODO make use of $step->getNextStepFromDatabase() instead of doing a direct
|
||||
* DataObject::get() which is doing the same thing.
|
||||
*
|
||||
* @param $step Subclass of MultiFormStep to find the next step of
|
||||
* @param $stepsFound $stepsFound DataObjectSet reference, the steps found to call back on
|
||||
* @return DataObjectSet
|
||||
@ -466,6 +495,9 @@ abstract class MultiForm extends Form {
|
||||
* field filled out with a serialized value, then we know that the user has
|
||||
* clicked next on the given step, to proceed.
|
||||
*
|
||||
* @TODO Not sure if it's entirely appropriate to check if Data is set as a
|
||||
* way to determine a step is "completed".
|
||||
*
|
||||
* @return int
|
||||
*/
|
||||
public function getCompletedStepCount() {
|
||||
@ -498,7 +530,10 @@ abstract class MultiForm extends Form {
|
||||
* field, and not the actual field object of one. The actual checking is done
|
||||
* by doing a string check to see if "action_" is prefixed to the name of the
|
||||
* field. For example, in the form system: FormAction('next', 'Next') field
|
||||
* gives an ID of "action_next"
|
||||
* gives an ID of "action_next"
|
||||
*
|
||||
* The assumption here is the ID we're checking against has the prefix that we're
|
||||
* looking for, otherwise this won't work.
|
||||
*
|
||||
* @param string $fieldName The name of the field to check is an action
|
||||
* @param string $prefix The prefix of the string to check for, default is "action_"
|
||||
|
@ -18,10 +18,10 @@ class MultiFormObjectDecorator extends DataObjectDecorator {
|
||||
|
||||
public function updateDBFields() {
|
||||
return array(
|
||||
"db" => array(
|
||||
'db' => array(
|
||||
'MultiFormIsTemporary' => 'Boolean',
|
||||
),
|
||||
"has_one" => array(
|
||||
'has_one' => array(
|
||||
'MultiFormSession' => 'MultiFormSession',
|
||||
)
|
||||
);
|
||||
|
@ -22,7 +22,6 @@ class MultiFormPurgeTask extends DailyTask {
|
||||
*/
|
||||
public static $session_expiry_days = 7;
|
||||
|
||||
|
||||
public function run() {
|
||||
$controllers = ClassInfo::subclassesFor('MultiForm');
|
||||
|
||||
|
@ -4,8 +4,11 @@
|
||||
* Serializes one or more {@link MultiFormStep}s into
|
||||
* a database object.
|
||||
*
|
||||
* MultiFormSession also stores the current step, so that
|
||||
* the {@link MultiForm} and {@link MultiFormStep} classes
|
||||
* know what the current step is.
|
||||
*
|
||||
* @package multiform
|
||||
*
|
||||
*/
|
||||
class MultiFormSession extends DataObject {
|
||||
|
||||
@ -23,6 +26,9 @@ class MultiFormSession extends DataObject {
|
||||
'FormSteps' => 'MultiFormStep'
|
||||
);
|
||||
|
||||
/**
|
||||
* These actions are performed when write() is called on this object.
|
||||
*/
|
||||
public function onBeforeWrite() {
|
||||
// save submitter if a Member is logged in
|
||||
$currentMember = Member::currentMember();
|
||||
@ -30,7 +36,10 @@ class MultiFormSession extends DataObject {
|
||||
|
||||
parent::onBeforeWrite();
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* These actions are performed when delete() is called on this object.
|
||||
*/
|
||||
public function onBeforeDelete() {
|
||||
// delete dependent form steps
|
||||
$steps = $this->FormSteps();
|
||||
@ -40,8 +49,8 @@ class MultiFormSession extends DataObject {
|
||||
}
|
||||
|
||||
/**
|
||||
* Enter description here...
|
||||
*
|
||||
* Get all the temporary objects, and set them as temporary, writing
|
||||
* them back to the database.
|
||||
*/
|
||||
public function markTemporaryDataObjectsFinished() {
|
||||
$temporaryObjects = $this->getTemporaryDataObjects();
|
||||
@ -52,7 +61,9 @@ class MultiFormSession extends DataObject {
|
||||
}
|
||||
|
||||
/**
|
||||
* Enter description here...
|
||||
* Get all classes that implement the MultiFormObjectDecorator,
|
||||
* find the records for each and merge them together into a
|
||||
* DataObjectSet.
|
||||
*
|
||||
* @return DataObjectSet
|
||||
*/
|
||||
|
@ -1,10 +1,11 @@
|
||||
<?php
|
||||
|
||||
/**
|
||||
* MultiFormStep controls the behaviour of a single from step in the multi-form
|
||||
* process. All form steps should be subclasses of this class, as it encapsulates
|
||||
* the functionality required for the step to be aware of itself in the form step
|
||||
* process.
|
||||
* MultiFormStep controls the behaviour of a single form step in the multi-form
|
||||
* process. All form steps are required to be subclasses of this class, as it
|
||||
* encapsulates the functionality required for the step to be aware of itself
|
||||
* in the process by knowing what it's next step is, and if applicable, it's previous
|
||||
* step.
|
||||
*
|
||||
* @package multiform
|
||||
*/
|
||||
@ -20,11 +21,11 @@ class MultiFormStep extends DataObject {
|
||||
|
||||
/**
|
||||
* Centerpiece of the flow control for the form.
|
||||
* If set to a string, you pretty much have a linear
|
||||
* form flow - if set to an array, you should
|
||||
* use {@link getNextStep()} to enact flow control
|
||||
* and branching to different form steps,
|
||||
* most likely based on previously set session data
|
||||
*
|
||||
* If set to a string, you have a linear form flow
|
||||
* If set to an array, you should use {@link getNextStep()}
|
||||
* to enact flow control and branching to different form
|
||||
* steps, most likely based on previously set session data
|
||||
* (e.g. a checkbox field or a dropdown).
|
||||
*
|
||||
* @var array|string
|
||||
@ -42,8 +43,9 @@ class MultiFormStep extends DataObject {
|
||||
protected static $is_final_step = false;
|
||||
|
||||
/**
|
||||
* Title of this step, can be used by each step that sub-classes this.
|
||||
* It's useful for creating a list of steps in your template.
|
||||
* Title of this step.
|
||||
*
|
||||
* Used for the step indicator templates.
|
||||
*
|
||||
* @var string
|
||||
*/
|
||||
@ -54,7 +56,7 @@ class MultiFormStep extends DataObject {
|
||||
* (Form object is created in {@link MultiForm}.
|
||||
*
|
||||
* This function needs to be implemented on your
|
||||
* subclasses of MultiFormStep
|
||||
* subclasses of MultiFormStep.
|
||||
*
|
||||
* @return FieldSet
|
||||
*/
|
||||
@ -63,11 +65,11 @@ class MultiFormStep extends DataObject {
|
||||
}
|
||||
|
||||
/**
|
||||
* Additional form actions to be rendered with this step.
|
||||
* Additional form actions to be added to this step.
|
||||
* (Form object is created in {@link MultiForm}.
|
||||
*
|
||||
* Note: This is optional, and is to be implemented
|
||||
* on your subclasses of MultiFormStep
|
||||
* on your subclasses of MultiFormStep.
|
||||
*
|
||||
* @return FieldSet
|
||||
*/
|
||||
@ -185,6 +187,8 @@ class MultiFormStep extends DataObject {
|
||||
|
||||
/**
|
||||
* Accessor method for self::$next_steps
|
||||
*
|
||||
* @return string|array
|
||||
*/
|
||||
public function getNextSteps() {
|
||||
return $this->stat('next_steps');
|
||||
@ -226,8 +230,7 @@ class MultiFormStep extends DataObject {
|
||||
|
||||
/**
|
||||
* Determines whether this step is the final step in the multi-step process or not,
|
||||
* based on the variable $is_final_step - to set the final step, create this variable
|
||||
* on your form step class.
|
||||
* based on the variable $is_final_step - which must be defined on at least one step.
|
||||
*
|
||||
* @return boolean
|
||||
*/
|
||||
|
Loading…
Reference in New Issue
Block a user