Linking

Overview

Cascade CMS provides a number of different ways to manage links in content depending on the type of asset containing the link, the type of link (internal or external), and the location of both assets.

Asset links in XML-based content

Certain attributes of some elements in XML-based assets are automatically checked by Cascade CMS for asset links. Those XML-based assets are:

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

The table below describes which elements and attributes are automatically checked for links to CMS-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

System-asset pseudo-tags

To create asset links in non-XML content or outside of a recognized attribute (see "Asset links in XML-based content" above), you can use system-asset pseudo-tags to mark the path as a CMS-managed asset.

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

Scenarios where you may require system-asset pseudo-tags include:

  • background images in CSS
  • imported CSS files
  • images referenced in JavaScript rollover code (either in JavaScript files or in page content)

Example using system-asset pseudo-tags with a path for a CSS background image:

body {
   background: url('[system-asset]/_files/images/background.png[/system-asset]')
}
Note - To ensure asset links within a file are tracked and rewritten correctly, ensure that the Rewrite asset links in file option is enabled in its Configure tab.

Local asset pseudo-tags

[system-asset:local]/path/to/asset[/system-asset:local]

Used to create a link to the asset at the path provided in whichever site the current page is located.

For example, consider a Template shared by many sites, each with their own custom CSS file. You can use  system-asset:local pseudo-tags in the Template to tell the CMS to include the CSS file specific to the site where the current page is located.

<link href="[system-asset:local]_files/css/main.css[/system-asset:local]"/>

This type of link doesn't point to a specific asset; so while the link will be rewritten during preview and when published, it's not tracked or link-checked.

Embedded image pseudo-tags

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

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

Output pseudo-tags and attribute

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

Used to create a link to a different Output of the page specified.

<a system-page-output="pdf">Printer-friendly Version</a>

Used to create a link to a different Output of the current page. When published, the system-page-output attribute is replaced by an href attribute.

Linking to a page rendering

Within Cascade CMS by default a link to another page is rewritten such that clicking on that link will display the page asset preview inside the Cascade CMS. In some cases, though, it's 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"/>

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]"/>

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're being rewritten for and which Output the target page has.

The following table shows three different pages, using different 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 absolute links by prepending the linked-to site's URL property. It's possible to link from one Output that publishes to one web server to a different Output that publishes to another web server, while both reside in the same site in the CMS.

Mobile Output Example

For example, when linking from an HTML Output that publishes to http://example.com, to a Mobile 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, HTML Output links to /pageB's Mobile Output using [system-asset:configuration=mobile]/pageB[/system-asset:configuration].
  • Page /pageA's HTML Output publishes to Destination HTML, while /pageB's Mobile 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.