4.6.x common.inc l($text, $path, $attributes = array(), $query = NULL, $fragment = NULL, $absolute = FALSE, $html = FALSE)
4.7.x common.inc l($text, $path, $attributes = array(), $query = NULL, $fragment = NULL, $absolute = FALSE, $html = FALSE)
5.x common.inc l($text, $path, $attributes = array(), $query = NULL, $fragment = NULL, $absolute = FALSE, $html = FALSE)
6.x common.inc l($text, $path, $options = array())
7.x common.inc l($text, $path, array $options = array())

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

string $text: The translated link text for the anchor tag.

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

array $options: An associative array of additional options. Defaults to an empty array. It may contain the following elements.

  • 'attributes': An associative array of HTML attributes to apply to the anchor tag. If element 'class' is included, it must be an array; 'title' must be a string; other elements are more flexible, as they just need to work in a call to drupal_attributes($options['attributes']).
  • '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. $text is not sanitized if 'html' is TRUE. The calling function must ensure that $text is already safe.
  • '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 value

string An HTML string containing a link to the given path.

See also

url()

142 calls to l()
actions_synchronize in includes/actions.inc
Synchronizes actions that are provided by modules in hook_action_info().
aggregator_form_category_submit in modules/aggregator/aggregator.admin.inc
Form submission handler for aggregator_form_category().
aggregator_form_feed_submit in modules/aggregator/aggregator.admin.inc
Form submission handler for aggregator_form_feed().
aggregator_view in modules/aggregator/aggregator.admin.inc
Displays the aggregator administration page.
authorize.php in ./authorize.php
Administrative script for running authorized file operations.

... See full list

2 string references to 'l'
FieldTranslationsTestCase::setUp in modules/field/tests/field.test
Set the default field storage backend for fields created during tests.
LocaleTranslationFunctionalTest::testJavaScriptTranslation in modules/locale/locale.test

File

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

Code

function l($text, $path, array $options = array()) {
  global $language_url;
  static $use_theme = NULL;

  // 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_url->language)) {
    $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']);
  }

  // Determine if rendering of the link is to be done with a theme function
  // or the inline default. Inline is faster, but if the theme system has been
  // loaded and a module or theme implements a preprocess or process function
  // or overrides the theme_link() function, then invoke theme(). Preliminary
  // benchmarks indicate that invoking theme() can slow down the l() function
  // by 20% or more, and that some of the link-heavy Drupal pages spend more
  // than 10% of the total page request time in the l() function.
  if (!isset($use_theme) && function_exists('theme')) {
    // Allow edge cases to prevent theme initialization and force inline link
    // rendering.
    if (variable_get('theme_link', TRUE)) {
      drupal_theme_initialize();
      $registry = theme_get_registry(FALSE);
      // We don't want to duplicate functionality that's in theme(), so any
      // hint of a module or theme doing anything at all special with the 'link'
      // theme hook should simply result in theme() being called. This includes
      // the overriding of theme_link() with an alternate function or template,
      // the presence of preprocess or process functions, or the presence of
      // include files.
      $use_theme = !isset($registry['link']['function']) || ($registry['link']['function'] != 'theme_link');
      $use_theme = $use_theme || !empty($registry['link']['preprocess functions']) || !empty($registry['link']['process functions']) || !empty($registry['link']['includes']);
    }
    else {
      $use_theme = FALSE;
    }
  }
  if ($use_theme) {
    return theme('link', array('text' => $text, 'path' => $path, 'options' => $options));
  }
  // The result of url() is a plain-text URL. Because we are using it here
  // in an HTML argument context, we need to encode it properly.
  return '<a href="' . check_plain(url($path, $options)) . '"' . drupal_attributes($options['attributes']) . '>' . ($options['html'] ? $text : check_plain($text)) . '</a>';
}

Comments

sime’s picture

djouuuuh’s picture

To make the path work in every template file, use file_create_url() like the theme_image function.

$src = file_create_url(path_to_theme() . '/path/to/image.png');
print l('<img src="' . $src . '" alt="Hello" title="Hello"/>', "http://www.example.com", array('html'=>TRUE));
emag’s picture

With my link I was including a destination. When I did that though the resulting link transformed the ? to %3F and the = to %3D. So I found this link: http://stackoverflow.com/questions/15278864/convert-special-characters-t... and used the rawurldecode to solve it.

OLD:
print l("LOGIN","user/login/?destination=frontpage", array('attributes' => array('id' =>'button','class' => array('buttonlogin'))));

NEW:
print rawurldecode(rawurldecode(l("LOGIN","user/login/?destination=frontpage", array('attributes' => array('id' =>'button','class' => array('buttonlogin'))))));

Sorry the code isn't blocked in, don't know the html to do that and the help didn't say, or I was blind and missed it.

gradedcatfood’s picture

Is their a reason why this function does not implement html_entity_decode() or decode_entities()? Should be trying to convert everything to valid HTML.

kurtismccartney’s picture

What if we were looking for something like this:

< a href="/" property="item" typeof="WebPage" >< span property="name" >Home< /span >< /a >

The following does not deliver the internal span:
l($content, $it['url'], array('attributes' => array('property' => 'item', 'typeof' => 'WebPage')));

Pages