class sap.m.Link

Control sample: sap.m.Link
Visiblity: public
UX Guidelines: Link
Implements: sap.ui.core.IShrinkablesap.ui.core.IFormContentsap.ui.core.ITitleContent
Available since: N/A
Module: sap/m/Link
Application Component: CA-UI5-CTR

A hyperlink control used to navigate to other apps and web pages or to trigger actions.

Overview

The Link control is a clickable text element visualized in such a way that it stands out from the standard text. On hover, it changes its style to underlined text to provide additional feedback to the user.

Usage

You can set the Link to be enabled or disabled.

To create a visual hierarchy in large lists of links, you can set the less important links as subtle or the more important ones as emphasized.

To specify where the linked content is opened, you can use the target property.

Responsive behavior

If there is not enough space, the text of the Link becomes truncated. If the wrapping property is set to true, the text will be displayed on several lines, instead of being truncated.

This control can be a drag source.

Constructor

Constructor for a new Link.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.Link(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
ariaHasPopup sap.ui.core.aria.HasPopup None

Specifies the value of the aria-haspopup attribute

If the value is None, the attribute will not be rendered. Otherwise it will be rendered according to the selected value.

NOTE: Use this property only when a link is related to a popover/popup. The value needs to be equal to the main/root role of the popup - e.g. dialog, menu or list (examples: if you have dialog -> dialog, if you have menu -> menu; if you have list -> list; if you have dialog containing a list -> dialog). Do not use it, if you open a standard sap.m.Dialog, MessageBox or other type of dialogs displayed as on overlay over the application.

Since: 1.86.0.

Visibility: public
emphasized boolean false

Emphasized links look visually more important than regular links.

Since: 1.22.

Visibility: public
emptyIndicatorMode sap.m.EmptyIndicatorMode Off

Specifies if an empty indicator should be displayed when there is no text.

Since: 1.89.

Visibility: public
enabled boolean true

Determines whether the link can be triggered by the user.

Visibility: public
href sap.ui.core.URI

Defines the link target URI. Supports standard hyperlink behavior. If a JavaScript action should be triggered, this should not be set, but instead an event handler for the press event should be registered.

Visibility: public
rel string

Specifies the value of the HTML rel attribute.

Note: A default value of noopener noreferrer is set only to links that have a cross-origin URL and a specified target with value other than _self.

Since: 1.84.

Visibility: public
subtle boolean false

Subtle links look more like standard text than like links. They should only be used to help with visual hierarchy between large data lists of important and less important links. Subtle links should not be used in any other use case.

Since: 1.22.

Visibility: public
target string

Specifies a target where the linked content will open.

Options are the standard values for window.open() supported by browsers: _self, _top, _blank, _parent, _search. Alternatively, a frame name can be entered. This property is only used when the href property is set.

Visibility: public
text string empty string

Defines the displayed link text.

Visibility: public
textAlign sap.ui.core.TextAlign Initial

Determines the horizontal alignment of the text.

Since: 1.28.0.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

This property specifies the element's text directionality with enumerated options. By default, the control inherits text direction from the parent DOM.

Since: 1.28.0.

Visibility: public
validateUrl boolean false

Defines whether the link target URI should be validated.

If validation fails, the value of the href property will still be set, but will not be applied to the DOM.

Note: Additional URLs are allowed through URLListValidator.

Since: 1.54.0.

Visibility: public
width sap.ui.core.CSSSize

Determines the width of the link (CSS-size such as % or px). When it is set, this is the exact size. When left blank, the text defines the size.

Visibility: public
wrapping boolean false

Determines whether the link text is allowed to wrap when there is no sufficient space.

Visibility: public

Associations

Name Cardinality Type Description
ariaDescribedBy 0..n sap.ui.core.Control

Association to controls / ids which describe this control (see WAI-ARIA attribute aria-describedby).

ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / ids which label this control (see WAI-ARIA attribute aria-labelledby).


Events Overview

Event Description
press

Event is fired when the user triggers the link control.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

press

Event is fired when the user triggers the link control.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
ctrlKey boolean

Indicates whether the CTRL key was pressed when the link was selected.

Since: 1.58.

metaKey boolean

Indicates whether the "meta" key was pressed when the link was selected.

On Macintosh keyboards, this is the command key (⌘). On Windows keyboards, this is the windows key (⊞).

Since: 1.58.


Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Link.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Link itself.

Event is fired when the user triggers the link control.

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Link.

The passed function and listener object must match the ones used for event registration.

sap.m.Link.extend

Creates a new subclass of class sap.m.Link with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

firePress

Fires event press to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

getAccessibilityInfo

Returns the sap.m.Link accessibility information.

References:

  • sap.ui.core.Control#getAccessibilityInfo

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaHasPopup

Gets current value of property ariaHasPopup.

Specifies the value of the aria-haspopup attribute

If the value is None, the attribute will not be rendered. Otherwise it will be rendered according to the selected value.

NOTE: Use this property only when a link is related to a popover/popup. The value needs to be equal to the main/root role of the popup - e.g. dialog, menu or list (examples: if you have dialog -> dialog, if you have menu -> menu; if you have list -> list; if you have dialog containing a list -> dialog). Do not use it, if you open a standard sap.m.Dialog, MessageBox or other type of dialogs displayed as on overlay over the application.

Default value is None.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getEmphasized

Gets current value of property emphasized.

Emphasized links look visually more important than regular links.

Default value is false.

getEmptyIndicatorMode

Gets current value of property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

Default value is Off.

getEnabled

Gets current value of property enabled.

Determines whether the link can be triggered by the user.

Default value is true.

getHref

Gets current value of property href.

Defines the link target URI. Supports standard hyperlink behavior. If a JavaScript action should be triggered, this should not be set, but instead an event handler for the press event should be registered.

sap.m.Link.getMetadata

Returns a metadata object for class sap.m.Link.

getRel

Gets current value of property rel.

Specifies the value of the HTML rel attribute.

Note: A default value of noopener noreferrer is set only to links that have a cross-origin URL and a specified target with value other than _self.

getSubtle

Gets current value of property subtle.

Subtle links look more like standard text than like links. They should only be used to help with visual hierarchy between large data lists of important and less important links. Subtle links should not be used in any other use case.

Default value is false.

getTarget

Gets current value of property target.

Specifies a target where the linked content will open.

Options are the standard values for window.open() supported by browsers: _self, _top, _blank, _parent, _search. Alternatively, a frame name can be entered. This property is only used when the href property is set.

getText

Gets current value of property text.

Defines the displayed link text.

Default value is empty string.

getTextAlign

Gets current value of property textAlign.

Determines the horizontal alignment of the text.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

This property specifies the element's text directionality with enumerated options. By default, the control inherits text direction from the parent DOM.

Default value is Inherit.

getValidateUrl

Gets current value of property validateUrl.

Defines whether the link target URI should be validated.

If validation fails, the value of the href property will still be set, but will not be applied to the DOM.

Note: Additional URLs are allowed through URLListValidator.

Default value is false.

getWidth

Gets current value of property width.

Determines the width of the link (CSS-size such as % or px). When it is set, this is the exact size. When left blank, the text defines the size.

getWrapping

Gets current value of property wrapping.

Determines whether the link text is allowed to wrap when there is no sufficient space.

Default value is false.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setAriaHasPopup

Sets a new value for property ariaHasPopup.

Specifies the value of the aria-haspopup attribute

If the value is None, the attribute will not be rendered. Otherwise it will be rendered according to the selected value.

NOTE: Use this property only when a link is related to a popover/popup. The value needs to be equal to the main/root role of the popup - e.g. dialog, menu or list (examples: if you have dialog -> dialog, if you have menu -> menu; if you have list -> list; if you have dialog containing a list -> dialog). Do not use it, if you open a standard sap.m.Dialog, MessageBox or other type of dialogs displayed as on overlay over the application.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

setEmphasized

Sets a new value for property emphasized.

Emphasized links look visually more important than regular links.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setEmptyIndicatorMode

Sets a new value for property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Off.

setEnabled

Sets a new value for property enabled.

Determines whether the link can be triggered by the user.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setHref

Sets a new value for property href.

Defines the link target URI. Supports standard hyperlink behavior. If a JavaScript action should be triggered, this should not be set, but instead an event handler for the press event should be registered.

When called with a value of null or undefined, the default value of the property will be restored.

setRel

Sets a new value for property rel.

Specifies the value of the HTML rel attribute.

Note: A default value of noopener noreferrer is set only to links that have a cross-origin URL and a specified target with value other than _self.

When called with a value of null or undefined, the default value of the property will be restored.

setSubtle

Sets a new value for property subtle.

Subtle links look more like standard text than like links. They should only be used to help with visual hierarchy between large data lists of important and less important links. Subtle links should not be used in any other use case.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setTarget

Sets a new value for property target.

Specifies a target where the linked content will open.

Options are the standard values for window.open() supported by browsers: _self, _top, _blank, _parent, _search. Alternatively, a frame name can be entered. This property is only used when the href property is set.

When called with a value of null or undefined, the default value of the property will be restored.

setText

Sets a new value for property text.

Defines the displayed link text.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

setTextAlign

Sets a new value for property textAlign.

Determines the horizontal alignment of the text.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Initial.

setTextDirection

Sets a new value for property textDirection.

This property specifies the element's text directionality with enumerated options. By default, the control inherits text direction from the parent DOM.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Inherit.

setValidateUrl

Sets a new value for property validateUrl.

Defines whether the link target URI should be validated.

If validation fails, the value of the href property will still be set, but will not be applied to the DOM.

Note: Additional URLs are allowed through URLListValidator.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setWidth

Sets a new value for property width.

Determines the width of the link (CSS-size such as % or px). When it is set, this is the exact size. When left blank, the text defines the size.

When called with a value of null or undefined, the default value of the property will be restored.

setWrapping

Sets a new value for property wrapping.

Determines whether the link text is allowed to wrap when there is no sufficient space.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to add; if empty, nothing is inserted

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Link.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Link itself.

Event is fired when the user triggers the link control.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Link itself

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Link.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.Link.extend

Creates a new subclass of class sap.m.Link with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

firePress

Fires event press to attached listeners.

Listeners may prevent the default action of this event by calling the preventDefault method on the event object. The return value of this method indicates whether the default action should be executed.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

ctrlKey boolean

Indicates whether the CTRL key was pressed when the link was selected.

metaKey boolean

Indicates whether the "meta" key was pressed when the link was selected.

On Macintosh keyboards, this is the command key (⌘). On Windows keyboards, this is the windows key (⊞).

getAccessibilityInfo

Returns the sap.m.Link accessibility information.

References:

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaHasPopup

Gets current value of property ariaHasPopup.

Specifies the value of the aria-haspopup attribute

If the value is None, the attribute will not be rendered. Otherwise it will be rendered according to the selected value.

NOTE: Use this property only when a link is related to a popover/popup. The value needs to be equal to the main/root role of the popup - e.g. dialog, menu or list (examples: if you have dialog -> dialog, if you have menu -> menu; if you have list -> list; if you have dialog containing a list -> dialog). Do not use it, if you open a standard sap.m.Dialog, MessageBox or other type of dialogs displayed as on overlay over the application.

Default value is None.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getEmphasized

Gets current value of property emphasized.

Emphasized links look visually more important than regular links.

Default value is false.

getEmptyIndicatorMode

Gets current value of property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

Default value is Off.

getEnabled

Gets current value of property enabled.

Determines whether the link can be triggered by the user.

Default value is true.

getHref

Gets current value of property href.

Defines the link target URI. Supports standard hyperlink behavior. If a JavaScript action should be triggered, this should not be set, but instead an event handler for the press event should be registered.

sap.m.Link.getMetadata

Returns a metadata object for class sap.m.Link.

getRel

Gets current value of property rel.

Specifies the value of the HTML rel attribute.

Note: A default value of noopener noreferrer is set only to links that have a cross-origin URL and a specified target with value other than _self.

getSubtle

Gets current value of property subtle.

Subtle links look more like standard text than like links. They should only be used to help with visual hierarchy between large data lists of important and less important links. Subtle links should not be used in any other use case.

Default value is false.

getTarget

Gets current value of property target.

Specifies a target where the linked content will open.

Options are the standard values for window.open() supported by browsers: _self, _top, _blank, _parent, _search. Alternatively, a frame name can be entered. This property is only used when the href property is set.

getText

Gets current value of property text.

Defines the displayed link text.

Default value is empty string.

getTextAlign

Gets current value of property textAlign.

Determines the horizontal alignment of the text.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

This property specifies the element's text directionality with enumerated options. By default, the control inherits text direction from the parent DOM.

Default value is Inherit.

getValidateUrl

Gets current value of property validateUrl.

Defines whether the link target URI should be validated.

If validation fails, the value of the href property will still be set, but will not be applied to the DOM.

Note: Additional URLs are allowed through URLListValidator.

Default value is false.

getWidth

Gets current value of property width.

Determines the width of the link (CSS-size such as % or px). When it is set, this is the exact size. When left blank, the text defines the size.

getWrapping

Gets current value of property wrapping.

Determines whether the link text is allowed to wrap when there is no sufficient space.

Default value is false.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy int sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to be removed or its index or ID

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

setAriaHasPopup

Sets a new value for property ariaHasPopup.

Specifies the value of the aria-haspopup attribute

If the value is None, the attribute will not be rendered. Otherwise it will be rendered according to the selected value.

NOTE: Use this property only when a link is related to a popover/popup. The value needs to be equal to the main/root role of the popup - e.g. dialog, menu or list (examples: if you have dialog -> dialog, if you have menu -> menu; if you have list -> list; if you have dialog containing a list -> dialog). Do not use it, if you open a standard sap.m.Dialog, MessageBox or other type of dialogs displayed as on overlay over the application.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

Param Type DefaultValue Description
sAriaHasPopup sap.ui.core.aria.HasPopup None

New value for property ariaHasPopup

setEmphasized

Sets a new value for property emphasized.

Emphasized links look visually more important than regular links.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bEmphasized boolean false

New value for property emphasized

setEmptyIndicatorMode

Sets a new value for property emptyIndicatorMode.

Specifies if an empty indicator should be displayed when there is no text.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Off.

Param Type DefaultValue Description
sEmptyIndicatorMode sap.m.EmptyIndicatorMode Off

New value for property emptyIndicatorMode

setEnabled

Sets a new value for property enabled.

Determines whether the link can be triggered by the user.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEnabled boolean true

New value for property enabled

setHref

Sets a new value for property href.

Defines the link target URI. Supports standard hyperlink behavior. If a JavaScript action should be triggered, this should not be set, but instead an event handler for the press event should be registered.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sHref sap.ui.core.URI

New value for property href

setRel

Sets a new value for property rel.

Specifies the value of the HTML rel attribute.

Note: A default value of noopener noreferrer is set only to links that have a cross-origin URL and a specified target with value other than _self.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sRel string

New value for property rel

setSubtle

Sets a new value for property subtle.

Subtle links look more like standard text than like links. They should only be used to help with visual hierarchy between large data lists of important and less important links. Subtle links should not be used in any other use case.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bSubtle boolean false

New value for property subtle

setTarget

Sets a new value for property target.

Specifies a target where the linked content will open.

Options are the standard values for window.open() supported by browsers: _self, _top, _blank, _parent, _search. Alternatively, a frame name can be entered. This property is only used when the href property is set.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sTarget string

New value for property target

setText

Sets a new value for property text.

Defines the displayed link text.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

Param Type DefaultValue Description
sText string ''

New value for property text

setTextAlign

Sets a new value for property textAlign.

Determines the horizontal alignment of the text.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Initial.

Param Type DefaultValue Description
sTextAlign sap.ui.core.TextAlign Initial

New value for property textAlign

setTextDirection

Sets a new value for property textDirection.

This property specifies the element's text directionality with enumerated options. By default, the control inherits text direction from the parent DOM.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Inherit.

Param Type DefaultValue Description
sTextDirection sap.ui.core.TextDirection Inherit

New value for property textDirection

setValidateUrl

Sets a new value for property validateUrl.

Defines whether the link target URI should be validated.

If validation fails, the value of the href property will still be set, but will not be applied to the DOM.

Note: Additional URLs are allowed through URLListValidator.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bValidateUrl boolean false

New value for property validateUrl

setWidth

Sets a new value for property width.

Determines the width of the link (CSS-size such as % or px). When it is set, this is the exact size. When left blank, the text defines the size.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width

setWrapping

Sets a new value for property wrapping.

Determines whether the link text is allowed to wrap when there is no sufficient space.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bWrapping boolean false

New value for property wrapping