The TYPO3 link tag

This tutorial explains the components of the TYPO3 link tag that can be used in content elements and FCEs.

To enable an editor to put links (HTML a href tag) to a URL within a content element, TYPO3 provides a special tag called link. With this tag it is possible to set links to an internal page, an external web site, and to an e-mail address as well.

The generic structure of the link tag (all three variants) is as follows:

<link Target target-attribute CSS-class title-attribute>anchor text</link>

This will result in an a href tag of the form:

<a href="(converted) Target URL" class="CSS-class" target="target-attribute" title="title-attribute">anchor text</a>

A link tag can be inserted into a default content element (text, text with image etc.) as well as in Flexible Content Elements. Like other HTML tags, it has a unique identifer in an opening (here: "<link") and in a closing tag (here: "</link>"). Now, we will describe the different parts of the link tag.

The Target of a link is the only mandatory parameter of the TYPO3 link tag. All the other ones (target, class, and title) are optional. Depending on the type of link (internal, external, e-mail), a different Target needs to be provided:

To put a link to an internal page within the TYPO3 system, you use the unique ID (uid) of the target page as the Target. TYPO3 converts that uid into a valid URL. By doing so, it doesn't matter, whether SimulateStaticDocuments, realurl or none of those URL rewriting features has been activated.

This instruction generates a link to the page with uid 42:
 
<link 42>anchor text</link>

When defining an internal link, it is quite important that you use the unique ID. Because this ID will never change, links to the target page will still be valid, even if the alias or page title of the target page changes over time.

You can display the unique ID of a page, if you move your mouse over the page's icon in the page tree.

To link directly to an anchor on another page, you need to append the name of the anchor (i.e. content element) to the unique ID and separate both values with a hash character ('#'). If the anchor is on the current page, you can omit the unique ID and just write the hash followed by the anchor name.

You can display the uid of a content element by moving your mouse over the element's icon in the TYPO3 list module.

Linking to anchor '4711' on the page with uid 42:
 
<link 42#4711>link anchor text</link>

If the optional target attribute is omitted, TYPO3 will use the target that is defined in your TypoScript template record. Click here to learn, how to remove the default target='page' from link tags.

If the anchor text of the link is omitted, the title of the target page will be used instead.

If the target page can not be reached (e.g. if it's hidden, deleted, or access-restricted), just the link text without any link will be rendered.

A link to an external web site can be generated by writing its complete URL in the link tag. TYPO3 identifies an external link by the prefix http:// that has to be written before the actual web address.

External link to the TYPO3 link directory (typolink.org):
 
<link http://typolink.org>TYPO3 link directory</link>

If you omit the target attribute, the default target for external links (target="_blank") will be used in the generated link.

If you omit the link text, the external web site's URL will be used instead.

To generate an e-mail link, you just write the e-mail address into the link tag. TYPO3 uses the @ character to identify an e-mail address.

Link to the e-mail address info@example.com:
 
<link info@example.com>anchor text</link>

If the automatic e-mail encryption feature is enabled (TypoScript configuration spamProtectEmailAddresses), the linked e-mail address will be encrypted by a JavaScript function. This is done to avoid automatic e-mail grabbing by so called spam bots.

If the link text is omitted, the e-mail address will be used in the generated link instead.

The anchor text (the text that is wrapped in a link tag) is an important part of a link, not only when it comes to SEO (search engine optimization). Carefully chosen anchor texts are crucial for the usability of a site. They improve the understanding and orientation of the web site visitors.

If the anchor text is omitted, TYPO3 will insert an anchor text automatically, depending on the type of the link (internal, external, or e-mail).

The anchor text "Our Products" is used to link to internal page 42:
 
<link 42>Our Products</link>

Link to the TYPO3 link directory with empty anchor text
(will automatically be replaced by the given URL):
 
<link http://typolink.org></link>

By using the optional target attribute, you can define a target window, in which the linked page (internal or external) should be opened.

• page: Default for internal links in TYPO3 (How to remove the default target)
• _blank: Default for external links in TYPO3
• _top: Open on topmost window level (e.g. outside of HTML frames)
• 120x300: Open in a popup window of a given size (here: 120 pixels wide and 300 pixels high)
• - (dash): Must be specified if the default target shall be used and at least one of the subsequent attributes (class or title) is specified

Opens the internal page with uid 42 in a new browser window:
 
<link 42 _blank>anchor text</link>

Opens the homepage of the TYPO3 link directory in
a pop-up window of size 550x700 pixels using JavaScript:
 
<link http://typolink.org 550x700>anchor text</link>

The optional attribute class can contain a CSS (stylesheet) class that is used to modify the layout of the rendered link. The specified class needs to be defined in a stylesheet before, of course.

Using the CSS class 'highlight' in an internal link to page 42,
opened in a size 250x400 pop-up window:
 
<link 42 250x400 highlight>anchor text</link>

Using the CSS class 'external' in a link to the homepage of the
TYPO3 link directory, default target "_blank":
 
<link http://typolink.org - external>anchor text</link>

The optional title parameter can be used to specify a text for the title attribute of an a href tag. This text is displayed in a tooltip when moving the mouse over the generated link. Besides, this title text can also be used as additional information by search engine robots.

The text of this attribute must be wrapped by double quotes!

Using the text 'More information' as the title attribute of an
internal link to page with uid 42, opened in a new browser window,
no CSS class given:
 
<link 42 _blank - "More information">anchor text</link>

Using the text 'TYPO3 agencies and freelancers' as the title
attribute of a link to the typolink.org web site, default target
"_blank", no CSS class, no anchor text:
 
<link http://typolink.org - - "TYPO3 agencies and freelancers"></link>