Linking
Digest
Cascade Server provides users with a number of different ways to manage links in content. The different options depend 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.
End users will use the Insert Link and Insert Image buttons in the WYSIWYG to create content links in pages. Developers will typically use Cascade's specified link formats to create links in Formats, templates, blocks, files, and pages.
Concept
Managed Links
The asset types capable of containing managed links are:
- Pages
- Files
- Templates
- Formats
- Blocks
Managed links refer to links between assets where both the asset containing the link and asset being linked-to are managed by Cascade. Managed links are rewritten by the system to work both inside of Cascade and when published out of Cascade.
Most managed links are tracked. A tracked link is one that is updated automatically when the linked-to asset moves or changes names within Cascade.
Non-managed links do not have this capability. For example, a link to a page on a site of the form "http://www.hannonhill.com/page.html" is not tracked by Cascade. It would therefore not be updated if the linked-to file "page.html" were to change names or be moved. This holds true even if the page that publishes to that URL is managed by the system. In order to be managed, the link would need to point to the asset within the system.
Examples of other untracked links are explained below.
Linking for End Users (WYSIWYG)
End-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 a Cascade-managed asset (on the Internal tab) or enter an external link (on the External tab). In the WYSIWYG editor, it is possible to link to Pages, Files, and External Link assets. End-users that are familiar with HTML and have access to the View HTML button can edit link URLs in the source.
Inserting an Image Using the WYSIWYG Editor
Images can be inserted into the WYSIWYG using the Insert Image button on the WYSIWYG toolbar. Similar to the Insert Link button mentioned above, once the Insert Image button is clicked, the user will be prompted to select either a Cascade-managed image (on the Internal tab) or an externally managed image (on the External tab). The File Chooser located on the Internal tab can also be used to upload an image from the user's hard drive. If the current user has been granted the ability to upload files from chooser windows via his/her Roles, he or she can navigate to the Upload pane on the chooser and select a file from his/her hard drive to upload.
Linking for Developers
In addition to creating links in pages to other pages, developers will typically need to create links in:
- Templates to CSS files and JavaScript files managed in the system
- CSS Files to background images managed in the system
- In footer Blocks to main pages on the website
Cross-Site Linking
In Cascade 6.2, it is possible to create links in content to assets existing on different Sites. This is particularly useful when linking between pages on different sites or when linking to centrally managed support assets like CSS files and JavaScript.
The Insert Link/Insert Image dialogues provide a way to switch between Sites when choosing an asset to link to. The link formats used by developers also provide a way to specify an asset on a different site.
Technical
WYSIWYG Linking
The simplest way to create content links in the system is to use the WYSIWYG's Insert Link and Insert Image buttons.
Using the WYSIWYG to Link to Assets on other Sites
- Using the WYSIWYG, users are able to click the "insert link button,":
- After clicking the insert link button, users can choose if they want to link to a URL outside of the system (External) or if they want to link to pages or files inside the sytem (Internal).
On the "Internal" pane, click the chooser icon to select a file, page, or symlink to link to:
- When prompted to select the asset to which you'd like to link, you are able to select a different Site from the one you are in, using the dropdown at the top of the interface:
Users may only select Sites to which they have access via their Site roles. - After selecting the Site and asset to which you want to link, click "Submit" to insert the link in your content.
Managed Links within Assets Containing XML
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, XML Blocks, XHTML Blocks, Templates, 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 |  |
 |
|
| area | |
|
|
| body | |
|
|
| td | |
|
|
| table | |
|
|
| embed | |
|
|
| frame | |
|
|
| iframe | |
|
|
| img | |
|
|
| input | |
|
|
| param | |
|
|
| link | |
|
|
| script | |
|
|
When the link attribute contains a path to an asset within Cascade, it is considered a "managed" link. Within XML-based asset there are three primary ways to link to other assets managed within the system:
Same-Site Links
These are links that begin with "/" of the form. Same-site links are required to start with a "/" to be considered valid.
where /path/to/asset is a valid path to an asset in the same Site or the Global area.
Example:
<img src="/images/mypic.jpg"/> - links to an image called "mypic.jpg" inside of a folder "images" on the same Site as the asset containing the link.
Cross-Site Links
These are links of the form:
and are used to refer to assets on a different Site than the one in which the current asset resides.
Example:
<a href="site://intranet/hr/vacation">vacation schedule</a> - links to the "vacation" page in the "hr" folder on the "intranet" Site. In order for these links to resolve correctly upon publish, the linked-to asset must exist on the Site being referenced and must also be published.
Asset Local Links
These are links of the form:
and are used as a placeholder (usually in Templates) to link to an asset in the same site as the page where the link ultimately appears.
A good example of this would be if you had a single template being shared by two different Sites, each with their own CSS file. In each site there would be an asset residing at the path specified inside the [ system-asset:local]. Using the [ sytem-asset:local] tag, in this case, will instruct the system at render time to link to the CSS files specific to each Site where the Template is used. This type of link does not point to a specific asset, but instead, is relative to the site where the page that ultimately includes it resides. Therefore, it is managed and the link will be rewritten appropriately both when rendering in Cascade and when publishing, but it is not tracked or link-checked.
Example:
<link href="[system-asset:local]/css/main.css[ /system-asset:local]"/> - would be used in a Template to indicate a link to a CSS file called "main.css" that will appear in a directory called "css" on the Site where this Template is used for pages.
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.
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 the "Rewrite links in file" property enabled in 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:
If used inside a Site, site://[site-name]/path can be used inside the pseudo-tag to link to assets in other Sites.
Deprecated Link Formats
Previously, there were two different types of "system-asset" link types for linking to Pages and Files respectively.
- [ system-asset:page] was used to create links to Pages
- [ system-asset:file] was used to create links to Files
More Advanced Pseudo-Tags and Link Types
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.
This tag is used for supplying a link to a different output of the specified asset. By supplying the page path and the target associated with one of the Templates utilized by the linked-to page, the CMS will provide a link to the appropriate output. This syntax and the use of Targets is deprecated in favor of the following.
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 configuration, the CMS will provide a link to the appropriate output. This syntax is preferred over the above, deprecated [ system-asset:page:target=TargetName.
This tag is used to link to a different configuration of the same page (the page containing the tag). By supplying a system-page-output attribute to an “A” tag containing a configuration 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 a “HREF” attribute with the correct path.
Tracked Links
As mentioned previously, a tracked link is one where the link will be automatically updated by the system in the event that the linked-to asset moves or changes names. The updating of the link is done at the time when the content for the asset containing the link is rendered for view within Cascade or for publish or its contents are retrieved for edit. Link tracking was enabled at different times in the product's history for different link types. Currently, link tracking is enabled for the following:
-
Same-site links in recognized attributes of XML-based assets:
<link href="/path/my/site.css"/>Link tracking for this link type was introduced in 3.7.
-
Cross-site links in recognized attributes of XML-based assets:
<link href="site://different-site/path/to/site.css"/>Link tracking for this link type was introduced in 6.2 at the same time as cross-site linking.
-
"System-asset" (pseudo-tag) links in Files, Templates, Pages, Blocks, and XSLT Formats:
body { background: url('[ system-asset]/site/image.png[/ system-asset]')}"System-asset" link tracking was inroduced in 6.0.1. In order to enable link tracking for links of this style created before 6.0.1, edit the asset containing the link and submit.
Links between Pages and Page Configurations
Pages often publish to multiple locations with multiple output extensions by using Configuration Sets with more than one Page Configuration. Links within the Page content that link to other Pages will be rewritten differently upon publish depending on which Page Configuration they are being rewritten for and which configurations the target Page has.
The following table shows three different pages, using different Content Types and Configuration Sets.
| Page | Content Type | Configuration Set | Configurations |
|---|---|---|---|
|
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 configuration. When PageA links to PageB inside the default configuration (HTML), then the link will direct to the HTML configuration. If PageA is linking to PageB in the XML configuration, the link will direct to the XML configuration. The pages stay in the same configurations unless specified (using [ system-asset:configuration=HTML] for example).
Linking between PageA or PageB to PageC, which has different configurations, works a little differently. Since PageC does not have an HTML configuration, when PageA/PageB link to PageC in the HTML configuration, the link directs to the default configuration of PageC (ASP). There is no need to specify that PageA's HTML configuration needs to link to PageC's ASP configuration.
Linking from the XML configuration in PageA/PageB to PageC will stay in the XML configuration, 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. Cascade Server version 6.10 introduces a Destination's Web URL property. It is now possible to link from one Configuration that publishes to one web server to another Configuration that publishes to another web server, while both reside in the same "Site" in Cascade.
Mobile configuration example
For example, when linking from a standard HTML Configuration that publishes to http://example.com, to a mobile HTML Configuration 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 Configuration, either using a [ system-asset:configuration ] tag or simply linking to a page that has a different default Configuration.
- The linked-to Configuration 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 Configuration links to /pageB's mobile HTML Configuration using [ system-asset:configuration=mobile ]/pageB[ /system-asset:configuration ].
- Page /pageA's standard HTML Configuration publishes to Destination Standard, while /pageB's mobile HTML Configuration 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 configuration 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 Destiantion Web URL is used instead.