Added phpdoc to methods and classes

This commit is contained in:
Sean Harvey 2008-04-22 11:03:03 +00:00
parent ec747bc6c6
commit 6f07bf39b2
5 changed files with 98 additions and 50 deletions

View File

@ -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_"

View File

@ -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',
)
);

View File

@ -22,7 +22,6 @@ class MultiFormPurgeTask extends DailyTask {
*/
public static $session_expiry_days = 7;
public function run() {
$controllers = ClassInfo::subclassesFor('MultiForm');

View File

@ -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
*/

View File

@ -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
*/