From e7c71b41258be1eb4a80b3ad035ff166be4bb61c Mon Sep 17 00:00:00 2001 From: mark_story Date: Tue, 3 Feb 2009 18:48:28 +0000 Subject: [PATCH] Updating doc blocks in helpers. Helps generate cleaner API. git-svn-id: https://svn.cakephp.org/repo/branches/1.2.x.x@8014 3807eeeb-6ff5-0310-8944-8be069107fe0 --- cake/libs/view/helpers/ajax.php | 11 ++- cake/libs/view/helpers/form.php | 116 +++++++++++++++----------- cake/libs/view/helpers/html.php | 4 +- cake/libs/view/helpers/javascript.php | 15 ++-- cake/libs/view/helpers/number.php | 4 +- cake/libs/view/helpers/paginator.php | 39 ++++----- cake/libs/view/helpers/time.php | 11 +-- 7 files changed, 108 insertions(+), 92 deletions(-) diff --git a/cake/libs/view/helpers/ajax.php b/cake/libs/view/helpers/ajax.php index 82589bfb784..e8df8f75964 100644 --- a/cake/libs/view/helpers/ajax.php +++ b/cake/libs/view/helpers/ajax.php @@ -303,12 +303,11 @@ function remoteTimer($options = null) { * (all elements available in params). The options for defining callbacks is the same * as AjaxHelper::link(). * - * @param mixed $params Either a string identifying the form target, or an array of method - * parameters, including: - * - 'params' => Acts as the form target - * - 'type' => 'post' or 'get' - * - 'options' => An array containing all HTML and script options used to - * generate the form tag and Ajax request. + * @param mixed $params Either a string identifying the form target, or an array of method parameters, including: + * - 'params' => Acts as the form target + * - 'type' => 'post' or 'get' + * - 'options' => An array containing all HTML and script options used to + * generate the form tag and Ajax request. * @param array $type How form data is posted: 'get' or 'post' * @param array $options Callback/HTML options * @return string JavaScript/HTML code diff --git a/cake/libs/view/helpers/form.php b/cake/libs/view/helpers/form.php index 604f4823dda..bf23e529fbb 100644 --- a/cake/libs/view/helpers/form.php +++ b/cake/libs/view/helpers/form.php @@ -72,16 +72,18 @@ class FormHelper extends AppHelper { var $requestType = null; /** * Returns an HTML FORM element. - * + * + * Options: + * + * - 'type' Form method defaults to POST + * - 'action' The Action the form submits to. Can be a string or array, + * - 'url' The url the form submits to. Can be a string or a url array, + * - 'default' Allows for the creation of Ajax forms. + * - 'onsubmit' Used in conjunction with 'default' to create ajax forms. + * * @access public * @param string $model The model object which the form is being defined for * @param array $options - * 'type' Form method defaults to POST - * 'action' The Action the form submits to. Can be a string or array, - * 'url' The url the form submits to. Can be a string or a url array, - * 'default' Allows for the creation of Ajax forms. - * 'onsubmit' Used in conjunction with 'default' to create ajax forms. - * * @return string An formatted opening FORM tag. */ function create($model = null, $options = array()) { @@ -375,13 +377,15 @@ function isFieldError($field) { /** * Returns a formatted error message for given FORM field, NULL if no errors. * - * @param string $field A field name, like "Modelname.fieldname" - * @param mixed $text Error message or array of $options - * @param array $options Rendering options for
wrapper tag - * 'escape' bool Whether or not to html escape the contents of the error. - * 'wrap' mixed Whether or not the error message should be wrapped in a div. If a - * string, will be used as the HTML tag to use. - * 'class' string The classname for the error message + * Options: + * + * - 'escape' bool Whether or not to html escape the contents of the error. + * - 'wrap' mixed Whether or not the error message should be wrapped in a div. If a + * string, will be used as the HTML tag to use. + * - 'class' string The classname for the error message + * @param string $field A field name, like "Modelname.fieldname" + * @param mixed $text Error message or array of $options + * @param array $options Rendering options for
wrapper tag * @return string If there are errors this method returns an error message, otherwise null. * @access public */ @@ -553,17 +557,18 @@ function inputs($fields = null, $blacklist = null) { } /** * Generates a form input element complete with label and wrapper div - * + * + * Options - See each field type method for more information. + * + * - 'type' - Force the type of widget you want. e.g. ```type => 'select'``` + * - 'label' - control the label + * - 'div' - control the wrapping div element + * - 'options' - for widgets that take options e.g. radio, select + * - 'error' - control the error message that is produced + * * @param string $fieldName This should be "Modelname.fieldname" * @param array $options - Each type of input takes different options. - * See each field type method for more information. - * 'type' - Force the type of widget you want. e.g. type => 'select' - * 'label' - control the label - * 'div' - control the wrapping div element - * 'options' - for widgets that take options e.g. radio, select - * 'error' - control the error message that is produced - * - * @return string + * @return string Completed form widget */ function input($fieldName, $options = array()) { $view =& ClassRegistry::getObject('view'); @@ -824,10 +829,10 @@ function input($fieldName, $options = array()) { * * @param string $fieldName Name of a field, like this "Modelname.fieldname" * @param array $options Array of HTML attributes. - * 'value' - the value of the checkbox - * 'checked' - boolean indicate that this checkbox is checked. + * - 'value' - the value of the checkbox + * - checked' - boolean indicate that this checkbox is checked. * @todo Right now, automatically setting the 'checked' value is dependent on whether or not the - * checkbox is bound to a model. This should probably be re-evaluated in future versions. + * checkbox is bound to a model. This should probably be re-evaluated in future versions. * @return string An HTML text input element */ function checkbox($fieldName, $options = array()) { @@ -854,14 +859,16 @@ function checkbox($fieldName, $options = array()) { /** * Creates a set of radio widgets. * + * Attributes: + * + * - 'separator' - define the string in between the radio buttons + * - 'legend' - control whether or not the widget set has a fieldset & legend + * - 'value' - indicate a value that is should be checked + * - 'label' - boolean to indicate whether or not labels for widgets show be displayed + * * @param string $fieldName Name of a field, like this "Modelname.fieldname" * @param array $options Radio button options array. * @param array $attributes Array of HTML attributes. - * 'separator' - define the string in between the radio buttons - * 'legend' - control whether or not the widget set has a fieldset & legend - * 'value' - indicate a value that is should be checked - * 'label' - boolean to indicate whether or not labels for widgets show be displayed - * * @return string */ function radio($fieldName, $options = array(), $attributes = array()) { @@ -1069,11 +1076,11 @@ function button($title, $options = array()) { /** * Creates a submit button element. * - * @param string $caption The label appearing on the button OR if string contains :// or the - * extension .jpg, .jpe, .jpeg, .gif, .png use an image if the extension - * exists, AND the first character is /, image is relative to webroot, - * OR if the first character is not /, image is relative to webroot/img. - * @param array $options + * @param string $caption The label appearing on the button OR if string contains :// or the + * extension .jpg, .jpe, .jpeg, .gif, .png use an image if the extension + * exists, AND the first character is /, image is relative to webroot, + * OR if the first character is not /, image is relative to webroot/img. + * @param array $options * @return string A HTML submit button */ function submit($caption = null, $options = array()) { @@ -1135,18 +1142,21 @@ function submit($caption = null, $options = array()) { /** * Returns a formatted SELECT element. * + * Attributes: + * + * - 'showParents' - If included in the array and set to true, an additional option element + * will be added for the parent of each option group. + * - 'multiple' - show a multiple select box. If set to 'checkbox' multiple checkboxes will be + * created instead. + * * @param string $fieldName Name attribute of the SELECT * @param array $options Array of the OPTION elements (as 'value'=>'Text' pairs) to be used in the - * SELECT element + * SELECT element * @param mixed $selected The option selected by default. If null, the default value - * from POST data will be used when available. - * @param array $attributes The HTML attributes of the select element. - * 'showParents' - If included in the array and set to true, an additional option element - * will be added for the parent of each option group. - * 'multiple' - show a multiple select box. If set to 'checkbox' multiple checkboxes will be - * created instead. + * from POST data will be used when available. + * @param array $attributes The HTML attributes of the select element. * @param mixed $showEmpty If true, the empty select option is shown. If a string, - * that string is displayed as the empty element. + * that string is displayed as the empty element. * @return string Formatted SELECT element */ function select($fieldName, $options = array(), $selected = null, $attributes = array(), $showEmpty = '') { @@ -1300,11 +1310,13 @@ function year($fieldName, $minYear = null, $maxYear = null, $selected = null, $a /** * Returns a SELECT element for months. * + * Attributes: + * + * - 'monthNames' is set and false 2 digit numbers will be used instead of text. + * * @param string $fieldName Prefix name for the SELECT element * @param string $selected Option which is selected. * @param array $attributes Attributes for the select element - * 'monthNames' is set and false 2 digit numbers will be used instead of text. - * * @param boolean $showEmpty Show/hide the empty select option * @return string */ @@ -1460,16 +1472,18 @@ function meridian($fieldName, $selected = null, $attributes = array(), $showEmpt /** * Returns a set of SELECT elements for a full datetime setup: day, month and year, and then time. * + * Attributes: + * + * - 'monthNames' If set and false numbers will be used for month select instead of text. + * - 'minYear' The lowest year to use in the year select + * - 'maxYear' The maximum year to use in the year select + * - 'interval' The interval for the minutes select. Defaults to 1 + * - 'separator' The contents of the string between select elements. Defaults to '-' * @param string $fieldName Prefix name for the SELECT element * @param string $dateFormat DMY, MDY, YMD or NONE. * @param string $timeFormat 12, 24, NONE * @param string $selected Option which is selected. * @param string $attributes array of Attributes - * 'monthNames' If set and false numbers will be used for month select instead of text. - * 'minYear' The lowest year to use in the year select - * 'maxYear' The maximum year to use in the year select - * 'interval' The interval for the minutes select. Defaults to 1 - * 'separator' The contents of the string between select elements. Defaults to '-' * @param bool $showEmpty Whether or not to show an empty default value. * @return string The HTML formatted OPTION element */ diff --git a/cake/libs/view/helpers/html.php b/cake/libs/view/helpers/html.php index 706f6e6d231..86ffe6b64a8 100644 --- a/cake/libs/view/helpers/html.php +++ b/cake/libs/view/helpers/html.php @@ -531,7 +531,7 @@ function tableCells($data, $oddTrOptions = null, $evenTrOptions = null, $useCoun * * @param string $name Tag name. * @param string $text String content that will appear inside the div element. - * If null, only a start tag will be printed + * If null, only a start tag will be printed * @param array $attributes Additional HTML attributes of the DIV tag * @param boolean $escape If true, $text will be HTML-escaped * @return string The formatted tag element @@ -555,7 +555,7 @@ function tag($name, $text = null, $attributes = array(), $escape = false) { * * @param string $class CSS class name of the div element. * @param string $text String content that will appear inside the div element. - * If null, only a start tag will be printed + * If null, only a start tag will be printed * @param array $attributes Additional HTML attributes of the DIV tag * @param boolean $escape If true, $text will be HTML-escaped * @return string The formatted DIV element diff --git a/cake/libs/view/helpers/javascript.php b/cake/libs/view/helpers/javascript.php index af7e37b9edc..a316ad2277a 100644 --- a/cake/libs/view/helpers/javascript.php +++ b/cake/libs/view/helpers/javascript.php @@ -154,14 +154,15 @@ function __construct($options = array()) { * * @param string $script The JavaScript to be wrapped in SCRIPT tags. * @param array $options Set of options: - * - allowCache: boolean, designates whether this block is cacheable using the - * current cache settings. - * - safe: boolean, whether this block should be wrapped in CDATA tags. Defaults - * to helper's object configuration. - * - inline: whether the block should be printed inline, or written - * to cached for later output (i.e. $scripts_for_layout). + * - allowCache: boolean, designates whether this block is cacheable using the + * current cache settings. + * - safe: boolean, whether this block should be wrapped in CDATA tags. Defaults + * to helper's object configuration. + * - inline: whether the block should be printed inline, or written + * to cached for later output (i.e. $scripts_for_layout). + * * @return string The full SCRIPT element, with the JavaScript inside it, or null, - * if 'inline' is set to false. + * if 'inline' is set to false. */ function codeBlock($script = null, $options = array()) { if (!empty($options) && !is_array($options)) { diff --git a/cake/libs/view/helpers/number.php b/cake/libs/view/helpers/number.php index e866e5a8b56..479ef9ddd04 100644 --- a/cake/libs/view/helpers/number.php +++ b/cake/libs/view/helpers/number.php @@ -85,7 +85,7 @@ function toPercentage($number, $precision = 2) { * * @param float $number A floating point number * @param integer $options if int then places, if string then before, if (,.-) then use it - * or array with places and before keys + * or array with places and before keys * @return string formatted number * @static */ @@ -128,7 +128,7 @@ function format($number, $options = false) { * * @param float $number * @param string $currency Shortcut to default options. Valid values are 'USD', 'EUR', 'GBP', otherwise - * set at least 'before' and 'after' options. + * set at least 'before' and 'after' options. * @param array $options * @return string Number formatted as a currency. */ diff --git a/cake/libs/view/helpers/paginator.php b/cake/libs/view/helpers/paginator.php index 90b9d4b19dd..0f00be5f0eb 100644 --- a/cake/libs/view/helpers/paginator.php +++ b/cake/libs/view/helpers/paginator.php @@ -47,20 +47,21 @@ class PaginatorHelper extends AppHelper { * Holds the default options for pagination links * * The values that may be specified are: - * - $options['format'] Format of the counter. Supported formats are 'range' and 'pages' - * and custom (default). In the default mode the supplied string is - * parsed and constants are replaced by their actual values. - * Constants: %page%, %pages%, %current%, %count%, %start%, %end% . - * - $options['separator'] The separator of the actual page and number of pages (default: ' of '). - * - $options['url'] Url of the action. See Router::url() - * - $options['url']['sort'] the key that the recordset is sorted. - * - $options['url']['direction'] Direction of the sorting (default: 'asc'). - * - $options['url']['page'] Page # to display. - * - $options['model'] The name of the model. - * - $options['escape'] Defines if the title field for the link should be escaped (default: true). - * - $options['update'] DOM id of the element updated with the results of the AJAX call. + * + * - $options['format'] Format of the counter. Supported formats are 'range' and 'pages' + * and custom (default). In the default mode the supplied string is parsed and constants are replaced + * by their actual values. + * Constants: %page%, %pages%, %current%, %count%, %start%, %end% . + * - $options['separator'] The separator of the actual page and number of pages (default: ' of '). + * - $options['url'] Url of the action. See Router::url() + * - $options['url']['sort'] the key that the recordset is sorted. + * - $options['url']['direction'] Direction of the sorting (default: 'asc'). + * - $options['url']['page'] Page # to display. + * - $options['model'] The name of the model. + * - $options['escape'] Defines if the title field for the link should be escaped (default: true). + * - $options['update'] DOM id of the element updated with the results of the AJAX call. * If this key isn't specified Paginator will use plain HTML links. - * - $options['indicator'] DOM id of the element that will be shown when doing AJAX requests. + * - $options['indicator'] DOM id of the element that will be shown when doing AJAX requests. * * @var array */ @@ -83,8 +84,8 @@ function params($model = null) { /** * Sets default options for all pagination links * - * @param mixed $options Default options for pagination links. If a string is supplied - it - * is used as the DOM id element to update. See #options for list of keys. + * @param mixed $options Default options for pagination links. If a string is supplied - it + * is used as the DOM id element to update. See #options for list of keys. */ function options($options = array()) { if (is_string($options)) { @@ -129,7 +130,7 @@ function current($model = null) { * @param string $model Optional model name. Uses the default if none is specified. * @param mixed $options Options for pagination links. See #options for list of keys. * @return string The name of the key by which the recordset is being sorted, or - * null if the results are not currently sorted. + * null if the results are not currently sorted. */ function sortKey($model = null, $options = array()) { if (empty($options)) { @@ -157,7 +158,7 @@ function sortKey($model = null, $options = array()) { * @param string $model Optional model name. Uses the default if none is specified. * @param mixed $options Options for pagination links. See #options for list of keys. * @return string The direction by which the recordset is being sorted, or - * null if the results are not currently sorted. + * null if the results are not currently sorted. */ function sortDir($model = null, $options = array()) { $dir = null; @@ -208,8 +209,8 @@ function next($title = 'Next >>', $options = array(), $disabledTitle = null, $di * @param string $title Title for the link. * @param string $key The name of the key that the recordset should be sorted. * @param array $options Options for sorting link. See #options for list of keys. - * @return string A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified - * key the returned link will sort by 'desc'. + * @return string A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified + * key the returned link will sort by 'desc'. */ function sort($title, $key = null, $options = array()) { $options = array_merge(array('url' => array(), 'model' => null), $options); diff --git a/cake/libs/view/helpers/time.php b/cake/libs/view/helpers/time.php index f3ed12bed3a..ab630f728bd 100644 --- a/cake/libs/view/helpers/time.php +++ b/cake/libs/view/helpers/time.php @@ -284,12 +284,13 @@ function toRSS($dateString, $userOffset = null) { /** * Returns either a relative date or a formatted date depending * on the difference between the current time and given datetime. - * $datetime should be in a strtotime-parsable format, like MySQL's datetime datatype. + * $datetime should be in a strtotime - parsable format, like MySQL's datetime datatype. * * Options: - * 'format' => a fall back format if the relative time is longer than the duration specified by end - * 'end' => The end of relative time telling - * 'userOffset' => Users offset from GMT (in hours) + * + * - 'format' => a fall back format if the relative time is longer than the duration specified by end + * - 'end' => The end of relative time telling + * - 'userOffset' => Users offset from GMT (in hours) * * Relative dates look something like this: * 3 weeks, 4 days ago @@ -464,7 +465,7 @@ function timeAgoInWords($dateTime, $options = array()) { * * @param mixed $dateTime Datetime string (strtotime-compatible) or Unix timestamp * @param mixed $options Default format string, if timestamp is used in $dateTime, or an array of options to be passed - * on to timeAgoInWords(). + * on to timeAgoInWords(). * @return string Relative time string. * @see TimeHelper::timeAgoInWords */