Linking

Overview

Cascade CMS provides users with a number of different ways to manage links in content depending on the type of asset containing the link, the type of link, the type of asset being linked to (if the linked-to asset is inside the system), and the location of both assets.

Linking from the WYSIWYG

Users are able to use the WYSIWYG's link/unlink buttons to add and remove hyperlinks from pages. After clicking the Insert Link button, users are prompted to choose an internal, Cascade-managed asset (pages, files, external links) or enter an external link.

Managed Links in XML-Based Assets

Specific attributes of specific elements in XML-based assets are checked by Cascade to see if they contain links to managed assets. The XML-based assets are:

  • Pages
  • Templates
  • XML Blocks
  • XHTML Blocks
  • XSLT Formats

The following table provides a summary of elements and attributes automatically checked for links to managed content when editing, creating, or rendering the content.

Element href src background
a Yes No No
area Yes Yes Yes
body No Yes Yes
td No No Yes
table No No Yes
embed Yes Yes No
frame No Yes No
iframe No Yes No
img No Yes No
input Yes Yes Yes
param Yes Yes Yes
link Yes Yes No
script No Yes No

When the link attribute contains a path to an asset within Cascade, it is considered a "managed" link. Within an XML-based asset there are three primary ways to link to other assets managed within the system.

Linking from Files and Other Non-Recognized Attributes

To create links to other system managed assets in content that is either not XML-based or does not appear in a recognized attribute (see recognized attributes above), use the [system-asset] pseudo tags.

Examples of this include links to:

  • Background images in CSS styles.
  • Images referenced in JavaScript rollover code (either in JavaScript files or in page content).
  • Imported CSS files from other CSS files.

In order for these links to be managed and tracked by the system, users must wrap the link in Cascade's proprietary [system-asset] pseudo-tags.

[system-asset]/path[/system-asset]

This tag enables the user to specify a managed link to a page, file, or symlink in the system by supplying a path to it. The managed link will render properly both when using the asset within the system and upon publish. If these links are embedded in files, the file must have Rewrite links in file enabled in its Configure tab order for the system to recognize it as a link.

Here is an example using [system-asset] around the path for a CSS background image:

body {
   background: url('[system-asset]/site/marble.png[/system-asset]')
}

If used inside a site, site://[site-name]/path can be used inside the pseudo-tag to link to assets in other sites.

Note - If it is necessary to use a fully-qualified URL (i.e. absolute link), enable Maintain absolute links when rewriting under the file's Configure tab.

More Advanced Pseudo-Tags and Link Types

[system-asset:embedded-image]/path[/system-asset:embedded-image]

This tag is used for embedding images in PDF and RTF file formats. By supplying a path to the tag, the system is able to pass the appropriate image to the FO processor so that it can display in the resulting document.

[system-asset:configuration=output_name]/path[/system-asset:configuration]

This tag is used for supplying a link to a different output of the specified asset. By supplying the page path and the name of the desired output, Cascade will provide a link to the appropriate output.

<a system-page-output="outputformat">link </a>

This tag is used to link to a different output of the same page (the page containing the tag). By supplying a system-page-output attribute to an <a> tag containing an output name or a target name associated with that target, the CMS will link to that particular version of the page. The system-page-output attribute gets replaced by an <href> attribute with the correct path.

Links Between Pages and Page Outputs

Pages often publish to multiple locations with multiple output extensions by using configurations with more than one page output. Links within the page content that link to other pages will be rewritten differently upon publish depending on which page output they are being rewritten for and which output the target page has.

The following table shows three different pages, using different content types and configurations.

Page Content Type Configuration Output
PageA CT1 CS1 HTML (Default)
PageB XML
PageC CT2 CS2 ASP (Default)
XML

When a page links to another page, it tries to link to the same output. When PageA links to PageB inside the default output (HTML), then the link will direct to the HTML output. If PageA is linking to PageB in the XML output, the link will direct to the XML output. The pages stay in the same outputs unless specified (using [system-asset:configuration=HTML] for example).

Linking between PageA or PageB to PageC, which has different outputs, works a little differently. Since PageC does not have an HTML output, when PageA/PageB link to PageC in the HTML output, the link directs to the default output of PageC (ASP). There is no need to specify that PageA's HTML output needs to link to PageC's ASP output.

Linking from the XML output in PageA/PageB to PageC will stay in the XML output, since they are both named XML.

Link Rewriting Using Destination URLs

Once a page is published, links in that page to other assets managed in Cascade in the same site are rewritten using a relative link format, by default. Cross-site links are rewritten as fully-qualified links by prepending the linked-to site's URL property. It is possible to link from one output that publishes to one web server to another output that publishes to another web server, while both reside in the same "site" in Cascade.

Mobile Output Example

For example, when linking from a standard HTML output that publishes to http://example.com, to a mobile HTML output that publishes to http://m.example.com, the Mobile Destination URL will be used.

Here is a complete list of requirements for a Destination URL to be used when link rewriting:

  • Link points to a different output, either using a [system-asset:configuration] tag or simply linking to a page that has a different default output.
  • The linked-to output publishes only to selected destinations, which is specified at Content Type level.
  • Out of the selected Destinations, only one distinct Web URL property is specified; two or more Destinations can have a Web URL specified, but they must be identical.
  • The page that is currently being published that contains the link is not currently being published to a Destination with the Web URL.

Therefore, going back to the example above, the following setting would produce a link that uses Destination URL upon publish:

  • Page /pageA, standard HTML output links to /pageB's mobile HTML output using [system-asset:configuration=mobile]/pageB[/system-asset:configuration].
  • Page /pageA's standard HTML output publishes to Destination Standard, while /pageB's mobile HTML output publishes only to Destination Mobile - both configured at Content Type level.
  • Destination Mobile has a URL set to http://m.example.com. Destination Standard has a URL set to http://example.com.
  • The resulting link upon publish would look like this: http://m.example.com/pageB.html and it would be linked from a page located at: http://example.com/pageA.html.

Overriding the Site URL for Cross-Site Links

The Destination's Web URL, when specified, also overrides the Site's URL when cross-site linking to a page output that is set to publish to a particular Destination via it's Content Type. In this case, the site's URL is ignored and the Destination Web URL is used instead.

Linking to a Rendered Version of a Page

Within Cascade CMS by default a link to another page is rewritten such that clicking on that link will display the page asset view inside the Cascade CMS user interface. In some cases, though, it is necessary to link to the actual rendering of the page itself and not the page asset. This is useful, for example, when the linked-to page generates pure JavaScript content and we want to link to that page from inside of a script tag's src attribute. Along these same lines, its possible to link to a page that generates pure CSS using a link tag with an href attribute that references the CSS file.

To be able to link to the actual rendering, the parameter raw needs to be included in the link, for example:

<link href="/css/page-that-renders-css?raw"/>

Using this parameter affects only renderings inside of Cascade CMS. It does not have an effect on published pages because the raw parameter is stripped during publishing:

<link href="../css/page-that-renders-css.css"/>

Note: the above example will generate a link to the default Output for the Page. If you need to generate a link to a different Output's rendering, use:

<link href="[system-asset:configuration=configuration_name]/css/page-that-renders-css?raw[/system-asset:configuration]"/>