Index: includes/common.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/common.inc,v retrieving revision 1.1128 diff -u -r1.1128 common.inc --- includes/common.inc 12 Mar 2010 14:20:32 -0000 1.1128 +++ includes/common.inc 17 Mar 2010 18:23:07 -0000 @@ -1903,23 +1903,38 @@ */ /** - * 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 '' 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 '' 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: - * - '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. - * - '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. - * - 'alias': Defaults to FALSE. Whether the given path is a URL alias - * already. + * An associative array of additional options, with the following elements: + * - 'query': An array of query key/value properties to append to the URL. + * These should not be URL-encoded. + * - '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. + * - 'alias' (default FALSE): Whether the given path is an alias already. * - 'external': Whether the given path is an external URL. * - 'language': An optional language object. Used to build the URL to link * to and look up the proper alias for the link. @@ -1934,9 +1949,6 @@ * * @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. @@ -2126,47 +2138,31 @@ } /** - * 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. * * @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 '', 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. + * 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 $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. + * 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. + * - 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;