4 Link Formats

4.1 About Link Formats

There are many ways to make a link in Site Studio. You use the expected HTML path-based link, as well as some Site Studio extensions that maximize the portability and reusability of the architecture in Site Studio 11g.

Within the Site Studio-specific methods, there are three main types of links. There are links to a content file (such as a data file or a native document), links to a node, and links to a static resource, such as an image.

4.2 Using Path-Based Links

A path-based link is simply a link using a path. You can use Idoc Script variables to replace a section of the path if you wish. The variable will be evaluated by the server and replaced in the served HTML.

Path-based links can be written as absolute or relative. Relative links, as well as links using an Idoc variable, are recommended because they are more portable. Absolute links are very easily broken when the site is modified. The only time an absolute link is recommended is when linking to an outside website.

When a path-based link is created using the Link Wizard, the portion of the path from the server to the Web site root is replaced with an Idoc variable.

Examples

The basic path-based link is a full URL just as expected:

http://www.oracle.com/support/index.html

The same link created using an Idoc variable (specifically ssServerRelativeSiteRoot) would look like this:

<!--$ssServerRelativeSiteRoot-->support/index.html
<a href="[!--$ssServerRelativeSiteRoot--]support/index.html">

Note that the content in the variable includes the final "/" in the path segment.

Relative paths are used as they would be in any static HTML instance:

../../support/index.html
<a href="../../support/index.html">

In some examples, you may see the angle bracket used (for example, <!--$wcmUrl('nodelink', '30)-->), and in other examples, you may see the square bracket used ([!--$wcmUrl('nodelink', '30)--]. Site Studio writes the square bracket to XML files and other places where an angle bracket might cause escaping problems, and it writes the square bracket to templates. You should know that they can be used interchangeably; however you should keep in mind which instance might cause a problem with escaping when you choose to use one or the other.

4.3 Using wcmUrl

This is a script-extension designed to encapsulate the other link forms, specifically the server-side ssNodeLink, ssLink, and ssWeblayoutUrl. This is the recommended link format to use with Site Studio to make the most of its use.

It only requires one parameter, the type. The other parameters may or may not be required depending on the type specified.

The wcmUrl script extension is a server-side script link that incorporates the functionality of the script links listed in "Using Server-Side Script Links". Maintaining them all using one script extension allows not only for use with Oracle Web Content Management, but also makes it easier to search out the links in a content file or template.

Parameters

• type: the type of link, entered as one of the following. [nodelink | link | resource]Nodelink is used to create links to sections, which by default end with index.htm. Link is used to create links to content, which by default end with <contentId>. Resource is used to link to weblayout static resources, such as images.

• nodeId: the ID of the node referenced. Used only when the type is set to either nodelink or link.

• siteId: the site ID of the Web site referenced. Used only when the type is set to either nodelink or link.

• dDocName: the dDocName of the content referenced. Used only when the type is set to either link or resource.

• Xpath: path to the content referenced. Used only when the type is set to either link or resource.

Examples

Before evaluation:

[!--$wcmUrl('link', 'switched_region_CDF')--]
[!--$wcmUrl('nodelink', '30')--]
[!--$wcmUrl('resource' 'groups/public/documents/adacct/mydocname.jpg')--]

These examples use single quotes for the parameters. Other examples may show double quotes. Both work, however, just as with the angle bracket and square bracket, there may be some instances where using one instead of the other will help prevent possible escaping problems.

Evaluated by the server:

<a href="http://YourUrl.com/Website/support/CRM/switch.html"
<a href="http://YourUrl.com/Website/region/West/">
<a href="http://YourUrl.com/Website/groups/public/documents/adacct/mydocname.jpg">

The first line shows a link to a content file referenced by the dDocName, the second is a link to a node referenced by the nodeId, and the third is a link to the XPath of an image file on the Oracle Content Server.

If a value for a link evaluates as bad, such as when it is linked to a resource is no longer there, then the link evaluates as a token link. For more information, see "Token Links as Returned Server-Side Links".

4.4 Using Server-Side Script Links

A server-side script link is a link that is written in script, but is then evaluated by the server and replaced in the displayed HTML. If someone chooses to view the source of the displayed page, they will only see the URL (either a relative or a full URL).

The server-side script links are written in Idoc Script. Whether it is a variable or a function call, the server-side link evaluates on the server and you will never see it in the displayed Web page's source.

Contains these topics:

• "ssLink"

• "ssNodeLink"

• "ssWebLayoutUrl"

[!--$ssLINK('dDocName')--]

<a href="http://YourUrl.com/Website/section/subsection/content/index.htm">

[!--$ssNodeLink('30')--]

<a href="http://YourUrl.com/Website/support/CRM">

[!--$ssWebLayoutUrl('groups/public/documents/adacct/mydocname.jpg')--]

<a href="http://YourUrl.com/Website/groups/public/documents/adacct/mydocname.jpg">

4.5 Using Token Links

Token links (also known as late-resolving links) are not resolved until they are actually clicked. View source would reveal a URL that has ssLINK or ssNODELINK in the URL. Token links are not resolved until they are clicked (thus the term "late-resolving," as the link resolution happens after the page is served). By comparison, the script links are resolved on the server before serving the Web page.

You should be aware that ssLINK and ssNODELINK are token links; although ssLink and ssNodeLink have the same name as ssLINK and ssNODELINK, the camel case ssLink and ssNodeLink are script links.

Token links are a recommended way of including a link in a native document. Because the Word doc goes through Dynamic Converter and converts to HTML, it is much easier to write them with token links. It is possible otherwise, but this way is simpler.

This section contains these topics:

• "ssLINK"

• "ssNODELINK"

• "Token Links as Returned Server-Side Links"

[!--$ssLINK('dDocName')--]

<a href="http://YourUrl.com/Website/ssLINK/dDocName">

[!--$ssNODELINK('10027')--]

<a href="http://YourUrl.com/Website/ssNODELINK/10027">

<!--$ssLink('Bad_dDocName')-->

<a href="http://YourUrl.com/Website/ssLINK/Bad_dDocName">

4.6 Using JavaScript Links

It is possible to use JavaScript to enter a link in a site asset. This is not recommended, but is still available as a possible method.

The links are used just as you would use ssLINK or ssNODELINK, with the same parameters. And like ssLINK and ssNODELINK, JavaScript links are late-evaluated. The only difference is in explicitly calling them as JavaScript.

Examples

javascript:link('dDocName')
javascript:nodelink('nodeId')