diff options
author | Dries Buytaert <dries@buytaert.net> | 2010-04-06 16:41:08 +0000 |
---|---|---|
committer | Dries Buytaert <dries@buytaert.net> | 2010-04-06 16:41:08 +0000 |
commit | 0b66c971682c6fa21b93234a6ba5593bc0adbbec (patch) | |
tree | 847d9340bcc180376bb76aeb3c9bdaa2d9cbc2e2 /includes | |
parent | bfd0c7fd0a486c325acdb03784e5afd95589c9d4 (diff) | |
download | brdo-0b66c971682c6fa21b93234a6ba5593bc0adbbec.tar.gz brdo-0b66c971682c6fa21b93234a6ba5593bc0adbbec.tar.bz2 |
- Patch #303987 by jhodgdon, CitizenKane: l() documentation needs to say something about encoding.
Diffstat (limited to 'includes')
-rw-r--r-- | includes/common.inc | 99 |
1 files changed, 49 insertions, 50 deletions
diff --git a/includes/common.inc b/includes/common.inc index 3ea773a21..12474d3c4 100644 --- a/includes/common.inc +++ b/includes/common.inc @@ -1900,21 +1900,37 @@ function format_username($account) { */ /** - * Generate a URL. + * Generates an internal or external URL. + * + * When creating links in modules, consider whether l() could be a better + * alternative than url(). * * @param $path - * The Drupal path being linked to, such as "admin/content", or an existing - * URL like "http://drupal.org/". The special path '<front>' may also be given - * and will generate the site's base URL. + * The internal path or external URL being linked to, such as "node/34" or + * "http://example.com/foo". A few notes: + * - If you provide a full URL, it will be considered an external URL. + * - If you provide only the path (e.g. "node/34"), it will be + * considered an internal link. In this case, it should be a system URL, + * and it will be replaced with the alias, if one exists. Additional query + * arguments for internal paths must be supplied in $options['query'], not + * included in $path. + * - If you provide an internal path and $options['alias'] is set to TRUE, the + * path is assumed already to be the correct path alias, and the alias is + * not looked up. + * - The special string '<front>' generates a link to the site's base URL. + * - If your external URL contains a query (e.g. http://example.com/foo?a=b), + * then you can either URL encode the query keys and values yourself and + * include them in $path, or use $options['query'] to let this function + * URL encode them. * @param $options - * An associative array of additional options, with the following keys: + * An associative array of additional options, with the following elements: * - 'query': An array of query key/value-pairs (without any URL-encoding) to - * append to the link. - * - 'fragment': A fragment identifier (or named anchor) to append to the - * link. Do not include the leading '#' character. + * append to the URL. + * - 'fragment': A fragment identifier (named anchor) to append to the URL. + * Do not include the leading '#' character. * - 'absolute': Defaults to FALSE. Whether to force the output to be an * absolute link (beginning with http:). Useful for links that will be - * displayed outside the site, such as in a RSS feed. + * displayed outside the site, such as in an RSS feed. * - 'alias': Defaults to FALSE. Whether the given path is a URL alias * already. * - 'external': Whether the given path is an external URL. @@ -1933,9 +1949,6 @@ function format_username($account) { * * @return * A string containing a URL to the given path. - * - * When creating links in modules, consider whether l() could be a better - * alternative than url(). */ function url($path = NULL, array $options = array()) { // Merge in defaults. @@ -2125,50 +2138,36 @@ function drupal_attributes(array $attributes = array()) { } /** - * Format an internal Drupal link. + * Formats an internal or external URL link as an HTML anchor tag. * - * This function correctly handles aliased paths, and allows themes to highlight - * links to the current page correctly, so all internal links output by modules - * should be generated by this function if possible. + * This function correctly handles aliased paths, and adds an 'active' class + * attribute to links that point to the current page (for theming), so all + * internal links output by modules should be generated by this function if + * possible. * * @param $text - * The text to be enclosed with the anchor tag. + * The link text for the anchor tag. * @param $path - * The Drupal path being linked to, such as "admin/content". Can be an - * external or internal URL. - * - If you provide the full URL, it will be considered an external URL. - * - If you provide only the path (e.g. "admin/content"), it is - * considered an internal link. In this case, it must be a system URL - * as the url() function will generate the alias. - * - If you provide '<front>', it generates a link to the site's - * base URL (again via the url() function). - * - If you provide a path, and 'alias' is set to TRUE (see below), it is - * used as is. - * @param $options - * An associative array of additional options, with the following keys: - * - attributes: An associative array of HTML attributes to apply to the - * anchor tag. - * - query: A query string to append to the link, or an array of query - * key/value properties. - * - fragment: A fragment identifier (named anchor) to append to the link. - * Do not include the '#' character. - * - absolute: (default FALSE) Whether to force the output to be an absolute - * link (beginning with http:). Useful for links that will be displayed - * outside the site, such as in an RSS feed. - * - html: (default FALSE) Whether $text is HTML, or just plain-text. For - * example for making an image a link, this must be set to TRUE, or else - * you will see the escaped HTML. - * - alias: (default FALSE) Whether the given path is an alias already. - * - language: An optional language object. If the path being linked to is - * internal to the site, $options['language'] is used to look up the alias - * for the URL, and to determine whether the link is "active", or pointing - * to the current page (the language as well as the path must match). If - * $options['language'] is omitted, the language defined by the current - * page's URL will be used; this depends on the site's language - * negotiation settings (sub-domain or URL prefix). + * The internal path or external URL being linked to, such as "node/34" or + * "http://example.com/foo". After the url() function is called to construct + * the URL from $path and $options, the resulting URL is passed through + * check_plain() before it is inserted into the HTML anchor tag, to ensure + * well-formed HTML. See url() for more information and notes. + * @param array $options + * An associative array of additional options, with the following elements: + * - 'attributes': An associative array of HTML attributes to apply to the + * anchor tag. + * - 'html' (default FALSE): Whether $text is HTML or just plain-text. For + * example, to make an image tag into a link, this must be set to TRUE, or + * you will see the escaped HTML image tag. + * - 'language': An optional language object. If the path being linked to is + * internal to the site, $options['language'] is used to determine whether + * the link is "active", or pointing to the current page (the language as + * well as the path must match). This element is also used by url(). + * - Additional $options elements used by the url() function. * * @return - * an HTML string containing a link to the given path. + * An HTML string containing a link to the given path. */ function l($text, $path, array $options = array()) { global $language_url; |