Skip to content

WLink

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 19 revisions

WLink is a component for creating links to other resources. WInternalLink is a convenience helper to create a page-internal link to another WComponent based on the target component's id. WContentLink is a convenience helper for creating a 'link' to a pop-up to load a file resource (such as a PDF) supplied by WContent.

WLink, WInternalLink and WContentLink

This documentation specifies WLink but all of these same notes apply to WInternalLink and WContentLink which are convenience helpers in the Java API.

Creating a link

WLink can be created using a constructor or a WLink.Builder. WInternalLink and WContentLink do not have an equivalent Builder.

// a WLink which will have its URL and text set separately.
WLink aLink = new WLink();

// a simple link
WLink aLink = new WLink("http://www.example.com", "example.com");

// with WindowAttributes attrib
WLink attributeLink = new WLink("http://www.example.com",
    "example.com", attrib);

WInternalLink's constructor accepts another WComponent as the linked component.

// Given a WSection section with a text heading
WInternalLink linkToSection = new InternalLink(
    section.getDecorationLabel().getText(), section);

WContentLink does not take a URL in any of its constructors. It must be associated with a piece of content using setContentAccess.

WContentLink openPdfLink = new WContentLink("Open PDF");
// assume resource located at PATH_TO_PDF
openPdfLink.setContentAccess(new InternalResource(PATH_TO_PDF));

Using WLink.Builder to create a WLink:

WLink buiderLink = new WLink.Builder("example dot com",
    "http://www.example.com")
    .windowName("examplewindow").build();

For more examples of using WLink.Builder see using WindowAttributes.

Setting URL

The URL is used to set the location of the WLink's target resource. It is a required property with no default and must be explicitly specified for each instance of a WLink in the application.

For WLink the url may be specified on a constructor or by the property accessor.

// given WLink link
link.setUrl("http://www.example.com");

For WInternalLink the url is a reference to a target component.

// given WInternalLink link and target WComponent component
link.setReference(component);

For WContentLink the url is set by reference to an implementation of the ContentAccess interface (such as InternalResource).

// given WContentLink link and InternalResource file
link.setContentAccess(file);

Accessibility

WLink will be accessible if it is created with a reasonable labelling string - even if this string is not displayed on the final output because an image is displayed as the only content of the link.

WLink link = new WLink("http://www.example.com", "Example.com");

At a bare minimum a WLink must have at least one of:

  • a displayed text label (preferred);
  • a toolTip which adequately describes the purpose of the link; or
  • setting the accessibleText property to a value which adequately describes the purpose of the link.

When a Wlink has WindowAttributes with properties in addition to windowName the HTML button element produced to open the pop-up will be marked with the attribute aria-haspopup="true". This is the minimum we can do to help AT users be pre-informed that a button will open a pop-up but it is not in itself sufficient. It is best practice to ensure that all users are aware a link (or button) will open a new window (or browser tab) before they invoke it. This is best done in the link text as it is then available to all users.

If a WLink contains an image and the imagePosition property is not set then the image must have adequate alt text. This is obtained from the WLink text description.

Setting a toolTip

WLink may have a toolTip to add extended context to the link but note that this may have follow-on accessibility problems.

// with WLink `link`
link.setToolTip("Some further context to this link.");

Additional labelling text

WLink may have accessible text applied to give more context to assistive technologies. This should be used with care and restraint as it may result in less accessible applications.

// with WLink `link`
link.setAccessibleText("Some further context to this link.");

Access Keys

A WLink may be given an access key to provide rapid keyboard access. When a user uses an access key to access a WLink the link or button may fire automatically.

Usability

WLink creates links and links navigate to other resources. If a link is followed then the content of the current page may be lost, this may result in a user losing work if they accidentally follow a poorly labelled link. If the WLink navigates to a reference internal to the current page then this issue does not arise, this is also the case for WInternalLink. WContentLink always opens the content in a new window/tab/application and therefore is not subject to this issue.

To mitigate this issue the link can be forced to open in a new window or tab by using a WindowAttributes sub-component. Unfortunately this causes other usability and accessibility issues and so should be used with care. The minimum requirement for WindowAttributes is a title for the new window but the WindowAttributes component supports many properties for determining the browser chrome available in the pop-up window and you should refer to the its documentation.

IE on Windows Mobile 8

No links will open in a new window/tab on Windows Mobile 8. If your application has an external audience or an audience which includes users of Windows Mobile 8 then it cannot use WLink to open a new tab: all links open in the current tab.

HTML output

Appearance

A "normal" WLink when rendered as a HTML a element has a simple appearance:

A link

Stylistically WLink et al appear like WButton especially with respect to the implementation of images and (the imagePosition property. When the link is rendered as a button then the button appearance is exactly as per WButton.

When rendered as a HTML a element WLink has a :visited state which may appear different from an unvisited link.

A visited link

Button Style

A WLink may be output in a button style. This is used as part of the determination of the element which is output and is the sole determinant of the style applied to that element. If this output style is used the rendered component will always output a button element and it will appear as a button; otherwise the WLink will output an element determined as described in HTML output but which will, if a button element, be styled as a link (see WButton render modes for visual samples of this). To render a WLink in this style use renderAsButton(boolean);

Button styled WLink

// render WLink `buttonishLink` as a button
buttonishLink.renderAsButton(true);

// to change this back to a regular link
buttonishLink.renderAsButton(false);

Why use buttons

A HTML a element has one purpose and that is to link to other resources. According to the HTML5 specification this link may open a new viewport by setting the target attribute of the link. The HTML a element is not designed to undertake actions within the client other than navigation.

The appropriate tool for undertaking a client side action is a HTML button element. Opening a pop-up window with particular parameters (such as size, position or absence of certain browser features) is a scripted action, and therefore the appropriate, and semantically correct, HTML element to undertake this action is a button.

Nested image

Wlink may contain an image either alone or along with the link text. Any image may be used and it is output as a HTML img element. If this property is set and imagePosition is not set the image will be the only content of the WLink and the text description of the link is used as the alt attribute of the image and must be set.

WLink imageLink = new WLink(SOME_URL);
imageLink.setImage(new ImageResource(PATH_TO_IMAGE, IMAGE_DESCRIPTION));

Image position

Setting an image postion allows the image to co-exist with text content. It has four available values:

  • NORTH - the image will appear centred above the link text;
  • EAST - the image will appear to the right of the link text;
  • SOUTH - the image will appear centred below the link text; and
  • WEST - the image will appear to the left of the link text.

WLink with the imagePosition property set has appearance identical to WButton.

// To place an image to the 'west' of the link text
WLink imageLink = new WLink(SOME_URL, LINK_TEXT);
imageLink.setImage(new ImageResource(PATH_TO_IMAGE, IMAGE_DESCRIPTION));
imageLink.setImagePosition(WLink.ImagePosition.WEST);

Disabling

A WLink may be disabled on page load. When disabled the WLink will not respond to user input or interaction. This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call.

Disabled links

HTML a elements do not support a disabled state. The WComponents framework does allow links to be disabled and uses the aria-disabled state. A WLink which outputs a button element and is in a disabled state is in a HTML disabled state whether is it styled as a link or as a button.

  • disabled link:

    Disabled link

  • rendered as a button:

    Disabled Link with button style

Hiding

A WLink may be hidden on page load. When hidden the WLink is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl.

Related components

Further information

Some start pages

Clone this wiki locally