com.sdl.web.api.linking

Interface ComponentLink

public interface ComponentLink

The ComponentLink interface provides functionality to validate and resolve links to ComponentPresentations on Pages. After a link has been resolved, the PageLink class is used to link to the targeted page.

The goal of the ComponentLink is to create a link to another (published) instance of a component, having a different template ID than the one supplied as a parameter.

From all candidates, the one with the highest priority is selected. If more than one is left, the first one on the same page as the page parameter is selected: if there is no one on the same with the same page, then the first one having the same path as supplied page is selected.

If still no link is found, the link which is nearest the current page is returned. Otherwise, the latest published Component Presentation with the highest priority is selected. If no other published instance of the supplied component is found, then the link can't resolve.

//create a new ComponentLink instance for publication 1: ComponentLink componentLink = new ComponentLinkImpl("tcm:0-1-1"); //resolve a link and print it to the output stream: out.println(componentLink.getLinkAsString("tcm:1-456-64", "tcm:1-123", "tcm:1-345-16", "style='color: red;'", "read more", false);

Method Summary

Modifier and Type	Method and Description
Link	getLink(int targetComponentId) Gets a URL to the first page that is found containing the requested targetComponentId.
Link	getLink(int sourcePageId, int targetComponentId, int excludeComponentTemplateId, String linkTagAttributes, String linkText, boolean showTextOnFail, boolean addAnchor) Tries to create a link to a suitable component presentation on a page and returns this as a Link object.
Link	getLink(String targetComponentURI) Gets a URL to the first page that is found containing the requested targetComponentId.
Link	getLink(String sourcePageURI, String targetComponentURI, String excludeTemplateURI, String linkTagAttributes, String linkText, boolean showTextOnFail, boolean showAnchor) Tries to create a link to a suitable component presentation on a page and returnes this as a Link object.
String	getLinkAsString(int sourcePageId, int targetComponentId, int excludeTemplateId, String linkTagAttributes, String linkText, boolean showTextOnFail) Calls the public method getLinkAsString with an additional parameter for the anchor with the value false.
String	getLinkAsString(int sourcePageId, int targetComponentId, int excludeTemplateId, String linkTagAttributes, String linkText, boolean showTextOnFail, boolean showAnchor) Creates a new Link instance and returnes this as a String.
String	getLinkAsString(String pageURI, String componentURI, String templateURI, String linkTagAttributes, String linkText, boolean showTextOnFail) Tries to create a link to a suitable component presentation on a page and returns this as a Link object.
String	getLinkAsString(String sourcePageURI, String targetComponentURI, String excludeTemplateURI, String linkTagAttributes, String linkText, boolean showTextOnFail, boolean showAnchor) Creates a new Link instance and returns this as a String.

Method Detail

getLinkAsString

String getLinkAsString(int sourcePageId,
                       int targetComponentId,
                       int excludeTemplateId,
                       String linkTagAttributes,
                       String linkText,
                       boolean showTextOnFail)

Calls the public method getLinkAsString with an additional parameter for the anchor with the value false.

Parameters:

sourcePageId - The ID of the page where this link is inserted on.

targetComponentId - The ID of the component to link to.

excludeTemplateId - The ID of the component template used in this component presentation. Component presentations having the component template specified here are not used as a target for this link. This is why you usually specify the template id of the source component presentation here.

linkTagAttributes - Attributes to include in the link.

linkText - The text that builds up the link.

showTextOnFail - Indicates if the linkText needs to be returned . in case no link can be build: an empty string is returned if false.

Returns:

String the link (<a href="..">... </a>), linktext or empty string.

getLinkAsString

String getLinkAsString(int sourcePageId,
                       int targetComponentId,
                       int excludeTemplateId,
                       String linkTagAttributes,
                       String linkText,
                       boolean showTextOnFail,
                       boolean showAnchor)

Creates a new Link instance and returnes this as a String.

Parameters:

sourcePageId - The ID of the page where this link is inserted on.

targetComponentId - The ID of the component to link to.

excludeTemplateId - The ID of the component template used in this component presentation. Component presentations having the component template specified here are not used as a target for this link. This is why you usually specify the template id of the source component presentation here.

linkTagAttributes - Attributes to include in the link.

linkText - The text that builds up the link.

showTextOnFail - Indicates if the linkText needs to be returned . in case no link can be build: an empty string is returned if false.

showAnchor - Indicates if an showAnchor should be used to point to the position of the targetted component presentation on a page.

Returns:

String the link (<a href="..">... </a>), linktext or empty string.

getLinkAsString

String getLinkAsString(String sourcePageURI,
                       String targetComponentURI,
                       String excludeTemplateURI,
                       String linkTagAttributes,
                       String linkText,
                       boolean showTextOnFail,
                       boolean showAnchor)

Creates a new Link instance and returns this as a String.

Parameters:

sourcePageURI - The TCM:URI of the page where this link is inserted on.

targetComponentURI - The TCM:URI of the component to link to.

excludeTemplateURI - The TCM:URI of the component template used in this component presentation. Component presentations having the component template specified here are not used as a target for this link. This is why you usually specify the template TCM:URI of the source component presentation here.

linkTagAttributes - Attributes to include in the link.

linkText - The text that builds up the link.

showTextOnFail - Indicates if the linkText needs to be returned . in case no link can be build: an empty string is returned if false.

showAnchor - Indicates if an showAnchor should be used to point to the position of the targetted component presentation on a page.

Returns:

String the link (<a href="..">... </a>), linktext or empty string.

getLinkAsString

String getLinkAsString(String pageURI,
                       String componentURI,
                       String templateURI,
                       String linkTagAttributes,
                       String linkText,
                       boolean showTextOnFail)

Tries to create a link to a suitable component presentation on a page and returns this as a Link object.

Parameters:

pageURI - The TCM:URI of the page where this link is inserted on.

componentURI - The TCM:URI of the component to link to.

templateURI - The TCM:URI of the component template used in this component presentation.

linkTagAttributes - Attributes to include in the link.

linkText - The text that builds up the link.

showTextOnFail - Indicates if the linkText needs to be returned . in case no link can be build: an empty string is returned if false.

Returns:

String the link (<a href="..">... </a>), linktext or empty string.

getLink

Link getLink(String sourcePageURI,
             String targetComponentURI,
             String excludeTemplateURI,
             String linkTagAttributes,
             String linkText,
             boolean showTextOnFail,
             boolean showAnchor)

Tries to create a link to a suitable component presentation on a page and returnes this as a Link object.

Parameters:

sourcePageURI - The TCM:URI of the page where this link is inserted on.

targetComponentURI - The TCM:URI of the component to link to.

excludeTemplateURI - The TCM:URI of the component template used in this component presentation. Component presentations having the component template specified here are not used as a target for this link. This is why you usually specify the template id of the source component presentation here.

linkTagAttributes - Attributes to include in the link.

linkText - The text that builds up the link.

showTextOnFail - Indicates if the linkText needs to be returned . in case no link can be build: an empty string is returned if false.

showAnchor - Indicates if an showAnchor should be used to point to the position of the targetted component presentation on a page.

Returns:

A Link object that resolves if the link was resolved.

getLink

Link getLink(int targetComponentId)

Gets a URL to the first page that is found containing the requested targetComponentId. Template priorities are ignored for this specific method.

Parameters:

targetComponentId - Component ID for the component that needs to found.

Returns:

A Link object that resolves if the link was resolved.

getLink

Link getLink(String targetComponentURI)

Gets a URL to the first page that is found containing the requested targetComponentId. Template priorities are ignored for this specific method.

Parameters:

targetComponentURI - Component URI for the component that needs to found.

Returns:

A Link object that resolves if the link was resolved.

getLink

Link getLink(int sourcePageId,
             int targetComponentId,
             int excludeComponentTemplateId,
             String linkTagAttributes,
             String linkText,
             boolean showTextOnFail,
             boolean addAnchor)

Tries to create a link to a suitable component presentation on a page and returns this as a Link object. Component Presentations using the Component with the ID passed as the componentID parameter and the Component Template with the ID passed in the componentTemplateID parameter will NOT be linked to.
The linkTagAttributes parameter can be used to pass extra attributes to add to the >a href element.

Parameters:

sourcePageId - The ID of the page you want to create a link from.

targetComponentId - The ID of the component you want to link to.

excludeComponentTemplateId - The ID of the component template used in this Component Presentation. Component presentations having the component template specified here are not used as a target for this link. This is why you usually specify the template id of the source component presentation here.

linkTagAttributes - Attributes to add to the >a href element.

linkText - The text that will be displayed in the link (the text between the >a tags).

showTextOnFail - Sets whether or not the link text will be displayed if no suitable link can be resolved.

addAnchor - Sets whether or not the addAnchor to the component will be added to the link.

Returns:

A Link object that resolves if the link was resolved.