Drupal 6 l() - the missing link documentation

The format

The drupal 6 link function takes the format of:

l($text, $path, $options = array())

This will format an internal Drupal link.

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.

Parameters

$text - The text to be enclosed with the anchor tag.

$path - The Drupal path being linked to, such as "admin/content/node". Can be an external or internal URL.

An example of these Parameters at work:

<?php print l('Some link text', 'path/to/page'); ?>

Will produce: Some link text

<a href="/path/to/page">Some link text</a>

Nice and simple so far.

• If you provide the full URL, it will be considered an external URL.
• If you provide only the path (e.g. "admin/content/node"), it is considered an internal link. In this case, it must be a system URL as the url() function will generate the alias. Which means you can use both node/999 or "path/to/page" and both will point to /path/to/page.
• 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.

$options - An associative array of additional options, with the following keys:

• 'attributes'

  An associative array of HTML attributes to apply to the anchor tag. You can go to W3schools website - a link reference to see what attributes you can apply.

  Example 1

  <?php print l('Some link text', 'path/to/page', array('attributes' => array('title' => 'Go to this page', 'class' => 'link'))); ?>

  Some link text

  <a class="link" title="Go to this page" href="/path/to/page">Some link text</a>

  Example 2

  <?php print l('Some link text', 'path/to/page', array('attributes' => array('onclick' => 'window.open(this.href); return false;'))); ?>

  Some link text

  <a onclick="window.open(this.href); return false;" href="/path/to/page">Some link text</a>

• 'query'

  A query string to append to the link, or an array of query key/value properties.

  Example

  <?php print l('Some link text', 'path/to/page', array('query' => 'id=4')); ?>

  Some link text

  <a href="/path/to/page?id=4">Some link text</a>

• 'fragment'

  A fragment identifier (named anchor) to append to the link. Do not include the '#' character.

  Example 1

  <?php print l('Some link text', 'path/to/page', array('fragment' => 'half-way-down')); ?>

  Some link text

  <a href="/path/to/page#half-way-down">Some link text</a>

  Example 2

  <?php print l('Some link text', '', array('fragment' => ' ', 'external' => TRUE)); ?>

  Some link text

  <a href="#">Some link text</a>

  Note the external=TRUE and the space in the fragment will add a hash-only link

• '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.

  Example

  <?php print l(t('Some link text'), 'path/to/page', array('absolute' => TRUE)); ?>

  Some link text

  <a href="http://www.example.com/path/to/page">Some link text</a>

• 'html' (default FALSE)

  Whether the title 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.

  Example 1

  <?php print l('Some link text &raquo;', 'path/to/page', array('html' => TRUE)); ?>

  Some link text »

  <a href="/path/to/page">Some link text &raquo;</a>

  NB. with html set to false we would get <a href="/path/to/page">Some link text &amp;raquo;</a> - Some link text &raquo;

  Example 2

  <?php print l('<img src="/path/to/images/image.png" alt="An image" />', 'path/to/page', array('html' => TRUE)); ?>

  <a href="/path/to/page"><img src="/path/to/images/image.png" alt="An image" /></a>

  NB. with html set to false we would get <img src="/path/to/images/image.png" alt="An image" />

• 'alias' (default FALSE)

  Whether the given path is an alias already.

  Example

  <?php print l('Some link text', 'node/999', array('alias' => TRUE)); ?>

  <?php
   print l('Some link text', 'node/999', array('alias' => TRUE)); 
  ?>

  <a href="node/999">Some link text</a>

Return value

an HTML string containing a link to the given path.