l | common.inc | Drupal 7

5 common.inc	`l($text, $path, $attributes = array(), $query = NULL, $fragment = NULL, $absolute = FALSE, $html = FALSE)`
6 common.inc	`l($text, $path, $options = array())`
7 common.inc	`l($text, $path, array $options = array())`
8 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.

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_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, with 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

An HTML string containing a link to the given path.

▸ 145 functions call l()

▾ 145 functions call 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.
BlockTestCase::testCustomBlock in modules/block/block.test: Test creating custom block, moving it to a specific region and then deleting it.
block_help in modules/block/block.module: Implements hook_help().
BlogTestCase::verifyBlogs in modules/blog/blog.test: Verify the logged in user has the desired access to the various blog nodes.
blog_user_view in modules/blog/blog.module: Implements hook_user_view().
blog_view in modules/blog/blog.module: Implements hook_view().
BookTestCase::checkBookNode in modules/book/book.test: Check the outline of sub-pages; previous, up, and next; and printer friendly version.
book_admin_edit_submit in modules/book/book.admin.inc: Handle submission of the book administrative page form.
book_admin_overview in modules/book/book.admin.inc: Returns an administrative overview of all books.
book_render in modules/book/book.pages.inc: Menu callback; prints a listing of all books.
comment_form_submit in modules/comment/comment.module: Process comment form submissions; prepare the comment, store it, and set a redirection target.
comment_reply in modules/comment/comment.pages.inc: This function is responsible for generating a comment reply form. There are several cases that have to be handled, including:
CommonURLUnitTest::testLActiveClass in modules/simpletest/tests/common.test
CommonURLUnitTest::testLCustomClass in modules/simpletest/tests/common.test: Tests for custom class in l() function.
CommonURLUnitTest::testLXSS in modules/simpletest/tests/common.test: Confirm that invalid text given as $path is filtered.
contact_category_edit_form_submit in modules/contact/contact.admin.inc: Form submission handler for contact_category_edit_form().
contact_category_list in modules/contact/contact.admin.inc: Categories/list tab.
dashboard_permission in modules/dashboard/dashboard.module: Implements hook_permission().
dblog_event in modules/dblog/dblog.admin.inc: Menu callback; displays details about a log message.
DrupalTestCase::verbose in modules/simpletest/drupal_web_test_case.php: Logs verbose message in a text file.
drupal_pre_render_link in includes/common.inc: #pre_render callback to render a link into #markup.
field_help in modules/field/field.module: Implements hook_help().
field_system_info_alter in modules/field/field.module: Implements hook_system_info_alter().
field_ui_fields_list in modules/field_ui/field_ui.admin.inc: Menu callback; lists all defined fields for quick reference.
filter_permission in modules/filter/filter.module: Implements hook_permission().
ForumTestCase::verifyForums in modules/forum/forum.test: Verify the logged in user has access to a forum nodes.
ForumTestCase::verifyForumView in modules/forum/forum.test: Verify display of forum page.
forum_node_view in modules/forum/forum.module: Implements hook_node_view().
help_links_as_list in modules/help/help.admin.inc: Provides a formatted list of available help topics.
help_page in modules/help/help.admin.inc: Menu callback; prints a page listing general help for a module.
hook_requirements in modules/system/system.api.php: Check installation requirements and do status reporting.
hook_user_view in modules/user/user.api.php: The user's account information is being displayed.
hook_view in modules/node/node.api.php: Display a node.
ImageFieldDisplayTestCase::_testImageFieldFormatters in modules/image/image.test: Test image formatters on node display.
locale_date_format_language_overview_page in modules/locale/locale.admin.inc: Display edit date format links for each language.
menu_edit_item in modules/menu/menu.admin.inc: Menu callback; Build the menu link editing form.
menu_get_active_breadcrumb in includes/menu.inc: Get the breadcrumb for the current page, as determined by the active trail.
menu_overview_page in modules/menu/menu.admin.inc: Menu callback which shows an overview page of all the custom menus and their descriptions.
ModuleUpdater::postInstallTasks in modules/system/system.updater.inc: Return an array of links to pages that should be visited post operation.
node_form_submit in modules/node/node.pages.inc
node_overview_types in modules/node/content_types.inc: Displays the content type admin overview page.
node_page_default in modules/node/node.module: Menu callback; Generate a listing of promoted nodes.
node_requirements in modules/node/node.module: Implements hook_requirements().
node_revision_overview in modules/node/node.pages.inc: Generate an overview table of older revisions of a node.
node_title_list in modules/node/node.module: Gathers a listing of links to nodes.
node_type_form_submit in modules/node/content_types.inc: Form submission handler for node_type_form().
openid_user_identities in modules/openid/openid.pages.inc: Menu callback; Manage OpenID identities for the specified user.
path_admin_overview in modules/path/path.admin.inc: Return a listing of all defined URL aliases.
poll_page in modules/poll/poll.pages.inc: Menu callback to provide a simple list of all polls available.
profile_admin_overview in modules/profile/profile.admin.inc: Form builder to display a listing of all editable profile fields.
profile_block_view in modules/profile/profile.module: Implements hook_block_view().
profile_field_delete_submit in modules/profile/profile.admin.inc: Process a field delete form submission.
profile_field_form_submit in modules/profile/profile.admin.inc: Process profile_field_form submissions.
profile_view_field in modules/profile/profile.module
SearchConfigSettingsForm::setUp in modules/search/search.test: Generates a random database prefix, runs the install scripts on the prefixed database and enable the specified modules. After installation many caches are flushed and the internal browser is setup so that the page requests will run on the new prefix.…
SearchRankingTestCase::testHTMLRankings in modules/search/search.test: Test rankings of HTML tags.
search_view in modules/search/search.pages.inc: Menu callback; presents the search form and/or search results.
seven_admin_block_content in themes/seven/template.php: Overrides theme_admin_block_content().
seven_node_add_list in themes/seven/template.php: Display the list of available node types for node creation.
shortcut_set_admin in modules/shortcut/shortcut.admin.inc: Menu page callback: builds the page for administering shortcut sets.
shortcut_set_customize in modules/shortcut/shortcut.admin.inc: Form callback: builds the form for customizing shortcut sets.
StatisticsReportsTestCase::testPopularContentBlock in modules/statistics/statistics.test: Tests the "popular content" block.
statistics_access_log in modules/statistics/statistics.admin.inc: Menu callback; Displays recent page accesses.
statistics_node_tracker in modules/statistics/statistics.pages.inc
statistics_recent_hits in modules/statistics/statistics.admin.inc: Menu callback; presents the "recent hits" page.
statistics_top_visitors in modules/statistics/statistics.admin.inc: Menu callback; presents the "top visitors" page.
statistics_user_tracker in modules/statistics/statistics.pages.inc
syslog_form_system_logging_settings_alter in modules/syslog/syslog.module: Implements hook_form_FORM_ID_alter().
system_actions_manage in modules/system/system.admin.inc: Menu callback; Displays an overview of available and configured actions.
system_date_time_formats in modules/system/system.admin.inc: Displays the date format strings overview page.
system_ip_blocking in modules/system/system.admin.inc: Menu callback. Display blocked IP addresses.
system_requirements in modules/system/system.install: Test and report Drupal installation requirements.
system_token_info in modules/system/system.tokens.inc: Implements hook_token_info().
system_update_7013 in modules/system/system.install: Convert default time zone offset to default time zone name.
tablesort_header in includes/tablesort.inc: Format a column header.
TaxonomyTermIndexTestCase::testTaxonomyTermHierarchyBreadcrumbs in modules/taxonomy/taxonomy.test: Tests that there is a link to the parent term on the child term page.
taxonomy_form_term_submit in modules/taxonomy/taxonomy.admin.inc: Submit handler to insert or update a term.
taxonomy_form_vocabulary_submit in modules/taxonomy/taxonomy.admin.inc: Form submission handler for taxonomy_form_vocabulary().
taxonomy_term_page in modules/taxonomy/taxonomy.pages.inc: Menu callback; displays all nodes associated with a term.
template_preprocess_aggregator_feed_source in modules/aggregator/aggregator.pages.inc: Processes variables for aggregator-feed-source.tpl.php.
template_preprocess_aggregator_item in modules/aggregator/aggregator.pages.inc: Processes variables for aggregator-item.tpl.php.
template_preprocess_comment in modules/comment/comment.module: Process variables for comment.tpl.php.
template_preprocess_forums in modules/forum/forum.module: Process variables for forums.tpl.php
template_preprocess_forum_topic_list in modules/forum/forum.module: Preprocess variables to format the topic listing.
template_preprocess_user_picture in modules/user/user.module: Process variables for user-picture.tpl.php.
ThemeUpdater::postInstallTasks in modules/system/system.updater.inc: Return an array of links to pages that should be visited post operation.
theme_admin_block_content in modules/system/system.admin.inc: Returns HTML for the content of an administrative block.
theme_book_admin_table in modules/book/book.admin.inc: Returns HTML for a book administration form.
theme_book_title_link in modules/book/book.module: Returns HTML for a link to a book title when used as a block title.
theme_comment_block in modules/comment/comment.module: Returns HTML for a list of recent comments to be displayed in the comment block.
theme_dashboard_disabled_blocks in modules/dashboard/dashboard.module: Returns HTML for a set of disabled blocks, for display in dashboard customization mode.
theme_dblog_message in modules/dblog/dblog.admin.inc: Returns HTML for a log message.
theme_feed_icon in includes/theme.inc: Returns HTML for a feed icon.
theme_file_link in modules/file/file.module: Returns HTML for a link to a file.
theme_filter_tips_more_info in modules/filter/filter.module: Returns HTML for a link to the more extensive filter tips.
theme_image_formatter in modules/image/image.field.inc: Returns HTML for an image field formatter.
theme_image_style_list in modules/image/image.admin.inc: Returns HTML for the page containing the list of image styles.
theme_image_style_preview in modules/image/image.admin.inc: Returns HTML for a preview of an image style.
theme_links in includes/theme.inc: Returns HTML for a set of links.
theme_locale_languages_overview_form in modules/locale/locale.admin.inc: Returns HTML for the language overview form.
theme_menu_link in includes/menu.inc: Returns HTML for a menu link and submenu.
theme_menu_local_action in includes/menu.inc: Returns HTML for a single local action link.
theme_menu_local_task in includes/menu.inc: Returns HTML for a single local task link.
theme_more_help_link in includes/theme.inc: Returns HTML for a "more help" link.
theme_more_link in includes/theme.inc: Returns HTML for a "more" link, like those used in blocks.
theme_node_add_list in modules/node/node.pages.inc: Returns HTML for a list of available node types for node creation.
theme_node_recent_block in modules/node/node.module: Returns HTML for a list of recent content.
theme_node_recent_content in modules/node/node.module: Returns HTML for a recent node to be displayed in the recent content block.
theme_pager_link in includes/pager.inc: Returns HTML for a link to a specific query result page.
theme_system_compact_link in modules/system/system.module: Returns HTML for a link to show or hide inline help descriptions.
theme_toolbar_toggle in modules/toolbar/toolbar.module: Formats an element used to toggle the toolbar drawer's visibility.
theme_update_last_check in modules/update/update.module: Returns HTML for the last time we checked for update data.
theme_update_report in modules/update/update.report.inc: Returns HTML for the project status report.
theme_update_version in modules/update/update.report.inc: Returns HTML for the version display of a project.
theme_username in includes/theme.inc: Returns HTML for a username, potentially linked to the user's page.
theme_user_admin_roles in modules/user/user.admin.inc: Returns HTML for the role order and new role form.
tracker_page in modules/tracker/tracker.pages.inc: Menu callback; prints a listing of active nodes on the site.
translation_node_overview in modules/translation/translation.pages.inc: Overview page for a node's translations.
trigger_assign_form in modules/trigger/trigger.admin.inc: Returns the form for assigning an action to a trigger.
UpdateCoreTestCase::testNormalUpdateAvailable in modules/update/update.test: Tests the update module when one normal update ("7.1") is available.
UpdateCoreTestCase::testSecurityUpdateAvailable in modules/update/update.test: Tests the update module when a security update ("7.2") is available.
UpdateTestContribCase::testHookUpdateStatusAlter in modules/update/update.test: Check that hook_update_status_alter() works to change a status.
UpdateTestContribCase::testNoReleasesAvailable in modules/update/update.test: Tests when there is no available release data for a contrib module.
UpdateTestContribCase::testUpdateBaseThemeSecurityUpdate in modules/update/update.test: Test that subthemes are notified about security updates for base themes.
UpdateTestContribCase::testUpdateBrokenFetchURL in modules/update/update.test: Make sure that if we fetch from a broken URL, sane things happen.
UpdateTestContribCase::testUpdateContribBasic in modules/update/update.test: Test the basic functionality of a contrib module on the status report.
UpdateTestContribCase::testUpdateContribOrder in modules/update/update.test: Test that contrib projects are ordered by project name.
UpdateTestContribCase::testUpdateShowDisabledThemes in modules/update/update.test: Test that disabled themes are only shown when desired.
UpdateTestHelper::standardTests in modules/update/update.test: Run a series of assertions that are applicable for all update statuses.
update_manager_update_form in modules/update/update.manager.inc: Build the form for the update manager page to update existing projects.
UpgradePathTaxonomyTestCase::testTaxonomyUpgrade in modules/simpletest/tests/upgrade/upgrade.taxonomy.test: Basic tests for the taxonomy upgrade.
UserAdminTestCase::testUserAdmin in modules/user/user.test: Registers a user and deletes it.
user_account_form in modules/user/user.module: Helper function to add default user account fields to user registration and edit form.
user_login_block in modules/user/user.module
user_register_submit in modules/user/user.module: Submit handler for the user registration form.
user_update_7002 in modules/user/user.install: Convert user time zones from time zone offsets to time zone names.
_locale_translate_seek in includes/locale.inc: Perform a string search and display results in a table
_menu_overview_tree_form in modules/menu/menu.admin.inc: Recursive helper function for menu_overview_form().
_node_mass_update_batch_process in modules/node/node.admin.inc: Node Mass Update Batch operation
_openid_user_login_form_alter in modules/openid/openid.module
_statistics_link in modules/statistics/statistics.module: It is possible to adjust the width of columns generated by the statistics module.
_update_requirement_check in modules/update/update.install: Private helper method to fill in the requirements array.

File

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

Code

<?php
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

Class attributes must be array

Posted by tanoshimi on June 11, 2010 at 2:08pm

Note that to attach a class to a link via the $attributes array, then the class element itself must also be an array (even if it contains a single element)

In other words, Drupal 6.x:

<?php
  l(t('Link text'), 'about-us', array('attributes' => array('class' => 'about-link')));
?>

Drupal 7.x:

<?php
  l(t('Link text'), 'about-us', array('attributes' => array('class' => array('about-link'))));
?>

So, are we to assume...

Posted by johnvsc on February 9, 2011 at 3:10am

that multiple classes would be this:

<?php
  l(t('Link text'), 'about-us', array('attributes' => array('class' => array('about-link','another-class'))));
?>

Nope

Posted by rjbrown99 on August 6, 2011 at 10:24pm

Nope, multiple classes seems to be this - one array key, multiple values separated by a space.

<?php
  l(t('Link text'), 'about-us', array('attributes' => array('class' => 'about-link another-class')));
?>

Um, nope!

Posted by paul2 on January 31, 2012 at 3:45pm

So that is correct for D6, @rjbrown99, but in D7 the 'class' attribute value must be an array (see the $options parameter explained above). Just see how l() manipulates the 'class' attribute in the function body above; that code will break if you pass a string as you suggested.

Wrong:

<?php
  l(t('Link text'), 'about-us', array('attributes' => array('class' => 'about-link another-class')));
?>

Right:

<?php
  l(t('Link text'), 'about-us', array('attributes' => array('class' => array('about-link', 'another-class'))));
?>

ajax links

Posted by sirkitree on March 14, 2011 at 9:00pm

Most of the time an ajax link is just a fragment:
href="#"

In order to accomplish this, use the 'fragment' in $options. ex:

<?php
l(t('Refresh'), '', array('attributes' => array('id' => 'refresh-link-id', 'class' => 'refresh-link'), 'fragment' => 'refresh'));
?>

This will output the following:

<a href="/#refresh" id="refresh-link-id" class="refresh-link">Refresh</a>

Create link with target='_blank'

Posted by MichaelCole on March 18, 2011 at 11:38pm

l(t('View Map & Directions'), $map_address_url, array('attributes' => array('target'=>'_blank')))

Attach destination to link url

Posted by Ypthor on March 28, 2011 at 10:29am

e.g. if url points to a page with a form, you'll be redirected to destination url

<?php
l('Title', 'url', array('query' => array('destination' => 'destination_url')))
?>

This creates:

<a href="url?destination=destination_url">Title</a>

More options at once

Posted by borgo on April 19, 2011 at 2:13pm

Combination of the above.

<?php
        global $base_url;

        print l(
          '<img src="' . render(file_create_url($node->field_image['en'][0]['uri'])) . '"/>', 
          $base_url . $node_url, 
            array(
              'attributes' => array(
                'id' => 'my-id', 
                'class' => 'my-class'
              ), 
              'query' => array(
                'foo' => 'bar'
              ), 
              'fragment' => 'refresh',
              'html' => TRUE
            )
        );
?>

Creates:

<a href="http://www.example.com/node/1?foo=bar#refresh" id="my-id" class="my-class"><img src="http://www.example.com/files/image.jpg"/></a>

Perfect

Posted by crossfish on October 5, 2011 at 6:30pm

Now that's what I call a great comment. Shows the what/how and the final output. Thanks borgo!

watch out for error

Posted by batigolix on January 3, 2012 at 9:36am

borgo's code example contains an error, though

<?php
  'attributes' => array(
    'id' => 'my-id',
    'class' => 'my-class'
  ),
<
?>

should read:

<?php
  'attributes' => array(
    'id' => 'my-id',
    'class' => array('my-class')
  ),
<
?>

Classes must be placed in an array. See http://api.drupal.org/api/drupal/includes--common.inc/function/l/7#comme...

If you want a simple

Posted by geerlingguy on June 29, 2011 at 10:21pm

If you want a simple anchor/fragment link (similar to what sirkitree said in the ajax links comment above), but with just the anchor (href="#namedanchor"), do something like the following:

<?php
l(t('My Anchor Link'), '', array(
  'fragment' => 'namedanchor',
  'external' => TRUE,
  'attributes' => array(
    'title' => 'Title here.'
  ),
));
?>

This outputs:

<a href="#namedanchor" title="Title here.">My Anchor Link</a>

You cannot use the l() function to create a simple 'name' anchor, though (like <a name="namehere"></a>). For this, you'll need to create the link manually.

How about '<a href="edit?id=1">'

Posted by chenxing678 on June 23, 2011 at 2:24am

How about ''

link to javascript:void(0)

Posted by FOOLVER on August 20, 2011 at 10:01am

here is a hint to link to javascript:void(0)

l($text,'javascript:void(0)',array('fragment' => '','external'=>true));

D7 linked image

Posted by ishmael-sanchez on October 12, 2011 at 10:25pm

Change field and style name to suit your needs.

<?php
 l(theme_image_style(array('path' => $variables['node']->field_logo['und']['0']['uri'], 'style_name' => '100x100')), 'node/' . $variables['node']->nid, array('html' => TRUE));
?>

Local anchor

Posted by vertikal.dk on January 3, 2012 at 10:57am

If you want to link to a local anchor (# on the same page), it requires a bit of tweaking. Using an empty path will lead to the root of the site, so you need to pump in the current path using $_GET['q'].

This example will create a local link to the comments section of a node:

<?php
 $link = l(t('Comments'), $_GET['q'], array('fragment' => 'comments')); 
?>

In a node located on the address http://mysite.tld/my_node this will output http://mysite.tld/my_node#comments

Martin

l