From 3007fa55d59b549c71b4fb68cd91f0aa162ff2e5 Mon Sep 17 00:00:00 2001 From: Sam Minnee Date: Mon, 20 Aug 2007 23:22:30 +0000 Subject: [PATCH] Added return type hinting to comments git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@40596 467b73ca-7a2a-4603-9d3b-597d59a354a9 --- core/control/Controller.php | 18 +++++++++++++ forms/Form.php | 52 +++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/core/control/Controller.php b/core/control/Controller.php index 78dc43439..a7a550465 100644 --- a/core/control/Controller.php +++ b/core/control/Controller.php @@ -38,6 +38,9 @@ class Controller extends ViewableData { $this->urlParams = $urlParams; } + /** + * @return + */ function getURLParams() { return $this->urlParams; } @@ -46,8 +49,10 @@ class Controller extends ViewableData { * Execute the appropriate action handler. If none is given, use defaultAction to display * a template. The default action will be appropriate in most cases where displaying data * is the core goal; the Viewer can call methods on the controller to get the data it needs. + * * @param array $urlParams named parameters extracted from the URL, including Action. * @param array $requestParams GET and POST variables. + * @return HTTPResponse The response that this controller produces, including HTTP headers such as redirection info */ protected $baseInitCalled = false; function run($requestParams) { @@ -214,6 +219,7 @@ class Controller extends ViewableData { /** * Return an SSViewer object to process the data + * @return SSViewer The viewer identified being the default handler for this Controller/Action combination */ function getViewer($action) { // Hard-coded templates @@ -270,12 +276,17 @@ class Controller extends ViewableData { $this->baseInitCalled = true; } + /** + * Deprecated - use Controller::curr() instead + * @returns Controller + */ public static function currentController() { return self::curr(); } /** * Returns the current controller + * @returns Controller */ public static function curr() { if(Controller::$controller_stack) { @@ -287,6 +298,7 @@ class Controller extends ViewableData { /** * Tests whether we have a currently active controller or not + * @return boolean True if there is at least 1 controller in the stack. */ public static function has_curr() { return Controller::$controller_stack ? true : false; @@ -297,6 +309,7 @@ class Controller extends ViewableData { * @param perm The permission to be checked, such as 'View'. * @param member The member whose permissions need checking. Defaults to the currently logged * in user. + * @return boolean */ function can($perm, $member = null) { if(!$member) $member = Member::currentUser(); @@ -312,6 +325,7 @@ class Controller extends ViewableData { /** * returns a date object for use within a template * Usage: $Now.Year - Returns 2006 + * @return Date The current date */ function Now() { $d = new Date(null); @@ -339,6 +353,7 @@ class Controller extends ViewableData { /** * Returns true if the visitor has been here before + * @return boolean */ function PastVisitor() { return Cookie::get("PastVisitor") ? true : false; @@ -346,6 +361,7 @@ class Controller extends ViewableData { /** * Return true if the visitor has signed up for a login account before + * @return boolean */ function PastMember() { return Cookie::get("PastMember") ? true : false; @@ -390,6 +406,7 @@ class Controller extends ViewableData { /** * Get the Session object representing this Controller's session + * @return Session */ function getSession() { return $this->session; @@ -404,6 +421,7 @@ class Controller extends ViewableData { /** * Returns true if this controller is processing an ajax request + * @return boolean True if this controller is processing an ajax request */ function isAjax() { return ( diff --git a/forms/Form.php b/forms/Form.php index e82cf497f..c2353b7b1 100644 --- a/forms/Form.php +++ b/forms/Form.php @@ -129,10 +129,17 @@ class Form extends ViewableData { $this->validator->removeValidation(); } + /** + * Get the {@link Validator} attached to this form. + * @return Validator + */ function getValidator() { return $this->validator; } + /** + * Set the {@link Validator} on this form. + */ function setValidator( Validator $validator ) { if($validator) { $this->validator = $validator; @@ -140,6 +147,9 @@ class Form extends ViewableData { } } + /** + * Remove the {@link Validator} from this from. + */ function unsetValidator(){ $this->validator = null; } @@ -161,10 +171,18 @@ class Form extends ViewableData { /** * Return the form's fields - used by the templates + * @return FieldSet The form fields */ function Fields() { return $this->fields; } + + /** + * Get a named field from this form's fields. + * It will traverse into composite fields for you, to find the field you want. + * It will only return a data field. + * @return FormField + */ function dataFieldByName($name) { return $this->fields->dataFieldByName($name); } @@ -172,6 +190,7 @@ class Form extends ViewableData { /** * Return the form's action buttons - used by the templates + * @return FieldSet The action list */ function Actions() { return $this->actions; @@ -220,6 +239,7 @@ class Form extends ViewableData { /** * Return the attributes of the form tag - used by the templates + * @return string The attribute string */ function FormAttributes() { // Forms shouldn't be cached, cos their error messages won't be shown @@ -242,6 +262,11 @@ class Form extends ViewableData { $this->target = $target; } + /** + * Returns the encoding type of the form. + * This will be either multipart/form-data - if there are field fields - or application/x-www-form-urlencoded + * @return string The encoding mime type + */ function FormEncType() { if(is_array($this->fields->dataFields())){ foreach($this->fields->dataFields() as $field) { @@ -251,14 +276,27 @@ class Form extends ViewableData { return "application/x-www-form-urlencoded"; } + /** + * Returns the form method. + * @return string 'get' or 'post' + */ function FormMethod() { return $this->formMethod; } + + /** + * Set the form method - get or post + */ function setFormMethod($method) { $this->formMethod = strtolower($method); if($this->formMethod == 'get') $this->fields->push(new HiddenField('executeForm', '', $this->name)); } + /** + * Return the form's action attribute. + * This is build by adding an executeForm get variable to the parent controller's Link() value + * @return string The + */ function FormAction() { // "get" form needs ?executeForm added as a hidden field if($this->formMethod == 'post') { @@ -282,6 +320,7 @@ class Form extends ViewableData { /** * Returns the field referenced by $_GET[fieldName]. * Used for embedding entire extra helper forms inside complex field types (such as ComplexTableField) + * @return FormField The field referenced by $_GET[fieldName] */ function ReferencedField() { return $this->dataFieldByName($_GET['fieldName']); @@ -350,6 +389,11 @@ class Form extends ViewableData { } protected $record; + + /** + * Returns the DataObject that has given this form its data. + * @return DataObject + */ function getRecord() { return $this->record; } @@ -642,6 +686,10 @@ class Form extends ViewableData { // TESTING HELPERS ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////// + /** + * Test a submission of this form. + * @return HTTPResponse the response object that the handling controller produces. You can interrogate this in your unit test. + */ function testSubmission($action, $data) { $data['action_' . $action] = true; $data['executeForm'] = $this->name; @@ -652,6 +700,10 @@ class Form extends ViewableData { //return $response; } + /** + * Test an ajax submission of this form. + * @return HTTPResponse the response object that the handling controller produces. You can interrogate this in your unit test. + */ function testAjaxSubmission($action, $data) { $data['ajax'] = 1; return $this->testSubmission($action, $data);