Commit ebba90fe authored by Dries's avatar Dries

- Patch #5708 by Goba: moved the URL aliasing functions to a common place, so
  they will be part of the same documentation group, as well as created a new
  'formatting functions' group and added a lot of docs for them.  Also fixed
  some small errors reported by the doxygen parser.
parent 6450c712
......@@ -118,10 +118,10 @@ function drupal_get_html_head() {
/* @} */
/**
* @name URL path
* @name URL path alias
* @ingroup common
*
* Function to handle path aliases.
* Functions to handle path aliases.
*/
function drupal_get_path_map($action = "") {
static $map = NULL;
......@@ -144,15 +144,34 @@ function drupal_get_path_map($action = "") {
function drupal_rebuild_path_map() {
drupal_get_path_map("rebuild");
}
/* @} */
/**
* @name HTTP handling
* @ingroup common
*
* Functions to properly handle HTTP responses.
* @{
* Given an old url, return the alias.
*/
function drupal_get_path_alias($path) {
if (($map = drupal_get_path_map()) && ($newpath = array_search($path, $map))) {
return $newpath;
}
elseif (function_exists("conf_url_rewrite")) {
return conf_url_rewrite($path, 'outgoing');
}
}
/**
* Given an alias, return the default url.
*/
function drupal_get_normal_path($path) {
if (($map = drupal_get_path_map()) && isset($map[$path])) {
return $map[$path];
}
elseif (function_exists("conf_url_rewrite")) {
return conf_url_rewrite($path, 'incoming');
}
else {
return $path;
}
}
/* @} */
/**
* @name HTTP headers
......@@ -176,6 +195,14 @@ function drupal_get_headers() {
}
/* @} */
/**
* @name HTTP handling
* @ingroup common
*
* Functions to properly handle HTTP responses.
* @{
*/
/**
* HTTP redirects. Makes sure the redirected url is formatted correctly and
* includes the session ID.
......@@ -520,6 +547,7 @@ function drupal_specialchars($input, $quotes = ENT_NOQUOTES) {
* @ingroup common
*
* Functions to validate user input.
* @{
*/
/**
......@@ -703,6 +731,14 @@ function check_file($filename) {
return is_uploaded_file($filename);
}
/**
* @name Formatting
* @ingroup common
*
* Functions to format numbers, strings, dates, etc.
* @{
*/
function format_rss_channel($title, $link, $description, $items, $language = "en", $args = array()) {
// arbitrary elements may be added using the $args associative array
......@@ -747,11 +783,18 @@ function format_rss_item($title, $link, $description, $args = array()) {
* @param $plural The string for the plural case. Please make sure it's clear
* this is plural, to ease translation. Use %count in places of the item
* count, as in "%count new comments".
* @return Translated string
*/
function format_plural($count, $singular, $plural) {
return t($count == 1 ? $singular : $plural, array("%count" => $count));
}
/**
* Generates a string representation for the given byte count.
*
* @param $size The size in bytes
* @return Translated string representation of the size
*/
function format_size($size) {
$suffix = t("bytes");
if ($size > 1024) {
......@@ -765,6 +808,13 @@ function format_size($size) {
return t("%size %suffix", array("%size" => $size, "%suffix" => $suffix));
}
/**
* Formats a time interval with the requested granularity.
*
* @param $timestamp The length of the interval in seconds
* @param $granularity How much units to consider when generating the string
* @return Translated string representation of the interval
*/
function format_interval($timestamp, $granularity = 2) {
$units = array("1 year|%count years" => 31536000, "1 week|%count weeks" => 604800, "1 day|%count days" => 86400, "1 hour|%count hours" => 3600, "1 min|%count min" => 60, "1 sec|%count sec" => 1);
foreach ($units as $key => $value) {
......@@ -782,6 +832,20 @@ function format_interval($timestamp, $granularity = 2) {
return ($output) ? $output : t("0 sec");
}
/**
* Formats a date with the given configured format or a custom format string.
* Drupal allows administrators to select formatting strings for 'small',
* 'medium' and 'large' date formats. This function can handle these formats,
* as well as any custom format.
*
* @param $timestamp The exact date to format
* @param $type Could be 'small', 'medium' or 'large' for the preconfigured
* date formats. If 'custom' is specified, the next parameter
* should contain the format string
* @param $format Format string (as required by the PHP date() function).
* Only required if 'custom' date format is requested.
* @return Translated date string in the requested format
*/
function format_date($timestamp, $type = "medium", $format = "") {
global $user;
......@@ -816,6 +880,14 @@ function format_date($timestamp, $type = "medium", $format = "") {
return $date;
}
/**
* Formats a username.
*
* @param $object User object
* @return String containing a HTML link to the user's page if the
* passed object suggests that this is a site user. Otherwise
* only the user name is returned.
*/
function format_name($object) {
if ($object->uid && $object->name) {
......@@ -854,6 +926,7 @@ function format_name($object) {
return $output;
}
/* @} */
/**
* @defgroup from Form generation
......@@ -939,33 +1012,6 @@ function form_weight($title = NULL, $name = "weight", $value = 0, $delta = 10, $
}
/* @} */
/**
* Given an old url, return the alias.
*/
function drupal_get_path_alias($path) {
if (($map = drupal_get_path_map()) && ($newpath = array_search($path, $map))) {
return $newpath;
}
elseif (function_exists("conf_url_rewrite")) {
return conf_url_rewrite($path, 'outgoing');
}
}
/**
* Given an alias, return the default url.
*/
function drupal_get_normal_path($path) {
if (($map = drupal_get_path_map()) && isset($map[$path])) {
return $map[$path];
}
elseif (function_exists("conf_url_rewrite")) {
return conf_url_rewrite($path, 'incoming');
}
else {
return $path;
}
}
function url($url = NULL, $query = NULL, $fragment = NULL) {
global $base_url;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment