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_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.
File
- includes/
common.inc, line 1617 - Common functions that many Drupal modules will need to reference.
Code
<?php
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>';
}
?>
Comments
It is not necessary to wrap
It is not necessary to wrap the $text argument with t() as long as the html option is FALSE (the default). l() will automatically check_plain() the link text for you.
check_plain() and t() are different
t() is necessary if you are providing translatable text. The purpose of t() is to provide translation, while check_plain() is used to escape any possible malicious character. Often t() is used an easy way to provide secure text since it pushes things through check_plain, but this is just an added bonus. use t() for translating!.
Example with custom class, attributes
This will produce a link with the class="widelink" and rel="lightbox" attributes on the a tag.
<?phpl(
t('My link'),
'node/56',
array(
'attributes' => array(
'class' => 'widelink',
'rel' => 'lightbox',
)
)
);
?>
Open link a in new window
All components are already mentioned but no example straight into you face, so to open link in new windows use:
<?phpl(t('Title'),$url, array('attributes' => array('target' => '_blank')));
?>
Hope this will save time for some of you.
Valid HTML
That's helpful but the HTML won't validate for strict doc types.
Something like the following code should work:
<?phpl(t('Title'), $url, array('attributes' => array('onclick' => 'window.open(this.href); return false;')));
?>
Links to an anchor, or hash-only links
To create a link to a named anchor (e.g. #namedanchor), you will need to use a small work-around.
<?phpl('linktext', '', array('fragment' => 'namedanchor', 'external' => TRUE));
?>
To create a hash-only link (to #), you'll need to adapt it to:
<?phpl('linktext', '', array('fragment' => ' ', 'external' => TRUE));
?>
(Note that the fragment does contain a space.)
how to prevent l() from screwing up an ubercart purchase link
In porting a D5 site to D6, I found within their Ubercart logic they are generating a purchase item image-link like this:
$buy_img = theme_image('sites/all/themes/customTheme/images/buy.png', 'BUY', 'Buy The' . check_plain($node->title), array('class' => 'coins'));$buy_link = 'cart/add/e-p' . $node->nid . '_q1_m0?destination=cart/checkout';
print l( $buy_img, $buy_link, array('html' => true) );
The problem is the l() function is supposed to generate this:
http://localhost/cart/add/e-p176_q1_m0?destination=cart/checkoutbut is generating this incorrect link with character encoding rather than '?' and '=' characters:
http://localhost/cart/add/e-p176_q1_m0%3Fdestination%3Dcart/checkoutApparently, the D5 l() function does not do that same character encoding, and was not an issue... So here's the fix for D6:
$buy_link = 'cart/add/e-p' . $node->nid . '_q1_m0';print l( $buy_img, $buy_link, array('html' => true, 'query' => 'destination=cart/checkout') );
The solution being to place the query string portion of the link into a 'query' attribute.
Add permissions to view links
I thought this was helpful...
if (user_access('create blog entries')) {$items[] = l(t('Create new blog entry.'), "node/add/blog");
}
Used in blog module function blog_page_last
Internal Module Links
To clarify for those who want their module to support the 'Clean URLs' option.
<?php$var = l("Click Text", "ModuleName");
?>
returns a link complete with
<a href=tags.For a link that goes with your hook_menu() and 'page arguments' you just add the arguments to the path.
<?php$var = l("Click Text", "ModuleName/value/value");
?>
If you need a link without the
<a href=tags use 'url' instead.<?php$var = url("ModuleName/value/value")
?>
Examples
Various implementation of l() function
simple:
<?phpl(t('Link text'), 'about-us');
?>
with class:
<?phpl(t('Link text'), 'about-us', array('attributes' => array('class' => 'about-link')));
?>
link to user:
<?phpl(t($user->name), 'user/'.$user->uid, array('attributes' => array('class' => 'link', 'id' => 'xxx', 'title' => 'Title')));
?>
Always use user/user id!!!
simple link with image:
<?php$img = '<img src="'.$base_path . $directory . '/images/rssIcon.png" />';
l($img, 'user/3', array('html' => array('html' => 'true')));
// also valid
l($img, 'user/3', array('html' => 'true'));
?>
complex link with image:
<?phpl($img, 'user/3', array('attributes' => array('class' => 'link', 'id' => 'xxx', 'title' => 'Title'), 'html' => 'true'));
?>
Some of those examples
*might* lead to security issues.. (I mean... sure I did some of those mistakes... back in the days... :) )
the l() function sanitize the first argument (the text) when the option "html" isn't TRUE...
it means that you need to really take care about what the first argument will be if using the "html" option
For example:
<?php// making an img tag like might not be the safest solution
//$img = '<img src="'.$base_path . $directory . '/images/rssIcon.png" />';
// this would be much better, but still, you need to know that the $directory variable is also safe
$img = theme('image', $directory .'/images/rssIcon.png');
// this is, I think, not possible...
//l($img, 'user/3', array('html' => array('html' => 'true')));
// is ok
l($img, 'user/3', array('html' => 'true'));
?>
<?php// well, stop me if I am wrong, but I guess might be useful to wrap $user->name within t()..
//l(t($user->name), 'user/'.$user->uid, array('attributes' => array('class' => 'link', 'id' => 'xxx', 'title' => 'Title')));
// Something who might be handy if you need to "define" an HTML id is the form_clean_id()
// it will prevent to have twice the same id in the HTML (which is bad :) )
l($user->name, 'user/'.$user->uid, array('attributes' => array('class' => 'link', 'id' => form_clean_id('xxx'), 'title' => 'Title')));
?>
Just a note..
if you need to have a variable in a translation.. like it might have been the case in the example
<?phpl(t('Some string related to @user_name', array(
'@user_name' => $user->name
)), 'user/'. $user->uid);
// I might explain why it might be better to use @user_name over a simple @user... but it's not the topic ;)
?>
or...
<?phptheme('username', $user);
// whatever..
?>
anyway, it was nice from you to help!
t() is only for translatable strings
I don't think it is a good idea to use t($user->name)
This may create a translatable string for each user name. The translator will never reach a hundred per cent translation unless he translates each username, and if he does so he will change a value he shouldn't change.
I'd suggest to use t() every time a string needs to be translated, and in no other circumstance.
in $options you forget to
in $options you forget to explain language options, to protect links against language prefix names like 'site.name.com/en/sites/defailt/files/blag.pdf'
I protect my site against this using below solution
<?php$link = l($title, $path, array('language' => 'pl'));
?>
'boxes' table in database
<?phpl($img, 'user/3', array('attributes' => array('class' => 'link', 'id' => 'xxx', 'title' => 'Title'), 'html' => 'true'));
?>
For Drupal6
If you look at the description of the function in Drupal 6 parameters you will find under $options:
But I was not able to put additional parameters into URL in this case:
print l("Click here", $internal_path, array('listing_url' => 'data'
));
So I made the following changes as the user described above and it worked:
print l("Click here", $internal_path, array('query' => array(
'listing_url' => 'data'
),
));
Title and Alt attributes are sanitized
Actually all the "attributes" values are sanitized in
drupal_attributes, so if you do anything to sanitize it yourself, you can end up double encoding. For example, l($title, $path, array('attributes' => array('title' => t('All about @names', array('@names' => 'Adam & Eve'))))) will result in the ampersand being double encoded. In this example, it is okay to use '!names' becausedrupal_attributeswill do acheck_plainfor you.Link to #
to create a hash-only link (to #) you'll need to adapt it to:
l('linktext', '', array('fragment' => ' ', 'external' => TRUE));
(note that fragment does contains a space.)
Thanks to alexanderpas!
Can't figure out how to
Can't figure out how to combine attributes and fragment, since I need both - the first one to apply a class, second one to generate proper URI to the comment. What is wrong in my code below?
<?php$block_content .= l(t('Conversate'), "node/$links->nid", array('attributes'=>array('class'=>'comment')), array('fragment' => "comment-$links->cid")).'</div>';
?>
I rewrote your code with the
I rewrote your code with the correct syntax (I think but have not tested)
Main problem was: 'fragment' should not be in another array but just a key of the $options array.
<?php$block_content .= l(t('Conversate'), "node/".$links->nid, array('attributes'=>array('class'=>'comment'), 'fragment' => "comment-".$links->cid).'</div>';
?>
If this code doesn't work, here is my code wich, I'm sure works. Hope it will help you
<?php
print l("<span>View responses</span>", "node/".$fields['nid']->content,
array(
'fragment' => 'responses',
'attributes' => array (
'class' => 'btn_arrow_blue'
),
'html' => TRUE
)
);
?>
Pretty much the same: a "class" attribute, an anchor and some html in the label (that's why I need the 'html' => TRUE
It builds:
<a class="btn_arrow_blue" href="/node'spath#responses"><span>View responses</span>
</a>
Properly using destination
If you want to use the l() function and provide the destination:
<?phpl('Login first','user/login', array(
'query' => array(
'destination' => 'node/'. $node->nid
)
)
);
?>
The above code will provide you with an anchor tag with the href pointed to
user/login?destination=node/NIDThis is only useful if you are linking to a page that consist of a form, and you want the user to be redirected to another page after submitting the form.
For all other options available, make sure to see the documentation for the url() function.
drupal_get_destination()
You can use the destination of the current page with drupal_get_destination() like so
<?phpl(
t('edit'),
'node/'.$nid.'/edit',
array(
'query' => drupal_get_destination()
)
);
?>
Links with Javascript or jQuery
If you want to use a link like an event-handler, your code could look like this:
$link = l("Click me", $_GET['q'], array("attributes" => array("title" => t("Click this link"), "onclick" => '$("div.element_with_onclick_event").trigger("click");'), 'fragment' => 'anything'));This will create an HTML-Markup like this:
<a class="active" onclick="$("div.element_with_onclick_event").trigger("click");" title="Click this link " href="/current_path#anything">Click me</a>When you click on this link, the Trigger-Event "Click" for div.element_with_onclick_event will be called...
Don't forget print
I thought it might help some people to say that sometimes you need to add print, like so:
<?phpprint l(t('Link text'), 'node/10');
?>