Same name and namespace in other branches
  1. 4.6.x includes/common.inc \l()
  2. 4.7.x includes/common.inc \l()
  3. 5.x includes/common.inc \l()
  4. 7.x includes/common.inc \l()

Formats an internal or external URL link as an HTML anchor tag.

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.

However, for links enclosed in translatable text you should use t() and embed the HTML anchor tag directly in the translated string. For example:

t('Visit the <a href="@url">settings</a> page', array(
  '@url' => url('admin'),
));

This keeps the context of the link title ('settings' in the example) for translators.

Parameters

$text: The link text for the anchor tag.

$path: 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_url() before it is inserted into the HTML anchor tag, to ensure well-formed HTML. See url() for more information and notes.

$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 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).This element is also used by url().
  • Additional $options elements used by the url() function.

Return value

An HTML string containing a link to the given path.

100 calls to l()
aggregator_view in modules/aggregator/aggregator.admin.inc
Displays the aggregator administration page.
block_admin_display_form in modules/block/block.admin.inc
Generate main blocks administration form.
blogapi_blogger_edit_post in modules/blogapi/blogapi.module
Blogging API callback. Modifies the specified blog node.
blogapi_blogger_new_post in modules/blogapi/blogapi.module
Blogging API callback. Inserts a new blog post as a node.
blog_form in modules/blog/blog.module
Implementation of hook_form().

... See full list

File

includes/common.inc, line 1658
Common functions that many Drupal modules will need to reference.

Code

function l($text, $path, $options = array()) {
  global $language;

  // Merge in defaults.
  $options += array(
    'attributes' => array(),
    'html' => FALSE,
  );

  // Append active class.
  if (($path == $_GET['q'] || $path == '<front>' && drupal_is_front_page()) && (empty($options['language']) || $options['language']->language == $language->language)) {
    if (isset($options['attributes']['class'])) {
      $options['attributes']['class'] .= ' active';
    }
    else {
      $options['attributes']['class'] = 'active';
    }
  }

  // Remove all HTML and PHP tags from a tooltip. For best performance, we act only
  // if a quick strpos() pre-check gave a suspicion (because strip_tags() is expensive).
  if (isset($options['attributes']['title']) && strpos($options['attributes']['title'], '<') !== FALSE) {
    $options['attributes']['title'] = strip_tags($options['attributes']['title']);
  }
  return '<a href="' . check_url(url($path, $options)) . '"' . drupal_attributes($options['attributes']) . '>' . ($options['html'] ? $text : check_plain($text)) . '</a>';
}