adulau/cakephp2-php8
1
0
Fork 0
mirror of https://github.com/kamilwylegala/cakephp2-php8.git synced 2024-11-15 03:18:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updating doc blocks for the helpers. Unifying formatting and adding missing @access tags and fixing various formatting differences.

Browse source
This commit is contained in:
Mark Story 2010-01-25 17:59:05 -05:00
parent 134ce68dce
commit a77a064164
14 changed files with 450 additions and 268 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

160
cake/libs/view/helper.php
View file

@ -26,9 +26,8 @@
App::import('Core', 'Overloadable'); App::import('Core', 'Overloadable');
/** /**
* Backend for helpers. * Abstract base class for all other Helpers in CakePHP.
* * Provides common methods and features.
* Long description for class
* *
* @package cake * @package cake
* @subpackage cake.cake.libs.view * @subpackage cake.cake.libs.view
@ -57,11 +56,11 @@ class Helper extends Overloadable {
var $webroot = null; var $webroot = null;
/** /**
* Theme name * The current theme name if any.
* *
* @var string * @var string
*/ */
var $themeWeb = null; var $theme = null;
/** /**
* URL to current action. * URL to current action.
@ -158,8 +157,9 @@ class Helper extends Overloadable {
/** /**
* Parses tag templates into $this->tags. * Parses tag templates into $this->tags.
* *
* @param $name file name * @param $name file name inside app/config to load.
* @return array merged tags from config/$name.php * @return array merged tags from config/$name.php
* @access public
*/ */
function loadConfig($name = 'tags') { function loadConfig($name = 'tags') {
if (file_exists(CONFIGS . $name .'.php')) { if (file_exists(CONFIGS . $name .'.php')) {
@ -174,18 +174,14 @@ class Helper extends Overloadable {
/** /**
* Finds URL for specified action. * Finds URL for specified action.
* *
* Returns an URL pointing to a combination of controller and action. Param * Returns a URL pointing at the provided parameters.
* $url can be:
* + Empty - the method will find adress to actuall controller/action.
* + '/' - the method will find base URL of application.
* + A combination of controller/action - the method will find url for it.
* *
* @param mixed $url Cake-relative URL, like "/products/edit/92" or "/presidents/elect/4" * @param mixed $url Either a relative string url like `/products/view/23` or
* or an array specifying any of the following: 'controller', 'action', * an array of url parameters. Using an array for urls will allow you to leverage
* and/or 'plugin', in addition to named arguments (keyed array elements), * the reverse routing features of CakePHP.
* and standard URL arguments (indexed array elements) * @param boolean $full If true, the full base URL will be prepended to the result
* @param boolean $full If true, the full base URL will be prepended to the result
* @return string Full translated URL with base path. * @return string Full translated URL with base path.
* @access public
*/ */
function url($url = null, $full = false) { function url($url = null, $full = false) {
return h(Router::url($url, $full)); return h(Router::url($url, $full));
@ -194,19 +190,20 @@ class Helper extends Overloadable {
/** /**
* Checks if a file exists when theme is used, if no file is found default location is returned * Checks if a file exists when theme is used, if no file is found default location is returned
* *
* @param string $file * @param string $file The file to create a webroot path to.
* @return string $webPath web path to file. * @return string $webPath web path to file.
* @access public
*/ */
function webroot($file) { function webroot($file) {
$asset = explode('?', $file); $asset = explode('?', $file);
$asset[1] = isset($asset[1]) ? '?' . $asset[1] : null; $asset[1] = isset($asset[1]) ? '?' . $asset[1] : null;
$webPath = "{$this->webroot}" . $asset[0]; $webPath = "{$this->webroot}" . $asset[0];
$file = $asset[0]; $file = $asset[0];
if (!empty($this->theme)) { if (!empty($this->theme)) {
$file = trim($file, '/'); $file = trim($file, '/');
$theme = $this->theme . '/'; $theme = $this->theme . '/';
if (DS === '\\') { if (DS === '\\') {
$file = str_replace('/', '\\', $file); $file = str_replace('/', '\\', $file);
} }
@ -215,7 +212,7 @@ class Helper extends Overloadable {
$webPath = "{$this->webroot}theme/" . $theme . $asset[0]; $webPath = "{$this->webroot}theme/" . $theme . $asset[0];
} else { } else {
$viewPaths = App::path('views'); $viewPaths = App::path('views');
foreach ($viewPaths as $viewPath) { foreach ($viewPaths as $viewPath) {
$path = $viewPath . 'themed'. DS . $this->theme . DS . 'webroot' . DS . $file; $path = $viewPath . 'themed'. DS . $this->theme . DS . 'webroot' . DS . $file;
@ -233,12 +230,13 @@ class Helper extends Overloadable {
} }
/** /**
* Adds a timestamp to a file based resource based on the value of `Asset.timestamp` in * Adds a timestamp to a file based resource based on the value of `Asset.timestamp` in
* Configure. If Asset.timestamp is true and debug > 0, or Asset.timestamp == 'force' * Configure. If Asset.timestamp is true and debug > 0, or Asset.timestamp == 'force'
* a timestamp will be added. * a timestamp will be added.
* *
* @param string $path The file path to timestamp, the path must be inside WWW_ROOT * @param string $path The file path to timestamp, the path must be inside WWW_ROOT
* @return string Path with a timestamp added, or not. * @return string Path with a timestamp added, or not.
* @access public
*/ */
function assetTimestamp($path) { function assetTimestamp($path) {
$timestampEnabled = ( $timestampEnabled = (
@ -309,6 +307,7 @@ class Helper extends Overloadable {
* @param string $insertBefore String to be inserted before options. * @param string $insertBefore String to be inserted before options.
* @param string $insertAfter String to be inserted ater options. * @param string $insertAfter String to be inserted ater options.
* @return string Composed attributes. * @return string Composed attributes.
* @access public
*/ */
function _parseAttributes($options, $exclude = null, $insertBefore = ' ', $insertAfter = null) { function _parseAttributes($options, $exclude = null, $insertBefore = ' ', $insertAfter = null) {
if (is_array($options)) { if (is_array($options)) {
@ -334,6 +333,7 @@ class Helper extends Overloadable {
/** /**
* Formats an individual attribute, and returns the string value of the composed attribute. * Formats an individual attribute, and returns the string value of the composed attribute.
* Works with minimized attributes that have the same value as their name such as 'disabled' and 'checked'
* *
* @param string $key The name of the attribute to create * @param string $key The name of the attribute to create
* @param string $value The value of the attribute to create. * @param string $value The value of the attribute to create.
@ -343,7 +343,8 @@ class Helper extends Overloadable {
function __formatAttribute($key, $value, $escape = true) { function __formatAttribute($key, $value, $escape = true) {
$attribute = ''; $attribute = '';
$attributeFormat = '%s="%s"'; $attributeFormat = '%s="%s"';
$minimizedAttributes = array('compact', 'checked', 'declare', 'readonly', 'disabled', 'selected', 'defer', 'ismap', 'nohref', 'noshade', 'nowrap', 'multiple', 'noresize'); $minimizedAttributes = array('compact', 'checked', 'declare', 'readonly', 'disabled',
'selected', 'defer', 'ismap', 'nohref', 'noshade', 'nowrap', 'multiple', 'noresize');
if (is_array($value)) { if (is_array($value)) {
$value = ''; $value = '';
} }
@ -364,6 +365,7 @@ class Helper extends Overloadable {
* @param mixed $entity A field name, like "ModelName.fieldName" or "ModelName.ID.fieldName" * @param mixed $entity A field name, like "ModelName.fieldName" or "ModelName.ID.fieldName"
* @param boolean $setScope Sets the view scope to the model specified in $tagValue * @param boolean $setScope Sets the view scope to the model specified in $tagValue
* @return void * @return void
* @access public
*/ */
function setEntity($entity, $setScope = false) { function setEntity($entity, $setScope = false) {
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
@ -373,7 +375,7 @@ class Helper extends Overloadable {
} elseif (!empty($view->entityPath) && $view->entityPath == $entity) { } elseif (!empty($view->entityPath) && $view->entityPath == $entity) {
return; return;
} }
if ($entity === null) { if ($entity === null) {
$view->model = null; $view->model = null;
$view->association = null; $view->association = null;
@ -382,7 +384,7 @@ class Helper extends Overloadable {
$view->entityPath = null; $view->entityPath = null;
return; return;
} }
$view->entityPath = $entity; $view->entityPath = $entity;
$model = $view->model; $model = $view->model;
$sameScope = $hasField = false; $sameScope = $hasField = false;
@ -391,7 +393,7 @@ class Helper extends Overloadable {
if (empty($parts)) { if (empty($parts)) {
return; return;
} }
$count = count($parts); $count = count($parts);
if ($count === 1) { if ($count === 1) {
$sameScope = true; $sameScope = true;
@ -412,7 +414,7 @@ class Helper extends Overloadable {
} }
} }
} }
if (ClassRegistry::isKeySet($model)) { if (ClassRegistry::isKeySet($model)) {
$ModelObj =& ClassRegistry::getObject($model); $ModelObj =& ClassRegistry::getObject($model);
for ($i = 0; $i < $count; $i++) { for ($i = 0; $i < $count; $i++) {
@ -476,7 +478,7 @@ class Helper extends Overloadable {
break; break;
default: default:
$reverse = array_reverse($parts); $reverse = array_reverse($parts);
if ($hasField) { if ($hasField) {
$view->field = $field; $view->field = $field;
if (!is_numeric($reverse[1]) && $reverse[1] != $model) { if (!is_numeric($reverse[1]) && $reverse[1] != $model) {
@ -509,6 +511,7 @@ class Helper extends Overloadable {
* Gets the currently-used model of the rendering context. * Gets the currently-used model of the rendering context.
* *
* @return string * @return string
* @access public
*/ */
function model() { function model() {
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
@ -523,6 +526,7 @@ class Helper extends Overloadable {
* Gets the ID of the currently-used model of the rendering context. * Gets the ID of the currently-used model of the rendering context.
* *
* @return mixed * @return mixed
* @access public
*/ */
function modelID() { function modelID() {
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
@ -533,6 +537,7 @@ class Helper extends Overloadable {
* Gets the currently-used model field of the rendering context. * Gets the currently-used model field of the rendering context.
* *
* @return string * @return string
* @access public
*/ */
function field() { function field() {
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
@ -540,11 +545,12 @@ class Helper extends Overloadable {
} }
/** /**
* Returns false if given FORM field has no errors. Otherwise it returns the constant set in the array Model->validationErrors. * Returns false if given FORM field has no errors. Otherwise it returns the constant set in
* the array Model->validationErrors.
* *
* @param string $model Model name as string * @param string $model Model name as a string
* @param string $field Fieldname as string * @param string $field Fieldname as a string
* @param integer $modelID Unique index identifying this record within the form * @param integer $modelID Unique index identifying this record within the form
* @return boolean True on errors. * @return boolean True on errors.
*/ */
function tagIsInvalid($model = null, $field = null, $modelID = null) { function tagIsInvalid($model = null, $field = null, $modelID = null) {
@ -558,10 +564,14 @@ class Helper extends Overloadable {
/** /**
* Generates a DOM ID for the selected element, if one is not set. * Generates a DOM ID for the selected element, if one is not set.
* Uses the current View::entity() settings to generate a CamelCased id attribute.
* *
* @param mixed $options * @param mixed $options Either an array of html attributes to add $id into, or a string
* @param string $id * with a view entity path to get a domId for.
* @return mixed * @param string $id The name of the 'id' attribute.
* @return mixed If $options was an array, an array will be returned with $id set. If a string
* was supplied, a string will be returned.
* @todo Refactor this method to not have as many input/output options.
*/ */
function domId($options = null, $id = 'id') { function domId($options = null, $id = 'id') {
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
@ -573,10 +583,10 @@ class Helper extends Overloadable {
$this->setEntity($options); $this->setEntity($options);
return $this->domId(); return $this->domId();
} }
$entity = $view->entity(); $entity = $view->entity();
$model = array_shift($entity); $model = array_shift($entity);
$dom = $model . join('',array_map(array('Inflector','camelize'),$entity)); $dom = $model . join('', array_map(array('Inflector', 'camelize'), $entity));
if (is_array($options) && !array_key_exists($id, $options)) { if (is_array($options) && !array_key_exists($id, $options)) {
$options[$id] = $dom; $options[$id] = $dom;
@ -587,12 +597,17 @@ class Helper extends Overloadable {
} }
/** /**
* Gets the input field name for the current tag * Gets the input field name for the current tag. Creates input name attributes
* using CakePHP's data[Model][field] formatting.
* *
* @param array $options * @param mixed $options If an array, should be an array of attributes that $key needs to be added to.
* @param string $key * If a string or null, will be used as the View entity.
* @return array * @param string $field
* @param string $key The name of the attribute to be set, defaults to 'name'
* @return mixed If an array was given for $options, an array with $key set will be returned.
* If a string was supplied a string will be returned.
* @access protected * @access protected
* @todo Refactor this method to not have as many input/output options.
*/ */
function _name($options = array(), $field = null, $key = 'name') { function _name($options = array(), $field = null, $key = 'name') {
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
@ -631,10 +646,14 @@ class Helper extends Overloadable {
/** /**
* Gets the data for the current tag * Gets the data for the current tag
* *
* @param array $options * @param mixed $options If an array, should be an array of attributes that $key needs to be added to.
* @param string $key * If a string or null, will be used as the View entity.
* @return array * @param string $field
* @param string $key The name of the attribute to be set, defaults to 'value'
* @return mixed If an array was given for $options, an array with $key set will be returned.
* If a string was supplied a string will be returned.
* @access public * @access public
* @todo Refactor this method to not have as many input/output options.
*/ */
function value($options = array(), $field = null, $key = 'value') { function value($options = array(), $field = null, $key = 'value') {
if ($options === null) { if ($options === null) {
@ -647,11 +666,11 @@ class Helper extends Overloadable {
if (is_array($options) && isset($options[$key])) { if (is_array($options) && isset($options[$key])) {
return $options; return $options;
} }
if (!empty($field)) { if (!empty($field)) {
$this->setEntity($field); $this->setEntity($field);
} }
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
$result = null; $result = null;
@ -692,11 +711,13 @@ class Helper extends Overloadable {
} }
/** /**
* Sets the defaults for an input tag * Sets the defaults for an input tag. Will set the
* name, value, and id attributes for an array of html attributes. Will also
* add a 'form-error' class if the field contains validation errors.
* *
* @param array $options * @param string $field The field name to initialize.
* @param string $key * @param array $options Array of options to use while initializing an input field.
* @return array * @return array Array options for the form input.
* @access protected * @access protected
*/ */
function _initInputField($field, $options = array()) { function _initInputField($field, $options = array()) {
@ -716,10 +737,11 @@ class Helper extends Overloadable {
/** /**
* Adds the given class to the element options * Adds the given class to the element options
* *
* @param array $options * @param array $options Array options/attributes to add a class to
* @param string $class * @param string $class The classname being added.
* @param string $key * @param string $key the key to use for class.
* @return array * @return array Array of options with $key set.
* @access public
*/ */
function addClass($options = array(), $class = null, $key = 'class') { function addClass($options = array(), $class = null, $key = 'class') {
if (isset($options[$key]) && trim($options[$key]) != '') { if (isset($options[$key]) && trim($options[$key]) != '') {
@ -735,37 +757,55 @@ class Helper extends Overloadable {
* *
* This method can be overridden in subclasses to do generalized output post-processing * This method can be overridden in subclasses to do generalized output post-processing
* *
* @param string $str String to be output. * @param string $str String to be output.
* @return string * @return string
* @deprecated This method will be removed in future versions.
*/ */
function output($str) { function output($str) {
return $str; return $str;
} }
/** /**
* Before render callback. Overridden in subclasses. * Before render callback. beforeRender is called before the view file is rendered.
* *
* Overridden in subclasses.
*
* @return void
* @access public
*/ */
function beforeRender() { function beforeRender() {
} }
/** /**
* After render callback. Overridden in subclasses. * After render callback. afterRender is called after the view file is rendered
* but before the layout has been rendered.
* *
* Overridden in subclasses.
*
* @return void
* @access public
*/ */
function afterRender() { function afterRender() {
} }
/** /**
* Before layout callback. Overridden in subclasses. * Before layout callback. beforeLayout is called before the layout is rendered.
* *
* Overridden in subclasses.
*
* @return void
* @access public
*/ */
function beforeLayout() { function beforeLayout() {
} }
/** /**
* After layout callback. Overridden in subclasses. * After layout callback. afterLayout is called after the layout has rendered.
* *
* Overridden in subclasses.
*
* @return void
* @access public
*/ */
function afterLayout() { function afterLayout() {
} }
@ -801,6 +841,7 @@ class Helper extends Overloadable {
/** /**
* Resets the vars used by Helper::clean() to null * Resets the vars used by Helper::clean() to null
* *
* @return void
* @access private * @access private
*/ */
function __reset() { function __reset() {
@ -811,6 +852,7 @@ class Helper extends Overloadable {
/** /**
* Removes harmful content from output * Removes harmful content from output
* *
* @return void
* @access private * @access private
*/ */
function __clean() { function __clean() {

14
cake/libs/view/helpers/cache.php
View file

@ -61,7 +61,7 @@ class CacheHelper extends AppHelper {
* @param string $file File to cache * @param string $file File to cache
* @param string $out output to cache * @param string $out output to cache
* @param boolean $cache * @param boolean $cache
* @return view ouput * @return string view ouput
*/ */
function cache($file, $out, $cache = false) { function cache($file, $out, $cache = false) {
$cacheTime = 0; $cacheTime = 0;
@ -114,8 +114,8 @@ class CacheHelper extends AppHelper {
/** /**
* Parse file searching for no cache tags * Parse file searching for no cache tags
* *
* @param string $file * @param string $file The filename that needs to be parsed.
* @param boolean $cache * @param string $cache The cached content
* @access private * @access private
*/ */
function __parseFile($file, $cache) { function __parseFile($file, $cache) {
@ -154,7 +154,7 @@ class CacheHelper extends AppHelper {
/** /**
* Parse the output and replace cache tags * Parse the output and replace cache tags
* *
* @param sting $cache * @param string $cache Output to replace content in.
* @return string with all replacements made to <cake:nocache><cake:nocache> * @return string with all replacements made to <cake:nocache><cake:nocache>
* @access private * @access private
*/ */
@ -187,9 +187,9 @@ class CacheHelper extends AppHelper {
/** /**
* Write a cached version of the file * Write a cached version of the file
* *
* @param string $file * @param string $content view content to write to a cache file.
* @param sting $timestamp * @param sting $timestamp Duration to set for cache file.
* @return cached view * @return boolean success of caching view.
* @access private * @access private
*/ */
function __writeFile($content, $timestamp, $useCallbacks = false) { function __writeFile($content, $timestamp, $useCallbacks = false) {

126
cake/libs/view/helpers/form.php
View file

@ -76,6 +76,7 @@ class FormHelper extends AppHelper {
* The default model being used for the current form. * The default model being used for the current form.
* *
* @var string * @var string
* @access public
*/ */
var $defaultModel = null; var $defaultModel = null;
@ -147,14 +148,14 @@ class FormHelper extends AppHelper {
/** /**
* Returns an HTML FORM element. * Returns an HTML FORM element.
* *
* #### Options: * ### Options:
* *
* - `type` Form method defaults to POST * - `type` Form method defaults to POST
* - `action` The Action the form submits to. Can be a string or array, * - `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, * - `url` The url the form submits to. Can be a string or a url array,
* - `default` Allows for the creation of Ajax forms. * - `default` Allows for the creation of Ajax forms.
* - `onsubmit` Used in conjunction with 'default' to create ajax forms. * - `onsubmit` Used in conjunction with 'default' to create ajax forms.
* - `inputDefaults' set the default $options for FormHelper::input(). Any options that would * - `inputDefaults` set the default $options for FormHelper::input(). Any options that would
* be set when using FormHelper::input() can be set here. Options set with `inputDefaults` * be set when using FormHelper::input() can be set here. Options set with `inputDefaults`
* can be overridden when calling input() * can be overridden when calling input()
* - `encoding` Set the accept-charset encoding for the form. Defaults to `Configure::read('App.encoding')` * - `encoding` Set the accept-charset encoding for the form. Defaults to `Configure::read('App.encoding')`
@ -305,6 +306,7 @@ class FormHelper extends AppHelper {
* *
* {{{ * {{{
* array usage: * array usage:
*
* array('label' => 'save'); value="save" * array('label' => 'save'); value="save"
* array('label' => 'save', 'name' => 'Whatever'); value="save" name="Whatever" * array('label' => 'save', 'name' => 'Whatever'); value="save" name="Whatever"
* array('name' => 'Whatever'); value="Submit" name="Whatever" * array('name' => 'Whatever'); value="Submit" name="Whatever"
@ -387,10 +389,12 @@ class FormHelper extends AppHelper {
} }
/** /**
* Determine which fields of a form should be used for hash * Determine which fields of a form should be used for hash.
* Populates $this->fields
* *
* @param mixed $field Reference to field to be secured * @param mixed $field Reference to field to be secured
* @param mixed $value Field value, if value should not be tampered with * @param mixed $value Field value, if value should not be tampered with.
* @return void
* @access private * @access private
*/ */
function __secure($field = null, $value = null) { function __secure($field = null, $value = null) {
@ -433,12 +437,12 @@ class FormHelper extends AppHelper {
/** /**
* Returns a formatted error message for given FORM field, NULL if no errors. * Returns a formatted error message for given FORM field, NULL if no errors.
* *
* Options: * ### Options:
* *
* - 'escape' bool Whether or not to html escape the contents of the error. * - `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 * - `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. * string, will be used as the HTML tag to use.
* - 'class' string The classname for the error message * - `class` string The classname for the error message
* *
* @param string $field A field name, like "Modelname.fieldname" * @param string $field A field name, like "Modelname.fieldname"
* @param mixed $text Error message or array of $options * @param mixed $text Error message or array of $options
@ -492,7 +496,8 @@ class FormHelper extends AppHelper {
} }
/** /**
* Returns a formatted LABEL element for HTML FORMs. * Returns a formatted LABEL element for HTML FORMs. Will automatically generate
* a for attribute if one is not provided.
* *
* @param string $fieldName This should be "Modelname.fieldname" * @param string $fieldName This should be "Modelname.fieldname"
* @param string $text Text that will appear in the label field. * @param string $text Text that will appear in the label field.
@ -551,7 +556,7 @@ class FormHelper extends AppHelper {
* }}} * }}}
* *
* @param mixed $fields An array of fields to generate inputs for, or null. * @param mixed $fields An array of fields to generate inputs for, or null.
* @param array $blacklist a simple array of fields to skip. * @param array $blacklist a simple array of fields to not create inputs for.
* @return string Completed form inputs. * @return string Completed form inputs.
* @access public * @access public
*/ */
@ -632,19 +637,26 @@ class FormHelper extends AppHelper {
/** /**
* Generates a form input element complete with label and wrapper div * Generates a form input element complete with label and wrapper div
* *
* Options - See each field type method for more information. Any options that are part of * ### Options
* $attributes or $options for the different type methods can be included in $options for input(). *
* See each field type method for more information. Any options that are part of
* $attributes or $options for the different **type** methods can be included in `$options` for input().
* *
* - `type` - Force the type of widget you want. e.g. `type => 'select'` * - `type` - Force the type of widget you want. e.g. `type => 'select'`
* - `label` - control the label * - `label` - Either a string label, or an array of options for the label. See FormHelper::label()
* - `div` - control the wrapping div element * - `div` - Either `false` to disable the div, or an array of options for the div.
* See HtmlHelper::div() for more options.
* - `options` - for widgets that take options e.g. radio, select * - `options` - for widgets that take options e.g. radio, select
* - `error` - control the error message that is produced * - `error` - control the error message that is produced
* - `empty` - String or boolean to enable empty select box options. * - `empty` - String or boolean to enable empty select box options.
* - `before` - Content to place before the label + input.
* - `after` - Content to place after the label + input.
* - `between` - Content to place between the label + input.
* *
* @param string $fieldName This should be "Modelname.fieldname" * @param string $fieldName This should be "Modelname.fieldname"
* @param array $options Each type of input takes different options. * @param array $options Each type of input takes different options.
* @return string Completed form widget * @return string Completed form widget.
* @access public
*/ */
function input($fieldName, $options = array()) { function input($fieldName, $options = array()) {
$this->setEntity($fieldName); $this->setEntity($fieldName);
@ -905,16 +917,18 @@ class FormHelper extends AppHelper {
/** /**
* Creates a checkbox input widget. * Creates a checkbox input widget.
* *
* Options: * ### Options:
* *
* - `value` - the value of the checkbox * - `value` - the value of the checkbox
* - `checked` - boolean indicate that this checkbox is checked. * - `checked` - boolean indicate that this checkbox is checked.
* - `hiddenField` - boolean to indicate if you want the results of checkbox() to include * - `hiddenField` - boolean to indicate if you want the results of checkbox() to include
* a hidden input with a value of ''. * a hidden input with a value of ''.
* - `disabled` - create a disabled input.
* *
* @param string $fieldName Name of a field, like this "Modelname.fieldname" * @param string $fieldName Name of a field, like this "Modelname.fieldname"
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes.
* @return string An HTML text input element * @return string An HTML text input element.
* @access public
*/ */
function checkbox($fieldName, $options = array()) { function checkbox($fieldName, $options = array()) {
$options = $this->_initInputField($fieldName, $options) + array('hiddenField' => true); $options = $this->_initInputField($fieldName, $options) + array('hiddenField' => true);
@ -946,9 +960,10 @@ class FormHelper extends AppHelper {
} }
/** /**
* Creates a set of radio widgets. * Creates a set of radio widgets. Will create a legend and fieldset
* by default. Use $options to control this
* *
* Attributes: * ### Attributes:
* *
* - `separator` - define the string in between the radio buttons * - `separator` - define the string in between the radio buttons
* - `legend` - control whether or not the widget set has a fieldset & legend * - `legend` - control whether or not the widget set has a fieldset & legend
@ -959,8 +974,9 @@ class FormHelper extends AppHelper {
* *
* @param string $fieldName Name of a field, like this "Modelname.fieldname" * @param string $fieldName Name of a field, like this "Modelname.fieldname"
* @param array $options Radio button options array. * @param array $options Radio button options array.
* @param array $attributes Array of HTML attributes. * @param array $attributes Array of HTML attributes, and special attributes above.
* @return string * @return string Completed radio widget set.
* @access public
*/ */
function radio($fieldName, $options = array(), $attributes = array()) { function radio($fieldName, $options = array(), $attributes = array()) {
$attributes = $this->_initInputField($fieldName, $attributes); $attributes = $this->_initInputField($fieldName, $attributes);
@ -1042,7 +1058,8 @@ class FormHelper extends AppHelper {
* *
* @param string $fieldName Name of a field, in the form "Modelname.fieldname" * @param string $fieldName Name of a field, in the form "Modelname.fieldname"
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes.
* @return string An HTML text input element * @return string A generated HTML text input element
* @access public
*/ */
function text($fieldName, $options = array()) { function text($fieldName, $options = array()) {
$options = $this->_initInputField($fieldName, array_merge( $options = $this->_initInputField($fieldName, array_merge(
@ -1060,7 +1077,8 @@ class FormHelper extends AppHelper {
* *
* @param string $fieldName Name of a field, like in the form "Modelname.fieldname" * @param string $fieldName Name of a field, like in the form "Modelname.fieldname"
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes.
* @return string * @return string A generated password input.
* @access public
*/ */
function password($fieldName, $options = array()) { function password($fieldName, $options = array()) {
$options = $this->_initInputField($fieldName, $options); $options = $this->_initInputField($fieldName, $options);
@ -1074,9 +1092,14 @@ class FormHelper extends AppHelper {
/** /**
* Creates a textarea widget. * Creates a textarea widget.
* *
* ### Options:
*
* - `escape` - Whether or not the contents of the textarea should be escaped. Defaults to true.
*
* @param string $fieldName Name of a field, in the form "Modelname.fieldname" * @param string $fieldName Name of a field, in the form "Modelname.fieldname"
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes, and special options above.
* @return string An HTML text input element * @return string A generated HTML text input element
* @access public
*/ */
function textarea($fieldName, $options = array()) { function textarea($fieldName, $options = array()) {
$options = $this->_initInputField($fieldName, $options); $options = $this->_initInputField($fieldName, $options);
@ -1100,9 +1123,9 @@ class FormHelper extends AppHelper {
/** /**
* Creates a hidden input field. * Creates a hidden input field.
* *
* @param string $fieldName Name of a field, in the form"Modelname.fieldname" * @param string $fieldName Name of a field, in the form of "Modelname.fieldname"
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes.
* @return string * @return string A generated hidden input
* @access public * @access public
*/ */
function hidden($fieldName, $options = array()) { function hidden($fieldName, $options = array()) {
@ -1133,7 +1156,7 @@ class FormHelper extends AppHelper {
* *
* @param string $fieldName Name of a field, in the form "Modelname.fieldname" * @param string $fieldName Name of a field, in the form "Modelname.fieldname"
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes.
* @return string * @return string A generated file input.
* @access public * @access public
*/ */
function file($fieldName, $options = array()) { function file($fieldName, $options = array()) {
@ -1151,13 +1174,13 @@ class FormHelper extends AppHelper {
} }
/** /**
* Creates a <button> tag. * Creates a `<button>` tag.
* *
* Options: * ### Options:
* *
* - `escape` - HTML entity encode the $title of the button. Defaults to false. * - `escape` - HTML entity encode the $title of the button. Defaults to false.
* *
* @param string $title The button's caption. Not automatically HTML encoded * @param string $title The button's caption. Not automatically HTML encoded
* @param array $options Array of options and HTML attributes. * @param array $options Array of options and HTML attributes.
* @return string A HTML button tag. * @return string A HTML button tag.
* @access public * @access public
@ -1184,6 +1207,7 @@ class FormHelper extends AppHelper {
* OR if the first character is not /, image is relative to webroot/img. * OR if the first character is not /, image is relative to webroot/img.
* @param array $options * @param array $options
* @return string A HTML submit button * @return string A HTML submit button
* @access public
*/ */
function submit($caption = null, $options = array()) { function submit($caption = null, $options = array()) {
if (!$caption) { if (!$caption) {
@ -1252,7 +1276,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a formatted SELECT element. * Returns a formatted SELECT element.
* *
* Attributes: * ### Attributes:
* *
* - `showParents` - If included in the array and set to true, an additional option 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. * will be added for the parent of each option group.
@ -1260,6 +1284,7 @@ class FormHelper extends AppHelper {
* created instead. * created instead.
* - `empty` - If true, the empty select option is shown. If a string, * - `empty` - 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.
* - `escape` - If true contents of options will be HTML entity encoded. Defaults to true.
* *
* @param string $fieldName Name attribute of the SELECT * @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 * @param array $options Array of the OPTION elements (as 'value'=>'Text' pairs) to be used in the
@ -1268,6 +1293,7 @@ class FormHelper extends AppHelper {
* from POST data will be used when available. * from POST data will be used when available.
* @param array $attributes The HTML attributes of the select element. * @param array $attributes The HTML attributes of the select element.
* @return string Formatted SELECT element * @return string Formatted SELECT element
* @access public
*/ */
function select($fieldName, $options = array(), $selected = null, $attributes = array()) { function select($fieldName, $options = array(), $selected = null, $attributes = array()) {
$select = array(); $select = array();
@ -1356,7 +1382,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a SELECT element for days. * Returns a SELECT element for days.
* *
* Attributes: * ### Attributes:
* *
* - `empty` - If true, the empty select option is shown. If a string, * - `empty` - 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.
@ -1364,7 +1390,8 @@ class FormHelper extends AppHelper {
* @param string $fieldName Prefix name for the SELECT element * @param string $fieldName Prefix name for the SELECT element
* @param string $selected Option which is selected. * @param string $selected Option which is selected.
* @param array $attributes HTML attributes for the select element * @param array $attributes HTML attributes for the select element
* @return string * @return string A generated day select box.
* @access public
*/ */
function day($fieldName, $selected = null, $attributes = array()) { function day($fieldName, $selected = null, $attributes = array()) {
$attributes += array('empty' => true); $attributes += array('empty' => true);
@ -1381,7 +1408,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a SELECT element for years * Returns a SELECT element for years
* *
* Attributes: * ### Attributes:
* *
* - `empty` - If true, the empty select option is shown. If a string, * - `empty` - 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.
@ -1392,6 +1419,7 @@ class FormHelper extends AppHelper {
* @param string $selected Option which is selected. * @param string $selected Option which is selected.
* @param array $attributes Attribute array for the select elements. * @param array $attributes Attribute array for the select elements.
* @return string Completed year select input * @return string Completed year select input
* @access public
*/ */
function year($fieldName, $minYear = null, $maxYear = null, $selected = null, $attributes = array()) { function year($fieldName, $minYear = null, $maxYear = null, $selected = null, $attributes = array()) {
$attributes += array('empty' => true); $attributes += array('empty' => true);
@ -1428,7 +1456,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a SELECT element for months. * Returns a SELECT element for months.
* *
* Attributes: * ### Attributes:
* *
* - `monthNames` - If false, 2 digit numbers will be used instead of text. * - `monthNames` - If false, 2 digit numbers will be used instead of text.
* If a array, the given array will be used. * If a array, the given array will be used.
@ -1438,7 +1466,8 @@ class FormHelper extends AppHelper {
* @param string $fieldName Prefix name for the SELECT element * @param string $fieldName Prefix name for the SELECT element
* @param string $selected Option which is selected. * @param string $selected Option which is selected.
* @param array $attributes Attributes for the select element * @param array $attributes Attributes for the select element
* @return string * @return string A generated month select dropdown.
* @access public
*/ */
function month($fieldName, $selected = null, $attributes = array()) { function month($fieldName, $selected = null, $attributes = array()) {
$attributes += array('empty' => true); $attributes += array('empty' => true);
@ -1464,7 +1493,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a SELECT element for hours. * Returns a SELECT element for hours.
* *
* Attributes: * ### Attributes:
* *
* - `empty` - If true, the empty select option is shown. If a string, * - `empty` - 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.
@ -1474,6 +1503,7 @@ class FormHelper extends AppHelper {
* @param string $selected Option which is selected. * @param string $selected Option which is selected.
* @param array $attributes List of HTML attributes * @param array $attributes List of HTML attributes
* @return string Completed hour select input * @return string Completed hour select input
* @access public
*/ */
function hour($fieldName, $format24Hours = false, $selected = null, $attributes = array()) { function hour($fieldName, $format24Hours = false, $selected = null, $attributes = array()) {
$attributes += array('empty' => true); $attributes += array('empty' => true);
@ -1498,7 +1528,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a SELECT element for minutes. * Returns a SELECT element for minutes.
* *
* Attributes: * ### Attributes:
* *
* - `empty` - If true, the empty select option is shown. If a string, * - `empty` - 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.
@ -1506,7 +1536,8 @@ class FormHelper extends AppHelper {
* @param string $fieldName Prefix name for the SELECT element * @param string $fieldName Prefix name for the SELECT element
* @param string $selected Option which is selected. * @param string $selected Option which is selected.
* @param string $attributes Array of Attributes * @param string $attributes Array of Attributes
* @return string Completed minute select input * @return string Completed minute select input.
* @access public
*/ */
function minute($fieldName, $selected = null, $attributes = array()) { function minute($fieldName, $selected = null, $attributes = array()) {
$attributes += array('empty' => true); $attributes += array('empty' => true);
@ -1537,6 +1568,7 @@ class FormHelper extends AppHelper {
* @param mixed $selected The current selected value. * @param mixed $selected The current selected value.
* @param array $attributes Array of attributes, must contain 'empty' key. * @param array $attributes Array of attributes, must contain 'empty' key.
* @return string Currently selected value. * @return string Currently selected value.
* @access private
*/ */
function __dateTimeSelected($select, $fieldName, $selected, $attributes) { function __dateTimeSelected($select, $fieldName, $selected, $attributes) {
if ((empty($selected) || $selected === true) && $value = $this->value($fieldName)) { if ((empty($selected) || $selected === true) && $value = $this->value($fieldName)) {
@ -1558,7 +1590,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a SELECT element for AM or PM. * Returns a SELECT element for AM or PM.
* *
* Attributes: * ### Attributes:
* *
* - `empty` - If true, the empty select option is shown. If a string, * - `empty` - 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.
@ -1568,6 +1600,7 @@ class FormHelper extends AppHelper {
* @param string $attributes Array of Attributes * @param string $attributes Array of Attributes
* @param bool $showEmpty Show/Hide an empty option * @param bool $showEmpty Show/Hide an empty option
* @return string Completed meridian select input * @return string Completed meridian select input
* @access public
*/ */
function meridian($fieldName, $selected = null, $attributes = array()) { function meridian($fieldName, $selected = null, $attributes = array()) {
$attributes += array('empty' => true); $attributes += array('empty' => true);
@ -1598,7 +1631,7 @@ class FormHelper extends AppHelper {
/** /**
* Returns a set of SELECT elements for a full datetime setup: day, month and year, and then time. * Returns a set of SELECT elements for a full datetime setup: day, month and year, and then time.
* *
* Attributes: * ### Attributes:
* *
* - `monthNames` If false, 2 digit numbers will be used instead of text. * - `monthNames` If false, 2 digit numbers will be used instead of text.
* If a array, the given array will be used. * If a array, the given array will be used.
@ -1614,7 +1647,8 @@ class FormHelper extends AppHelper {
* @param string $timeFormat 12, 24. * @param string $timeFormat 12, 24.
* @param string $selected Option which is selected. * @param string $selected Option which is selected.
* @param string $attributes array of Attributes * @param string $attributes array of Attributes
* @return string The HTML formatted OPTION element * @return string Generated set of select boxes for the date and time formats chosen.
* @access public
*/ */
function dateTime($fieldName, $dateFormat = 'DMY', $timeFormat = '12', $selected = null, $attributes = array()) { function dateTime($fieldName, $dateFormat = 'DMY', $timeFormat = '12', $selected = null, $attributes = array()) {
$attributes += array('empty' => true); $attributes += array('empty' => true);
@ -1982,9 +2016,9 @@ class FormHelper extends AppHelper {
* *
* - `secure` - boolean whether or not the the field should be added to the security fields. * - `secure` - boolean whether or not the the field should be added to the security fields.
* *
* @param string $field * @param string $field Name of the field to initialize options for.
* @param array $options * @param array $options Array of options to append options into.
* @return array * @return array Array of options for the input.
* @access protected * @access protected
*/ */
function _initInputField($field, $options = array()) { function _initInputField($field, $options = array()) {

101
cake/libs/view/helpers/html.php
View file

@ -91,49 +91,10 @@ class HtmlHelper extends AppHelper {
'javascriptend' => '</script>' 'javascriptend' => '</script>'
); );
/**
* Base URL
*
* @var string
* @access public
*/
var $base = null;
/**
* URL to current action.
*
* @var string
* @access public
*/
var $here = null;
/**
* Parameter array.
*
* @var array
* @access public
*/
var $params = array();
/**
* Current action.
*
* @var string
* @access public
*/
var $action = null;
/**
* Enter description here...
*
* @var array
* @access public
*/
var $data = null;
/** /**
* Breadcrumbs. * Breadcrumbs.
* *
* @var array * @var array
* @access protected * @access protected
*/ */
var $_crumbs = array(); var $_crumbs = array();
@ -155,7 +116,7 @@ class HtmlHelper extends AppHelper {
/** /**
* Document type definitions * Document type definitions
* *
* @var array * @var array
* @access private * @access private
*/ */
var $__docTypes = array( var $__docTypes = array(
@ -209,7 +170,7 @@ class HtmlHelper extends AppHelper {
/** /**
* Creates a link to an external resource and handles basic meta tags * Creates a link to an external resource and handles basic meta tags
* *
* #### Options * ### Options
* *
* - `inline` Whether or not the link element should be output inline, or in scripts_for_layout. * - `inline` Whether or not the link element should be output inline, or in scripts_for_layout.
* *
@ -217,7 +178,7 @@ class HtmlHelper extends AppHelper {
* @param mixed $url The address of the external resource or string for content attribute * @param mixed $url The address of the external resource or string for content attribute
* @param array $options Other attributes for the generated tag. If the type attribute is html, * @param array $options Other attributes for the generated tag. If the type attribute is html,
* rss, atom, or icon, the mime-type is returned. * rss, atom, or icon, the mime-type is returned.
* @return string A completed <link /> element. * @return string A completed `<link />` element.
* @access public * @access public
*/ */
function meta($type, $url = null, $options = array()) { function meta($type, $url = null, $options = array()) {
@ -280,7 +241,8 @@ class HtmlHelper extends AppHelper {
/** /**
* Returns a charset META-tag. * Returns a charset META-tag.
* *
* @param string $charset The character set to be used in the meta tag. Example: "utf-8". * @param string $charset The character set to be used in the meta tag. If empty,
* The App.encoding value will be used. Example: "utf-8".
* @return string A meta tag containing the specified character set. * @return string A meta tag containing the specified character set.
* @access public * @access public
*/ */
@ -300,7 +262,7 @@ class HtmlHelper extends AppHelper {
* *
* If the $url is empty, $title is used instead. * If the $url is empty, $title is used instead.
* *
* #### Options * ### Options
* *
* - `escape` Set to false to disable escaping of title and attributes. * - `escape` Set to false to disable escaping of title and attributes.
* *
@ -308,7 +270,7 @@ class HtmlHelper extends AppHelper {
* @param mixed $url Cake-relative URL or array of URL parameters, or external URL (starts with http://) * @param mixed $url Cake-relative URL or array of URL parameters, or external URL (starts with http://)
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes.
* @param string $confirmMessage JavaScript confirmation message. * @param string $confirmMessage JavaScript confirmation message.
* @return string An <a /> element. * @return string An `<a />` element.
* @access public * @access public
*/ */
function link($title, $url = null, $options = array(), $confirmMessage = false) { function link($title, $url = null, $options = array(), $confirmMessage = false) {
@ -353,7 +315,7 @@ class HtmlHelper extends AppHelper {
/** /**
* Creates a link element for CSS stylesheets. * Creates a link element for CSS stylesheets.
* *
* #### Options * ### Options
* *
* - `inline` If set to false, the generated tag appears in the head tag of the layout. Defaults to true * - `inline` If set to false, the generated tag appears in the head tag of the layout. Defaults to true
* *
@ -418,14 +380,14 @@ class HtmlHelper extends AppHelper {
} }
/** /**
* Returns one or many <script> tags depending on the number of scripts given. * Returns one or many `<script>` tags depending on the number of scripts given.
* *
* If the filename is prefixed with "/", the path will be relative to the base path of your * If the filename is prefixed with "/", the path will be relative to the base path of your
* application. Otherwise, the path will be relative to your JavaScript path, usually webroot/js. * application. Otherwise, the path will be relative to your JavaScript path, usually webroot/js.
* *
* Can include one or many Javascript files. * Can include one or many Javascript files.
* *
* #### Options * ### Options
* *
* - `inline` - Whether script should be output inline or into scripts_for_layout. * - `inline` - Whether script should be output inline or into scripts_for_layout.
* - `once` - Whether or not the script should be checked for uniqueness. If true scripts will only be * - `once` - Whether or not the script should be checked for uniqueness. If true scripts will only be
@ -433,8 +395,9 @@ class HtmlHelper extends AppHelper {
* *
* @param mixed $url String or array of javascript files to include * @param mixed $url String or array of javascript files to include
* @param mixed $options Array of options, and html attributes see above. If boolean sets $options['inline'] = value * @param mixed $options Array of options, and html attributes see above. If boolean sets $options['inline'] = value
* @return mixed String of <script /> tags or null if $inline is false or if $once is true and the file has been * @return mixed String of `<script />` tags or null if $inline is false or if $once is true and the file has been
* included before. * included before.
* @access public
*/ */
function script($url, $options = array()) { function script($url, $options = array()) {
if (is_bool($options)) { if (is_bool($options)) {
@ -480,6 +443,7 @@ class HtmlHelper extends AppHelper {
$view->addScript($out); $view->addScript($out);
} }
} }
/** /**
* Wrap $script in a script tag. * Wrap $script in a script tag.
* *
@ -491,6 +455,7 @@ class HtmlHelper extends AppHelper {
* @param string $script The script to wrap * @param string $script The script to wrap
* @param array $options The options to use. * @param array $options The options to use.
* @return mixed string or null depending on the value of `$options['inline']` * @return mixed string or null depending on the value of `$options['inline']`
* @access public
*/ */
function scriptBlock($script, $options = array()) { function scriptBlock($script, $options = array()) {
$options += array('safe' => true, 'inline' => true); $options += array('safe' => true, 'inline' => true);
@ -508,6 +473,7 @@ class HtmlHelper extends AppHelper {
return null; return null;
} }
} }
/** /**
* Begin a script block that captures output until HtmlHelper::scriptEnd() * Begin a script block that captures output until HtmlHelper::scriptEnd()
* is called. This capturing block will capture all output between the methods * is called. This capturing block will capture all output between the methods
@ -520,6 +486,7 @@ class HtmlHelper extends AppHelper {
* *
* @param array $options Options for the code block. * @param array $options Options for the code block.
* @return void * @return void
* @access public
*/ */
function scriptStart($options = array()) { function scriptStart($options = array()) {
$options += array('safe' => true, 'inline' => true); $options += array('safe' => true, 'inline' => true);
@ -527,12 +494,14 @@ class HtmlHelper extends AppHelper {
ob_start(); ob_start();
return null; return null;
} }
/** /**
* End a Buffered section of Javascript capturing. * End a Buffered section of Javascript capturing.
* Generates a script tag inline or in `$scripts_for_layout` depending on the settings * Generates a script tag inline or in `$scripts_for_layout` depending on the settings
* used when the scriptBlock was started * used when the scriptBlock was started
* *
* @return mixed depending on the settings of scriptStart() either a script tag or null * @return mixed depending on the settings of scriptStart() either a script tag or null
* @access public
*/ */
function scriptEnd() { function scriptEnd() {
$buffer = ob_get_clean(); $buffer = ob_get_clean();
@ -540,10 +509,20 @@ class HtmlHelper extends AppHelper {
$this->_scriptBlockOptions = array(); $this->_scriptBlockOptions = array();
return $this->scriptBlock($buffer, $options); return $this->scriptBlock($buffer, $options);
} }
/** /**
* Builds CSS style data from an array of CSS properties * Builds CSS style data from an array of CSS properties
* *
* @param array $data Style data array * ### Usage:
*
* {{{
* echo $html->style(array('margin' => '10px', 'padding' => '10px'), true);
*
* // creates
* 'margin:10px;padding:10px;'
* }}}
*
* @param array $data Style data array, keys will be used as property names, values as property values.
* @param boolean $oneline Whether or not the style block should be displayed on one line. * @param boolean $oneline Whether or not the style block should be displayed on one line.
* @return string CSS styling data * @return string CSS styling data
* @access public * @access public
@ -567,7 +546,7 @@ class HtmlHelper extends AppHelper {
* *
* @param string $separator Text to separate crumbs. * @param string $separator Text to separate crumbs.
* @param string $startText This will be the first crumb, if false it defaults to first crumb in array * @param string $startText This will be the first crumb, if false it defaults to first crumb in array
* @return string * @return string Composed bread crumbs
* @access public * @access public
*/ */
function getCrumbs($separator = '&raquo;', $startText = false) { function getCrumbs($separator = '&raquo;', $startText = false) {
@ -591,10 +570,20 @@ class HtmlHelper extends AppHelper {
} }
/** /**
* Creates a formatted IMG element. If `$options['url']` is provided, an image link will be * Creates a formatted IMG element. If `$options['url']` is provided, an image link will be
* generated with the link pointed at `$options['url']`. This method will set an empty * generated with the link pointed at `$options['url']`. This method will set an empty
* alt attribute if one is not supplied. * alt attribute if one is not supplied.
* *
* ### Usage
*
* Create a regular image:
*
* `echo $html->image('cake_icon.png', array('alt' => 'CakePHP'));`
*
* Create an image link:
*
* `echo $html->image('cake_icon.png', array('alt' => 'CakePHP', 'url' => 'http://cakephp.org'));`
*
* @param string $path Path to the image file, relative to the app/webroot/img/ directory. * @param string $path Path to the image file, relative to the app/webroot/img/ directory.
* @param array $options Array of HTML attributes. * @param array $options Array of HTML attributes.
* @return string completed img tag * @return string completed img tag
@ -702,7 +691,7 @@ class HtmlHelper extends AppHelper {
/** /**
* Returns a formatted block tag, i.e DIV, SPAN, P. * Returns a formatted block tag, i.e DIV, SPAN, P.
* *
* #### Options * ### Options
* *
* - `escape` Whether or not the contents should be html_entity escaped. * - `escape` Whether or not the contents should be html_entity escaped.
* *
@ -732,7 +721,7 @@ class HtmlHelper extends AppHelper {
/** /**
* Returns a formatted DIV tag for HTML FORMs. * Returns a formatted DIV tag for HTML FORMs.
* *
* #### Options * ### Options
* *
* - `escape` Whether or not the contents should be html_entity escaped. * - `escape` Whether or not the contents should be html_entity escaped.
* *
@ -753,7 +742,7 @@ class HtmlHelper extends AppHelper {
/** /**
* Returns a formatted P tag. * Returns a formatted P tag.
* *
* #### Options * ### Options
* *
* - `escape` Whether or not the contents should be html_entity escaped. * - `escape` Whether or not the contents should be html_entity escaped.
* *

34
cake/libs/view/helpers/jquery_engine.php
View file

@ -4,12 +4,14 @@
* *
* Provides jQuery specific Javascript for JsHelper. * Provides jQuery specific Javascript for JsHelper.
* *
* Implements the JsHelper interface for jQuery. All $options arrays
* support all options found in the JsHelper, as well as those in the jQuery
* documentation.
*
* PHP versions 4 and 5 * PHP versions 4 and 5
* *
* CakePHP : Rapid Development Framework <http://www.cakephp.org/> * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
* Copyright 2006-2009, Cake Software Foundation, Inc. * Copyright 2005-2009, Cake Software Foundation, Inc. (http://cakefoundation.org)
* 1785 E. Sahara Avenue, Suite 490-204
* Las Vegas, Nevada 89104
* *
* Licensed under The MIT License * Licensed under The MIT License
* Redistributions of files must retain the above copyright notice. * Redistributions of files must retain the above copyright notice.
@ -27,6 +29,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* Option mappings for jQuery * Option mappings for jQuery
* *
* @var array * @var array
* @access protected
*/ */
var $_optionMap = array( var $_optionMap = array(
'request' => array( 'request' => array(
@ -52,9 +55,10 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
); );
/** /**
* callback arguments lists * Callback arguments lists
* *
* @var string * @var string
* @access protected
*/ */
var $_callbackArguments = array( var $_callbackArguments = array(
'slider' => array( 'slider' => array(
@ -103,6 +107,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* when jQuery is put into noConflict() mode. * when jQuery is put into noConflict() mode.
* *
* @var string * @var string
* @access public
*/ */
var $jQueryObject = '$'; var $jQueryObject = '$';
@ -114,8 +119,8 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* @param string $selection the selection to apply * @param string $selection the selection to apply
* @param string $options Array of options for method * @param string $options Array of options for method
* @param string $callbacks Array of callback / special options. * @param string $callbacks Array of callback / special options.
* @return string Composed method string
* @access public * @access public
* @return string
*/ */
function _methodTemplate($method, $template, $options, $extraSafeKeys = array()) { function _methodTemplate($method, $template, $options, $extraSafeKeys = array()) {
$options = $this->_mapOptions($method, $options); $options = $this->_mapOptions($method, $options);
@ -133,6 +138,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* *
* @param string $selector The selector that is targeted * @param string $selector The selector that is targeted
* @return object instance of $this. Allows chained methods. * @return object instance of $this. Allows chained methods.
* @access public
*/ */
function get($selector) { function get($selector) {
if ($selector == 'window' || $selector == 'document') { if ($selector == 'window' || $selector == 'document') {
@ -155,6 +161,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* @param string $callback The Javascript function you wish to trigger or the function literal * @param string $callback The Javascript function you wish to trigger or the function literal
* @param array $options Options for the event. * @param array $options Options for the event.
* @return string completed event handler * @return string completed event handler
* @access public
*/ */
function event($type, $callback, $options = array()) { function event($type, $callback, $options = array()) {
$defaults = array('wrap' => true, 'stop' => true); $defaults = array('wrap' => true, 'stop' => true);
@ -171,10 +178,11 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
} }
/** /**
* Create a domReady event. This is a special event in many libraries * Create a domReady event. For jQuery
* *
* @param string $functionBody The code to run on domReady * @param string $functionBody The code to run on domReady
* @return string completed domReady method * @return string completed domReady method
* @access public
*/ */
function domReady($functionBody) { function domReady($functionBody) {
$this->get('document'); $this->get('document');
@ -187,6 +195,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* @param string $method The method you want to apply to the selection * @param string $method The method you want to apply to the selection
* @param string $callback The function body you wish to apply during the iteration. * @param string $callback The function body you wish to apply during the iteration.
* @return string completed iteration * @return string completed iteration
* @access public
*/ */
function each($callback) { function each($callback) {
return $this->selection . '.each(function () {' . $callback . '});'; return $this->selection . '.each(function () {' . $callback . '});';
@ -198,6 +207,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* @param string $name The name of the effect to trigger. * @param string $name The name of the effect to trigger.
* @param array $options Array of options for the effect. * @param array $options Array of options for the effect.
* @return string completed string with effect. * @return string completed string with effect.
* @access public
* @see JsBaseEngineHelper::effect() * @see JsBaseEngineHelper::effect()
*/ */
function effect($name, $options = array()) { function effect($name, $options = array()) {
@ -228,8 +238,9 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* If the 'update' key is set, success callback will be overridden. * If the 'update' key is set, success callback will be overridden.
* *
* @param mixed $url * @param mixed $url
* @param array $options * @param array $options See JsHelper::request() for options.
* @return string The completed ajax call. * @return string The completed ajax call.
* @access public
*/ */
function request($url, $options = array()) { function request($url, $options = array()) {
$url = $this->url($url); $url = $this->url($url);
@ -266,6 +277,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the sortable. * @param array $options Array of options for the sortable.
* @return string Completed sortable script. * @return string Completed sortable script.
* @access public
* @see JsHelper::sortable() for options list. * @see JsHelper::sortable() for options list.
*/ */
function sortable($options = array()) { function sortable($options = array()) {
@ -280,6 +292,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the draggable element. * @param array $options Array of options for the draggable element.
* @return string Completed Draggable script. * @return string Completed Draggable script.
* @access public
* @see JsHelper::drag() for options list. * @see JsHelper::drag() for options list.
*/ */
function drag($options = array()) { function drag($options = array()) {
@ -294,6 +307,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the droppable element. * @param array $options Array of options for the droppable element.
* @return string Completed Droppable script. * @return string Completed Droppable script.
* @access public
* @see JsHelper::drop() for options list. * @see JsHelper::drop() for options list.
*/ */
function drop($options = array()) { function drop($options = array()) {
@ -308,6 +322,7 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the droppable element. * @param array $options Array of options for the droppable element.
* @return string Completed Slider script. * @return string Completed Slider script.
* @access public
* @see JsHelper::slider() for options list. * @see JsHelper::slider() for options list.
*/ */
function slider($options = array()) { function slider($options = array()) {
@ -321,7 +336,8 @@ class JqueryEngineHelper extends JsBaseEngineHelper {
* form, errors will be created in the Javascript. * form, errors will be created in the Javascript.
* *
* @param array $options Options for the serialization * @param array $options Options for the serialization
* @return string completed form serialization script * @return string completed form serialization script.
* @access public
* @see JsHelper::serializeForm() for option list. * @see JsHelper::serializeForm() for option list.
*/ */
function serializeForm($options = array()) { function serializeForm($options = array()) {

51
cake/libs/view/helpers/js.php
View file

@ -57,6 +57,7 @@ class JsHelper extends AppHelper {
* Scripts that are queued for output * Scripts that are queued for output
* *
* @var array * @var array
* @see JsHelper::buffer()
* @access private * @access private
*/ */
var $__bufferedScripts = array(); var $__bufferedScripts = array();
@ -186,7 +187,7 @@ class JsHelper extends AppHelper {
* caches them to a file and returns a linked script. If no scripts have been * caches them to a file and returns a linked script. If no scripts have been
* buffered this method will return null * buffered this method will return null
* *
* Options * ### Options
* *
* - `inline` - Set to true to have scripts output as a script block inline * - `inline` - Set to true to have scripts output as a script block inline
* if `cache` is also true, a script link tag will be generated. (default true) * if `cache` is also true, a script link tag will be generated. (default true)
@ -198,6 +199,7 @@ class JsHelper extends AppHelper {
* @param array $options options for the code block * @param array $options options for the code block
* @return mixed Completed javascript tag if there are scripts, if there are no buffered * @return mixed Completed javascript tag if there are scripts, if there are no buffered
* scripts null will be returned. * scripts null will be returned.
* @access public
*/ */
function writeBuffer($options = array()) { function writeBuffer($options = array()) {
$defaults = array('onDomReady' => true, 'inline' => true, 'cache' => false, 'clear' => true, 'safe' => true); $defaults = array('onDomReady' => true, 'inline' => true, 'cache' => false, 'clear' => true, 'safe' => true);
@ -230,7 +232,7 @@ class JsHelper extends AppHelper {
} }
/** /**
* Write a script to the cached scripts. * Write a script to the buffered scripts.
* *
* @param string $script Script string to add to the buffer. * @param string $script Script string to add to the buffer.
* @param boolean $top If true the script will be added to the top of the * @param boolean $top If true the script will be added to the top of the
@ -247,7 +249,7 @@ class JsHelper extends AppHelper {
} }
/** /**
* Get all the cached scripts * Get all the buffered scripts
* *
* @param boolean $clear Whether or not to clear the script caches (default true) * @param boolean $clear Whether or not to clear the script caches (default true)
* @return array Array of scripts added to the request. * @return array Array of scripts added to the request.
@ -266,8 +268,8 @@ class JsHelper extends AppHelper {
/** /**
* Generates the object string for variables passed to javascript. * Generates the object string for variables passed to javascript.
* *
* @return string * @return string Generated JSON object of all set vars
* @access public * @access protected
*/ */
function _createVars() { function _createVars() {
if (!empty($this->__jsVars)) { if (!empty($this->__jsVars)) {
@ -354,7 +356,7 @@ class JsHelper extends AppHelper {
* both those for FormHelper::submit() and JsBaseEngine::request(), JsBaseEngine::event(); * both those for FormHelper::submit() and JsBaseEngine::request(), JsBaseEngine::event();
* *
* Forms submitting with this method, cannot send files. Files do not transfer over XmlHttpRequest * Forms submitting with this method, cannot send files. Files do not transfer over XmlHttpRequest
* and require an iframe. * and require an iframe or flash.
* *
* @param string $title The display text of the submit button. * @param string $title The display text of the submit button.
* @param array $options Array of options to use. * @param array $options Array of options to use.
@ -402,7 +404,7 @@ class JsHelper extends AppHelper {
* @param array $options Options to filter. * @param array $options Options to filter.
* @param array $additional Array of additional keys to extract and include in the return options array. * @param array $additional Array of additional keys to extract and include in the return options array.
* @return array Array of js options and Htmloptions * @return array Array of js options and Htmloptions
* @access public * @access protected
*/ */
function _getHtmlOptions($options, $additional = array()) { function _getHtmlOptions($options, $additional = array()) {
$htmlKeys = array_merge(array('class', 'id', 'escape', 'onblur', 'onfocus', 'rel', 'title'), $additional); $htmlKeys = array_merge(array('class', 'id', 'escape', 'onblur', 'onfocus', 'rel', 'title'), $additional);
@ -482,7 +484,7 @@ class JsBaseEngineHelper extends AppHelper {
} }
/** /**
* Create an alert message in Javascript * Create an `alert()` message in Javascript
* *
* @param string $message Message you want to alter. * @param string $message Message you want to alter.
* @return string completed alert() * @return string completed alert()
@ -493,10 +495,11 @@ class JsBaseEngineHelper extends AppHelper {
} }
/** /**
* Redirects to a URL * Redirects to a URL. Creates a window.location modification snippet
* that can be used to trigger 'redirects' from Javascript.
* *
* @param mixed $url * @param mixed $url
* @param array $options * @param array $options
* @return string completed redirect in javascript * @return string completed redirect in javascript
* @access public * @access public
*/ */
@ -505,7 +508,7 @@ class JsBaseEngineHelper extends AppHelper {
} }
/** /**
* Create a confirm() message * Create a `confirm()` message
* *
* @param string $message Message you want confirmed. * @param string $message Message you want confirmed.
* @return string completed confirm() * @return string completed confirm()
@ -530,7 +533,7 @@ class JsBaseEngineHelper extends AppHelper {
} }
/** /**
* Create a prompt() Javascript function * Create a `prompt()` Javascript function
* *
* @param string $message Message you want to prompt. * @param string $message Message you want to prompt.
* @param string $default Default message * @param string $default Default message
@ -545,7 +548,7 @@ class JsBaseEngineHelper extends AppHelper {
* Generates a JavaScript object in JavaScript Object Notation (JSON) * Generates a JavaScript object in JavaScript Object Notation (JSON)
* from an array. Will use native JSON encode method if available, and $useNative == true * from an array. Will use native JSON encode method if available, and $useNative == true
* *
* Options: * ### Options:
* *
* - `prefix` - String prepended to the returned data. * - `prefix` - String prepended to the returned data.
* - `postfix` - String appended to the returned data. * - `postfix` - String appended to the returned data.
@ -647,9 +650,9 @@ class JsBaseEngineHelper extends AppHelper {
* *
* List of escaped elements: * List of escaped elements:
* *
* + "\r" => '\n' * - "\r" => '\n'
* + "\n" => '\n' * - "\n" => '\n'
* + '"' => '\"' * - '"' => '\"'
* *
* @param string $script String that needs to get escaped. * @param string $script String that needs to get escaped.
* @return string Escaped string. * @return string Escaped string.
@ -812,7 +815,7 @@ class JsBaseEngineHelper extends AppHelper {
* *
* ### Supported Effects * ### Supported Effects
* *
* The following effects are supported by all JsEngines * The following effects are supported by all core JsEngines
* *
* - `show` - reveal an element. * - `show` - reveal an element.
* - `hide` - hide an element. * - `hide` - hide an element.
@ -867,7 +870,7 @@ class JsBaseEngineHelper extends AppHelper {
/** /**
* Create a draggable element. Works on the currently selected element. * Create a draggable element. Works on the currently selected element.
* Additional options may be supported by your library. * Additional options may be supported by the library implementation.
* *
* ### Options * ### Options
* *
@ -891,7 +894,7 @@ class JsBaseEngineHelper extends AppHelper {
/** /**
* Create a droppable element. Allows for draggable elements to be dropped on it. * Create a droppable element. Allows for draggable elements to be dropped on it.
* Additional options may be supported by your library. * Additional options may be supported by the library implementation.
* *
* ### Options * ### Options
* *
@ -913,6 +916,7 @@ class JsBaseEngineHelper extends AppHelper {
/** /**
* Create a sortable element. * Create a sortable element.
* Additional options may be supported by the library implementation.
* *
* ### Options * ### Options
* *
@ -937,7 +941,8 @@ class JsBaseEngineHelper extends AppHelper {
} }
/** /**
* Create a slider UI widget. Comprised of a track and knob * Create a slider UI widget. Comprised of a track and knob.
* Additional options may be supported by the library implementation.
* *
* ### Options * ### Options
* *
@ -984,11 +989,11 @@ class JsBaseEngineHelper extends AppHelper {
/** /**
* Parse an options assoc array into an Javascript object literal. * Parse an options assoc array into an Javascript object literal.
* Similar to object() but treats any non-integer value as a string, * Similar to object() but treats any non-integer value as a string,
* does not include { } * does not include `{ }`
* *
* @param array $options Options to be converted * @param array $options Options to be converted
* @param array $safeKeys Keys that should not be escaped. * @param array $safeKeys Keys that should not be escaped.
* @return string * @return string Parsed JSON options without enclosing { }.
* @access protected * @access protected
*/ */
function _parseOptions($options, $safeKeys = array()) { function _parseOptions($options, $safeKeys = array()) {

10
cake/libs/view/helpers/number.php
View file

@ -66,9 +66,10 @@ class NumberHelper extends AppHelper {
/** /**
* Formats a number with a level of precision. * Formats a number with a level of precision.
* *
* @param float $number A floating point number. * @param float $number A floating point number.
* @param integer $precision The precision of the returned number. * @param integer $precision The precision of the returned number.
* @return float Enter description here... * @return float Enter description here...
* @access public
*/ */
function precision($number, $precision = 3) { function precision($number, $precision = 3) {
return sprintf("%01.{$precision}f", $number); return sprintf("%01.{$precision}f", $number);
@ -79,6 +80,7 @@ class NumberHelper extends AppHelper {
* *
* @param integer $length Size in bytes * @param integer $length Size in bytes
* @return string Human readable size * @return string Human readable size
* @access public
*/ */
function toReadableSize($size) { function toReadableSize($size) {
switch (true) { switch (true) {
@ -101,6 +103,7 @@ class NumberHelper extends AppHelper {
* @param float $number A floating point number * @param float $number A floating point number
* @param integer $precision The precision of the returned number * @param integer $precision The precision of the returned number
* @return string Percentage string * @return string Percentage string
* @access public
*/ */
function toPercentage($number, $precision = 2) { function toPercentage($number, $precision = 2) {
return $this->precision($number, $precision) . '%'; return $this->precision($number, $precision) . '%';
@ -113,6 +116,7 @@ class NumberHelper extends AppHelper {
* @param integer $options if int then places, if string then before, if (,.-) then use it * @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 * @return string formatted number
* @access public
*/ */
function format($number, $options = false) { function format($number, $options = false) {
$places = 0; $places = 0;
@ -169,6 +173,7 @@ class NumberHelper extends AppHelper {
* set at least 'before' and 'after' options. * set at least 'before' and 'after' options.
* @param array $options * @param array $options
* @return string Number formatted as a currency. * @return string Number formatted as a currency.
* @access public
*/ */
function currency($number, $currency = 'USD', $options = array()) { function currency($number, $currency = 'USD', $options = array()) {
$default = $this->_currencyDefaults; $default = $this->_currencyDefaults;
@ -237,6 +242,7 @@ class NumberHelper extends AppHelper {
* @param array $options The array of options for this format. * @param array $options The array of options for this format.
* @return void * @return void
* @see NumberHelper::currency() * @see NumberHelper::currency()
* @access public
*/ */
function addFormat($formatName, $options) { function addFormat($formatName, $options) {
$this->_currencies[$formatName] = $options + $this->_currencyDefaults; $this->_currencies[$formatName] = $options + $this->_currencyDefaults;

51
cake/libs/view/helpers/paginator.php
View file

@ -67,9 +67,11 @@ class PaginatorHelper extends AppHelper {
* - `$options['escape']` Defines if the title field for the link should be escaped (default: true). * - `$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['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. * 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. **Only supported by
* AjaxHelper**
* *
* @var array * @var array
* @access public
*/ */
var $options = array(); var $options = array();
@ -98,6 +100,9 @@ class PaginatorHelper extends AppHelper {
/** /**
* Before render callback. Overridden to merge passed args with url options. * Before render callback. Overridden to merge passed args with url options.
*
* @return void
* @access public
*/ */
function beforeRender() { function beforeRender() {
$this->options['url'] = array_merge($this->params['pass'], $this->params['named']); $this->options['url'] = array_merge($this->params['pass'], $this->params['named']);
@ -110,6 +115,7 @@ class PaginatorHelper extends AppHelper {
* *
* @param string $model Optional model name. Uses the default if none is specified. * @param string $model Optional model name. Uses the default if none is specified.
* @return array The array of paging parameters for the paginated resultset. * @return array The array of paging parameters for the paginated resultset.
* @access public
*/ */
function params($model = null) { function params($model = null) {
if (empty($model)) { if (empty($model)) {
@ -125,7 +131,9 @@ class PaginatorHelper extends AppHelper {
* Sets default options for all pagination links * Sets default options for all pagination links
* *
* @param mixed $options Default options for pagination links. If a string is supplied - it * @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. * is used as the DOM id element to update. See PaginatorHelper::$options for list of keys.
* @return void
* @access public
*/ */
function options($options = array()) { function options($options = array()) {
if (is_string($options)) { if (is_string($options)) {
@ -158,6 +166,7 @@ class PaginatorHelper extends AppHelper {
* *
* @param string $model Optional model name. Uses the default if none is specified. * @param string $model Optional model name. Uses the default if none is specified.
* @return string The current page number of the recordset. * @return string The current page number of the recordset.
* @access public
*/ */
function current($model = null) { function current($model = null) {
$params = $this->params($model); $params = $this->params($model);
@ -175,6 +184,7 @@ class PaginatorHelper extends AppHelper {
* @param mixed $options Options for pagination links. See #options for list of keys. * @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 * @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.
* @access public
*/ */
function sortKey($model = null, $options = array()) { function sortKey($model = null, $options = array()) {
if (empty($options)) { if (empty($options)) {
@ -207,6 +217,7 @@ class PaginatorHelper extends AppHelper {
* @param mixed $options Options for pagination links. See #options for list of keys. * @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 * @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.
* @access public
*/ */
function sortDir($model = null, $options = array()) { function sortDir($model = null, $options = array()) {
$dir = null; $dir = null;
@ -231,7 +242,7 @@ class PaginatorHelper extends AppHelper {
/** /**
* Generates a "previous" link for a set of paged records * Generates a "previous" link for a set of paged records
* *
* Options: * ### Options:
* *
* - `tag` The tag wrapping tag you want to use, defaults to 'span' * - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `escape` Whether you want the contents html entity encoded, defaults to true * - `escape` Whether you want the contents html entity encoded, defaults to true
@ -242,6 +253,7 @@ class PaginatorHelper extends AppHelper {
* @param string $disabledTitle Title when the link is disabled. * @param string $disabledTitle Title when the link is disabled.
* @param mixed $disabledOptions Options for the disabled pagination link. See #options for list of keys. * @param mixed $disabledOptions Options for the disabled pagination link. See #options for list of keys.
* @return string A "previous" link or $disabledTitle text if the link is disabled. * @return string A "previous" link or $disabledTitle text if the link is disabled.
* @access public
*/ */
function prev($title = '<< Previous', $options = array(), $disabledTitle = null, $disabledOptions = array()) { function prev($title = '<< Previous', $options = array(), $disabledTitle = null, $disabledOptions = array()) {
return $this->__pagingLink('Prev', $title, $options, $disabledTitle, $disabledOptions); return $this->__pagingLink('Prev', $title, $options, $disabledTitle, $disabledOptions);
@ -250,7 +262,7 @@ class PaginatorHelper extends AppHelper {
/** /**
* Generates a "next" link for a set of paged records * Generates a "next" link for a set of paged records
* *
* Options: * ### Options:
* *
* - `tag` The tag wrapping tag you want to use, defaults to 'span' * - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `escape` Whether you want the contents html entity encoded, defaults to true * - `escape` Whether you want the contents html entity encoded, defaults to true
@ -261,6 +273,7 @@ class PaginatorHelper extends AppHelper {
* @param string $disabledTitle Title when the link is disabled. * @param string $disabledTitle Title when the link is disabled.
* @param mixed $disabledOptions Options for the disabled pagination link. See above for list of keys. * @param mixed $disabledOptions Options for the disabled pagination link. See above for list of keys.
* @return string A "next" link or or $disabledTitle text if the link is disabled. * @return string A "next" link or or $disabledTitle text if the link is disabled.
* @access public
*/ */
function next($title = 'Next >>', $options = array(), $disabledTitle = null, $disabledOptions = array()) { function next($title = 'Next >>', $options = array(), $disabledTitle = null, $disabledOptions = array()) {
return $this->__pagingLink('Next', $title, $options, $disabledTitle, $disabledOptions); return $this->__pagingLink('Next', $title, $options, $disabledTitle, $disabledOptions);
@ -270,7 +283,7 @@ class PaginatorHelper extends AppHelper {
* Generates a sorting link. Sets named parameters for the sort and direction. Handles * Generates a sorting link. Sets named parameters for the sort and direction. Handles
* direction switching automatically. * direction switching automatically.
* *
* Options: * ### Options:
* *
* - `escape` Whether you want the contents html entity encoded, defaults to true * - `escape` Whether you want the contents html entity encoded, defaults to true
* - `model` The model to use, defaults to PaginatorHelper::defaultModel() * - `model` The model to use, defaults to PaginatorHelper::defaultModel()
@ -281,6 +294,7 @@ class PaginatorHelper extends AppHelper {
* @param array $options Options for sorting link. See above for list of keys. * @param array $options Options for sorting link. See above for list of keys.
* @return string A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified * @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'. * key the returned link will sort by 'desc'.
* @access public
*/ */
function sort($title, $key = null, $options = array()) { function sort($title, $key = null, $options = array()) {
$options = array_merge(array('url' => array(), 'model' => null), $options); $options = array_merge(array('url' => array(), 'model' => null), $options);
@ -317,7 +331,7 @@ class PaginatorHelper extends AppHelper {
/** /**
* Generates a plain or Ajax link with pagination parameters * Generates a plain or Ajax link with pagination parameters
* *
* Options * ### Options
* *
* - `update` The Id of the DOM element you wish to update. Creates Ajax enabled links * - `update` The Id of the DOM element you wish to update. Creates Ajax enabled links
* with the AjaxHelper. * with the AjaxHelper.
@ -328,6 +342,7 @@ class PaginatorHelper extends AppHelper {
* @param mixed $url Url for the action. See Router::url() * @param mixed $url Url for the action. See Router::url()
* @param array $options Options for the link. See #options for list of keys. * @param array $options Options for the link. See #options for list of keys.
* @return string A link with pagination parameters. * @return string A link with pagination parameters.
* @access public
*/ */
function link($title, $url = array(), $options = array()) { function link($title, $url = array(), $options = array()) {
$options = array_merge(array('model' => null, 'escape' => true), $options); $options = array_merge(array('model' => null, 'escape' => true), $options);
@ -356,6 +371,7 @@ class PaginatorHelper extends AppHelper {
* @param boolean $asArray Return the url as an array, or a URI string * @param boolean $asArray Return the url as an array, or a URI string
* @param string $model Which model to paginate on * @param string $model Which model to paginate on
* @return mixed By default, returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript) * @return mixed By default, returns a full pagination URL string for use in non-standard contexts (i.e. JavaScript)
* @access public
*/ */
function url($options = array(), $asArray = false, $model = null) { function url($options = array(), $asArray = false, $model = null) {
$paging = $this->params($model); $paging = $this->params($model);
@ -381,6 +397,7 @@ class PaginatorHelper extends AppHelper {
/** /**
* Protected method for generating prev/next links * Protected method for generating prev/next links
* *
* @access protected
*/ */
function __pagingLink($which, $title = null, $options = array(), $disabledTitle = null, $disabledOptions = array()) { function __pagingLink($which, $title = null, $options = array(), $disabledTitle = null, $disabledOptions = array()) {
$check = 'has' . $which; $check = 'has' . $which;
@ -421,6 +438,7 @@ class PaginatorHelper extends AppHelper {
* *
* @param string $model Optional model name. Uses the default if none is specified. * @param string $model Optional model name. Uses the default if none is specified.
* @return boolean True if the result set is not at the first page. * @return boolean True if the result set is not at the first page.
* @access public
*/ */
function hasPrev($model = null) { function hasPrev($model = null) {
return $this->__hasPage($model, 'prev'); return $this->__hasPage($model, 'prev');
@ -431,6 +449,7 @@ class PaginatorHelper extends AppHelper {
* *
* @param string $model Optional model name. Uses the default if none is specified. * @param string $model Optional model name. Uses the default if none is specified.
* @return boolean True if the result set is not at the last page. * @return boolean True if the result set is not at the last page.
* @access public
*/ */
function hasNext($model = null) { function hasNext($model = null) {
return $this->__hasPage($model, 'next'); return $this->__hasPage($model, 'next');
@ -442,6 +461,7 @@ class PaginatorHelper extends AppHelper {
* @param string $model Optional model name. Uses the default if none is specified. * @param string $model Optional model name. Uses the default if none is specified.
* @param int $page The page number - if not set defaults to 1. * @param int $page The page number - if not set defaults to 1.
* @return boolean True if the given result set has the specified page number. * @return boolean True if the given result set has the specified page number.
* @access public
*/ */
function hasPage($model = null, $page = 1) { function hasPage($model = null, $page = 1) {
if (is_numeric($model)) { if (is_numeric($model)) {
@ -453,8 +473,12 @@ class PaginatorHelper extends AppHelper {
} }
/** /**
* Protected method * Does $model have $page in its range?
* *
* @param string $model Model name to get parameters for.
* @param integer $page Page number you are checking.
* @return boolean Whether model has $page
* @access protected
*/ */
function __hasPage($model, $page) { function __hasPage($model, $page) {
$params = $this->params($model); $params = $this->params($model);
@ -470,6 +494,7 @@ class PaginatorHelper extends AppHelper {
* Gets the default model of the paged sets * Gets the default model of the paged sets
* *
* @return string Model name or null if the pagination isn't initialized. * @return string Model name or null if the pagination isn't initialized.
* @access public
*/ */
function defaultModel() { function defaultModel() {
if ($this->__defaultModel != null) { if ($this->__defaultModel != null) {
@ -485,7 +510,7 @@ class PaginatorHelper extends AppHelper {
/** /**
* Returns a counter string for the paged result set * Returns a counter string for the paged result set
* *
* Options * ### Options
* *
* - `model` The model to use, defaults to PaginatorHelper::defaultModel(); * - `model` The model to use, defaults to PaginatorHelper::defaultModel();
* - `format` The format string you want to use, defaults to 'pages' Which generates output like '1 of 5' * - `format` The format string you want to use, defaults to 'pages' Which generates output like '1 of 5'
@ -496,6 +521,7 @@ class PaginatorHelper extends AppHelper {
* *
* @param mixed $options Options for the counter string. See #options for list of keys. * @param mixed $options Options for the counter string. See #options for list of keys.
* @return string Counter string. * @return string Counter string.
* @access public
*/ */
function counter($options = array()) { function counter($options = array()) {
if (is_string($options)) { if (is_string($options)) {
@ -558,7 +584,7 @@ class PaginatorHelper extends AppHelper {
* Returns a set of numbers for the paged result set * Returns a set of numbers for the paged result set
* uses a modulus to decide how many numbers to show on each side of the current page (default: 8) * uses a modulus to decide how many numbers to show on each side of the current page (default: 8)
* *
* Options * ### Options
* *
* - `before` Content to be inserted before the numbers * - `before` Content to be inserted before the numbers
* - `after` Content to be inserted after the numbers * - `after` Content to be inserted after the numbers
@ -573,6 +599,7 @@ class PaginatorHelper extends AppHelper {
* *
* @param mixed $options Options for the numbers, (before, after, model, modulus, separator) * @param mixed $options Options for the numbers, (before, after, model, modulus, separator)
* @return string numbers string. * @return string numbers string.
* @access public
*/ */
function numbers($options = array()) { function numbers($options = array()) {
if ($options === true) { if ($options === true) {
@ -678,7 +705,7 @@ class PaginatorHelper extends AppHelper {
/** /**
* Returns a first or set of numbers for the first pages * Returns a first or set of numbers for the first pages
* *
* Options: * ### Options:
* *
* - `tag` The tag wrapping tag you want to use, defaults to 'span' * - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `before` Content to insert before the link/tag * - `before` Content to insert before the link/tag
@ -688,6 +715,7 @@ class PaginatorHelper extends AppHelper {
* @param mixed $first if string use as label for the link, if numeric print page numbers * @param mixed $first if string use as label for the link, if numeric print page numbers
* @param mixed $options * @param mixed $options
* @return string numbers string. * @return string numbers string.
* @access public
*/ */
function first($first = '<< first', $options = array()) { function first($first = '<< first', $options = array()) {
$options = array_merge( $options = array_merge(
@ -731,7 +759,7 @@ class PaginatorHelper extends AppHelper {
/** /**
* Returns a last or set of numbers for the last pages * Returns a last or set of numbers for the last pages
* *
* Options: * ### Options:
* *
* - `tag` The tag wrapping tag you want to use, defaults to 'span' * - `tag` The tag wrapping tag you want to use, defaults to 'span'
* - `before` Content to insert before the link/tag * - `before` Content to insert before the link/tag
@ -741,6 +769,7 @@ class PaginatorHelper extends AppHelper {
* @param mixed $last if string use as label for the link, if numeric print page numbers * @param mixed $last if string use as label for the link, if numeric print page numbers
* @param mixed $options Array of options * @param mixed $options Array of options
* @return string numbers string. * @return string numbers string.
* @access public
*/ */
function last($last = 'last >>', $options = array()) { function last($last = 'last >>', $options = array()) {
$options = array_merge( $options = array_merge(

26
cake/libs/view/helpers/prototype_engine.php
View file

@ -29,6 +29,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
* @var boolean * @var boolean
*/ */
var $_multiple = false; var $_multiple = false;
/** /**
* Option mappings for Prototype * Option mappings for Prototype
* *
@ -123,13 +124,14 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
$this->selection = '$$("' . $selector . '")'; $this->selection = '$$("' . $selector . '")';
return $this; return $this;
} }
/** /**
* Add an event to the script cache. Operates on the currently selected elements. * Add an event to the script cache. Operates on the currently selected elements.
* *
* ### Options * ### Options
* *
* - 'wrap' - Whether you want the callback wrapped in an anonymous function. (defaults true) * - `wrap` - Whether you want the callback wrapped in an anonymous function. (defaults true)
* - 'stop' - Whether you want the event to stopped. (defaults true) * - `stop` - Whether you want the event to stopped. (defaults true)
* *
* @param string $type Type of event to bind to the current 946 id * @param string $type Type of event to bind to the current 946 id
* @param string $callback The Javascript function you wish to trigger or the function literal * @param string $callback The Javascript function you wish to trigger or the function literal
@ -150,34 +152,40 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
$out = $this->selection . ".observe(\"{$type}\", $callback);"; $out = $this->selection . ".observe(\"{$type}\", $callback);";
return $out; return $out;
} }
/** /**
* Create a domReady event. This is a special event in many libraries * Create a domReady event. This is a special event in many libraries
* *
* @param string $functionBody The code to run on domReady * @param string $functionBody The code to run on domReady
* @return string completed domReady method * @return string completed domReady method
* @access public
*/ */
function domReady($functionBody) { function domReady($functionBody) {
$this->selection = 'document'; $this->selection = 'document';
return $this->event('dom:loaded', $functionBody, array('stop' => false)); return $this->event('dom:loaded', $functionBody, array('stop' => false));
} }
/** /**
* Create an iteration over the current selection result. * Create an iteration over the current selection result.
* *
* @param string $method The method you want to apply to the selection * @param string $method The method you want to apply to the selection
* @param string $callback The function body you wish to apply during the iteration. * @param string $callback The function body you wish to apply during the iteration.
* @return string completed iteration * @return string completed iteration
* @access public
*/ */
function each($callback) { function each($callback) {
return $this->selection . '.each(function (item, index) {' . $callback . '});'; return $this->selection . '.each(function (item, index) {' . $callback . '});';
} }
/** /**
* Trigger an Effect. * Trigger an Effect.
* *
* #### Note: Effects require Scriptaculous to be loaded. * ### Note: Effects require Scriptaculous to be loaded.
* *
* @param string $name The name of the effect to trigger. * @param string $name The name of the effect to trigger.
* @param array $options Array of options for the effect. * @param array $options Array of options for the effect.
* @return string completed string with effect. * @return string completed string with effect.
* @access public
* @see JsBaseEngineHelper::effect() * @see JsBaseEngineHelper::effect()
*/ */
function effect($name, $options = array()) { function effect($name, $options = array()) {
@ -214,12 +222,14 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
} }
return $effect; return $effect;
} }
/** /**
* Create an Ajax or Ajax.Updater call. * Create an Ajax or Ajax.Updater call.
* *
* @param mixed $url * @param mixed $url
* @param array $options * @param array $options
* @return string The completed ajax call. * @return string The completed ajax call.
* @access public
*/ */
function request($url, $options = array()) { function request($url, $options = array()) {
$url = '"'. $this->url($url) . '"'; $url = '"'. $this->url($url) . '"';
@ -246,6 +256,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
} }
return "var jsRequest = new Ajax$type($url$options);"; return "var jsRequest = new Ajax$type($url$options);";
} }
/** /**
* Create a sortable element. * Create a sortable element.
* *
@ -253,6 +264,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the sortable. * @param array $options Array of options for the sortable.
* @return string Completed sortable script. * @return string Completed sortable script.
* @access public
* @see JsHelper::sortable() for options list. * @see JsHelper::sortable() for options list.
*/ */
function sortable($options = array()) { function sortable($options = array()) {
@ -262,6 +274,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
} }
return 'var jsSortable = Sortable.create(' . $this->selection . $options . ');'; return 'var jsSortable = Sortable.create(' . $this->selection . $options . ');';
} }
/** /**
* Create a Draggable element. * Create a Draggable element.
* *
@ -269,6 +282,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the draggable. * @param array $options Array of options for the draggable.
* @return string Completed draggable script. * @return string Completed draggable script.
* @access public
* @see JsHelper::draggable() for options list. * @see JsHelper::draggable() for options list.
*/ */
function drag($options = array()) { function drag($options = array()) {
@ -281,6 +295,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
} }
return 'var jsDrag = new Draggable(' . $this->selection . $options . ');'; return 'var jsDrag = new Draggable(' . $this->selection . $options . ');';
} }
/** /**
* Create a Droppable element. * Create a Droppable element.
* *
@ -288,6 +303,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the droppable. * @param array $options Array of options for the droppable.
* @return string Completed droppable script. * @return string Completed droppable script.
* @access public
* @see JsHelper::droppable() for options list. * @see JsHelper::droppable() for options list.
*/ */
function drop($options = array()) { function drop($options = array()) {
@ -297,6 +313,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
} }
return 'Droppables.add(' . $this->selection . $options . ');'; return 'Droppables.add(' . $this->selection . $options . ');';
} }
/** /**
* Creates a slider control widget. * Creates a slider control widget.
* *
@ -304,6 +321,7 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
* *
* @param array $options Array of options for the slider. * @param array $options Array of options for the slider.
* @return string Completed slider script. * @return string Completed slider script.
* @access public
* @see JsHelper::slider() for options list. * @see JsHelper::slider() for options list.
*/ */
function slider($options = array()) { function slider($options = array()) {
@ -323,11 +341,13 @@ class PrototypeEngineHelper extends JsBaseEngineHelper {
$this->selection = $slider; $this->selection = $slider;
return $out; return $out;
} }
/** /**
* Serialize the form attached to $selector. * Serialize the form attached to $selector.
* *
* @param array $options Array of options. * @param array $options Array of options.
* @return string Completed serializeForm() snippet * @return string Completed serializeForm() snippet
* @access public
* @see JsHelper::serializeForm() * @see JsHelper::serializeForm()
*/ */
function serializeForm($options = array()) { function serializeForm($options = array()) {

38
cake/libs/view/helpers/rss.php
View file

@ -102,10 +102,11 @@ class RssHelper extends XmlHelper {
var $version = '2.0'; var $version = '2.0';
/** /**
* Returns an RSS document wrapped in <rss /> tags * Returns an RSS document wrapped in `<rss />` tags
* *
* @param array $attrib <rss /> tag attributes * @param array $attrib `<rss />` tag attributes
* @return string An RSS document * @return string An RSS document
* @access public
*/ */
function document($attrib = array(), $content = null) { function document($attrib = array(), $content = null) {
if ($content === null) { if ($content === null) {
@ -120,12 +121,13 @@ class RssHelper extends XmlHelper {
} }
/** /**
* Returns an RSS <channel /> element * Returns an RSS `<channel />` element
* *
* @param array $attrib <channel /> tag attributes * @param array $attrib `<channel />` tag attributes
* @param mixed $elements Named array elements which are converted to tags * @param mixed $elements Named array elements which are converted to tags
* @param mixed $content Content (<item />'s belonging to this channel * @param mixed $content Content (`<item />`'s belonging to this channel
* @return string An RSS <channel /> * @return string An RSS `<channel />`
* @access public
*/ */
function channel($attrib = array(), $elements = array(), $content = null) { function channel($attrib = array(), $elements = array(), $content = null) {
$view =& ClassRegistry::getObject('view'); $view =& ClassRegistry::getObject('view');
@ -166,12 +168,13 @@ class RssHelper extends XmlHelper {
/** /**
* Transforms an array of data using an optional callback, and maps it to a set * Transforms an array of data using an optional callback, and maps it to a set
* of <item /> tags * of `<item />` tags
* *
* @param array $items The list of items to be mapped * @param array $items The list of items to be mapped
* @param mixed $callback A string function name, or array containing an object * @param mixed $callback A string function name, or array containing an object
* and a string method name * and a string method name
* @return string A set of RSS <item /> elements * @return string A set of RSS `<item />` elements
* @access public
*/ */
function items($items, $callback = null) { function items($items, $callback = null) {
if ($callback != null) { if ($callback != null) {
@ -188,11 +191,12 @@ class RssHelper extends XmlHelper {
} }
/** /**
* Converts an array into an <item /> element and its contents * Converts an array into an `<item />` element and its contents
* *
* @param array $attrib The attributes of the <item /> element * @param array $attrib The attributes of the `<item />` element
* @param array $elements The list of elements contained in this <item /> * @param array $elements The list of elements contained in this `<item />`
* @return string An RSS <item /> element * @return string An RSS `<item />` element
* @access public
*/ */
function item($att = array(), $elements = array()) { function item($att = array(), $elements = array()) {
$content = null; $content = null;
@ -275,7 +279,7 @@ class RssHelper extends XmlHelper {
/** /**
* Converts a time in any format to an RSS time * Converts a time in any format to an RSS time
* *
* @param mixed $time * @param mixed $time
* @return string An RSS-formatted timestamp * @return string An RSS-formatted timestamp
* @see TimeHelper::toRSS * @see TimeHelper::toRSS
*/ */

13
cake/libs/view/helpers/session.php
View file

@ -27,7 +27,6 @@ if (!class_exists('cakesession')) {
* *
* @package cake * @package cake
* @subpackage cake.cake.libs.view.helpers * @subpackage cake.cake.libs.view.helpers
*
*/ */
class SessionHelper extends CakeSession { class SessionHelper extends CakeSession {
@ -36,7 +35,7 @@ class SessionHelper extends CakeSession {
* *
* @var array * @var array
*/ */
var $helpers = null; var $helpers = array();
/** /**
* Used to determine if methods implementation is used, or bypassed * Used to determine if methods implementation is used, or bypassed
@ -62,6 +61,7 @@ class SessionHelper extends CakeSession {
* Turn sessions on if 'Session.start' is set to false in core.php * Turn sessions on if 'Session.start' is set to false in core.php
* *
* @param string $base * @param string $base
* @access public
*/ */
function activate($base = null) { function activate($base = null) {
$this->__active = true; $this->__active = true;
@ -70,11 +70,10 @@ class SessionHelper extends CakeSession {
/** /**
* Used to read a session values set in a controller for a key or return values for all keys. * Used to read a session values set in a controller for a key or return values for all keys.
* *
* In your view: $session->read('Controller.sessKey'); * In your view: `$session->read('Controller.sessKey');`
* Calling the method without a param will return all session vars * Calling the method without a param will return all session vars
* *
* @param string $name the name of the session key you want to read * @param string $name the name of the session key you want to read
*
* @return values from the session vars * @return values from the session vars
* @access public * @access public
*/ */
@ -88,7 +87,7 @@ class SessionHelper extends CakeSession {
/** /**
* Used to check is a session key has been set * Used to check is a session key has been set
* *
* In your view: $session->check('Controller.sessKey'); * In your view: `$session->check('Controller.sessKey');`
* *
* @param string $name * @param string $name
* @return boolean * @return boolean
@ -104,7 +103,7 @@ class SessionHelper extends CakeSession {
/** /**
* Returns last error encountered in a session * Returns last error encountered in a session
* *
* In your view: $session->error(); * In your view: `$session->error();`
* *
* @return string last error * @return string last error
* @access public * @access public
@ -120,7 +119,7 @@ class SessionHelper extends CakeSession {
* Used to render the message set in Controller::Session::setFlash() * Used to render the message set in Controller::Session::setFlash()
* *
* In your view: $session->flash('somekey'); * In your view: $session->flash('somekey');
* Will default to flash if no param is passed * Will default to flash if no param is passed
* *
* @param string $key The [Message.]key you are rendering in the view. * @param string $key The [Message.]key you are rendering in the view.
* @return boolean|string Will return the value if $key is set, or false if not set. * @return boolean|string Will return the value if $key is set, or false if not set.

18
cake/libs/view/helpers/text.php
View file

@ -45,10 +45,10 @@ class TextHelper extends AppHelper {
* Highlights a given phrase in a text. You can specify any expression in highlighter that * Highlights a given phrase in a text. You can specify any expression in highlighter that
* may include the \1 expression to include the $phrase found. * may include the \1 expression to include the $phrase found.
* *
* Options: * ### Options:
* *
* - 'format' The piece of html with that the phrase will be highlighted * - `format` The piece of html with that the phrase will be highlighted
* - 'html' If true, will ignore any HTML tags, ensuring that only the correct text is highlighted * - `html` If true, will ignore any HTML tags, ensuring that only the correct text is highlighted
* *
* @param string $text Text to search the phrase in * @param string $text Text to search the phrase in
* @param string $phrase The phrase that will be searched * @param string $phrase The phrase that will be searched
@ -166,16 +166,17 @@ class TextHelper extends AppHelper {
* Cuts a string to the length of $length and replaces the last characters * Cuts a string to the length of $length and replaces the last characters
* with the ending if the text is longer than length. * with the ending if the text is longer than length.
* *
* Options: * ### Options:
* *
* - 'ending' Will be used as Ending and appended to the trimmed string * - `ending` Will be used as Ending and appended to the trimmed string
* - 'exact' If false, $text will not be cut mid-word * - `exact` If false, $text will not be cut mid-word
* - 'html' If true, HTML tags would be handled correctly * - `html` If true, HTML tags would be handled correctly
* *
* @param string $text String to truncate. * @param string $text String to truncate.
* @param integer $length Length of returned string, including ellipsis. * @param integer $length Length of returned string, including ellipsis.
* @param array $options An array of html attributes and options. * @param array $options An array of html attributes and options.
* @return string Trimmed string. * @return string Trimmed string.
* @access public
*/ */
function truncate($text, $length = 100, $options = array()) { function truncate($text, $length = 100, $options = array()) {
$default = array( $default = array(
@ -279,7 +280,8 @@ class TextHelper extends AppHelper {
} }
/** /**
* Extracts an excerpt from the text surrounding the phrase with a number of characters on each side determined by radius. * Extracts an excerpt from the text surrounding the phrase with a number of characters on each side
* determined by radius.
* *
* @param string $text String to search the phrase in * @param string $text String to search the phrase in
* @param string $phrase Phrase that will be searched for * @param string $phrase Phrase that will be searched for

48
cake/libs/view/helpers/time.php
View file

@ -32,9 +32,11 @@ class TimeHelper extends AppHelper {
* Converts a string representing the format for the function strftime and returns a * Converts a string representing the format for the function strftime and returns a
* windows safe and i18n aware format. * windows safe and i18n aware format.
* *
* @param string $format Format with specifiers for strftime function. Accepts the special specifier %S which mimics th modifier S for date() * @param string $format Format with specifiers for strftime function.
* Accepts the special specifier %S which mimics th modifier S for date()
* @param string UNIX timestamp * @param string UNIX timestamp
* @return string windows safe and date() function compatible format for strftime * @return string windows safe and date() function compatible format for strftime
* @access public
*/ */
function convertSpecifiers($format, $time = null) { function convertSpecifiers($format, $time = null) {
if (!$time) { if (!$time) {
@ -50,6 +52,7 @@ class TimeHelper extends AppHelper {
* *
* @param array $specifier match from regular expression * @param array $specifier match from regular expression
* @return string converted element * @return string converted element
* @access private
*/ */
function __translateSpecifier($specifier) { function __translateSpecifier($specifier) {
switch ($specifier[1]) { switch ($specifier[1]) {
@ -138,6 +141,7 @@ class TimeHelper extends AppHelper {
* @param string $serverTime UNIX timestamp * @param string $serverTime UNIX timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string UNIX timestamp * @return string UNIX timestamp
* @access public
*/ */
function convert($serverTime, $userOffset) { function convert($serverTime, $userOffset) {
$serverOffset = $this->serverOffset(); $serverOffset = $this->serverOffset();
@ -150,6 +154,7 @@ class TimeHelper extends AppHelper {
* Returns server's offset from GMT in seconds. * Returns server's offset from GMT in seconds.
* *
* @return int Offset * @return int Offset
* @access public
*/ */
function serverOffset() { function serverOffset() {
return date('Z', time()); return date('Z', time());
@ -161,6 +166,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string * @param string $dateString Datetime string
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Parsed timestamp * @return string Parsed timestamp
* @access public
*/ */
function fromString($dateString, $userOffset = null) { function fromString($dateString, $userOffset = null) {
if (empty($dateString)) { if (empty($dateString)) {
@ -186,6 +192,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Formatted date string * @return string Formatted date string
* @access public
*/ */
function nice($dateString = null, $userOffset = null) { function nice($dateString = null, $userOffset = null) {
if ($dateString != null) { if ($dateString != null) {
@ -208,6 +215,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Described, relative date string * @return string Described, relative date string
* @access public
*/ */
function niceShort($dateString = null, $userOffset = null) { function niceShort($dateString = null, $userOffset = null) {
$date = $dateString ? $this->fromString($dateString, $userOffset) : time(); $date = $dateString ? $this->fromString($dateString, $userOffset) : time();
@ -234,6 +242,7 @@ class TimeHelper extends AppHelper {
* @param string $fieldName Name of database field to compare with * @param string $fieldName Name of database field to compare with
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Partial SQL string. * @return string Partial SQL string.
* @access public
*/ */
function daysAsSql($begin, $end, $fieldName, $userOffset = null) { function daysAsSql($begin, $end, $fieldName, $userOffset = null) {
$begin = $this->fromString($begin, $userOffset); $begin = $this->fromString($begin, $userOffset);
@ -252,6 +261,7 @@ class TimeHelper extends AppHelper {
* @param string $fieldName Name of database field to compare with * @param string $fieldName Name of database field to compare with
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Partial SQL string. * @return string Partial SQL string.
* @access public
*/ */
function dayAsSql($dateString, $fieldName, $userOffset = null) { function dayAsSql($dateString, $fieldName, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -264,6 +274,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return boolean True if datetime string is today * @return boolean True if datetime string is today
* @access public
*/ */
function isToday($dateString, $userOffset = null) { function isToday($dateString, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -275,6 +286,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString * @param string $dateString
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return boolean True if datetime string is within current week * @return boolean True if datetime string is within current week
* @access public
*/ */
function isThisWeek($dateString, $userOffset = null) { function isThisWeek($dateString, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -286,6 +298,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString * @param string $dateString
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return boolean True if datetime string is within current month * @return boolean True if datetime string is within current month
* @access public
*/ */
function isThisMonth($dateString, $userOffset = null) { function isThisMonth($dateString, $userOffset = null) {
$date = $this->fromString($dateString); $date = $this->fromString($dateString);
@ -297,6 +310,7 @@ class TimeHelper extends AppHelper {
* *
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @return boolean True if datetime string is within current year * @return boolean True if datetime string is within current year
* @access public
*/ */
function isThisYear($dateString, $userOffset = null) { function isThisYear($dateString, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -309,6 +323,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return boolean True if datetime string was yesterday * @return boolean True if datetime string was yesterday
* @access public
*/ */
function wasYesterday($dateString, $userOffset = null) { function wasYesterday($dateString, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -321,6 +336,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return boolean True if datetime string was yesterday * @return boolean True if datetime string was yesterday
* @access public
*/ */
function isTomorrow($dateString, $userOffset = null) { function isTomorrow($dateString, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -328,10 +344,12 @@ class TimeHelper extends AppHelper {
} }
/** /**
* Returns the quart * Returns the quarter
*
* @param string $dateString * @param string $dateString
* @param boolean $range if true returns a range in Y-m-d format * @param boolean $range if true returns a range in Y-m-d format
* @return boolean True if datetime string is within current week * @return boolean True if datetime string is within current week
* @access public
*/ */
function toQuarter($dateString, $range = false) { function toQuarter($dateString, $range = false) {
$time = $this->fromString($dateString); $time = $this->fromString($dateString);
@ -368,6 +386,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string to be represented as a Unix timestamp * @param string $dateString Datetime string to be represented as a Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return integer Unix timestamp * @return integer Unix timestamp
* @access public
*/ */
function toUnix($dateString, $userOffset = null) { function toUnix($dateString, $userOffset = null) {
return $this->fromString($dateString, $userOffset); return $this->fromString($dateString, $userOffset);
@ -379,6 +398,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Formatted date string * @return string Formatted date string
* @access public
*/ */
function toAtom($dateString, $userOffset = null) { function toAtom($dateString, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -391,6 +411,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Formatted date string * @return string Formatted date string
* @access public
*/ */
function toRSS($dateString, $userOffset = null) { function toRSS($dateString, $userOffset = null) {
$date = $this->fromString($dateString, $userOffset); $date = $this->fromString($dateString, $userOffset);
@ -402,11 +423,11 @@ class TimeHelper extends AppHelper {
* on the difference between the current time and given datetime. * on the difference between the current time and given datetime.
* $datetime should be in a <i>strtotime</i> - parsable format, like MySQL's datetime datatype. * $datetime should be in a <i>strtotime</i> - parsable format, like MySQL's datetime datatype.
* *
* Options: * ### Options:
* *
* - 'format' => a fall back format if the relative time is longer than the duration specified by end * - `format` => a fall back format if the relative time is longer than the duration specified by end
* - 'end' => The end of relative time telling * - `end` => The end of relative time telling
* - 'userOffset' => Users offset from GMT (in hours) * - `userOffset` => Users offset from GMT (in hours)
* *
* Relative dates look something like this: * Relative dates look something like this:
* 3 weeks, 4 days ago * 3 weeks, 4 days ago
@ -420,6 +441,7 @@ class TimeHelper extends AppHelper {
* @param string $dateString Datetime string or Unix timestamp * @param string $dateString Datetime string or Unix timestamp
* @param array $options Default format if timestamp is used in $dateString * @param array $options Default format if timestamp is used in $dateString
* @return string Relative time string. * @return string Relative time string.
* @access public
*/ */
function timeAgoInWords($dateTime, $options = array()) { function timeAgoInWords($dateTime, $options = array()) {
$userOffset = null; $userOffset = null;
@ -584,7 +606,9 @@ class TimeHelper extends AppHelper {
* @param mixed $options Default format string, if timestamp is used in $dateTime, or an array of options to be passed * @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. * @return string Relative time string.
* @see TimeHelper::timeAgoInWords * @see TimeHelper::timeAgoInWords
* @access public
* @deprecated This method alias will be removed in future versions.
*/ */
function relativeTime($dateTime, $options = array()) { function relativeTime($dateTime, $options = array()) {
return $this->timeAgoInWords($dateTime, $options); return $this->timeAgoInWords($dateTime, $options);
@ -593,10 +617,12 @@ class TimeHelper extends AppHelper {
/** /**
* Returns true if specified datetime was within the interval specified, else false. * Returns true if specified datetime was within the interval specified, else false.
* *
* @param mixed $timeInterval the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute. * @param mixed $timeInterval the numeric value with space then time type.
* Example of valid types: 6 hours, 2 days, 1 minute.
* @param mixed $dateString the datestring or unix timestamp to compare * @param mixed $dateString the datestring or unix timestamp to compare
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return bool * @return bool
* @access public
*/ */
function wasWithinLast($timeInterval, $dateString, $userOffset = null) { function wasWithinLast($timeInterval, $dateString, $userOffset = null) {
$tmp = str_replace(' ', '', $timeInterval); $tmp = str_replace(' ', '', $timeInterval);
@ -619,6 +645,7 @@ class TimeHelper extends AppHelper {
* *
* @param string $dateString Datetime string * @param string $dateString Datetime string
* @return string Formatted date string * @return string Formatted date string
* @access public
*/ */
function gmt($string = null) { function gmt($string = null) {
if ($string != null) { if ($string != null) {
@ -647,6 +674,7 @@ class TimeHelper extends AppHelper {
* @param boolean $invalid flag to ignore results of fromString == false * @param boolean $invalid flag to ignore results of fromString == false
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Formatted date string * @return string Formatted date string
* @access public
*/ */
function format($format, $date = null, $invalid = false, $userOffset = null) { function format($format, $date = null, $invalid = false, $userOffset = null) {
$time = $this->fromString($date, $userOffset); $time = $this->fromString($date, $userOffset);
@ -665,11 +693,13 @@ class TimeHelper extends AppHelper {
/** /**
* Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string. * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
* It take in account the default date format for the current language if a LC_TIME file is used. * It take in account the default date format for the current language if a LC_TIME file is used.
*
* @param string $dateString Datetime string * @param string $dateString Datetime string
* @param string $format strftime format string. * @param string $format strftime format string.
* @param boolean $invalid flag to ignore results of fromString == false * @param boolean $invalid flag to ignore results of fromString == false
* @param int $userOffset User's offset from GMT (in hours) * @param int $userOffset User's offset from GMT (in hours)
* @return string Formatted and translated date string * @return string Formatted and translated date string @access public
* @access public
*/ */
function i18nFormat($date, $format = null, $invalid = false, $userOffset = null) { function i18nFormat($date, $format = null, $invalid = false, $userOffset = null) {
$date = $this->fromString($date, $userOffset); $date = $this->fromString($date, $userOffset);

28
cake/libs/view/helpers/xml.php
View file

@ -39,6 +39,7 @@ class XmlHelper extends AppHelper {
/** /**
* Constructor * Constructor
*
* @return void * @return void
*/ */
function __construct() { function __construct() {
@ -50,8 +51,9 @@ class XmlHelper extends AppHelper {
/** /**
* Returns an XML document header * Returns an XML document header
* *
* @param array $attrib Header tag attributes * @param array $attrib Header tag attributes
* @return string XML header * @return string XML header
* @access public
*/ */
function header($attrib = array()) { function header($attrib = array()) {
if (Configure::read('App.encoding') !== null) { if (Configure::read('App.encoding') !== null) {
@ -71,10 +73,10 @@ class XmlHelper extends AppHelper {
/** /**
* Adds a namespace to any documents generated * Adds a namespace to any documents generated
* *
* @param string $name The namespace name * @param string $name The namespace name
* @param string $url The namespace URI; can be empty if in the default namespace map * @param string $url The namespace URI; can be empty if in the default namespace map
* @return boolean False if no URL is specified, and the namespace does not exist * @return boolean False if no URL is specified, and the namespace does not exist
* default namespace map, otherwise true * default namespace map, otherwise true
* @deprecated * @deprecated
* @see Xml::addNs() * @see Xml::addNs()
*/ */
@ -88,6 +90,7 @@ class XmlHelper extends AppHelper {
* @param string $name The namespace name or URI * @param string $name The namespace name or URI
* @deprecated * @deprecated
* @see Xml::removeNs() * @see Xml::removeNs()
* @access public
*/ */
function removeNs($name) { function removeNs($name) {
return $this->Xml->removeGlobalNamespace($name); return $this->Xml->removeGlobalNamespace($name);
@ -96,11 +99,12 @@ class XmlHelper extends AppHelper {
/** /**
* Generates an XML element * Generates an XML element
* *
* @param string $name The name of the XML element * @param string $name The name of the XML element
* @param array $attrib The attributes of the XML element * @param array $attrib The attributes of the XML element
* @param mixed $content XML element content * @param mixed $content XML element content
* @param boolean $endTag Whether the end tag of the element should be printed * @param boolean $endTag Whether the end tag of the element should be printed
* @return string XML * @return string XML
* @access public
*/ */
function elem($name, $attrib = array(), $content = null, $endTag = true) { function elem($name, $attrib = array(), $content = null, $endTag = true) {
$namespace = null; $namespace = null;
@ -138,6 +142,7 @@ class XmlHelper extends AppHelper {
* Create closing tag for current element * Create closing tag for current element
* *
* @return string * @return string
* @access public
*/ */
function closeElem() { function closeElem() {
$name = $this->Xml->name(); $name = $this->Xml->name();
@ -150,11 +155,12 @@ class XmlHelper extends AppHelper {
/** /**
* Serializes a model resultset into XML * Serializes a model resultset into XML
* *
* @param mixed $data The content to be converted to XML * @param mixed $data The content to be converted to XML
* @param array $options The data formatting options. For a list of valid options, see * @param array $options The data formatting options. For a list of valid options, see
* XmlNode::__construct(). * XmlNode::__construct().
* @return string A copy of $data in XML format * @return string A copy of $data in XML format
* @see XmlNode * @see XmlNode
* @access public
*/ */
function serialize($data, $options = array()) { function serialize($data, $options = array()) {
$options += array('attributes' => false, 'format' => 'attributes'); $options += array('attributes' => false, 'format' => 'attributes');