Document toolboxDocument toolbox

LifeInCodes-HoverJS

lifeincodes-hoverjs is a library that can be used to add hover functionality to Jira Issue Links to all applications.

Version: 1.0.0

Requirements

This JS library can be used only by customers of Issue Preview for Jira App (https://marketplace.atlassian.com/apps/1220952/issue-preview-for-jira)

Usage

Import lifeincodes-hover.min.js in the pages you want the hover.
Import lifeincodes-hover.min.css to give the hover Jira look and feel.
Initialize LifeInCodesHover with a list of parameters.

Parameters

  1. Parameter name: $
    Mandatory: no, but if not passed, $ object must already be defined.
    Default value: $
    Possible values: a Javascript object representing jQuery $
    Comments: Atlassian pages have a wrapper on top of $, so the best practice is to use AJS.$ when used in Jira/Confluence/Bamboo pages

  2. Parameter name: source
    Mandatory: no
    Default value: N/A
    Possible values: any string
    Comments: A string used as an identifier of the application that calls the backend. Can be used for audit purposes

  3. Parameter name: requestHeaders
    Mandatory: no
    Default value: N/A
    Possible values: A map with all the request headers

  4. Parameter name: selector
    Mandatory: no
    Default value: a
    Possible values: any string representing a CSS selector
    Comments: A string representing the CSS selector of elements where the hover will be applied

  5. Parameter name: debugMode
    Mandatory: no
    Default value: false
    Possible values: true/false
    Comments: If enabled, it will print some events to console + not close the hover anymore. Use for debug purposes by the developers of this plugin. Don't forget to disable in production

  6. Parameter name: waitTime
    Mandatory: no
    Default value: 750
    Possible values: A int representing after how many milliseconds the backend call will be made

  7. Parameter name: getIssueKeyFunc
    Mandatory: no
    Default value: N/A
    Possible values: A valid Javascript function that returns the issue key of HTML elements
    Comments: The function will be applied on all elements that are returned by the selector parameter. The default function returns the correct issue key of all issue links in Jira/Confluence/Bamboo pages

  8. Parameter name: disableBrowserTitleHover
    Mandatory: no
    Default value: true
    Possible values: true/false
    Comments: If true, the default browser functionality of showing the HTML elements title in a small hover is removed.

  9. Parameter name: backendUrl
    Mandatory: yes
    Default value: N/A
    Possible values: Any string representing a valid rest endpoint
    Comments: There are 2 options:

    • A valid Issue Preview for Jira REST endpoint. If you are connecting from an application other than Jira/Confluence/Bamboo, a requestHeader must be passed named Authorization.

    • An external REST endpoint that will return exactly what the Issue Preview for Jira App endpoint returns. This can be used in case you want to intercept requests/add custom audit functionality/etc. The plugin will append a new url parameter named issueKey with the key of the issue link.
      We strongly advise not to change the return of the Issue Preview for Jira Plugin as it may cause future incompatibility!

Examples

  • Add hover capability to all <a> elements in the page

var options = { selector: "a", backendUrl: "www.my-jira.com:8080/jira", source: 'my-app' }; var lifeInCodesHover = new LifeInCodesHover(); lifeInCodesHover.init(options);
  • Jira basic authentication

// Authorization needs a base64 encoding of username:password. Example: "admin:admin" = "YWRtaW46YWRtaW4=", so var requestHeadersMap; requestHeadersMap['Authorization'] = 'Basic YWRtaW46YWRtaW4='; requestHeadersMap['Access-Control-Allow-Origin'] = '*'; var options = { source: "my-app", selector: "a:not(#header a)", waitTime: 1000, backendUrl: 'www.my-jira.com:8080/jira?customUrlParameter=XXX', requestHeaders: requestHeadersMap }; var lifeInCodesHover = new LifeInCodesHover(); lifeInCodesHover.init(options);
  • Jira OAUTH authentication
    For this, we recommend you connect to your backend server and connect to Jira through OAUTH from there.
    You will need to set up a user to connect to Jira.
    Remember that the user should have access to the Jira project/issue that you are trying to view or else the REST endpoint will not be rendered.

var options = { source: "my-app", selector: "a", backendUrl: 'www.my-jira.com:8080/jira' }; var lifeInCodesHover = new LifeInCodesHover(); lifeInCodesHover.init(options);

FAQ

Q: What do I need to do to use the hover in a third party app?
A: You will need to include in the page lifeincodes-hover.min.js, lifeincodes-hover.min.css, jQuery v3.4.1 or newer and jQuery Nicescroll v3.7.6 or newer. Then just init an object of type LifeInCodesHover with some options and that's it.

Q: What types of authentication do you support?
A: We have added support for basic authentication by making the request headers customizable. For Oauth you will have to connect to your own backend URL that will handle authentication before calling the Issue Preview for Jira REST endpoint.

Q: What browsers do you support?
A: The plugin has been tested with Chrome, Mozilla, IE 8+, Edge, Brave browsers.

Who do I talk to?

Dependencies

Used libraries: