Commit 0b66c971 authored by Dries's avatar Dries

- Patch #303987 by jhodgdon, CitizenKane: l() documentation needs to say something about encoding.

parent bfd0c7fd
......@@ -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;
......
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