Community Documentation

l

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()

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

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

that multiple classes would be this:

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

Nope

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!

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

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'

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

Attach destination to link url

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

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

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

watch out for error

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

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">'

How about ''

link to javascript:void(0)

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

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

D7 linked image

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

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

Login or register to post comments