From 6c1fd304841c633a1a2b2feb09596787b80ffe0b Mon Sep 17 00:00:00 2001 From: Rajesh Taneja Date: Fri, 6 Jan 2012 16:38:06 +0800 Subject: [PATCH] MDL-30974 form: Checked and updated docblock for form library --- lib/form/advcheckbox.php | 92 +++-- lib/form/button.php | 82 +++-- lib/form/cancel.php | 73 +++- lib/form/checkbox.php | 86 ++++- lib/form/dateselector.php | 140 +++---- lib/form/datetimeselector.php | 145 ++++---- lib/form/duration.php | 112 ++++-- lib/form/editor.php | 137 ++++++- lib/form/file.php | 72 +++- lib/form/filemanager.php | 123 ++++++- lib/form/filepicker.php | 78 +++- lib/form/format.php | 50 ++- lib/form/grading.php | 61 +-- lib/form/group.php | 79 +++- lib/form/header.php | 64 +++- lib/form/hidden.php | 58 ++- lib/form/htmleditor.php | 68 +++- lib/form/modgrade.php | 58 ++- lib/form/modvisible.php | 55 ++- lib/form/password.php | 60 ++- lib/form/passwordunmask.php | 50 ++- lib/form/questioncategory.php | 43 ++- lib/form/radio.php | 70 +++- lib/form/recaptcha.php | 74 ++-- lib/form/searchableselector.php | 31 +- lib/form/select.php | 95 +++-- lib/form/selectgroups.php | 298 ++++++--------- lib/form/selectwithlink.php | 104 ++++-- lib/form/selectyesno.php | 58 ++- lib/form/simpletest/testduration.php | 80 ++-- lib/form/static.php | 66 +++- lib/form/submit.php | 60 ++- lib/form/submitlink.php | 52 +++ lib/form/tags.php | 117 ++++-- lib/form/text.php | 71 +++- lib/form/textarea.php | 88 +++-- lib/form/url.php | 73 +++- lib/form/warning.php | 71 +++- lib/formslib.php | 529 ++++++++++++++------------- 39 files changed, 2567 insertions(+), 1156 deletions(-) diff --git a/lib/form/advcheckbox.php b/lib/form/advcheckbox.php index 4fe4650d6e1..62f74c31803 100644 --- a/lib/form/advcheckbox.php +++ b/lib/form/advcheckbox.php @@ -1,42 +1,59 @@ . + + +/** + * Advanced checkbox type form element + * + * Contains HTML class for an advcheckbox type form element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/advcheckbox.php'); /** - * HTML class for a advcheckbox type element + * HTML class for an advcheckbox type element * - * default behavior special for Moodle is to return '0' if not checked - * '1' for checked. + * Overloaded {@see HTML_QuickForm_advcheckbox} with default behavior modified for Moodle. + * This will return '0' if not checked and '1' if checked. * - * * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help will icon will be dispalyed. */ var $_helpbutton=''; - /** - * Group to which this checkbox belongs (for select all/select none button) - * @var string $_group - */ + /** @var string Group to which this checkbox belongs (for select all/select none button) */ var $_group; /** - * Class constructor + * constructor * - * @param string $elementName (optional)Input field name attribute - * @param string $elementLabel (optional)Input field label - * @param string $text (optional)Text to put after the checkbox - * @param mixed $attributes (optional)Either a typical HTML attribute string - * or an associative array - * @param mixed $values (optional)Values to pass if checked or not checked - * - * @since 1.0 - * @access public - * @return void + * @param string $elementName (optional) name of the checkbox + * @param string $elementLabel (optional) checkbox label + * @param string $text (optional) Text to put after the checkbox + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array + * @param mixed $values (optional) Values to pass if checked or not checked */ function MoodleQuickForm_advcheckbox($elementName=null, $elementLabel=null, $text=null, $attributes=null, $values=null) { @@ -65,29 +82,35 @@ class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{ } parent::HTML_QuickForm_advcheckbox($elementName, $elementLabel, $text, $attributes, $values); - } //end constructor - + } /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button - * @param string $function function name to call to get html + * @param array $helpbuttonargs array of arguments to make a help button + * @param string $function (optional)function name get help html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** + * Returns HTML for advchecbox form element. + * + * @return string + */ function toHtml() { return '' . parent::toHtml() . ''; @@ -96,7 +119,8 @@ class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{ /** * Returns the disabled field. Accessibility: the return "[ ]" from parent * class is not acceptable for screenreader users, and we DO want a label. - * @return string + * + * @return string */ function getFrozenHtml() { @@ -108,6 +132,6 @@ class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{ $output .= '/>'; } return $output; - } //end func getFrozenHtml + } } diff --git a/lib/form/button.php b/lib/form/button.php index eb16bad9f9d..ea708e37a54 100644 --- a/lib/form/button.php +++ b/lib/form/button.php @@ -1,63 +1,81 @@ | -// | Bertrand Mansion | -// +----------------------------------------------------------------------+ +// This file is part of Moodle - http://moodle.org/ +// +// Moodle is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// Moodle is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with Moodle. If not, see . + + +/** + * Button form element + * + * Contains HTML class for a button type element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ require_once("HTML/QuickForm/button.php"); /** * HTML class for a button type element * - * @author Adam Daniel - * @author Bertrand Mansion - * @version 1.1 - * @since PHP4.04pl1 - * @access public + * Overloaded {@see HTML_QuickForm_button} to add help button + * + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_button extends HTML_QuickForm_button { - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** + * constructor + * + * @param string $elementName (optional) name for the button + * @param string $value (optional) value for the button + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_button($elementName=null, $value=null, $attributes=null) { parent::HTML_QuickForm_button($elementName, $value, $attributes); } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** * Slightly different container template when frozen. * @@ -70,4 +88,4 @@ class MoodleQuickForm_button extends HTML_QuickForm_button return 'default'; } } -} //end class MoodleQuickForm_button +} diff --git a/lib/form/cancel.php b/lib/form/cancel.php index 79ab00a44e2..7d0138576ec 100644 --- a/lib/form/cancel.php +++ b/lib/form/cancel.php @@ -1,4 +1,30 @@ . + + +/** + * Button form element + * + * Contains HTML class for a button type element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + if (!defined('MOODLE_INTERNAL')) { die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page } @@ -7,21 +33,24 @@ global $CFG; require_once($CFG->libdir.'/form/submit.php'); /** - * HTML class for a submit type element + * HTML class for a submit cancel type element * - * @author Jamie Pratt - * @access public + * Overloaded {@see MoodleQuickForm_submit} with default behavior modified to cancel a form. + * + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_cancel extends MoodleQuickForm_submit { - // {{{ constructor - /** - * Class constructor + * constructor * - * @since 1.0 - * @access public - * @return void + * @param string $elementName (optional) name of the checkbox + * @param string $value (optional) value for the button + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array */ function MoodleQuickForm_cancel($elementName=null, $value=null, $attributes=null) { @@ -33,7 +62,16 @@ class MoodleQuickForm_cancel extends MoodleQuickForm_submit } MoodleQuickForm_submit::MoodleQuickForm_submit($elementName, $value, $attributes); $this->updateAttributes(array('onclick'=>'skipClientValidation = true; return true;')); - } //end constructor + } + + /** + * Called by HTML_QuickForm whenever form event is made on this element + * + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool + */ function onQuickFormEvent($event, $arg, &$caller) { switch ($event) { @@ -45,14 +83,23 @@ class MoodleQuickForm_cancel extends MoodleQuickForm_submit break; } return parent::onQuickFormEvent($event, $arg, $caller); - } // end func onQuickFormEvent + } + /** + * Returns the value of field without HTML tags + * + * @return string + */ function getFrozenHtml(){ return HTML_QuickForm_submit::getFrozenHtml(); } + /** + * Freeze the element so that only its value is returned + * + * @return bool + */ function freeze(){ return HTML_QuickForm_submit::freeze(); } - // }}} -} //end class MoodleQuickForm_cancel +} diff --git a/lib/form/checkbox.php b/lib/form/checkbox.php index bbccbc08600..b08d32e9c0f 100644 --- a/lib/form/checkbox.php +++ b/lib/form/checkbox.php @@ -1,37 +1,78 @@ . + + +/** + * checkbox form element + * + * Contains HTML class for a checkbox type element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/checkbox.php'); /** * HTML class for a checkbox type element * - * @author Jamie Pratt - * @access public + * Overloaded {@see HTML_QuickForm_checkbox} to add help button. Also, fixes bug in quickforms + * checkbox, which lets previous set value override submitted value if checkbox is not checked + * and no value is submitted + * + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** + * Constructor + * + * @param string $elementName (optional) name of the checkbox + * @param string $elementLabel (optional) checkbox label + * @param string $text (optional) Text to put after the checkbox + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_checkbox($elementName=null, $elementLabel=null, $text='', $attributes=null) { parent::HTML_QuickForm_checkbox($elementName, $elementLabel, $text, $attributes); } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; @@ -40,12 +81,10 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{ /** * Called by HTML_QuickForm whenever form event is made on this element * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @since 1.0 - * @access public - * @return void + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool */ function onQuickFormEvent($event, $arg, &$caller) { @@ -73,7 +112,13 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{ parent::onQuickFormEvent($event, $arg, $caller); } return true; - } // end func onQuickFormEvent + } + + /** + * Returns HTML for checbox form element. + * + * @return string + */ function toHtml() { return '' . parent::toHtml() . ''; @@ -82,7 +127,8 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{ /** * Returns the disabled field. Accessibility: the return "[ ]" from parent * class is not acceptable for screenreader users, and we DO want a label. - * @return string + * + * @return string */ function getFrozenHtml() { @@ -94,5 +140,5 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{ $output .= '/>'; } return $output; - } //end func getFrozenHtml + } } diff --git a/lib/form/dateselector.php b/lib/form/dateselector.php index 38d035d5556..73316fc0ce1 100644 --- a/lib/form/dateselector.php +++ b/lib/form/dateselector.php @@ -1,27 +1,29 @@ . -/////////////////////////////////////////////////////////////////////////// -// // -// NOTICE OF COPYRIGHT // -// // -// Moodle - Modular Object-Oriented Dynamic Learning Environment // -// http://moodle.org // -// // -// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // -// // -// This program is free software; you can redistribute it and/or modify // -// it under the terms of the GNU General Public License as published by // -// the Free Software Foundation; either version 2 of the License, or // -// (at your option) any later version. // -// // -// This program is distributed in the hope that it will be useful, // -// but WITHOUT ANY WARRANTY; without even the implied warranty of // -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // -// GNU General Public License for more details: // -// // -// http://www.gnu.org/copyleft/gpl.html // -// // -/////////////////////////////////////////////////////////////////////////// + +/** + * Group of date input element + * + * Contains class for a group of elements used to input a date. + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ global $CFG; require_once($CFG->libdir . '/form/group.php'); @@ -32,38 +34,36 @@ require_once($CFG->libdir . '/formslib.php'); * * Emulates moodle print_date_selector function * - * @package formslib + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_date_selector extends MoodleQuickForm_group { /** - * Control the fieldnames for form elements - * - * startyear => integer start of range of years that can be selected - * stopyear => integer last year that can be selected - * timezone => float/string timezone - * applydst => apply users daylight savings adjustment? - * optional => if true, show a checkbox beside the date to turn it on (or off) - */ + * Control the fieldnames for form elements + * startyear => int start of range of years that can be selected + * stopyear => int last year that can be selected + * timezone => float/string timezone + * applydst => apply users daylight savings adjustment? + * optional => if true, show a checkbox beside the date to turn it on (or off) + * @var array + */ protected $_options = array('startyear' => 1970, 'stopyear' => 2020, 'timezone' => 99, 'applydst' => true, 'optional' => false); - /** - * These complement separators, they are appended to the resultant HTML - * @access private - * @var array - */ + /** @var array These complement separators, they are appended to the resultant HTML */ protected $_wrap = array('', ''); - /** - * Class constructor - * - * @access public - * @param string Element's name - * @param mixed Label(s) for an element - * @param array Options to control the element's display - * @param mixed Either a typical HTML attribute string or an associative array - */ + /** + * constructor + * + * @param string $elementName Element's name + * @param mixed $elementLabel Label(s) for an element + * @param array $options Options to control the element's display + * @param mixed $attributes Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_date_selector($elementName = null, $elementLabel = null, $options = array(), $attributes = null) { $this->HTML_QuickForm_element($elementName, $elementLabel, $attributes); @@ -85,9 +85,11 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group form_init_date_js(); } - // }}} - // {{{ _createElements() - + /** + * This will create date group element constisting of day, month and year. + * + * @access private + */ function _createElements() { $this->_elements = array(); @@ -115,18 +117,13 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group } - // }}} - // {{{ onQuickFormEvent() - /** * Called by HTML_QuickForm whenever form event is made on this element - * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @since 1.0 - * @access public - * @return void + * + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool */ function onQuickFormEvent($event, $arg, &$caller) { @@ -176,10 +173,13 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group default: return parent::onQuickFormEvent($event, $arg, $caller); } - } // end func onQuickFormEvent - - // {{{ toHtml() + } + /** + * Returns HTML for advchecbox form element. + * + * @return string + */ function toHtml() { include_once('HTML/QuickForm/Renderer/Default.php'); @@ -189,21 +189,23 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group return $this->_wrap[0] . $renderer->toHtml() . $this->_wrap[1]; } - // }}} - // {{{ accept() - + /** + * Accepts a renderer + * + * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object + * @param bool $required Whether a group is required + * @param string $error An error message associated with a group + */ function accept(&$renderer, $required = false, $error = null) { $renderer->renderElement($this, $required, $error); } - // }}} - /** * Output a timestamp. Give it the name of the group. * - * @param array $submitValues - * @param bool $assoc + * @param array $submitValues values submitted. + * @param bool $assoc specifies if returned array is associative * @return array */ function exportValue(&$submitValues, $assoc = false) @@ -237,6 +239,4 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group return null; } } - - // }}} } diff --git a/lib/form/datetimeselector.php b/lib/form/datetimeselector.php index 957d7a39a62..1f8e4cafcf7 100644 --- a/lib/form/datetimeselector.php +++ b/lib/form/datetimeselector.php @@ -1,70 +1,70 @@ . -/////////////////////////////////////////////////////////////////////////// -// // -// NOTICE OF COPYRIGHT // -// // -// Moodle - Modular Object-Oriented Dynamic Learning Environment // -// http://moodle.org // -// // -// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // -// // -// This program is free software; you can redistribute it and/or modify // -// it under the terms of the GNU General Public License as published by // -// the Free Software Foundation; either version 2 of the License, or // -// (at your option) any later version. // -// // -// This program is distributed in the hope that it will be useful, // -// but WITHOUT ANY WARRANTY; without even the implied warranty of // -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // -// GNU General Public License for more details: // -// // -// http://www.gnu.org/copyleft/gpl.html // -// // -/////////////////////////////////////////////////////////////////////////// + +/** + * Group of date and time input element + * + * Contains class for a group of elements used to input a date and time. + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ global $CFG; require_once($CFG->libdir . '/form/group.php'); require_once($CFG->libdir . '/formslib.php'); /** + * Element used to input a date and time. + * * Class for a group of elements used to input a date and time. * - * Emulates moodle print_date_selector function and also allows you to select a time. - * - * @package formslib + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{ /** - * Options for the element - * - * startyear => integer start of range of years that can be selected - * stopyear => integer last year that can be selected - * defaulttime => default time value if the field is currently not set - * timezone => float/string timezone - * applydst => apply users daylight savings adjustment? - * step => step to increment minutes by - * optional => if true, show a checkbox beside the date to turn it on (or off) - */ + * Options for the element + * startyear => int start of range of years that can be selected + * stopyear => int last year that can be selected + * defaulttime => default time value if the field is currently not set + * timezone => float/string timezone + * applydst => apply users daylight savings adjustment? + * step => step to increment minutes by + * optional => if true, show a checkbox beside the date to turn it on (or off) + * @var array + */ var $_options = array('startyear' => 1970, 'stopyear' => 2020, 'defaulttime' => 0, 'timezone' => 99, 'applydst' => true, 'step' => 5, 'optional' => false); - /** - * These complement separators, they are appended to the resultant HTML - * @access private - * @var array - */ + /** @var array These complement separators, they are appended to the resultant HTML */ var $_wrap = array('', ''); - /** - * Class constructor - * - * @access public - * @param string Element's name - * @param mixed Label(s) for an element - * @param array Options to control the element's display - * @param mixed Either a typical HTML attribute string or an associative array - */ + /** + * Class constructor + * + * @param string $elementName Element's name + * @param mixed $elementLabel Label(s) for an element + * @param array $options Options to control the element's display + * @param mixed $attributes Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_date_time_selector($elementName = null, $elementLabel = null, $options = array(), $attributes = null) { $this->HTML_QuickForm_element($elementName, $elementLabel, $attributes); @@ -86,9 +86,11 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{ form_init_date_js(); } - // }}} - // {{{ _createElements() - + /** + * This will create date group element constisting of day, month and year. + * + * @access private + */ function _createElements() { $this->_elements = array(); @@ -129,18 +131,13 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{ } - // }}} - // {{{ onQuickFormEvent() - /** * Called by HTML_QuickForm whenever form event is made on this element * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @since 1.0 - * @access public - * @return void + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool */ function onQuickFormEvent($event, $arg, &$caller) { @@ -197,9 +194,11 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{ } } - // }}} - // {{{ toHtml() - + /** + * Returns HTML for advchecbox form element. + * + * @return string + */ function toHtml() { include_once('HTML/QuickForm/Renderer/Default.php'); @@ -209,21 +208,23 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{ return $this->_wrap[0] . $renderer->toHtml() . $this->_wrap[1]; } - // }}} - // {{{ accept() - + /** + * Accepts a renderer + * + * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object + * @param bool $required Whether a group is required + * @param string $error An error message associated with a group + */ function accept(&$renderer, $required = false, $error = null) { $renderer->renderElement($this, $required, $error); } - // }}} - /** * Output a timestamp. Give it the name of the group. * - * @param array $submitValues - * @param bool $assoc + * @param array $submitValues values submitted. + * @param bool $assoc specifies if returned array is associative * @return array */ function exportValue(&$submitValues, $assoc = false) @@ -261,6 +262,4 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{ return null; } } - - // }}} } diff --git a/lib/form/duration.php b/lib/form/duration.php index ba4082d17e4..1619d32b3ac 100644 --- a/lib/form/duration.php +++ b/lib/form/duration.php @@ -1,27 +1,29 @@ . -/////////////////////////////////////////////////////////////////////////// -// // -// NOTICE OF COPYRIGHT // -// // -// Moodle - Modular Object-Oriented Dynamic Learning Environment // -// http://moodle.org // -// // -// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // -// // -// This program is free software; you can redistribute it and/or modify // -// it under the terms of the GNU General Public License as published by // -// the Free Software Foundation; either version 2 of the License, or // -// (at your option) any later version. // -// // -// This program is distributed in the hope that it will be useful, // -// but WITHOUT ANY WARRANTY; without even the implied warranty of // -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // -// GNU General Public License for more details: // -// // -// http://www.gnu.org/copyleft/gpl.html // -// // -/////////////////////////////////////////////////////////////////////////// + +/** + * Duration form element + * + * Contains class to create length of time for element. + * + * @package core_form + * @copyright 2009 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ global $CFG; require_once($CFG->libdir . '/form/group.php'); @@ -29,30 +31,37 @@ require_once($CFG->libdir . '/formslib.php'); require_once($CFG->libdir . '/form/text.php'); /** + * Duration element + * * HTML class for a length of time. For example, 30 minutes of 4 days. The * values returned to PHP is the duration in seconds. * - * @package formslib + * @package core_form + * @category form + * @copyright 2009 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_duration extends MoodleQuickForm_group { /** * Control the fieldnames for form elements * optional => if true, show a checkbox beside the element to turn it on (or off) + * @var array */ protected $_options = array('optional' => false, 'defaultunit' => 60); + /** @var array associative array of time units (days, hours, minutes, seconds) */ private $_units = null; /** - * Class constructor + * constructor * - * @access public - * @param string $elementName Element's name - * @param mixed $elementLabel Label(s) for an element - * @param array $options Options to control the element's display. Recognised values are - * 'optional' => true/false - whether to display an 'enabled' checkbox next to the element. - * 'defaultunit' => 1|60|3600|86400 - the default unit to display when the time is blank. If not specified, minutes is used. - * @param mixed $attributes Either a typical HTML attribute string or an associative array + * @param string $elementName Element's name + * @param mixed $elementLabel Label(s) for an element + * @param array $options Options to control the element's display. Recognised values are + 'optional' => true/false - whether to display an 'enabled' checkbox next to the element. + 'defaultunit' => 1|60|3600|86400 - the default unit to display when the time is blank. + * If not specified, minutes is used. + * @param mixed $attributes Either a typical HTML attribute string or an associative array */ function MoodleQuickForm_duration($elementName = null, $elementLabel = null, $options = array(), $attributes = null) { $this->HTML_QuickForm_element($elementName, $elementLabel, $attributes); @@ -75,6 +84,8 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group { } /** + * Returns time associative array of unit length. + * * @return array unit length in seconds => string unit name. */ public function get_units() { @@ -90,9 +101,11 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group { } /** - * @param $seconds an amout of time in seconds. - * @return array($number, $unit) Conver an interval to the best possible unit. - * for example 1800 -> array(30, 60) = 30 minutes. + * Converts seconds to the best possible time unit. for example + * 1800 -> array(30, 60) = 30 minutes. + * + * @param int $seconds an amout of time in seconds. + * @return array associative array ($number => $unit) */ public function seconds_to_unit($seconds) { if ($seconds == 0) { @@ -106,7 +119,9 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group { return array($seconds, 1); } - // Override of standard quickforms method. + /** + * Override of standard quickforms method to create this element. + */ function _createElements() { $attributes = $this->getAttributes(); if (is_null($attributes)) { @@ -130,7 +145,14 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group { } } - // Override of standard quickforms method. + /** + * Called by HTML_QuickForm whenever form event is made on this element + * + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool + */ function onQuickFormEvent($event, $arg, $caller) { switch ($event) { case 'updateValue': @@ -174,7 +196,11 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group { } } - // Override of standard quickforms method. + /** + * Returns HTML for advchecbox form element. + * + * @return string + */ function toHtml() { include_once('HTML/QuickForm/Renderer/Default.php'); $renderer = new HTML_QuickForm_Renderer_Default(); @@ -183,7 +209,13 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group { return $renderer->toHtml(); } - // Override of standard quickforms method. + /** + * Accepts a renderer + * + * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object + * @param bool $required Whether a group is required + * @param string $error An error message associated with a group + */ function accept($renderer, $required = false, $error = null) { $renderer->renderElement($this, $required, $error); } @@ -192,8 +224,8 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group { * Output a timestamp. Give it the name of the group. * Override of standard quickforms method. * - * @param array $submitValues - * @param bool $notused Not used. + * @param array $submitValues + * @param bool $notused Not used. * @return array field name => value. The value is the time interval in seconds. */ function exportValue($submitValues, $notused = false) { diff --git a/lib/form/editor.php b/lib/form/editor.php index 1f475b37d34..5f06bc86a21 100644 --- a/lib/form/editor.php +++ b/lib/form/editor.php @@ -1,4 +1,29 @@ . + + +/** + * Editor input element + * + * Contains class to create preffered editor form element + * + * @package core_form + * @copyright 2009 Petr Skoda {@link http://skodak.org} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ global $CFG; @@ -6,19 +31,41 @@ require_once('HTML/QuickForm/element.php'); require_once($CFG->dirroot.'/lib/filelib.php'); require_once($CFG->dirroot.'/repository/lib.php'); -//TODO: -// * locking -// * freezing -// * ajax format conversion - +/** + * Editor element + * + * It creates preffered editor (textbox/TinyMce) form element for the format (Text/HTML) selected. + * + * @package core_form + * @category form + * @copyright 2009 Petr Skoda {@link http://skodak.org} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @todo MDL-29421 element Freezing + * @todo MDL-29426 ajax format conversion + */ class MoodleQuickForm_editor extends HTML_QuickForm_element { + /** @var string html for help button, if empty then no help will icon will be dispalyed. */ public $_helpbutton = ''; + /** @var string defines the type of editor */ public $_type = 'editor'; + + /** @var array options provided to initalize filepicker */ protected $_options = array('subdirs'=>0, 'maxbytes'=>0, 'maxfiles'=>0, 'changeformat'=>0, 'context'=>null, 'noclean'=>0, 'trusttext'=>0); + + /** @var array values for editor */ protected $_values = array('text'=>null, 'format'=>null, 'itemid'=>null); + /** + * Constructor + * + * @param string $elementName (optional) name of the editor + * @param string $elementLabel (optional) editor label + * @param array $attributes (optional) Either a typical HTML attribute string + * or an associative array + * @param array $options set of options to initalize filepicker + */ function MoodleQuickForm_editor($elementName=null, $elementLabel=null, $attributes=null, $options=null) { global $CFG, $PAGE; @@ -40,14 +87,29 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element { editors_head_setup(); } + /** + * Sets name of editor + * + * @param string $name name of the editor + */ function setName($name) { $this->updateAttributes(array('name'=>$name)); } + /** + * Returns name of element + * + * @return string + */ function getName() { return $this->getAttribute('name'); } + /** + * Updates editor values, if part of $_values + * + * @param array $values associative array of values to set + */ function setValue($values) { $values = (array)$values; foreach ($values as $name=>$value) { @@ -57,31 +119,66 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element { } } + /** + * Returns editor values + * + * @return array + */ function getValue() { return $this->_values; } + /** + * Returns maximum file size which can be uploaded + * + * @return int + */ function getMaxbytes() { return $this->_options['maxbytes']; } + /** + * Sets maximum file size which can be uploaded + * + * @param int $maxbytes file size + */ function setMaxbytes($maxbytes) { global $CFG; $this->_options['maxbytes'] = get_max_upload_file_size($CFG->maxbytes, $maxbytes); } + /** + * Returns maximum number of files which can be uploaded + * + * @return int + */ function getMaxfiles() { return $this->_options['maxfiles']; } + /** + * Sets maximum number of files which can be uploaded. + * + * @param int $num number of files + */ function setMaxfiles($num) { $this->_options['maxfiles'] = $num; } + /** + * Returns true if subdirectoy can be created, else false + * + * @return bool + */ function getSubdirs() { return $this->_options['subdirs']; } + /** + * Set option to create sub directory, while uploading file + * + * @param bool $allow true if sub directory can be created. + */ function setSubdirs($allow) { $this->_options['subdirs'] = $allow; } @@ -96,14 +193,23 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element { } /** - * Checks if editor used is tinymce and is required field + * Checks if editor used is a required field * - * @return true if required field. + * @return bool true if required field. */ function isRequired() { return (isset($this->_options['required']) && $this->_options['required']); } + /** + * Sets help button for editor + * + * @param mixed $_helpbuttonargs arguments to create help button + * @param string $function name of the callback function + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() + */ function setHelpButton($_helpbuttonargs, $function='_helpbutton') { if (!is_array($_helpbuttonargs)) { $_helpbuttonargs = array($_helpbuttonargs); @@ -119,10 +225,20 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element { $this->_helpbutton=call_user_func_array($function, $_helpbuttonargs); } + /** + * Returns html for help button. + * + * @return string html for help button + */ function getHelpButton() { return $this->_helpbutton; } + /** + * Returns type of editor element + * + * @return string + */ function getElementTemplateType() { if ($this->_flagFrozen){ return 'nodisplay'; @@ -131,6 +247,11 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element { } } + /** + * Returns HTML for editor form element. + * + * @return string + */ function toHtml() { global $CFG, $PAGE; require_once($CFG->dirroot.'/repository/lib.php'); @@ -285,4 +406,4 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element { return ''; } -} +} \ No newline at end of file diff --git a/lib/form/file.php b/lib/form/file.php index 2f69f60b60c..68ec7e49643 100644 --- a/lib/form/file.php +++ b/lib/form/file.php @@ -1,19 +1,57 @@ . + + +/** + * File type form element + * + * Contains HTML class for a file type form element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/file.php'); /** + * file element + * * HTML class for a form element to upload a file * - * @author Jamie Pratt - * @access public + * @package core_form + * @deprecated since Moodle 2.0 Please do not use this form element. + * @todo MDL-31294 remove this element + * @see MoodleQuickForm_filepicker + * @see MoodleQuickForm_filemanager + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_file extends HTML_QuickForm_file{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** + * Constructor + * + * @param string $elementName (optional) name of the editor + * @param string $elementLabel (optional) editor label + * @param array $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_file($elementName=null, $elementLabel=null, $attributes=null) { debugging('file forms element is deprecated, please use new filepicker instead'); parent::HTML_QuickForm_file($elementName, $elementLabel, $attributes); @@ -21,19 +59,17 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{ /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } /** * set html for help button - * - * @access public - * @param array $help array of arguments to make a help button - * @param string $function function name to call to get html */ function getHelpButton(){ return $this->_helpbutton; @@ -41,6 +77,11 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{ /** * Override createElement event to add max files + * + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool */ function onQuickFormEvent($event, $arg, &$caller) { @@ -50,7 +91,8 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{ return true; } return parent::onQuickFormEvent($event, $arg, $caller); - } // end func onQuickFormEvent + } + /** * Slightly different container template when frozen. * @@ -64,4 +106,4 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{ } } -} +} \ No newline at end of file diff --git a/lib/form/filemanager.php b/lib/form/filemanager.php index 1d9358590ef..60d4b25a47f 100644 --- a/lib/form/filemanager.php +++ b/lib/form/filemanager.php @@ -14,13 +14,15 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . + /** - * File manager + * FileManager form element * - * @package moodlecore - * @subpackage file - * @copyright 1999 onwards Dongsheng Cai - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * Contains HTML class for a filemanager form element + * + * @package core_form + * @copyright 2009 Dongsheng Cai + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ global $CFG; @@ -29,10 +31,31 @@ require_once('HTML/QuickForm/element.php'); require_once($CFG->dirroot.'/lib/filelib.php'); require_once($CFG->dirroot.'/repository/lib.php'); +/** + * Filemanager form element + * + * FilemaneManager lets user to upload/manage multiple files + * @package core_form + * @category form + * @copyright 2009 Dongsheng Cai + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class MoodleQuickForm_filemanager extends HTML_QuickForm_element { + /** @var string html for help button, if empty then no help will icon will be dispalyed. */ public $_helpbutton = ''; + + /** @var array options provided to initalize filemanager */ protected $_options = array('mainfile'=>'', 'subdirs'=>1, 'maxbytes'=>-1, 'maxfiles'=>-1, 'accepted_types'=>'*', 'return_types'=>FILE_INTERNAL); + /** + * Constructor + * + * @param string $elementName (optional) name of the filemanager + * @param string $elementLabel (optional) filemanager label + * @param array $attributes (optional) Either a typical HTML attribute string + * or an associative array + * @param array $options set of options to initalize filemanager + */ function MoodleQuickForm_filemanager($elementName=null, $elementLabel=null, $attributes=null, $options=null) { global $CFG, $PAGE; @@ -49,55 +72,124 @@ class MoodleQuickForm_filemanager extends HTML_QuickForm_element { parent::HTML_QuickForm_element($elementName, $elementLabel, $attributes); } + /** + * Sets name of filemanager + * + * @param string $name name of the filemanager + */ function setName($name) { $this->updateAttributes(array('name'=>$name)); } + /** + * Returns name of filemanager + * + * @return string + */ function getName() { return $this->getAttribute('name'); } + /** + * Updates filemanager attribute value + * + * @param string $value value to set + */ function setValue($value) { $this->updateAttributes(array('value'=>$value)); } + /** + * Returns filemanager attribute value + * + * @return string + */ function getValue() { return $this->getAttribute('value'); } + /** + * Returns maximum file size which can be uploaded + * + * @return int + */ function getMaxbytes() { return $this->_options['maxbytes']; } + /** + * Sets maximum file size which can be uploaded + * + * @param int $maxbytes file size + */ function setMaxbytes($maxbytes) { global $CFG; $this->_options['maxbytes'] = get_max_upload_file_size($CFG->maxbytes, $maxbytes); } + /** + * Returns true if subdirectoy can be created, else false + * + * @return bool + */ function getSubdirs() { return $this->_options['subdirs']; } + /** + * Set option to create sub directory, while uploading file + * + * @param bool $allow true if sub directory can be created. + */ function setSubdirs($allow) { $this->_options['subdirs'] = $allow; } + /** + * Returns maximum number of files which can be uploaded + * + * @return int + */ function getMaxfiles() { return $this->_options['maxfiles']; } + /** + * Sets maximum number of files which can be uploaded. + * + * @param int $num number of files + */ function setMaxfiles($num) { $this->_options['maxfiles'] = $num; } + /** + * Sets help button for filemanager + * + * @param mixed $helpbuttonargs arguments to create help button + * @param string $function name of the callback function + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() + */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** + * Returns html for help button. + * + * @return string html for help button + */ function getHelpButton() { return $this->_helpbutton; } + /** + * Returns type of filemanager element + * + * @return string + */ function getElementTemplateType() { if ($this->_flagFrozen){ return 'nodisplay'; @@ -106,6 +198,11 @@ class MoodleQuickForm_filemanager extends HTML_QuickForm_element { } } + /** + * Returns HTML for filemanager form element. + * + * @return string + */ function toHtml() { global $CFG, $USER, $COURSE, $PAGE, $OUTPUT; require_once("$CFG->dirroot/repository/lib.php"); @@ -159,19 +256,25 @@ class MoodleQuickForm_filemanager extends HTML_QuickForm_element { } } - - /** * Data structure representing a file manager. * + * This class defines the data structure for file mnager + * + * @package core_form * @copyright 2010 Dongsheng Cai * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later - * @since Moodle 2.0 + * @todo do not use this abstraction (skodak) */ class form_filemanaer_x { - //TODO: do not use this abstraction (skodak) - + /** @var stdClass $options options for filemanager */ public $options; + + /** + * Constructor + * + * @param stdClass $options options for filemanager + */ public function __construct(stdClass $options) { global $CFG, $USER, $PAGE; require_once($CFG->dirroot. '/repository/lib.php'); diff --git a/lib/form/filepicker.php b/lib/form/filepicker.php index 771daa11a0a..4dff5fd114b 100644 --- a/lib/form/filepicker.php +++ b/lib/form/filepicker.php @@ -1,4 +1,29 @@ . + + +/** + * Filepicker form element + * + * Contains HTML class for a single filepicker form element + * + * @package core_form + * @copyright 2009 Dongsheng Cai + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ global $CFG; @@ -6,17 +31,31 @@ require_once("HTML/QuickForm/button.php"); require_once($CFG->dirroot.'/repository/lib.php'); /** + * Filepicker form element + * * HTML class for a single filepicker element (based on button) * - * @author Moodle.com - * @version 1.0 - * @since Moodle 2.0 - * @access public + * @package core_form + * @category form + * @copyright 2009 Dongsheng Cai + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_filepicker extends HTML_QuickForm_input { + /** @var string html for help button, if empty then no help will icon will be dispalyed. */ public $_helpbutton = ''; + + /** @var array options provided to initalize filemanager */ protected $_options = array('maxbytes'=>0, 'accepted_types'=>'*', 'return_types'=>FILE_INTERNAL); + /** + * Constructor + * + * @param string $elementName (optional) name of the filepicker + * @param string $elementLabel (optional) filepicker label + * @param array $attributes (optional) Either a typical HTML attribute string + * or an associative array + * @param array $options set of options to initalize filepicker + */ function MoodleQuickForm_filepicker($elementName=null, $elementLabel=null, $attributes=null, $options=null) { global $CFG; @@ -33,14 +72,33 @@ class MoodleQuickForm_filepicker extends HTML_QuickForm_input { parent::HTML_QuickForm_input($elementName, $elementLabel, $attributes); } + /** + * Sets help button for filepicker + * + * @param mixed $helpbuttonargs arguments to create help button + * @param string $function name of the callback function + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() + */ function setHelpButton($helpbuttonargs, $function='helpbutton') { debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** + * Returns html for help button. + * + * @return string html for help button + */ function getHelpButton() { return $this->_helpbutton; } + /** + * Returns type of filepicker element + * + * @return string + */ function getElementTemplateType() { if ($this->_flagFrozen){ return 'nodisplay'; @@ -49,6 +107,11 @@ class MoodleQuickForm_filepicker extends HTML_QuickForm_input { } } + /** + * Returns HTML for filepicker form element. + * + * @return string + */ function toHtml() { global $CFG, $COURSE, $USER, $PAGE, $OUTPUT; $id = $this->_attributes['id']; @@ -111,6 +174,13 @@ class MoodleQuickForm_filepicker extends HTML_QuickForm_input { return $html; } + /** + * export uploaded file + * + * @param array $submitValues values submitted. + * @param bool $assoc specifies if returned array is associative + * @return array + */ function exportValue(&$submitValues, $assoc = false) { global $USER; diff --git a/lib/form/format.php b/lib/form/format.php index 011b97524ed..ee917c7c74f 100644 --- a/lib/form/format.php +++ b/lib/form/format.php @@ -1,25 +1,55 @@ . + + +/** + * editor format form element + * + * Contains HTML class for a editor format drop down element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + global $CFG; require_once "$CFG->libdir/form/select.php"; /** - * HTML class for a editor format drop down element + * editor format form element * - * @author Jamie Pratt - * @access public + * HTML class for a editor format drop down element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @deprecated since Moodle 2.0 Please do not use this form element. + * @todo MDL-31294, remove this element + * @see MoodleQuickForm_editor */ class MoodleQuickForm_format extends MoodleQuickForm_select{ /** * Class constructor * - * @param string Select name attribute - * @param mixed Label(s) for the select - * @param mixed Either a typical HTML attribute string or an associative array - * @param mixed Either a string returned from can_use_html_editor() or false for no html editor - * default 'detect' tells element to use html editor if it is available. - * @access public - * @return void + * @param string $elementName Select name attribute + * @param mixed $elementLabel Label(s) for the select + * @param mixed $attributes Either a typical HTML attribute string or an associative array + * @param mixed $useHtmlEditor Either a string returned from can_use_html_editor() or false for no html editor + * default 'detect' tells element to use html editor if it is available. */ function MoodleQuickForm_format($elementName=null, $elementLabel=null, $attributes=null, $useHtmlEditor=null) { diff --git a/lib/form/grading.php b/lib/form/grading.php index 115399ee7be..e89460bdda6 100644 --- a/lib/form/grading.php +++ b/lib/form/grading.php @@ -1,5 +1,4 @@ . + /** + * Advance grading form element + * * Element-container for advanced grading custom input * - * @copyright 2011 Marina Glancy - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package core_form + * @copyright 2011 Marina Glancy + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ global $CFG; @@ -31,36 +34,32 @@ if (class_exists('HTML_QuickForm')) { } /** + * Advance grading form element + * * HTML class for a grading element. This is a wrapper for advanced grading plugins. * When adding the 'grading' element to the form, developer must pass an object of * class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be * thrown. * This object is responsible for implementing functions to render element html and validate it * - * @author Marina Glancy - * @access public + * @package core_form + * @category form + * @copyright 2011 Marina Glancy + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_grading extends HTML_QuickForm_input{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; - /** - * Stores attributes passed to the element - * @var array - */ + /** @var array Stores attributes passed to the element */ private $gradingattributes; /** * Class constructor * - * @param string $elementName Input field name attribute - * @param mixed $elementLabel Label(s) for the input field - * @param mixed $attributes Either a typical HTML attribute string or an associative array - * @return void + * @param string $elementName Input field name attribute + * @param mixed $elementLabel Label(s) for the input field + * @param mixed $attributes Either a typical HTML attribute string or an associative array */ public function MoodleQuickForm_grading($elementName=null, $elementLabel=null, $attributes=null) { parent::HTML_QuickForm_input($elementName, $elementLabel, $attributes); @@ -83,7 +82,7 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{ /** * Returns the input field in HTML * - * @return string + * @return string */ public function toHtml(){ global $PAGE; @@ -93,9 +92,11 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{ /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ public function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); @@ -104,8 +105,7 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{ /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ public function getHelpButton(){ return $this->_helpbutton; @@ -126,11 +126,11 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{ * Adds necessary rules to the element and checks that coorenct instance of gradingform_instance * is passed in attributes * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @return void - * @throws moodle_exception + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool + * @throws moodle_exception */ public function onQuickFormEvent($event, $arg, &$caller) { if ($event == 'createElement') { @@ -151,8 +151,9 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{ * Function registered as rule for this element and is called when this element is being validated. * This is a wrapper to pass the validation to the method gradingform_instance::validate_grading_element * - * @param mixed $elementValue - * @param array $attributes + * @param mixed $elementValue value of element to be validated + * @param array $attributes element attributes + * @return MoodleQuickForm_grading */ static function _validate($elementValue, $attributes = null) { return $attributes['gradinginstance']->validate_grading_element($elementValue); diff --git a/lib/form/group.php b/lib/form/group.php index 64fe56acbb5..c26f507d941 100644 --- a/lib/form/group.php +++ b/lib/form/group.php @@ -1,47 +1,87 @@ . + + +/** + * Form element group + * + * Contains HTML class for group form element + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once("HTML/QuickForm/group.php"); /** * HTML class for a form element group * - * @author Adam Daniel - * @author Bertrand Mansion - * @version 1.0 - * @since PHP4.04pl1 - * @access public + * Overloaded {@see HTML_QuickForm_group} with default behavior modified for Moodle. + * + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_group extends HTML_QuickForm_group{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** + * constructor + * + * @param string $elementName (optional) name of the group + * @param string $elementLabel (optional) group label + * @param array $elements (optional) array of HTML_QuickForm_element elements to group + * @param string $separator (optional) string to seperate elements. + * @param string $appendName (optional) string to appened to grouped elements. + */ function MoodleQuickForm_group($elementName=null, $elementLabel=null, $elements=null, $separator=null, $appendName = true) { parent::HTML_QuickForm_group($elementName, $elementLabel, $elements, $separator, $appendName); } - //would cause problems with client side validation so will leave for now + + /** @var string template type, would cause problems with client side validation so will leave for now */ //var $_elementTemplateType='fieldset'; + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * set html for help button - * - * @access public - * @param array $help array of arguments to make a help button - * @param string $function function name to call to get html */ function getHelpButton(){ return $this->_helpbutton; } + + /** + * Returns element template, nodisplay/static/fieldset + * + * @return string + */ function getElementTemplateType(){ if ($this->_flagFrozen){ if ($this->getGroupType() == 'submit'){ @@ -54,6 +94,11 @@ class MoodleQuickForm_group extends HTML_QuickForm_group{ } } + /** + * Sets the grouped elements and hides label + * + * @param array $elements + */ function setElements($elements){ parent::setElements($elements); foreach ($this->_elements as $element){ diff --git a/lib/form/header.php b/lib/form/header.php index 9f22503b46b..042fb09d6cd 100644 --- a/lib/form/header.php +++ b/lib/form/header.php @@ -1,57 +1,87 @@ . + + +/** + * Header form element + * + * Contains a pseudo-element used for adding headers to form + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ require_once 'HTML/QuickForm/header.php'; /** + * Header form element + * * A pseudo-element used for adding headers to form * + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_header extends HTML_QuickForm_header { - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + /** + * constructor + * + * @param string $elementName name of the header element + * @param string $text text displayed in header element + */ function MoodleQuickForm_header($elementName = null, $text = null) { parent::HTML_QuickForm_header($elementName, $text); } - // {{{ accept() - /** * Accepts a renderer * - * @param object An HTML_QuickForm_Renderer object - * @access public - * @return void + * @param HTML_QuickForm_Renderer $renderer a HTML_QuickForm_Renderer object */ function accept(&$renderer) { $this->_text .= $this->getHelpButton(); $renderer->renderHeader($this); - } // end func accept + } - // }}} /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } -} //end class MoodleQuickForm_header +} \ No newline at end of file diff --git a/lib/form/hidden.php b/lib/form/hidden.php index 70014cb7846..02e88f41385 100644 --- a/lib/form/hidden.php +++ b/lib/form/hidden.php @@ -1,20 +1,54 @@ . + + +/** + * Hidden type form element + * + * Contains HTML class for a hidden type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/hidden.php'); /** + * Hidden type form element + * * HTML class for a hidden type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_hidden extends HTML_QuickForm_hidden{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + /** + * Constructor + * + * @param string $elementName (optional) name of the hidden element + * @param string $value (optional) value of the element + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_hidden($elementName=null, $value='', $attributes=null) { parent::HTML_QuickForm_hidden($elementName, $value, $attributes); } @@ -22,18 +56,20 @@ class MoodleQuickForm_hidden extends HTML_QuickForm_hidden{ /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return ''; diff --git a/lib/form/htmleditor.php b/lib/form/htmleditor.php index 0dbc0b737a2..0a8252bb8de 100644 --- a/lib/form/htmleditor.php +++ b/lib/form/htmleditor.php @@ -1,17 +1,62 @@ . + + +/** + * htmleditor type form element + * + * Contains HTML class for htmleditor type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + global $CFG; require_once("$CFG->libdir/form/textarea.php"); /** + * htmleditor type form element + * * HTML class for htmleditor type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_htmleditor extends MoodleQuickForm_textarea{ + /** @var string defines the type of editor */ var $_type; + + /** @var bool Does the user want and can edit using rich text html editor */ var $_canUseHtmlEditor; + + /** @var array default options for html editor, which can be overridden */ var $_options=array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>45, 'width'=>0,'height'=>0); + + /** + * Constructor + * + * @param string $elementName (optional) name of the html editor + * @param string $elementLabel (optional) editor label + * @param array $options set of options to create html editor + * @param array $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_htmleditor($elementName=null, $elementLabel=null, $options=array(), $attributes=null){ parent::MoodleQuickForm_textarea($elementName, $elementLabel, $attributes); // set the options, do not bother setting bogus ones @@ -39,17 +84,25 @@ class MoodleQuickForm_htmleditor extends MoodleQuickForm_textarea{ editors_head_setup(); } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** + * Returns the input field in HTML + * + * @return string + */ function toHtml(){ //if ($this->_canUseHtmlEditor && !$this->_flagFrozen){ // $script = ''; @@ -71,17 +124,16 @@ class MoodleQuickForm_htmleditor extends MoodleQuickForm_textarea{ true, $this->getAttribute('id')); } - } //end func toHtml + } /** * What to display when element is frozen. * - * @access public - * @return string + * @return string */ function getFrozenHtml() { $html = format_text($this->getValue()); return $html . $this->_getPersistantData(); - } //end func getFrozenHtml + } } diff --git a/lib/form/modgrade.php b/lib/form/modgrade.php index 0abb9465f59..04a65e0c3d6 100644 --- a/lib/form/modgrade.php +++ b/lib/form/modgrade.php @@ -1,27 +1,57 @@ . + + +/** + * Drop down form element to select the grade + * + * Contains HTML class for a drop down element to select the grade for an activity, + * used in mod update form + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + global $CFG; require_once "$CFG->libdir/form/select.php"; /** + * Drop down form element to select the grade + * * HTML class for a drop down element to select the grade for an activity, * used in mod update form * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_modgrade extends MoodleQuickForm_select{ + /** @var bool if true the hides grade */ var $_hidenograde = false; /** * Class constructor * - * @param string Select name attribute - * @param mixed Label(s) for the select - * @param mixed Either a typical HTML attribute string or an associative array - * @param mixed $options ignored - * @access public - * @return void + * @param string $elementName (optional) name attribute + * @param mixed $elementLabel (optional) Label for the drop down + * @param mixed $attributes (optional) Either a typical HTML attribute string or an associative array + * @param mixed $hidenograde (optional) hide grade */ function MoodleQuickForm_modgrade($elementName=null, $elementLabel=null, $attributes=null, $hidenograde=false) { @@ -29,17 +59,15 @@ class MoodleQuickForm_modgrade extends MoodleQuickForm_select{ $this->_type = 'modgrade'; $this->_hidenograde = $hidenograde; - } //end constructor + } /** * Called by HTML_QuickForm whenever form event is made on this element * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @since 1.0 - * @access public - * @return mixed + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return mixed */ function onQuickFormEvent($event, $arg, &$caller) { diff --git a/lib/form/modvisible.php b/lib/form/modvisible.php index 0b7b30536ca..2a6acd9437f 100644 --- a/lib/form/modvisible.php +++ b/lib/form/modvisible.php @@ -1,24 +1,52 @@ . + + +/** + * Drop down form element to select visibility in an activity mod update form + * + * Contains HTML class for a drop down element to select visibility in an activity mod update form + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + global $CFG; require_once "$CFG->libdir/form/select.php"; /** + * Drop down form element to select visibility in an activity mod update form + * * HTML class for a drop down element to select visibility in an activity mod update form * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_modvisible extends MoodleQuickForm_select{ /** * Class constructor * - * @param string $elementName Select name attribute - * @param mixed $elementLabel Label(s) for the select - * @param mixed $attributes Either a typical HTML attribute string or an associative array - * @param array $options ignored - * @access public - * @return void + * @param string $elementName Select name attribute + * @param mixed $elementLabel Label(s) for the select + * @param mixed $attributes Either a typical HTML attribute string or an associative array + * @param array $options ignored */ function MoodleQuickForm_modvisible($elementName=null, $elementLabel=null, $attributes=null, $options=null) { @@ -26,16 +54,15 @@ class MoodleQuickForm_modvisible extends MoodleQuickForm_select{ $this->_type = 'modvisible'; - } //end constructor + } /** * Called by HTML_QuickForm whenever form event is made on this element * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @access public - * @return mixed + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool */ function onQuickFormEvent($event, $arg, &$caller) { diff --git a/lib/form/password.php b/lib/form/password.php index cfe1d7544df..c443bad7c2a 100644 --- a/lib/form/password.php +++ b/lib/form/password.php @@ -1,19 +1,54 @@ . + + +/** + * Password type form element + * + * Contains HTML class for a password type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/password.php'); /** + * Password type form element + * * HTML class for a password type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_password extends HTML_QuickForm_password{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string, html for help button, if empty then no help */ var $_helpbutton=''; + + /** + * constructor + * + * @param string $elementName (optional) name of the password element + * @param string $elementLabel (optional) label for password element + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_password($elementName=null, $elementLabel=null, $attributes=null) { global $CFG; if (empty($CFG->xmlstrictheaders)) { @@ -32,21 +67,24 @@ class MoodleQuickForm_password extends HTML_QuickForm_password{ parent::HTML_QuickForm_password($elementName, $elementLabel, $attributes); } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; diff --git a/lib/form/passwordunmask.php b/lib/form/passwordunmask.php index 40e087e1fd6..e14eb6cb38b 100644 --- a/lib/form/passwordunmask.php +++ b/lib/form/passwordunmask.php @@ -1,4 +1,30 @@ . + + +/** + * Password type form element with unmask option + * + * Contains HTML class for a password type element with unmask option + * + * @package core_form + * @copyright 2009 Petr Skoda + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + if (!defined('MOODLE_INTERNAL')) { die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page } @@ -7,13 +33,24 @@ global $CFG; require_once($CFG->libdir.'/form/password.php'); /** + * Password type form element with unmask option + * * HTML class for a password type element with unmask option * - * @author Petr Skoda - * @access public + * @package core_form + * @category form + * @copyright 2009 Petr Skoda {@link http://skodak.org} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_passwordunmask extends MoodleQuickForm_password { - + /** + * constructor + * + * @param string $elementName (optional) name of the password element + * @param string $elementLabel (optional) label for password element + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_passwordunmask($elementName=null, $elementLabel=null, $attributes=null) { global $CFG; if (empty($CFG->xmlstrictheaders)) { @@ -32,6 +69,11 @@ class MoodleQuickForm_passwordunmask extends MoodleQuickForm_password { parent::MoodleQuickForm_password($elementName, $elementLabel, $attributes); } + /** + * Returns HTML for password form element. + * + * @return string + */ function toHtml() { global $PAGE; @@ -44,6 +86,6 @@ class MoodleQuickForm_passwordunmask extends MoodleQuickForm_password { array(array('formid' => $this->getAttribute('id'), 'checkboxname' => $unmask))); return $this->_getTabs() . '_getAttrString($this->_attributes) . ' />'; } - } //end func toHtml + } } diff --git a/lib/form/questioncategory.php b/lib/form/questioncategory.php index 779e8d5895f..4f7d9998ffd 100644 --- a/lib/form/questioncategory.php +++ b/lib/form/questioncategory.php @@ -1,11 +1,28 @@ . + + /** - * A moodle form field type for question categories. + * Drop down for question categories. * - * @copyright Jamie Pratt - * @author Jamie Pratt - * @license http://www.gnu.org/copyleft/gpl.html GNU Public License - * @package moodleforms + * Contains HTML class for a drop down element to select a question category. + * + * @package core_form + * @copyright 2007 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ global $CFG; @@ -13,10 +30,17 @@ require_once("$CFG->libdir/form/selectgroups.php"); require_once("$CFG->libdir/questionlib.php"); /** + * Drop down for question categories. + * * HTML class for a drop down element to select a question category. - * @access public + * + * @package core_form + * @category form + * @copyright 2007 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_questioncategory extends MoodleQuickForm_selectgroups { + /** @var array default options for question categories */ var $_options = array('top'=>false, 'currentcat'=>0, 'nochildrenof' => -1); /** @@ -24,11 +48,10 @@ class MoodleQuickForm_questioncategory extends MoodleQuickForm_selectgroups { * * @param string $elementName Select name attribute * @param mixed $elementLabel Label(s) for the select - * @param mixed $attributes Either a typical HTML attribute string or an associative array * @param array $options additional options. Recognised options are courseid, published and - * only_editable, corresponding to the arguments of question_category_options from moodlelib.php. - * @access public - * @return void + * only_editable, corresponding to the arguments of question_category_options + * from moodlelib.php. + * @param mixed $attributes Either a typical HTML attribute string or an associative array */ function MoodleQuickForm_questioncategory($elementName = null, $elementLabel = null, $options = null, $attributes = null) { MoodleQuickForm_selectgroups::MoodleQuickForm_selectgroups($elementName, $elementLabel, array(), $attributes); diff --git a/lib/form/radio.php b/lib/form/radio.php index 0287b0ff486..dd97ee9732d 100644 --- a/lib/form/radio.php +++ b/lib/form/radio.php @@ -1,37 +1,77 @@ . + + +/** + * radio type form element + * + * Contains HTML class for a radio type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/radio.php'); /** + * radio type form element + * * HTML class for a radio type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_radio extends HTML_QuickForm_radio{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** + * constructor + * + * @param string $elementName (optional) name of the radio element + * @param string $elementLabel (optional) label for radio element + * @param string $text (optional) Text to put after the radio element + * @param string $value (optional) default value + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array + */ function MoodleQuickForm_radio($elementName=null, $elementLabel=null, $text=null, $value=null, $attributes=null) { parent::HTML_QuickForm_radio($elementName, $elementLabel, $text, $value, $attributes); } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; @@ -49,9 +89,11 @@ class MoodleQuickForm_radio extends HTML_QuickForm_radio{ return 'default'; } } + /** * Returns the disabled field. Accessibility: the return "( )" from parent * class is not acceptable for screenreader users, and we DO want a label. + * * @return string */ function getFrozenHtml() @@ -64,6 +106,12 @@ class MoodleQuickForm_radio extends HTML_QuickForm_radio{ } return $output; } + + /** + * Returns HTML for advchecbox form element. + * + * @return string + */ function toHtml() { return '' . parent::toHtml() . ''; diff --git a/lib/form/recaptcha.php b/lib/form/recaptcha.php index 0282efdf0d4..35a0c8420ff 100644 --- a/lib/form/recaptcha.php +++ b/lib/form/recaptcha.php @@ -1,37 +1,57 @@ . -/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ /** - * textarea_counter.php + * recaptcha type form element * - * @category Admin - * @package admin - * @author Nicolas Connault + * Contains HTML class for a recaptcha type element + * + * @package core_form + * @copyright 2008 Nicolas Connault + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ +require_once('HTML/QuickForm/input.php'); /** - * @category Admin - * @package admin + * recaptcha type form element + * + * HTML class for a recaptcha type element + * + * @package core_form + * @category form + * @copyright 2008 Nicolas Connault + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_recaptcha extends HTML_QuickForm_input { - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + /** @var bool if true, recaptcha will be servered from https */ var $_https=false; /** - * - * $form->addElement('textarea_counter', 'message', 'Message', - * array('cols'=>60, 'rows'=>10), 160); - * + * constructor + * + * @param string $elementName (optional) name of the recaptcha element + * @param string $elementLabel (optional) label for recaptcha element + * @param mixed $attributes (optional) Either a typical HTML attribute string + * or an associative array */ function MoodleQuickForm_recaptcha($elementName = null, $elementLabel = null, $attributes = null) { global $CFG; @@ -47,9 +67,7 @@ class MoodleQuickForm_recaptcha extends HTML_QuickForm_input { /** * Returns the recaptcha element in HTML * - * @since 1.0 - * @access public - * @return string + * @return string */ function toHtml() { global $CFG, $PAGE; @@ -95,9 +113,11 @@ class MoodleQuickForm_recaptcha extends HTML_QuickForm_input { /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); @@ -106,13 +126,19 @@ class MoodleQuickForm_recaptcha extends HTML_QuickForm_input { /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** + * Checks input and challenged field + * + * @param string $challenge_field recaptcha shown to user + * @param string $response_field input value by user + * @return bool + */ function verify($challenge_field, $response_field) { global $CFG; require_once $CFG->libdir . '/recaptchalib.php'; diff --git a/lib/form/searchableselector.php b/lib/form/searchableselector.php index 10cf7d9c25e..4eb0101cbca 100644 --- a/lib/form/searchableselector.php +++ b/lib/form/searchableselector.php @@ -1,5 +1,4 @@ . /** - * HTML class for a searchable select type element + * searchable select type element * - * @package formlib - * @copyright 2009 Jerome Mouneyrac + * Contains HTML class for a searchable select type element + * + * @package core_form + * @copyright 2009 Jerome Mouneyrac * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ require_once('select.php'); /** + * searchable select type element + * * Display a select input with a search textfield input on the top * The search textfield is created by the javascript file searchselector.js * (so when javascript is not activated into the browser, the search field is not displayed) * If ever the select can be reset/unselect/blank/nooption, you will have to add an option "noselected" * and manage this special case when you get/set the form data (i.e. $mform->get_data()/$this->set_data($yourobject)). + * + * @package core_form + * @category form + * @copyright 2009 Jerome Mouneyrac + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_searchableselector extends MoodleQuickForm_select{ - - + /** + * Constructor + * + * @param string $elementName Select name attribute + * @param mixed $elementLabel Label(s) for the select + * @param array $options additional options. + * @param mixed $attributes Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_searchableselector($elementName=null, $elementLabel=null, $options=null, $attributes=null) { //set size default to 12 if (empty($attributes) || empty($attributes['size'])) { @@ -43,6 +57,11 @@ class MoodleQuickForm_searchableselector extends MoodleQuickForm_select{ parent::MoodleQuickForm_select($elementName, $elementLabel, $options, $attributes); } + /** + * Returns the select element in HTML + * + * @return string + */ function toHtml(){ global $OUTPUT; if ($this->_hiddenLabel){ diff --git a/lib/form/select.php b/lib/form/select.php index e76cd5718bf..22c8752d1b7 100644 --- a/lib/form/select.php +++ b/lib/form/select.php @@ -1,27 +1,75 @@ . + + +/** + * select type form element + * + * Contains HTML class for a select type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/select.php'); /** + * select type form element + * * HTML class for a select type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_select extends HTML_QuickForm_select{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** @var bool if true label will be hidden */ var $_hiddenLabel=false; + /** + * constructor + * + * @param string $elementName Select name attribute + * @param mixed $elementLabel Label(s) for the select + * @param mixed $options Data to be used to populate options + * @param mixed $attributes Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_select($elementName=null, $elementLabel=null, $options=null, $attributes=null) { parent::HTML_QuickForm_select($elementName, $elementLabel, $options, $attributes); } + + /** + * Sets label to be hidden + * + * @param bool $hiddenLabel sets if label should be hidden + */ function setHiddenLabel($hiddenLabel){ $this->_hiddenLabel = $hiddenLabel; } + + /** + * Returns HTML for select form element. + * + * @return string + */ function toHtml(){ if ($this->_hiddenLabel){ $this->_generateId(); @@ -35,29 +83,30 @@ class MoodleQuickForm_select extends HTML_QuickForm_select{ /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** * Removes an OPTION from the SELECT * - * @param string $value Value for the OPTION to remove - * @since 1.0 - * @access public - * @return void + * @param string $value Value for the OPTION to remove + * @return void */ function removeOption($value) { @@ -73,19 +122,16 @@ class MoodleQuickForm_select extends HTML_QuickForm_select{ return; } } - } // end func removeOption + } + /** * Removes all OPTIONs from the SELECT - * - * @param string $value Value for the OPTION to remove - * @since 1.0 - * @access public - * @return void */ function removeOptions() { $this->_options = array(); - } // end func removeOption + } + /** * Slightly different container template when frozen. Don't want to use a label tag * with a for attribute in that case for the element label but instead use a div. @@ -100,9 +146,14 @@ class MoodleQuickForm_select extends HTML_QuickForm_select{ return 'default'; } } + /** * We check the options and return only the values that _could_ have been * selected. We also return a scalar value if select is not "multiple" + * + * @param array $submitValues submitted values + * @param bool $assoc if true the retured value is associated array + * @return mixed */ function exportValue(&$submitValues, $assoc = false) { diff --git a/lib/form/selectgroups.php b/lib/form/selectgroups.php index 92b5ea05450..558cff04d56 100644 --- a/lib/form/selectgroups.php +++ b/lib/form/selectgroups.php @@ -1,79 +1,67 @@ | -// | Bertrand Mansion | -// +----------------------------------------------------------------------+ +// This file is part of Moodle - http://moodle.org/ +// +// Moodle is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// Moodle is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with Moodle. If not, see . + + +/** + * select type form element + * + * Class to dynamically create an HTML SELECT with all options grouped in optgroups + * + * @package core_form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ require_once('HTML/QuickForm/element.php'); /** + * select type form element + * * Class to dynamically create an HTML SELECT with all options grouped in optgroups * - * @author Adam Daniel - * @author Bertrand Mansion - * @version 1.0 - * @since PHP4.04pl1 - * @access public + * @package core_form + * @category form + * @copyright 2007 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { - // {{{ properties - - /** add choose option */ + /** @var bool add choose option */ var $showchoose = false; - /** - * Contains the select optgroups - * - * @var array - * @since 1.0 - * @access private - */ + /** @var array Contains the select optgroups */ var $_optGroups = array(); - /** - * Default values of the SELECT - * - * @var string - * @since 1.0 - * @access private - */ + /** @var string Default values of the SELECT */ var $_values = null; - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** @var bool if true label will be hidden */ var $_hiddenLabel=false; /** * Class constructor * - * @param string Select name attribute - * @param mixed Label(s) for the select - * @param mixed Data to be used to populate options - * @param mixed An array whose keys are labels for optgroups and whose values are arrays similar to those passed - * to the select element with keys that are values for options and values are strings for display. - * @param mixed Either a typical HTML attribute string or an associative array - * @param bool add standard moodle "Choose..." option as first item - * @since 1.0 - * @access public - * @return void + * @param string $elementName Select name attribute + * @param mixed $elementLabel Label(s) for the select + * @param array $optgrps Data to be used to populate options + * @param mixed $attributes Either a typical HTML attribute string or an associative array + * @param bool $showchoose add standard moodle "Choose..." option as first item */ function MoodleQuickForm_selectgroups($elementName=null, $elementLabel=null, $optgrps=null, $attributes=null, $showchoose=false) { @@ -84,19 +72,12 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { if (isset($optgrps)) { $this->loadArrayOptGroups($optgrps); } - } //end constructor - - // }}} - // {{{ apiVersion() - + } /** * Sets the default values of the select box * - * @param mixed $values Array or comma delimited string of selected values - * @since 1.0 - * @access public - * @return void + * @param mixed $values Array or comma delimited string of selected values */ function setSelected($values) { @@ -108,63 +89,42 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { } else { $this->_values = array($values); } - } //end func setSelected - - // }}} - // {{{ getSelected() + } /** * Returns an array of the selected values * - * @since 1.0 - * @access public - * @return array of selected values + * @return array of selected values */ function getSelected() { return $this->_values; - } // end func getSelected - - // }}} - // {{{ setName() + } /** * Sets the input field name * - * @param string $name Input field name attribute - * @since 1.0 - * @access public - * @return void + * @param string $name Input field name attribute */ function setName($name) { $this->updateAttributes(array('name' => $name)); - } //end func setName - - // }}} - // {{{ getName() + } /** * Returns the element name * - * @since 1.0 - * @access public - * @return string + * @return string */ function getName() { return $this->getAttribute('name'); - } //end func getName - - // }}} - // {{{ getPrivateName() + } /** * Returns the element name (possibly with brackets appended) * - * @since 1.0 - * @access public - * @return string + * @return string */ function getPrivateName() { @@ -173,80 +133,52 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { } else { return $this->getName(); } - } //end func getPrivateName - - // }}} - // {{{ setValue() + } /** * Sets the value of the form element * - * @param mixed $values Array or comma delimited string of selected values - * @since 1.0 - * @access public - * @return void + * @param mixed $value Array or comma delimited string of selected values */ function setValue($value) { $this->setSelected($value); - } // end func setValue - - // }}} - // {{{ getValue() + } /** * Returns an array of the selected values * - * @since 1.0 - * @access public - * @return array of selected values + * @return array of selected values */ function getValue() { return $this->_values; - } // end func getValue - - // }}} - // {{{ setSize() + } /** * Sets the select field size, only applies to 'multiple' selects * - * @param int $size Size of select field - * @since 1.0 - * @access public - * @return void + * @param int $size Size of select field */ function setSize($size) { $this->updateAttributes(array('size' => $size)); - } //end func setSize - - // }}} - // {{{ getSize() + } /** * Returns the select field size * - * @since 1.0 - * @access public - * @return int + * @return int */ function getSize() { return $this->getAttribute('size'); - } //end func getSize - - // }}} - // {{{ setMultiple() + } /** * Sets the select mutiple attribute * - * @param bool $multiple Whether the select supports multi-selections - * @since 1.2 - * @access public - * @return void + * @param bool $multiple Whether the select supports multi-selections */ function setMultiple($multiple) { @@ -255,32 +187,25 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { } else { $this->removeAttribute('multiple'); } - } //end func setMultiple - - // }}} - // {{{ getMultiple() + } /** * Returns the select mutiple attribute * - * @since 1.2 - * @access public - * @return bool true if multiple select, false otherwise + * @return bool true if multiple select, false otherwise */ function getMultiple() { return (bool)$this->getAttribute('multiple'); - } //end func getMultiple + } /** * Loads the options from an associative array * - * @param array $arr Associative array of options - * @param mixed $values (optional) Array or comma delimited string of selected values - * @since 1.0 - * @access public - * @return PEAR_Error on error or true - * @throws PEAR_Error + * @param array $arr Associative array of options + * @param mixed $values (optional) Array or comma delimited string of selected values + * @return PEAR_Error|bool on error or true + * @throws PEAR_Error */ function loadArrayOptGroups($arr, $values=null) { @@ -296,16 +221,14 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { } return true; } + /** * Adds a new OPTION to the SELECT * - * @param string $text Display text for the OPTION - * @param string $value Value for the OPTION - * @param mixed $attributes Either a typical HTML attribute string - * or an associative array - * @since 1.0 - * @access public - * @return void + * @param string $text Display text for the OPTION + * @param string $value Value for the OPTION + * @param mixed $attributes Either a typical HTML attribute string + * or an associative array */ function addOptGroup($text, $value, $attributes=null) { @@ -323,12 +246,11 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { /** * Loads the options from an associative array * - * @param array $arr Associative array of options - * @param mixed $values (optional) Array or comma delimited string of selected values - * @since 1.0 - * @access public - * @return PEAR_Error on error or true - * @throws PEAR_Error + * @param string $optgroup name of the options group + * @param array $arr Associative array of options + * @param mixed $values (optional) Array or comma delimited string of selected values + * @return PEAR_Error|bool on error or true + * @throws PEAR_Error */ function loadArrayOptions($optgroup, $arr, $values=null) { @@ -348,13 +270,11 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { /** * Adds a new OPTION to an optgroup * - * @param string $text Display text for the OPTION - * @param string $value Value for the OPTION - * @param mixed $attributes Either a typical HTML attribute string - * or an associative array - * @since 1.0 - * @access public - * @return void + * @param string $optgroup name of the option group + * @param string $text Display text for the OPTION + * @param string $value Value for the OPTION + * @param mixed $attributes Either a typical HTML attribute string + * or an associative array */ function addOption($optgroup, $text, $value, $attributes=null) { @@ -379,9 +299,7 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { /** * Returns the SELECT in HTML * - * @since 1.0 - * @access public - * @return string + * @return string */ function toHtml() { @@ -430,17 +348,12 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { } return $strHtml . $tabs . ''; } - } //end func toHtml - - // }}} - // {{{ getFrozenHtml() + } /** * Returns the value of field without HTML tags * - * @since 1.0 - * @access public - * @return string + * @return string */ function getFrozenHtml() { @@ -476,14 +389,15 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { } } return $html; - } //end func getFrozenHtml - - // }}} - // {{{ exportValue() + } /** * We check the options and return only the values that _could_ have been * selected. We also return a scalar value if select is not "multiple" + * + * @param array $submitValues submitted values + * @param bool $assoc if true the retured value is associated array + * @return mixed */ function exportValue(&$submitValues, $assoc = false) { @@ -522,9 +436,14 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { } } - // }}} - // {{{ onQuickFormEvent() - + /** + * Called by HTML_QuickForm whenever form event is made on this element + * + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return bool + */ function onQuickFormEvent($event, $arg, &$caller) { if ('updateValue' == $event) { @@ -545,24 +464,33 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element { return parent::onQuickFormEvent($event, $arg, $caller); } } + + /** + * Sets label to be hidden + * + * @param bool $hiddenLabel sets if label should be hidden + */ function setHiddenLabel($hiddenLabel){ $this->_hiddenLabel = $hiddenLabel; } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; diff --git a/lib/form/selectwithlink.php b/lib/form/selectwithlink.php index 637ce6a28cb..dc683396556 100644 --- a/lib/form/selectwithlink.php +++ b/lib/form/selectwithlink.php @@ -1,24 +1,67 @@ . + + +/** + * select type form element + * + * Contains HTML class for a select type element with options containing link + * + * @package core_form + * @copyright 2008 Nicolas Connault + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/select.php'); /** - * HTML class for a select type element + * select type form element * - * @author Jamie Pratt - * @access public + * HTML class for a select type element with options containing link + * + * @package core_form + * @category form + * @copyright 2008 Nicolas Connault + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** @var bool if true label will be hidden */ var $_hiddenLabel=false; + + /** @var string url to which select option will be posted */ var $_link=null; + + /** @var string data which will be posted to link */ var $_linklabel=null; + + /** @var string url return link */ var $_linkreturn=null; + /** + * constructor + * + * @param string $elementName Select name attribute + * @param mixed $elementLabel Label(s) for the select + * @param array $options Data to be used to populate options + * @param mixed $attributes Either a typical HTML attribute string or an associative array + * @param bool $linkdata data to be posted + */ function MoodleQuickForm_selectwithlink($elementName=null, $elementLabel=null, $options=null, $attributes=null, $linkdata=null) { if (!empty($linkdata['link']) && !empty($linkdata['label'])) { @@ -31,11 +74,22 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{ } parent::HTML_QuickForm_select($elementName, $elementLabel, $options, $attributes); - } //end constructor + } + /** + * Sets label to be hidden + * + * @param bool $hiddenLabel sets if label should be hidden + */ function setHiddenLabel($hiddenLabel){ $this->_hiddenLabel = $hiddenLabel; } + + /** + * Returns the SELECT in HTML + * + * @return string + */ function toHtml(){ $retval = ''; if ($this->_hiddenLabel){ @@ -68,29 +122,29 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{ /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** * Removes an OPTION from the SELECT * - * @param string $value Value for the OPTION to remove - * @since 1.0 - * @access public - * @return void + * @param string $value Value for the OPTION to remove */ function removeOption($value) { @@ -104,19 +158,16 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{ return; } } - } // end func removeOption + } + /** * Removes all OPTIONs from the SELECT - * - * @param string $value Value for the OPTION to remove - * @since 1.0 - * @access public - * @return void */ function removeOptions() { $this->_options = array(); - } // end func removeOption + } + /** * Slightly different container template when frozen. Don't want to use a label tag * with a for attribute in that case for the element label but instead use a div. @@ -131,9 +182,14 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{ return 'default'; } } + /** * We check the options and return only the values that _could_ have been * selected. We also return a scalar value if select is not "multiple" + * + * @param array $submitValues submitted values + * @param bool $assoc if true the retured value is associated array + * @return mixed */ function exportValue(&$submitValues, $assoc = false) { diff --git a/lib/form/selectyesno.php b/lib/form/selectyesno.php index f451b8d6aca..c5eb181711b 100644 --- a/lib/form/selectyesno.php +++ b/lib/form/selectyesno.php @@ -1,42 +1,66 @@ . + + +/** + * Yes/No drop down type form element + * + * Contains HTML class for a simple yes/ no drop down element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + global $CFG; require_once "$CFG->libdir/form/select.php"; /** + * Yes/No drop down type form element + * * HTML class for a simple yes/ no drop down element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_selectyesno extends MoodleQuickForm_select{ - - /** * Class constructor * - * @param string Select name attribute - * @param mixed Label(s) for the select - * @param mixed Either a typical HTML attribute string or an associative array - * @param mixed $options ignored - * @access public - * @return void + * @param string $elementName Select name attribute + * @param mixed $elementLabel Label(s) for the select + * @param mixed $attributes Either a typical HTML attribute string or an associative array + * @param mixed $options ignored, not used. */ function MoodleQuickForm_selectyesno($elementName=null, $elementLabel=null, $attributes=null, $options=null) { HTML_QuickForm_element::HTML_QuickForm_element($elementName, $elementLabel, $attributes, null); $this->_type = 'selectyesno'; - } //end constructor + } /** * Called by HTML_QuickForm whenever form event is made on this element * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @since 1.0 - * @access public - * @return mixed + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + * @return mixed */ function onQuickFormEvent($event, $arg, &$caller) { diff --git a/lib/form/simpletest/testduration.php b/lib/form/simpletest/testduration.php index ee8b4daa8f1..d57f9a49c87 100644 --- a/lib/form/simpletest/testduration.php +++ b/lib/form/simpletest/testduration.php @@ -1,27 +1,29 @@ . -/////////////////////////////////////////////////////////////////////////// -// // -// NOTICE OF COPYRIGHT // -// // -// Moodle - Modular Object-Oriented Dynamic Learning Environment // -// http://moodle.org // -// // -// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // -// // -// This program is free software; you can redistribute it and/or modify // -// it under the terms of the GNU General Public License as published by // -// the Free Software Foundation; either version 2 of the License, or // -// (at your option) any later version. // -// // -// This program is distributed in the hope that it will be useful, // -// but WITHOUT ANY WARRANTY; without even the implied warranty of // -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // -// GNU General Public License for more details: // -// // -// http://www.gnu.org/copyleft/gpl.html // -// // -/////////////////////////////////////////////////////////////////////////// + +/** + * Unit tests for forms lib. + * + * This file contains all unit test related to forms library. + * + * @package core_form + * @copyright 2009 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ if (!defined('MOODLE_INTERNAL')) { die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page @@ -31,29 +33,49 @@ global $CFG; require_once($CFG->libdir . '/form/duration.php'); /** - * Unit tests for (some of) ../duration.php. + * Unit tests for MoodleQuickForm_duration * - * @license http://www.gnu.org/copyleft/gpl.html GNU Public License - * @package formslib + * Contains test cases for testing MoodleQuickForm_duration + * + * @package core_form + * @category unittest + * @copyright 2009 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class duration_form_element_test extends UnitTestCase { + /** @var MoodleQuickForm_duration Keeps reference of MoodleQuickForm_duration object */ private $element; - public static $includecoverage = array('lib/form/duration.php'); + /** @var array Path of MoodleQuickForm_duration, to be analysed by the coverage report */ + public static $includecoverage = array('lib/form/duration.php'); + + /** + * Initalize test wide variable, it is called in start of the testcase + */ function setUp() { $this->element = new MoodleQuickForm_duration(); } + /** + * Clears the data set in the setUp() method call. + * @see duration_form_element_test::setUp() + */ function tearDown() { $this->element = null; } + /** + * Testcase for testing contructor. + */ function test_constructor() { // Test trying to create with an invalid unit. $this->expectException(); $this->element = new MoodleQuickForm_duration('testel', null, array('defaultunit' => 123)); } + /** + * Testcase for testing units (seconds, minutes, hours and days) + */ function test_get_units() { $units = $this->element->get_units(); ksort($units); @@ -61,6 +83,9 @@ class duration_form_element_test extends UnitTestCase { 3600 => get_string('hours'), 86400 => get_string('days'))); } + /** + * Testcase for testing conversion of seconds to the best possible unit + */ function test_seconds_to_unit() { $this->assertEqual($this->element->seconds_to_unit(0), array(0, 60)); // Zero minutes, for a nice default unit. $this->assertEqual($this->element->seconds_to_unit(1), array(1, 1)); @@ -76,6 +101,9 @@ class duration_form_element_test extends UnitTestCase { $this->assertEqual($this->element->seconds_to_unit(0), array(0, 86400)); // Zero minutes, for a nice default unit. } + /** + * Testcase to check generated timestamp + */ function test_exportValue() { $el = new MoodleQuickForm_duration('testel'); $el->_createElements(); diff --git a/lib/form/static.php b/lib/form/static.php index 82584393fbe..825b3e1a56f 100644 --- a/lib/form/static.php +++ b/lib/form/static.php @@ -1,43 +1,87 @@ . + + +/** + * Text type form element + * + * Contains HTML class for a text type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once("HTML/QuickForm/static.php"); /** + * Text type element + * * HTML class for a text type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_static extends HTML_QuickForm_static{ + /** @var string Form element type */ var $_elementTemplateType='static'; - /** - * html for help button, if empty then no help - * - * @var string - */ + + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** + * constructor + * + * @param string $elementName (optional) name of the text field + * @param string $elementLabel (optional) text field label + * @param string $text (optional) Text to put in text field + */ function MoodleQuickForm_static($elementName=null, $elementLabel=null, $text=null) { parent::HTML_QuickForm_static($elementName, $elementLabel, $text); } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** + * Gets the type of form element + * + * @return string + */ function getElementTemplateType(){ return $this->_elementTemplateType; } diff --git a/lib/form/submit.php b/lib/form/submit.php index 3b6fd906f22..b4ccb99fa1b 100644 --- a/lib/form/submit.php +++ b/lib/form/submit.php @@ -1,28 +1,60 @@ . + + +/** + * submit type form element + * + * Contains HTML class for a submit type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once("HTML/QuickForm/submit.php"); /** + * submit type form element + * * HTML class for a submit type element * - * @author Adam Daniel - * @author Bertrand Mansion - * @version 1.0 - * @since PHP4.04pl1 - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_submit extends HTML_QuickForm_submit { + /** + * constructor + * + * @param string $elementName (optional) name of the field + * @param string $value (optional) field label + * @param string $attributes (optional) Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_submit($elementName=null, $value=null, $attributes=null) { parent::HTML_QuickForm_submit($elementName, $value, $attributes); } + /** * Called by HTML_QuickForm whenever form event is made on this element * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @since 1.0 - * @access public - * @return void + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object */ function onQuickFormEvent($event, $arg, &$caller) { @@ -43,7 +75,8 @@ class MoodleQuickForm_submit extends HTML_QuickForm_submit { } return parent::onQuickFormEvent($event, $arg, $caller); - } // end func onQuickFormEvent + } + /** * Slightly different container template when frozen. Don't want to display a submit * button if the form is frozen. @@ -58,6 +91,9 @@ class MoodleQuickForm_submit extends HTML_QuickForm_submit { } } + /** + * Freeze the element so that only its value is returned + */ function freeze(){ $this->_flagFrozen = true; } diff --git a/lib/form/submitlink.php b/lib/form/submitlink.php index 98286533c22..c644376df8d 100644 --- a/lib/form/submitlink.php +++ b/lib/form/submitlink.php @@ -1,13 +1,65 @@ . + + +/** + * submit link type form element + * + * Contains HTML class for a submitting to link + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + global $CFG; require_once("$CFG->libdir/form/submit.php"); +/** + * submit link type form element + * + * HTML class for a submitting to link + * + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class MoodleQuickForm_submitlink extends MoodleQuickForm_submit { + /** @var string javascript for submitting element's data */ var $_js; + + /** @var string callback function which will be called onclick event */ var $_onclick; + + /** + * constructor + * + * @param string $elementName (optional) name of the field + * @param string $value (optional) field label + * @param string $attributes (optional) Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_submitlink($elementName=null, $value=null, $attributes=null) { parent::MoodleQuickForm_submit($elementName, $value, $attributes); } + /** + * Returns HTML for submitlink form element. + * + * @return string + */ function toHtml() { $text = $this->_attributes['value']; $onmouseover = "window.status=\'" . $text . "\';"; diff --git a/lib/form/tags.php b/lib/form/tags.php index 3aeadcd095c..9f73b178768 100644 --- a/lib/form/tags.php +++ b/lib/form/tags.php @@ -1,56 +1,67 @@ . + /** - * Formslib field type for editing tags, both official and peronal. + * Drop down for question categories. * - * @license http://www.gnu.org/copyleft/gpl.html GNU Public License - * @package formslib - *//* **/ + * Contains HTML class for editing tags, both official and peronal. + * + * @package core_form + * @copyright 2009 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + global $CFG; require_once($CFG->libdir . '/form/group.php'); /** - * Formslib field type for editing tags. + * Form field type for editing tags. + * + * HTML class for editing tags, both official and peronal. + * + * @package core_form + * @category form + * @copyright 2009 Tim Hunt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_tags extends MoodleQuickForm_group { - /** Inidcates that the user should be the usual interface, with the official + /** + * Inidcates that the user should be the usual interface, with the official * tags listed seprately, and a text box where they can type anything. - * @var integer */ + * @var int + */ const DEFAULTUI = 'defaultui'; - /** Indicates that the user should only be allowed to select official tags. - * @var integer */ + + /** + * Indicates that the user should only be allowed to select official tags. + * @var int + */ const ONLYOFFICIAL = 'onlyofficial'; - /** Indicates that the user should just be given a text box to type in (they + + /** + * Indicates that the user should just be given a text box to type in (they * can still type official tags though. - * @var integer */ + * @var int + */ const NOOFFICIAL = 'noofficial'; /** - * Control the fieldnames for form elements - * - * display => integer, one of the constants above. + * Control the fieldnames for form elements display => int, one of the constants above. + * @var array */ protected $_options = array('display' => MoodleQuickForm_tags::DEFAULTUI); @@ -91,6 +102,11 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group { } } + /** + * Internal function to load official tags + * + * @access protected + */ protected function _load_official_tags() { global $CFG, $DB; if (!is_null($this->_officialtags)) { @@ -100,6 +116,9 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group { $this->_officialtags = $DB->get_records_menu('tag', array('tagtype' => 'official'), $namefield, 'id,' . $namefield); } + /** + * Creates the group's elements. + */ function _createElements() { global $CFG, $OUTPUT; $this->_elements = array(); @@ -159,6 +178,13 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group { } } + /** + * Called by HTML_QuickForm whenever form event is made on this element + * + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object + */ function onQuickFormEvent($event, $arg, &$caller) { switch ($event) { case 'updateValue': @@ -207,6 +233,11 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group { } } + /** + * Returns HTML for submitlink form element. + * + * @return string + */ function toHtml() { require_once('HTML/QuickForm/Renderer/Default.php'); $renderer = new HTML_QuickForm_Renderer_Default(); @@ -215,11 +246,25 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group { return $renderer->toHtml(); } + /** + * Accepts a renderer + * + * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object + * @param bool $required Whether a group is required + * @param string $error An error message associated with a group + */ function accept(&$renderer, $required = false, $error = null) { $renderer->renderElement($this, $required, $error); } + /** + * Output both official and peronal. + * + * @param array $submitValues values submitted. + * @param bool $assoc specifies if returned array is associative + * @return array + */ function exportValue(&$submitValues, $assoc = false) { $valuearray = array(); diff --git a/lib/form/text.php b/lib/form/text.php index 7d36b944e4b..40b1e9658c1 100644 --- a/lib/form/text.php +++ b/lib/form/text.php @@ -1,28 +1,74 @@ . + + +/** + * Text type form element + * + * Contains HTML class for a text type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once("HTML/QuickForm/text.php"); /** + * Text type form element + * * HTML class for a text type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_text extends HTML_QuickForm_text{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** @var bool if true label will be hidden */ var $_hiddenLabel=false; + /** + * constructor + * + * @param string $elementName (optional) name of the text field + * @param string $elementLabel (optional) text field label + * @param string $attributes (optional) Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_text($elementName=null, $elementLabel=null, $attributes=null) { parent::HTML_QuickForm_text($elementName, $elementLabel, $attributes); } + /** + * Sets label to be hidden + * + * @param bool $hiddenLabel sets if label should be hidden + */ function setHiddenLabel($hiddenLabel){ $this->_hiddenLabel = $hiddenLabel; } + + /** + * Returns HTML for this form element. + * + * @return string + */ function toHtml(){ if ($this->_hiddenLabel){ $this->_generateId(); @@ -36,22 +82,25 @@ class MoodleQuickForm_text extends HTML_QuickForm_text{ /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** * Slightly different container template when frozen. Don't want to use a label tag * with a for attribute in that case for the element label but instead use a div. diff --git a/lib/form/textarea.php b/lib/form/textarea.php index 7587ddfa1da..d3719b1aa65 100644 --- a/lib/form/textarea.php +++ b/lib/form/textarea.php @@ -1,55 +1,99 @@ . + + +/** + * Textarea type form element + * + * Contains HTML class for a textarea type element + * + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once('HTML/QuickForm/textarea.php'); /** + * Textarea type form element + * * HTML class for a textarea type element * - * @author Jamie Pratt - * @access public + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_textarea extends HTML_QuickForm_textarea{ - /** - * Need to store id of form as we may need it for helpbutton - * - * @var string - */ + /** @var string Need to store id of form as we may need it for helpbutton */ var $_formid = ''; - /** - * html for help button, if empty then no help - * - * @var string - */ + + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + /** @var bool if true label will be hidden */ var $_hiddenLabel=false; + /** + * constructor + * + * @param string $elementName (optional) name of the text field + * @param string $elementLabel (optional) text field label + * @param string $attributes (optional) Either a typical HTML attribute string or an associative array + */ function MoodleQuickForm_textarea($elementName=null, $elementLabel=null, $attributes=null) { parent::HTML_QuickForm_textarea($elementName, $elementLabel, $attributes); } + /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** + * Sets label to be hidden + * + * @param bool $hiddenLabel sets if label should be hidden + */ function setHiddenLabel($hiddenLabel){ $this->_hiddenLabel = $hiddenLabel; } + /** + * Returns HTML for this form element. + * + * @return string + */ function toHtml(){ if ($this->_hiddenLabel){ $this->_generateId(); @@ -63,12 +107,9 @@ class MoodleQuickForm_textarea extends HTML_QuickForm_textarea{ /** * Called by HTML_QuickForm whenever form event is made on this element * - * @param string $event Name of event - * @param mixed $arg event arguments - * @param object $caller calling object - * @since 1.0 - * @access public - * @return void + * @param string $event Name of event + * @param mixed $arg event arguments + * @param object $caller calling object */ function onQuickFormEvent($event, $arg, &$caller) { @@ -78,7 +119,8 @@ class MoodleQuickForm_textarea extends HTML_QuickForm_textarea{ break; } return parent::onQuickFormEvent($event, $arg, $caller); - } // end func onQuickFormEvent + } + /** * Slightly different container template when frozen. * diff --git a/lib/form/url.php b/lib/form/url.php index dd38f92cfe7..743a796468e 100644 --- a/lib/form/url.php +++ b/lib/form/url.php @@ -1,21 +1,56 @@ . + + +/** + * url type form element + * + * Contains HTML class for a url type element + * + * @package core_form + * @copyright 2009 Dongsheng Cai + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + require_once("HTML/QuickForm/text.php"); /** - * HTML class for a url type element + * url type form element * - * @author Jamie Pratt - * @access public + * HTML class for a url type element + * @package core_form + * @category form + * @copyright 2009 Dongsheng Cai + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_url extends HTML_QuickForm_text{ - /** - * html for help button, if empty then no help - * - * @var string - */ + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** @var bool if true label will be hidden */ var $_hiddenLabel=false; + /** + * Constructor + * + * @param string $elementName Element name + * @param mixed $elementLabel Label(s) for an element + * @param mixed $attributes Either a typical HTML attribute string or an associative array. + * @param array $options data which need to be posted. + */ function MoodleQuickForm_url($elementName=null, $elementLabel=null, $attributes=null, $options=null) { global $CFG; require_once("$CFG->dirroot/repository/lib.php"); @@ -29,9 +64,20 @@ class MoodleQuickForm_url extends HTML_QuickForm_text{ parent::HTML_QuickForm_text($elementName, $elementLabel, $attributes); } + /** + * Sets label to be hidden + * + * @param bool $hiddenLabel sets if label should be hidden + */ function setHiddenLabel($hiddenLabel){ $this->_hiddenLabel = $hiddenLabel; } + + /** + * Returns HTML for this form element. + * + * @return string + */ function toHtml(){ global $CFG, $COURSE, $USER, $PAGE, $OUTPUT; @@ -84,22 +130,25 @@ EOD; /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** * Slightly different container template when frozen. Don't want to use a label tag * with a for attribute in that case for the element label but instead use a div. diff --git a/lib/form/warning.php b/lib/form/warning.php index d472b9f48f5..3934e11b0ff 100644 --- a/lib/form/warning.php +++ b/lib/form/warning.php @@ -1,22 +1,58 @@ . + + +/** + * static warning element + * + * Contains class for static warning type element + * + * @package core_form + * @copyright 2008 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ require_once("HTML/QuickForm/static.php"); /** - * HTML class for a text type element + * static warning * - * @author Jamie Pratt - * @access public + * overrides {@see HTML_QuickForm_static} to display staic warning. + * + * @package core_form + * @category form + * @copyright 2008 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_warning extends HTML_QuickForm_static{ + /** @var string Form element type */ var $_elementTemplateType='warning'; - /** - * html for help button, if empty then no help - * - * @var string - */ + + /** @var string html for help button, if empty then no help */ var $_helpbutton=''; + + /** @var string class assigned to field, default is notifyproblem */ var $_class=''; + /** + * constructor + * + * @param string $elementName (optional) name of the field + * @param string $elementClass (optional) show as warning or notification => 'notifyproblem' + * @param string $text (optional) Text to put in warning field + */ function MoodleQuickForm_warning($elementName=null, $elementClass='notifyproblem', $text=null) { parent::HTML_QuickForm_static($elementName, null, $text); $this->_type = 'warning'; @@ -29,14 +65,21 @@ class MoodleQuickForm_warning extends HTML_QuickForm_static{ /** * set html for help button * - * @access public - * @param array $help array of arguments to make a help button + * @param array $helpbuttonargs array of arguments to make a help button * @param string $function function name to call to get html + * @deprecated since Moodle 2.0. Please do not call this function any more. + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::setHelpButton() */ function setHelpButton($helpbuttonargs, $function='helpbutton'){ debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead'); } + /** + * Returns HTML for this form element. + * + * @return string + */ function toHtml() { global $OUTPUT; return $OUTPUT->notification($this->_text, $this->_class); @@ -45,13 +88,17 @@ class MoodleQuickForm_warning extends HTML_QuickForm_static{ /** * get html for help button * - * @access public - * @return string html for help button + * @return string html for help button */ function getHelpButton(){ return $this->_helpbutton; } + /** + * Gets the type of form element + * + * @return string + */ function getElementTemplateType(){ return $this->_elementTemplateType; } diff --git a/lib/formslib.php b/lib/formslib.php index 0f06fcff0b8..8ce3e874192 100644 --- a/lib/formslib.php +++ b/lib/formslib.php @@ -30,11 +30,9 @@ * you should be using setType for every form element except select, radio or checkbox * elements, these elements clean themselves. * - * - * @copyright Jamie Pratt - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later - * @package core - * @subpackage form + * @package core_form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); @@ -47,6 +45,9 @@ require_once 'HTML/QuickForm/Rule.php'; require_once $CFG->libdir.'/filelib.php'; +/** + * EDITOR_UNLIMITED_FILES - hard-coded value for the 'maxfiles' option + */ define('EDITOR_UNLIMITED_FILES', -1); /** @@ -65,8 +66,9 @@ if (!empty($CFG->debug) and $CFG->debug >= DEBUG_ALL){ } /** + * Initalize javascript for date type form element * - * @staticvar bool $done + * @staticvar bool $done make sure it gets initalize once. * @global moodle_page $PAGE */ function form_init_date_js() { @@ -82,35 +84,30 @@ function form_init_date_js() { } /** + * Wrapper that separates quickforms syntax from moodle code + * * Moodle specific wrapper that separates quickforms syntax from moodle code. You won't directly * use this class you should write a class definition which extends this class or a more specific * subclass such a moodleform_mod for each form you want to display and/or process with formslib. * * You will write your own definition() method which performs the form set up. * - * @package moodlecore - * @copyright Jamie Pratt + * @package core_form + * @copyright 2006 Jamie Pratt * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @todo MDL-19380 rethink the file scanning */ abstract class moodleform { - /** @var string */ + /** @var string name of the form */ protected $_formname; // form name - /** - * quickform object definition - * - * @var MoodleQuickForm MoodleQuickForm - */ + + /** @var MoodleQuickForm quickform object definition */ protected $_form; - /** - * globals workaround - * - * @var array - */ + + /** @var array globals workaround */ protected $_customdata; - /** - * definition_after_data executed flag - * @var object definition_finalized - */ + + /** @var object definition_after_data executed flag */ protected $_definition_finalized = false; /** @@ -125,18 +122,16 @@ abstract class moodleform { * like * * @param mixed $action the action attribute for the form. If empty defaults to auto detect the - * current url. If a moodle_url object then outputs params as hidden variables. - * @param array $customdata if your form defintion method needs access to data such as $course - * $cm, etc. to construct the form definition then pass it in this array. You can - * use globals for somethings. + * current url. If a moodle_url object then outputs params as hidden variables. + * @param mixed $customdata if your form defintion method needs access to data such as $course + * $cm, etc. to construct the form definition then pass it in this array. You can + * use globals for somethings. * @param string $method if you set this to anything other than 'post' then _GET and _POST will * be merged and used as incoming data to the form. * @param string $target target frame for form submission. You will rarely use this. Don't use - * it if you don't need to as the target attribute is deprecated in xhtml - * strict. + * it if you don't need to as the target attribute is deprecated in xhtml strict. * @param mixed $attributes you can pass a string of html attributes here or an array. * @param bool $editable - * @return object moodleform */ function moodleform($action=null, $customdata=null, $method='post', $target='', $attributes=null, $editable=true) { global $CFG; @@ -196,10 +191,9 @@ abstract class moodleform { * To autofocus on first form element or first element with error. * * @param string $name if this is set then the focus is forced to a field with this name - * - * @return string javascript to select form element with first error or - * first element if no errors. Use this as a parameter - * when calling print_header + * @return string javascript to select form element with first error or + * first element if no errors. Use this as a parameter + * when calling print_header */ function focus($name=NULL) { $form =& $this->_form; @@ -234,7 +228,7 @@ abstract class moodleform { * Internal method. Alters submitted data to be suitable for quickforms processing. * Must be called when the form is fully set up. * - * @param string $method + * @param string $method name of the method which alters submitted data */ function _process_submission($method) { $submission = array(); @@ -265,9 +259,7 @@ abstract class moodleform { * Internal method. Validates all old-style deprecated uploaded files. * The new way is to upload files via repository api. * - * @global object - * @global object - * @param array $files + * @param array $files list of files to be validated * @return bool|array Success or an array of errors */ function _validate_files(&$files) { @@ -358,7 +350,7 @@ abstract class moodleform { * Internal method. Validates filepicker and filemanager files if they are * set as required fields. Also, sets the error message if encountered one. * - * @return bool/array with errors + * @return bool|array with errors */ protected function validate_draft_files() { global $USER; @@ -398,7 +390,7 @@ abstract class moodleform { * * note: $slashed param removed * - * @param mixed $default_values object or array of default values + * @param stdClass|array $default_values object or array of default values */ function set_data($default_values) { if (is_object($default_values)) { @@ -408,7 +400,13 @@ abstract class moodleform { } /** - * @deprecated + * Sets file upload manager + * + * @deprecated since Moodle 2.0 Please don't used this API + * @todo MDL-31300 this api will be removed. + * @see MoodleQuickForm_filepicker + * @see MoodleQuickForm_filemanager + * @param bool $um upload manager */ function set_upload_manager($um=false) { debugging('Old file uploads can not be used any more, please use new filepicker element'); @@ -424,7 +422,10 @@ abstract class moodleform { } /** - * @staticvar bool $nosubmit + * Checks if button pressed is not for submitting the form + * + * @staticvar bool $nosubmit keeps track of no submit button + * @return bool */ function no_submit_button_pressed(){ static $nosubmit = null; // one check is enough @@ -450,7 +451,6 @@ abstract class moodleform { * Check that form data is valid. * You should almost always use this, rather than {@see validate_defined_fields} * - * @staticvar bool $validated * @return bool true if form data valid */ function is_validated() { @@ -475,9 +475,9 @@ abstract class moodleform { * for example, to selectively add new elements depending on a no_submit_button press, * but only when the form is valid when the no_submit_button is pressed, * - * @param boolean $validateonnosubmit optional, defaults to false. The default behaviour - * is NOT to validate the form when a no submit button has been pressed. - * pass true here to override this behaviour + * @param bool $validateonnosubmit optional, defaults to false. The default behaviour + * is NOT to validate the form when a no submit button has been pressed. + * pass true here to override this behaviour * * @return bool true if form data valid */ @@ -532,7 +532,7 @@ abstract class moodleform { /** * Return true if a cancel button has been pressed resulting in the form being submitted. * - * @return boolean true if a cancel button has been pressed + * @return bool true if a cancel button has been pressed */ function is_cancelled(){ $mform =& $this->_form; @@ -596,8 +596,12 @@ abstract class moodleform { /** * Save verified uploaded files into directory. Upload process can be customised from definition() - * NOTE: please use save_stored_file() or save_file() * + * @deprecated since Moodle 2.0 + * @todo MDL-31294 remove this api + * @see moodleform::save_stored_file() + * @see moodleform::save_file() + * @param string $destination path where file should be stored * @return bool Always false */ function save_files($destination) { @@ -608,9 +612,8 @@ abstract class moodleform { /** * Returns name of uploaded file. * - * @global object - * @param string $elname, first element if null - * @return mixed false in case of failure, string if ok + * @param string $elname first element if null + * @return string|bool false in case of failure, string if ok */ function get_new_filename($elname=null) { global $USER; @@ -658,7 +661,6 @@ abstract class moodleform { /** * Save file to standard filesystem * - * @global object * @param string $elname name of element * @param string $pathname full path name of file * @param bool $override override file if exists @@ -707,8 +709,8 @@ abstract class moodleform { /** * Returns a temporary file, do not forget to delete after not needed any more. * - * @param string $elname - * @return string or false + * @param string $elname name of the elmenet + * @return string|bool either string or false */ function save_temp_file($elname) { if (!$this->get_new_filename($elname)) { @@ -733,9 +735,8 @@ abstract class moodleform { * Get draft files of a form element * This is a protected method which will be used only inside moodleforms * - * @global object $USER * @param string $elname name of element - * @return array + * @return array|bool|null */ protected function get_draft_files($elname) { global $USER; @@ -765,14 +766,15 @@ abstract class moodleform { /** * Save file to local filesystem pool * - * @global object * @param string $elname name of element - * @param int $newcontextid - * @param string $newfilearea - * @param string $newfilepath - * @param string $newfilename - use specified filename, if not specified name of uploaded file used - * @param bool $overwrite - overwrite file if exists - * @param int $newuserid - new userid if required + * @param int $newcontextid id of context + * @param string $newcomponent name of the component + * @param string $newfilearea name of file area + * @param int $newitemid item id + * @param string $newfilepath path of file where it get stored + * @param string $newfilename use specified filename, if not specified name of uploaded file used + * @param bool $overwrite overwrite file if exists + * @param int $newuserid new userid if required * @return mixed stored_file object or false if error; may throw exception if duplicate found */ function save_stored_file($elname, $newcontextid, $newcomponent, $newfilearea, $newitemid, $newfilepath='/', @@ -839,9 +841,8 @@ abstract class moodleform { /** * Get content of uploaded file. * - * @global object - * @param $element name of file upload element - * @return mixed false in case of failure, string if ok + * @param string $elname name of file upload element + * @return string|bool false in case of failure, string if ok */ function get_file_content($elname) { global $USER; @@ -887,7 +888,7 @@ abstract class moodleform { } /** - * Abstract method - always override! + * Form definition. Abstract method - always override! */ protected abstract function definition(); @@ -909,14 +910,15 @@ abstract class moodleform { * @param array $data array of ("fieldname"=>value) of submitted data * @param array $files array of uploaded files "element_name"=>tmp_file_path * @return array of "element_name"=>"error_description" if there are errors, - * or an empty array if everything is OK (true allowed for backwards compatibility too). + * or an empty array if everything is OK (true allowed for backwards compatibility too). */ function validation($data, $files) { return array(); } /** - * Helper used by {@link repeat_elements()}. + * Helper used by {@see repeat_elements()}. + * * @param int $i the index of this element. * @param HTML_QuickForm_element $elementclone * @param array $namecloned array of names @@ -943,20 +945,19 @@ abstract class moodleform { * Method to add a repeating group of elements to a form. * * @param array $elementobjs Array of elements or groups of elements that are to be repeated - * @param integer $repeats no of times to repeat elements initially + * @param int $repeats no of times to repeat elements initially * @param array $options Array of options to apply to elements. Array keys are element names. - * This is an array of arrays. The second sets of keys are the option types - * for the elements : - * 'default' - default value is value - * 'type' - PARAM_* constant is value - * 'helpbutton' - helpbutton params array is value - * 'disabledif' - last three moodleform::disabledIf() - * params are value as an array + * This is an array of arrays. The second sets of keys are the option types for the elements : + * 'default' - default value is value + * 'type' - PARAM_* constant is value + * 'helpbutton' - helpbutton params array is value + * 'disabledif' - last three moodleform::disabledIf() + * params are value as an array * @param string $repeathiddenname name for hidden element storing no of repeats in this form * @param string $addfieldsname name for button to add more fields * @param int $addfieldsno how many fields to add at a time * @param string $addstring name of button, {no} is replaced by no of blanks that will be added. - * @param boolean $addbuttoninside if true, don't call closeHeaderBefore($addfieldsname). Default false. + * @param bool $addbuttoninside if true, don't call closeHeaderBefore($addfieldsname). Default false. * @return int no of repeats of element in this page */ function repeat_elements($elementobjs, $repeats, $options, $repeathiddenname, @@ -1051,11 +1052,10 @@ abstract class moodleform { /** * Adds a link/button that controls the checked state of a group of checkboxes. * - * @global object - * @param int $groupid The id of the group of advcheckboxes this element controls + * @param int $groupid The id of the group of advcheckboxes this element controls * @param string $text The text of the link. Defaults to selectallornone ("select all/none") - * @param array $attributes associative array of HTML attributes - * @param int $originalValue The original general state of the checkboxes before the user first clicks this element + * @param array $attributes associative array of HTML attributes + * @param int $originalValue The original general state of the checkboxes before the user first clicks this element */ function add_checkbox_controller($groupid, $text = null, $attributes = null, $originalValue = 0) { global $CFG; @@ -1122,7 +1122,7 @@ EOS; * check for it being pressed using is_cancelled() and redirecting if it is true before trying to * get data with get_data(). * - * @param boolean $cancel whether to show cancel button, default true + * @param bool $cancel whether to show cancel button, default true * @param string $submitlabel label for submit button, defaults to get_string('savechanges') */ function add_action_buttons($cancel = true, $submitlabel=null){ @@ -1157,11 +1157,11 @@ EOS; * $enhancement = 'smartselect'; * $options = array('selectablecategories' => true|false) * - * @since 2.0 - * @param string|element $element - * @param string $enhancement - * @param array $options - * @param array $strings + * @since Moodle 2.0 + * @param string|element $element form element for which Javascript needs to be initalized + * @param string $enhancement which init function should be called + * @param array $options options passed to javascript + * @param array $strings strings for javascript */ function init_javascript_enhancement($element, $enhancement, array $options=array(), array $strings=null) { global $PAGE; @@ -1186,6 +1186,7 @@ EOS; /** * Returns a JS module definition for the mforms JS + * * @return array */ public static function get_js_module() { @@ -1203,58 +1204,47 @@ EOS; } /** + * MoodleQuickForm implementation + * * You never extend this class directly. The class methods of this class are available from * the private $this->_form property on moodleform and its children. You generally only * call methods on this class from within abstract methods that you override on moodleform such * as definition and definition_after_data * - * @package moodlecore - * @copyright Jamie Pratt + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { - /** @var array */ + /** @var array type (PARAM_INT, PARAM_TEXT etc) of element value */ var $_types = array(); + + /** @var array dependent state for the element/'s */ var $_dependencies = array(); - /** - * Array of buttons that if pressed do not result in the processing of the form. - * - * @var array - */ + + /** @var array Array of buttons that if pressed do not result in the processing of the form. */ var $_noSubmitButtons=array(); - /** - * Array of buttons that if pressed do not result in the processing of the form. - * - * @var array - */ + + /** @var array Array of buttons that if pressed do not result in the processing of the form. */ var $_cancelButtons=array(); - /** - * Array whose keys are element names. If the key exists this is a advanced element - * - * @var array - */ + /** @var array Array whose keys are element names. If the key exists this is a advanced element */ var $_advancedElements = array(); - /** - * Whether to display advanced elements (on page load) - * - * @var boolean - */ + /** @var bool Whether to display advanced elements (on page load) */ var $_showAdvanced = null; /** * The form name is derived from the class name of the wrapper minus the trailing form - * It is a name with words joined by underscores whereas the id attribute is words joined by - * underscores. - * - * @var unknown_type + * It is a name with words joined by underscores whereas the id attribute is words joined by underscores. + * @var string */ var $_formName = ''; /** - * String with the html for hidden params passed in as part of a moodle_url object for the action. Output in the form. - * + * String with the html for hidden params passed in as part of a moodle_url + * object for the action. Output in the form. * @var string */ var $_pageparams = ''; @@ -1262,14 +1252,12 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { /** * Class constructor - same parameters as HTML_QuickForm_DHTMLRulesTableless * - * @global object - * @staticvar int $formcounter - * @param string $formName Form's name. - * @param string $method (optional)Form's method defaults to 'POST' - * @param mixed $action (optional)Form's action - string or moodle_url - * @param string $target (optional)Form's target defaults to none - * @param mixed $attributes (optional)Extra attributes for
tag - * @access public + * @staticvar int $formcounter counts number of forms + * @param string $formName Form's name. + * @param string $method Form's method defaults to 'POST' + * @param string|moodle_url $action Form's action + * @param string $target (optional)Form's target defaults to none + * @param mixed $attributes (optional)Extra attributes for tag */ function MoodleQuickForm($formName, $method, $action, $target='', $attributes=null){ global $CFG, $OUTPUT; @@ -1311,7 +1299,7 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * If you set a header element to advanced then all elements it contains will also be set as advanced. * * @param string $elementName group or element name (not the element name of something inside a group). - * @param boolean $advanced default true sets the element to advanced. False removes advanced mark. + * @param bool $advanced default true sets the element to advanced. False removes advanced mark. */ function setAdvanced($elementName, $advanced=true){ if ($advanced){ @@ -1334,7 +1322,7 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * You can get the last state of the form and possibly save it for this user by using * value 'mform_showadvanced_last' in submitted data. * - * @param boolean $showadvancedNow + * @param bool $showadvancedNow if true will show adavance elements. */ function setShowAdvanced($showadvancedNow = null){ if ($showadvancedNow === null){ @@ -1364,6 +1352,12 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { } $this->setConstants(array('mform_showadvanced_last'=>$next)); } + + /** + * Gets show advance value, if advance elements are visible it will return true else false + * + * @return bool + */ function getShowAdvanced(){ return $this->_showAdvanced; } @@ -1372,9 +1366,7 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { /** * Accepts a renderer * - * @param object $renderer HTML_QuickForm_Renderer An HTML_QuickForm_Renderer object - * @access public - * @return void + * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object */ function accept(&$renderer) { if (method_exists($renderer, 'setAdvancedElements')){ @@ -1419,7 +1411,9 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { } /** - * @param string $elementName + * Adds one or more element names that indicate the end of a fieldset + * + * @param string $elementName name of the element */ function closeHeaderBefore($elementName){ $renderer =& $this->defaultRenderer(); @@ -1431,35 +1425,28 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * clean their own data. * * @param string $elementname - * @param integer $paramtype use the constants PARAM_*. - * * PARAM_CLEAN is deprecated and you should try to use a more specific type. - * * PARAM_TEXT should be used for cleaning data that is expected to be plain text. - * It will strip all html tags. But will still let tags for multilang support - * through. - * * PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the - * html editor. Data from the editor is later cleaned before display using - * format_text() function. PARAM_RAW can also be used for data that is validated - * by some other way or printed by p() or s(). - * * PARAM_INT should be used for integers. - * * PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying - * form actions. + * @param int $paramtype defines type of data contained in element. Use the constants PARAM_*. + * {@see lib/moodlelib.php} for defined parameter types */ function setType($elementname, $paramtype) { $this->_types[$elementname] = $paramtype; } /** - * See description of setType above. This can be used to set several types at once. + * This can be used to set several types at once. * - * @param array $paramtypes + * @param array $paramtypes types of parameters. + * @see MoodleQuickForm::setType */ function setTypes($paramtypes) { $this->_types = $paramtypes + $this->_types; } /** - * @param array $submission - * @param array $files + * Updates submitted values + * + * @param array $submission submitted values + * @param array $files list of files */ function updateSubmission($submission, $files) { $this->_flagSubmitted = false; @@ -1497,6 +1484,8 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { } /** + * Returns HTML for required elements + * * @return string */ function getReqHTML(){ @@ -1504,6 +1493,8 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { } /** + * Returns HTML for advanced elements + * * @return string */ function getAdvancedHTML(){ @@ -1516,23 +1507,24 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * * note: $slashed param removed * - * @param string $elementname element name - * @param mixed $values values for that element name - * @access public - * @return void + * @param string $elementName element name + * @param mixed $defaultValue values for that element name */ function setDefault($elementName, $defaultValue){ $this->setDefaults(array($elementName=>$defaultValue)); - } // end func setDefault + } + /** * Add an array of buttons to the form - * @param array $buttons An associative array representing help button to attach to - * to the form. keys of array correspond to names of elements in form. - * @deprecated since Moodle 2.0 - use addHelpButton() call on each element manually - * @param bool $suppresscheck - * @param string $function - * @access public - */ + * + * @param array $buttons An associative array representing help button to attach to + * to the form. keys of array correspond to names of elements in form. + * @param bool $suppresscheck if true then string check will be suppressed + * @param string $function callback function to dispaly help button. + * @deprecated since Moodle 2.0 use addHelpButton() call on each element manually + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::addHelpButton() + */ function setHelpButtons($buttons, $suppresscheck=false, $function='helpbutton'){ debugging('function moodle_form::setHelpButtons() is deprecated'); @@ -1540,16 +1532,18 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { // $this->setHelpButton($elementname, $button, $suppresscheck, $function); //} } + /** - * Add a single button. + * Add a help button to element * - * @deprecated use addHelpButton() instead * @param string $elementname name of the element to add the item to - * @param array $button arguments to pass to function $function - * @param boolean $suppresscheck whether to throw an error if the element - * doesn't exist. + * @param array $buttonargs arguments to pass to function $function + * @param bool $suppresscheck whether to throw an error if the element + * doesn't exist. * @param string $function - function to generate html from the arguments in $button - * @param string $function + * @deprecated since Moodle 2.0 - use addHelpButton() call on each element manually + * @todo MDL-31047 this api will be removed. + * @see MoodleQuickForm::addHelpButton() */ function setHelpButton($elementname, $buttonargs, $suppresscheck=false, $function='helpbutton'){ global $OUTPUT; @@ -1591,13 +1585,12 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * 1/ get_string($identifier, $component) - the title of the help page * 2/ get_string($identifier.'_help', $component) - the actual help page text * - * @since 2.0 + * @since Moodle 2.0 * @param string $elementname name of the element to add the item to * @param string $identifier help string identifier without _help suffix * @param string $component component name to look the help string in * @param string $linktext optional text to display next to the icon - * @param boolean $suppresscheck set to true if the element may not exist - * @return void + * @param bool $suppresscheck set to true if the element may not exist */ function addHelpButton($elementname, $identifier, $component = 'moodle', $linktext = '', $suppresscheck = false) { global $OUTPUT; @@ -1615,7 +1608,6 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * * @param string $elname name of element * @param mixed $value - * @return void */ function setConstant($elname, $value) { $this->_constantValues = HTML_QuickForm::arrayMerge($this->_constantValues, array($elname=>$value)); @@ -1624,7 +1616,10 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { } /** - * @param string $elementList + * export submitted values + * + * @param string $elementList list of elements in form + * @return array */ function exportValues($elementList = null){ $unfiltered = array(); @@ -1663,6 +1658,7 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { return $unfiltered; } + /** * Adds a validation rule for the given field * @@ -1670,14 +1666,13 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * To validate grouped elements as separated entities, * use addGroupRule instead of addRule. * - * @param string $element Form element name - * @param string $message Message to display for invalid data - * @param string $type Rule type, use getRegisteredRules() to get types - * @param string $format (optional)Required for extra rule data - * @param string $validation (optional)Where to perform validation: "server", "client" - * @param boolean $reset Client-side validation: reset the form element to its original value if there is an error? - * @param boolean $force Force the rule to be applied, even if the target form element does not exist - * @access public + * @param string $element Form element name + * @param string $message Message to display for invalid data + * @param string $type Rule type, use getRegisteredRules() to get types + * @param string $format (optional)Required for extra rule data + * @param string $validation (optional)Where to perform validation: "server", "client" + * @param bool $reset Client-side validation: reset the form element to its original value if there is an error? + * @param bool $force Force the rule to be applied, even if the target form element does not exist */ function addRule($element, $message, $type, $format=null, $validation='server', $reset = false, $force = false) { @@ -1686,7 +1681,8 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { $this->updateAttributes(array('onsubmit' => 'try { var myValidator = validate_' . $this->_formName . '; } catch(e) { return true; } return myValidator(this);')); } - } // end func addRule + } + /** * Adds a validation rule for the given group of elements * @@ -1696,14 +1692,13 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * the same rule will be applied to all elements in the group. * Use addRule if you need to validate the group against a function. * - * @param string $group Form group name - * @param mixed $arg1 Array for multiple elements or error message string for one element - * @param string $type (optional)Rule type use getRegisteredRules() to get types - * @param string $format (optional)Required for extra rule data - * @param int $howmany (optional)How many valid elements should be in the group - * @param string $validation (optional)Where to perform validation: "server", "client" - * @param bool $reset Client-side: whether to reset the element's value to its original state if validation failed. - * @access public + * @param string $group Form group name + * @param array|string $arg1 Array for multiple elements or error message string for one element + * @param string $type (optional)Rule type use getRegisteredRules() to get types + * @param string $format (optional)Required for extra rule data + * @param int $howmany (optional)How many valid elements should be in the group + * @param string $validation (optional)Where to perform validation: "server", "client" + * @param bool $reset Client-side: whether to reset the element's value to its original state if validation failed. */ function addGroupRule($group, $arg1, $type='', $format=null, $howmany=0, $validation = 'server', $reset = false) { @@ -1724,9 +1719,8 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { $this->updateAttributes(array('onsubmit' => 'try { var myValidator = validate_' . $this->_formName . '; } catch(e) { return true; } return myValidator(this);')); } } - } // end func addGroupRule + } - // }}} /** * Returns the client side validation script * @@ -1734,8 +1728,7 @@ class MoodleQuickForm extends HTML_QuickForm_DHTMLRulesTableless { * and slightly modified to run rules per-element * Needed to override this because of an error with client side validation of grouped elements. * - * @access public - * @return string Javascript to perform validation, empty string if no 'client' rules were added + * @return string Javascript to perform validation, empty string if no 'client' rules were added */ function getValidationScript() { @@ -1935,6 +1928,10 @@ function validate_' . $this->_formName . '(frm) { '; return $js; } // end func getValidationScript + + /** + * Sets default error message + */ function _setDefaultRuleMessages(){ foreach ($this->_rules as $field => $rulesarr){ foreach ($rulesarr as $key => $rule){ @@ -1950,6 +1947,11 @@ function validate_' . $this->_formName . '(frm) { } } + /** + * Get list of attributes which have dependencies + * + * @return array + */ function getLockOptionObject(){ $result = array(); foreach ($this->_dependencies as $dependentOn => $conditions){ @@ -1979,7 +1981,9 @@ function validate_' . $this->_formName . '(frm) { } /** - * @param mixed $element + * Get names of element or elements in a group. + * + * @param HTML_QuickForm_group|element $element element group or element object * @return array */ function _getElNamesRecursive($element) { @@ -2030,8 +2034,7 @@ function validate_' . $this->_formName . '(frm) { * of the $dependentOn element is $condition (such as equal) to $value. * * @param string $elementName the name of the element which will be disabled - * @param string $dependentOn the name of the element whose state will be checked for - * condition + * @param string $dependentOn the name of the element whose state will be checked for condition * @param string $condition the condition to check * @param mixed $value used in conjunction with condition. */ @@ -2048,24 +2051,34 @@ function validate_' . $this->_formName . '(frm) { $this->_dependencies[$dependentOn][$condition][$value][] = $elementName; } + /** + * Registers button as no submit button + * + * @param string $buttonname name of the button + */ function registerNoSubmitButton($buttonname){ $this->_noSubmitButtons[]=$buttonname; } /** - * @param string $buttonname - * @return mixed + * Checks if button is a no submit button, i.e it doesn't submit form + * + * @param string $buttonname name of the button to check + * @return bool */ function isNoSubmitButton($buttonname){ return (array_search($buttonname, $this->_noSubmitButtons)!==FALSE); } /** - * @param string $buttonname + * Registers a button as cancel button + * + * @param string $addfieldsname name of the button */ function _registerCancelButton($addfieldsname){ $this->_cancelButtons[]=$addfieldsname; } + /** * Displays elements without HTML input tags. * This method is different to freeze() in that it makes sure no hidden @@ -2074,8 +2087,8 @@ function validate_' . $this->_formName . '(frm) { * * This function also removes all previously defined rules. * - * @param mixed $elementList array or string of element(s) to be frozen - * @access public + * @param string|array $elementList array or string of element(s) to be frozen + * @return object|bool if element list is not empty then return error object, else true */ function hardFreeze($elementList=null) { @@ -2111,15 +2124,15 @@ function validate_' . $this->_formName . '(frm) { } return true; } + /** * Hard freeze all elements in a form except those whose names are in $elementList or hidden elements in a form. * * This function also removes all previously defined rules of elements it freezes. * - * throws HTML_QuickForm_Error - * - * @param array $elementList array or string of element(s) not to be frozen - * @access public + * @throws HTML_QuickForm_Error + * @param array $elementList array or string of element(s) not to be frozen + * @return bool returns true */ function hardFreezeAllVisibleExcept($elementList) { @@ -2145,13 +2158,13 @@ function validate_' . $this->_formName . '(frm) { } return true; } + /** * Tells whether the form was already submitted * * This is useful since the _submitFiles and _submitValues arrays * may be completely empty after the trackSubmit value is removed. * - * @access public * @return bool */ function isSubmitted() @@ -2160,71 +2173,53 @@ function validate_' . $this->_formName . '(frm) { } } - /** + * MoodleQuickForm renderer + * * A renderer for MoodleQuickForm that only uses XHTML and CSS and no * table tags, extends PEAR class HTML_QuickForm_Renderer_Tableless * * Stylesheet is part of standard theme and should be automatically included. * - * @package moodlecore - * @copyright Jamie Pratt + * @package core_form + * @copyright 2007 Jamie Pratt * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ - /** - * Element template array - * @var array - * @access private - */ + /** @var array Element template array */ var $_elementTemplates; + /** - * Template used when opening a hidden fieldset - * (i.e. a fieldset that is opened when there is no header element) - * @var string - * @access private - */ + * Template used when opening a hidden fieldset + * (i.e. a fieldset that is opened when there is no header element) + * @var string + */ var $_openHiddenFieldsetTemplate = "\n\t
"; - /** - * Header Template string - * @var string - * @access private - */ + + /** @var string Header Template string */ var $_headerTemplate = "\n\t\t{header}\n\t\t
{advancedimg}{button}
\n\t\t"; - /** - * Template used when opening a fieldset - * @var string - * @access private - */ + /** @var string Template used when opening a fieldset */ var $_openFieldsetTemplate = "\n\t
"; - /** - * Template used when closing a fieldset - * @var string - * @access private - */ + /** @var string Template used when closing a fieldset */ var $_closeFieldsetTemplate = "\n\t\t
"; - /** - * Required Note template string - * @var string - * @access private - */ + /** @var string Required Note template string */ var $_requiredNoteTemplate = "\n\t\t
{requiredNote}
"; + /** @var array list of elements which are marked as advance and will be grouped together */ var $_advancedElements = array(); - /** - * Whether to display advanced elements (on page load) - * - * @var integer 1 means show 0 means hide - */ + /** @var int Whether to display advanced elements (on page load) 1 => show, 0 => hide */ var $_showAdvanced; + /** + * Constructor + */ function MoodleQuickForm_Renderer(){ // switch next two lines for ol li containers for form items. // $this->_elementTemplates=array('default'=>"\n\t\t".'
  • {error}
    {element}
    • '); @@ -2243,7 +2238,9 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ } /** - * @param array $elements + * Set element's as adavance element + * + * @param array $elements form elements which needs to be grouped as advance elements. */ function setAdvancedElements($elements){ $this->_advancedElements = $elements; @@ -2252,7 +2249,7 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ /** * What to do when starting the form * - * @param object $form MoodleQuickForm + * @param MoodleQuickForm $form reference of the form */ function startForm(&$form){ $this->_reqHTML = $form->getReqHTML(); @@ -2271,9 +2268,11 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ } /** + * Create advance group of elements + * * @param object $group Passed by reference - * @param mixed $required - * @param mixed $error + * @param bool $required if input is required field + * @param string $error error message to display */ function startGroup(&$group, $required, $error){ // Make sure the element has an id. @@ -2319,9 +2318,11 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ parent::startGroup($group, $required, $error); } /** - * @param object $element - * @param mixed $required - * @param mixed $error + * Renders element + * + * @param HTML_QuickForm_element $element element + * @param bool $required if input is required field + * @param string $error error message to display */ function renderElement(&$element, $required, $error){ // Make sure the element has an id. @@ -2373,8 +2374,11 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ } /** + * Called when visiting a form, after processing all form elements + * Adds required note, form attributes, validation javascript and form content. + * * @global moodle_page $PAGE - * @param object $form Passed by reference + * @param moodleform $form Passed by reference */ function finishForm(&$form){ global $PAGE; @@ -2392,9 +2396,7 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ /** * Called when visiting a header element * - * @param object $header An HTML_QuickForm_header element being visited - * @access public - * @return void + * @param HTML_QuickForm_header $header An HTML_QuickForm_header element being visited * @global moodle_page $PAGE */ function renderHeader(&$header) { @@ -2446,8 +2448,13 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ } $this->_html .= $openFieldsetTemplate . $header_html; $this->_fieldsetsOpen++; - } // end func renderHeader + } + /** + * Return Array of element names that indicate the end of a fieldset + * + * @return array + */ function getStopFieldsetElements(){ return $this->_stopFieldsetElements; } @@ -2455,16 +2462,22 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{ /** * Required elements validation + * * This class overrides QuickForm validation since it allowed space or empty tag as a value + * + * @package core_form + * @category form + * @copyright 2006 Jamie Pratt + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class MoodleQuickForm_Rule_Required extends HTML_QuickForm_Rule { /** * Checks if an element is not empty. * This is a server-side validation, it works for both text fields and editor fields * - * @param string $value Value to check - * @param mixed $options Not used yet - * @return boolean true if value is not empty + * @param string $value Value to check + * @param int|string|array $options Not used yet + * @return bool true if value is not empty */ function validate($value, $options = null) { global $CFG; @@ -2492,7 +2505,7 @@ class MoodleQuickForm_Rule_Required extends HTML_QuickForm_Rule { * This function returns Javascript code used to build client-side validation. * It checks if an element is not empty. * - * @param int $format + * @param int $format format of data which needs to be validated. * @return array */ function getValidationScript($format = null) {