Jira tutorials on AMDs and new API?

Jira Development Jira Data Center
, ,
1

Hi team,

A page from 2020 / Jira 7.7 says that the Jira team plans to abandon globally-exposed JS methods, whether it be $, AJS or JIRA, and plugins will have to use require() with the correct import name. Two problems with that:

  • I don’t think the list of AMD modules is documented, and for what is documented, it doesn’t fulfill the classic usecases (issue panel, custom field, comments tabs, sprint board),
  • Even if AMD modules are documented, the list of events (such as JIRAEvents.bind(JIRAEventTypes.ISSUE_REFRESHED...) isn’t clear either.

Creating an issue panel, a custom field, adding JS to Jira issues, often relies on oral tradition, and on exploring the source code of Atlassian’s Jira source from back in 2010 when it was still entirely exposed. There are other difficulties in adopting AMD: The Jira Server doc, or list of Jira Server tutorials contain a tutorial about, for example, Custom Fields, but they do not mention the use of the new AMD API which will soon become mandatory. Also, people keep mentioning Atlassian’s WRM plugin, which is a layer on top of AMD, is a false lead because doesn’t solve the understanding of how to properly write healthy JS for Jira (or Confluence) for common usecases (issue panel, issue tabs at the bottom, custom fields and so on),

Can we please have centralized and updated information (and it would be a big Kudos if a developer could write it) about the basic usecases:

  • How to add Javascript to an issue panel, and ensure the JS is called each time the panel is refreshed (i.e. when the user clicks another issue),
  • Same for issue panels on the Sprint Board, for which the JS attaches differently,
  • How to add JS to a custom field, and likewise, how to get refreshed when the issue changes,
  • How to add JS to the Jira link issue dialog,
  • How to add JS to panels at the bottom of Jira issues,
  • Where to find the documented list of available AMD imports?
  • Where to find the documented list of Jira issue events?

Thank you very much!

PS: As a bonus, of course, boilerplate code with default Typescript + autocompletion of Jira’s JS APIs would be awesome, but let’s focus on the goal: Healthy code for the basic plugin points in Jira.

1 Like
2

Regarding the “write healthy JS for Jira”, I would like add the following points that the documentation should contain:

  • How to init your app in a reliable way (wait for all dependencies to be loaded), because there may be timing issues when customers have a lot of plugins
  • do’s and don’ts when writing plugins
    • don’t include CSS that mess with the global styling (there may be exceptions, like theming), so choose your UI Libs with care
    • don’t put your JS 3rd party libs into the global space, you may not be the only one using it. Even a temporary overwrite during JS loading could cause other plugins to fail to load (I’m looking at you JQuery :sweat_smile: )
    • Don’t change / overwrite basic JS functions / prototype with care (I have seen a custom JSON stringify or parse method in the past)
    • If you don’t want other plugins to mess with your code, use iframes (and how to)

I haven’t followed all the online events that happened, is it possible that this topic was covered in one of them? In case it was not, it would be a good topic to have at e.g. atlas-camp (may be too much for 1 person)

1 Like