com.tridion.linking

Class ComponentLink

java.lang.Object

com.tridion.linking.AbstractLink

com.tridion.linking.ComponentLink

public class ComponentLink
extends AbstractLink

The ComponentLink class 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 targetted 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 ComponentLink("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);

Constructor Summary

Constructors

Constructor and Description
ComponentLink(int publicationId) Creates a new ComponentLink instance.
ComponentLink(String publicationURI) Creates a new ComponentLink instance.
ComponentLink(String namespace, int publicationId, boolean relativeLink) Creates a new ComponentLink instance.

Method Summary

Modifier and Type	Method and Description
protected int	buildScore(String basePageURL, String foundLinkURL) Assigns a score to a Link URL (second parameter) based on its proximity to the Page URL (first parameter).
protected com.tridion.storage.LinkInfo	findBestMatch(List<com.tridion.storage.LinkInfo> filteredLinkInfo, int sourcePageId, String sourcePageURL) This method implements steps 3 - 6 of the business logic for linking.
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 excludeTemplateId, 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 returnes 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 returnes this as a String.
String	getLinkAsString(String sourcePageURI, String targetComponentURI, String excludeTemplateURI, String linkTagAttributes, String linkText, boolean showTextOnFail, boolean showAnchor, LinkStringStyle style) Creates a new Link instance and returnes this as a String.
protected List<com.tridion.storage.LinkInfo>	getLinkInfo(int publicationId, int componentId) Loads the ComponentLinkInfo for a component in a publication.

Methods inherited from class com.tridion.linking.AbstractLink

getBaseNamespaceId, getErrorList, getFullyQualifiedURL, getLinking, getNamespace, getNamespaceService, getPublicationId, getURL, isRelativeLink, isWrappedCacheDAO, setPublicationId

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComponentLink

public ComponentLink(int publicationId)

Creates a new ComponentLink instance. By default tries to resolve links using linking configuration.

Parameters:

publicationId - The ID of the publication that is targeted.

ComponentLink

public ComponentLink(String namespace,
                     int publicationId,
                     boolean relativeLink)

Creates a new ComponentLink instance.

Parameters:

namespace - The namespace of the publication that is targeted

publicationId - The ID of the publication that is targeted.

relativeLink - If true then the realtive URL will be returned from a Link object despite on linking configuration.

ComponentLink

public ComponentLink(String publicationURI)

Creates a new ComponentLink instance. By default tries to resolve links using linking configuration.

Parameters:

publicationURI - The TCM:URI of the publication that is targeted.

Method Detail

getLinkAsString

public 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

public 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

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

Creates a new Link instance and returnes 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 targeted component presentation on a page.

style - link style

Returns:

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

getLinkAsString

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

Creates a new Link instance and returnes 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 targeted component presentation on a page.

Returns:

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

getLinkAsString

public 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 returnes 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

public 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

public 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

public 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

public Link getLink(int sourcePageId,
                    int targetComponentId,
                    int excludeTemplateId,
                    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.

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 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.

findBestMatch

protected com.tridion.storage.LinkInfo findBestMatch(List<com.tridion.storage.LinkInfo> filteredLinkInfo,
                                                     int sourcePageId,
                                                     String sourcePageURL)

This method implements steps 3 - 6 of the business logic for linking. This method finds the nearest component presentation to link to from the current component presentation. This implements the following parts of the business logic for linking:

1. If the same component exists on the current page (where the ComponentLink originates), link to this, else:
2. If the same component exists on a page in the same structure group (published directory) as the current page, link to this component, else:
3. If the same component exists on a page in a child of the current structure group, link to this component, else:
4. Link to the component on the most proximate sibling or parent, else:

If any of the above criteria are filled, a link is returned, otherwise null is returned

Parameters:

filteredLinkInfo - A collection containing all possible links, with the current template filtered out

sourcePageId - The ID of the page the link originates from

sourcePageURL - The URL of the page the link originates from

Returns:

Either the best LinkInfo we can find, or null

buildScore

protected int buildScore(String basePageURL,
                         String foundLinkURL)

Assigns a score to a Link URL (second parameter) based on its proximity to the Page URL (first parameter). Scores are assigned as follows:
ComponentLink.SUBDIR_SCORE points for each directory below the current directory, plus ComponentLink.HIGHER_DIR_SCORE points for each directory we have to go up, to find a valid link .
So, a link to a page in a subdirectory would score 1 point, but a link to a page in a directory above the current page would score 100 points.

• In same path : score 0.
• For each directory below current directory, add 1 point.
• For each directory above current directory add 100 points.

So, if we have the following structure:

 /root/ a / d / e / f / g /
        b / h / i / j /
              / k / l /
        c / m / n / o /
              / p / q /
              / r / s / t /
 

If a component is on a page in directory d, and also on another page in directory d, the score would be 0.

If a component is on a page in directory d, and on a page in directory f, the score would be 2 (1 point for subdirectory e, and one point for subdirectory f).

If a component is on a page in directory d, and on a page in directory a, the score would be 100 (100 points for going up a directory).

If a component is on a page in directory d, and on a page in directory b, the score would be 201 (100 points for going up to directory a, 100 points for going up to directory root, 1 point for going down to directory b).

If a component is on a page in directory o, and on a page in directory q, and on a page in directory t, the scores would be:

• 202 for directory q (up two directories to directory m, 200 points, down two directories to directory q, 2 points)
• 203 for directory t (up two directories to directory m, 200 points, down three directories to directory t, 3 points)

Parameters:

basePageURL - The URL of the page to link from

foundLinkURL - The URL of the page you wish to compare

Returns:

An int representing the total score, to be used in comparing the relevance of links

getLinkInfo

protected List<com.tridion.storage.LinkInfo> getLinkInfo(int publicationId,
                                                         int componentId)

Loads the ComponentLinkInfo for a component in a publication. The collection returned contains a list of ComponentLinkInfo objects.

Parameters:

publicationId - The ID of the publication.

componentId - The ID of the component.

Returns:

A Collection of ComponentLinkInfo objects if they could be found. If an error occurs or the information isn't available, an empty collection will be returned.