org.opencms.staticexport

Interface I_CmsLinkSubstitutionHandler

All Known Implementing Classes:

CmsAdvancedLinkSubstitutionHandler, CmsDefaultLinkSubstitutionHandler, CmsLocalePrefixLinkSubstitutionHandler

public interface I_CmsLinkSubstitutionHandler

Allows to configure customized link substitution behavior.

Using this handler, you can completely customize the behavior of the link substitution.

This handler is plugged into CmsLinkManager.substituteLink(org.opencms.file.CmsObject, String, String, boolean), which is the central method to calculate links from VFS paths, used by the <cms:link /> tag and the rest of the OpenCms core.

Moreover, this handler is plugged into CmsLinkManager.getRootPath(CmsObject, String, String), which is the reverse method to calculate a VFS root path from a link.

For any implementation of this interface you must ensure the following:

     // path: String that represents a valid VFS resource root path
     // cms:  a valid OpenCms user context
     String httpLink = OpenCms.getLinkManager().substituteLinkForRootPath(cms, path);
     String vfsPath = OpenCms.getLinkManager().getRootPath(cms, httpLink);
     path.equals(vfsPath); // this must be true!
 

The default implementation of this interface is CmsDefaultLinkSubstitutionHandler.

Since:

7.0.2

See Also:

for the method where this handler is used to create a link from a VFS root path, for the method where this handler is used to create VFS root path from a link, for the default implementation of this interface

Method Summary

Modifier and Type	Method and Description
java.lang.String	getLink(CmsObject cms, java.lang.String link, java.lang.String siteRoot, boolean forceSecure) Returns a link from the URI stored in the provided OpenCms user context to the VFS resource indicated by the given link and siteRoot, for use on web pages.
java.lang.String	getLink(CmsObject cms, java.lang.String link, java.lang.String siteRoot, java.lang.String targetDetailPage, boolean forceSecure) Returns a link from the URI stored in the provided OpenCms user context to the VFS resource indicated by the given link and siteRoot, for use on web pages.
java.lang.String	getRootPath(CmsObject cms, java.lang.String targetUri, java.lang.String basePath) Returns the resource root path in the OpenCms VFS for the given target URI link, or null in case the link points to an external site.

Method Detail

getLink

java.lang.String getLink(CmsObject cms,
                         java.lang.String link,
                         java.lang.String siteRoot,
                         boolean forceSecure)

Returns a link from the URI stored in the provided OpenCms user context to the VFS resource indicated by the given link and siteRoot, for use on web pages.

The result should be an absolute link that contains the configured context path and servlet name, and in the case of the "online" project it will also be rewritten according to to the configured static export settings.

In case link is a relative URI, the current URI contained in the provided OpenCms user context cms is normally used to make the relative link absolute.

The provided siteRoot is assumed to be the "home" of the link. In case the current site of the given OpenCms user context cms is different from the provided siteRoot, the full server prefix is appended to the result link.

A server prefix is also added if

• the link is contained in a normal document and the link references a secure document
• the link is contained in a secure document and the link references a normal document

Please note the above text describes the default behavior as implemented by CmsDefaultLinkSubstitutionHandler, which can be fully customized using this handler interface.

Parameters:

cms - the current OpenCms user context

link - the link to process which is assumed to point to a VFS resource, with optional parameters

siteRoot - the site root of the link

forceSecure - if true generates always an absolute URL (with protocol and server name) for secure links

Returns:

a link from the URI stored in the provided OpenCms user context to the VFS resource indicated by the given link and siteRoot

See Also:

for the reverse function, which creates a VFS

getLink

java.lang.String getLink(CmsObject cms,
                         java.lang.String link,
                         java.lang.String siteRoot,
                         java.lang.String targetDetailPage,
                         boolean forceSecure)

Returns a link from the URI stored in the provided OpenCms user context to the VFS resource indicated by the given link and siteRoot, for use on web pages.

The result should be an absolute link that contains the configured context path and servlet name, and in the case of the "online" project it will also be rewritten according to to the configured static export settings.

In case link is a relative URI, the current URI contained in the provided OpenCms user context cms is normally used to make the relative link absolute.

The provided siteRoot is assumed to be the "home" of the link. In case the current site of the given OpenCms user context cms is different from the provided siteRoot, the full server prefix is appended to the result link.

A server prefix is also added if

• the link is contained in a normal document and the link references a secure document
• the link is contained in a secure document and the link references a normal document

Please note the above text describes the default behavior as implemented by CmsDefaultLinkSubstitutionHandler, which can be fully customized using this handler interface.

Parameters:

cms - the current OpenCms user context

link - the link to process which is assumed to point to a VFS resource, with optional parameters

siteRoot - the site root of the link

targetDetailPage - the target detail page, in case of linking to a specific detail page

forceSecure - if true generates always an absolute URL (with protocol and server name) for secure links

Returns:

a link from the URI stored in the provided OpenCms user context to the VFS resource indicated by the given link and siteRoot

See Also:

for the reverse function, which creates a VFS

getRootPath

java.lang.String getRootPath(CmsObject cms,
                             java.lang.String targetUri,
                             java.lang.String basePath)

Returns the resource root path in the OpenCms VFS for the given target URI link, or null in case the link points to an external site.

The default implementation applies the following transformations to the link:

• In case the link starts with a VFS prefix (for example /opencms/opencms, this prefix is removed from the result
• In case the link is not a root path, the current site root is appended to the result.

• In case the link is relative, it will be made absolute using the given absolute basePath as starting point.

• In case the link contains a server schema (for example http://www.mysite.de/), which points to a configured site in OpenCms, the server schema is replaced with the root path of the site.

• In case the link points to an external site, or in case it is not a valid URI, then null is returned.

Please note the above text describes the default behavior as implemented by CmsDefaultLinkSubstitutionHandler, which can be fully customized using this handler interface.

Parameters:

cms - the current users OpenCms context

targetUri - the target URI link

basePath - path to use as base in case the target URI is relative (can be null)

Returns:

the resource root path in the OpenCms VFS for the given target URI link, or null in case the link points to an external site

See Also:

for the reverse function, which creates a link form a VFS resource path