com.atlassian.applinks.api

Interface ApplicationLinkUIService

public interface ApplicationLinkUIService

Generates HTML fragments to support a standardized UX for displaying and controlling application link status.

A typical use case: A plugin servlet is generating some content that involves making an application link request, and it gets a CredentialsRequiredException indicating that the link is unavailable. The servlet can use ApplicationLinkUIService as follows to generate a standard message box with a "please authenticate with [application name]" link:

     ApplicationLinkUIService.MessageBuilder messageBuilder =
         applicationLinkUIService.authorisationRequest(myAppLink)
             .format(ApplicationLinkUIService.MessageFormat.BANNER);
     String messageHtml = messageBuilder.getHtml();
 

The ApplicationLinkUIService.MessageFormat.BANNER format is a standard AUI message box of the "warning" style, which is meant to be displayed at the very top of a page or a gadget. This is appropriate if the overall page/gadget content depends on the application link's state; successful completion of the authentication/authorisation flow will cause the page/gadget to be refreshed. To display a smaller inline message that does not apply to the entire page, use ApplicationLinkUIService.MessageFormat.INLINE instead.

In order for these elements to have the proper styling and behavior, the front end must import CSS and Javascript from the web resource "com.atlassian.applinks.applinks-plugin:applinks-public".

It is also possible to generate these elements entirely on the front end instead, if this is more convenient for a particular plugin. Functions for this are in "applinks.public.js" in the applinks-public web resource.

Internationalization of message text is handled by the standard I18nResolver mechanism.

Since:

3.6

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ApplicationLinkUIService.MessageBuilder An HTML fragment builder returned by authorisationRequest(ApplicationLink).
static class	ApplicationLinkUIService.MessageFormat Constants for use with MessageBuilder#format(MessageFormat).

Method Summary

Methods

Modifier and Type	Method and Description
ApplicationLinkUIService.MessageBuilder	authorisationRequest(ApplicationLink appLink) Returns a ApplicationLinkUIService.MessageBuilder to construct an HTML fragment with a "please authenticate with [application]" message, and a link that lets the user begin authentication.

Method Detail

authorisationRequest

ApplicationLinkUIService.MessageBuilder authorisationRequest(ApplicationLink appLink)

Returns a ApplicationLinkUIService.MessageBuilder to construct an HTML fragment with a "please authenticate with [application]" message, and a link that lets the user begin authentication.

Parameters:

appLink - an application link; cannot be null

Returns:

a ApplicationLinkUIService.MessageBuilder; will not be null