Jonathon Creenaune, JIRA Development Team Lead
Every tip, trick, guide and how to on integrating your plugin with JIRA 5+'s client side API.
* How to integrate with quick edit, inline edit, search
* Why you can't jQuery onready, and what you should do instead
* The kickass 1 (inline edit) APIs and the coming kickass 2 (search) APIs
40. <select id="assignee" class="hidden"></select>
JIRA.bind(JIRA.Events.NEW_CONTENT_ADDED, function(e, $ctx) {
new AJS.SingleSelect({
element: $ctx.find("#assignee"),
itemAttrDisplayed: "label",
ajaxOptions: {
url: "/rest/assignees",
query: true, // go back to server on each keystroke
formatResponse: function (response) {
// construct groups/options from the JSON response
return ret;
}
}
});
});
This presentation is about JIRA&#x2019;s frontend API\n\nBut before I get started\n
JIRA 2.7 (2004)\n
JIRA 2.7 (2004)\n
JIRA 3.13 (2008)\n\ntodo: might need to change, this is crap\n
JIRA 3.13 (2008)\n
JIRA 4.0\n
JIRA 4.0\n
Through 4.4 and into JIRA 5\n
Old-style editing\n
5.0 - quick edit\n
5.1 - inline edit\n
JIRA 5.0\n
JIRA 5.2 - new search\n
Editing a searcher\n
We reckon this is kickass. we are fist pumping about this.\n
We want you to kick ass too.\n\nThis preso is about all the things we provide to allow you to be awesome.\n\nThe awesome stuff we&#x2019;ve been doing in JIRA - viewing, editing and finding issues - how this impacts you as a plugin developer. It&#x2019;s about making your plugin UI harmonious with our changes. It&#x2019;s about how you can be awesome.\n\n\n\n
How can you turn this boring old select ...\n
Into this\n
How can you turn this html list ...\n
Into this\n\nThese things are not just custom fields - can use them anywhere\n\nAnd more:\n- General principles of frontend dev\n- Working with inline edit\n- Working with the new search interface\n
Wait, stop. Whoa. Do I need to do all of this? Are these APIs I need to implement?\n\nNo\n\nDesign goal - if you do absolutely nothing, you are still supported.\nIf you write a custom field, that can be edited, it&#x2019;s going to deliver us a blob of HTML.\n- We go to great lengths to ensure that that same HTML will work the same in the old editor, in quick edit, or in inline edit. It just works.\n\nAlso, if you want to take advantage of inline edit APIs in 5.1, or new searcher functionality in JIRA 5.2, will you need different versions of your plugin?\n\nNo\n\nWe want you to be able to build one version of your plugin. If it&#x2019;s in 5.2, it can take advantage of our new controls and new searcher APIs. But if it&#x2019;s delivered 5.0 or 5.1, it just works great in the old issue navigator.\n\nWhat is JIRA&#x2019;s frontend API?\n\n- web fragments - plugin points where you can add\n-- menus\n-- panels, like on view issue or project admin\n-- toolbars \n-- haven&#x2019;t added any over jira 5\n\n- web resources and web resource contexts (things like atl.admin, atl.general)\n-- bundles of resources like css, javascript\n- decorators\n-- provide things like header\n-- in most cases, when creating a new page\n-- again, haven&#x2019;t made any big changes \n\nCSS -some\n\nDOM - no\n\n
- web fragments - plugin points where you can add\n-- menus\n-- panels, like on view issue or project admin\n-- toolbars \n-- haven&#x2019;t added any over jira 5\n\n- web resources and web resource contexts (things like atl.admin, atl.general)\n-- bundles of resources like css, javascript\n- decorators\n-- provide things like header\n-- in most cases, when creating a new page\n-- again, haven&#x2019;t made any big changes \n\nCSS -some\n\n
\n
Let&#x2019;s get down to brass tacks\n\nJavascript - most of the work has gone in JIRA 5. controls, api&#x2019;s\n\nFirst - who has written javascript code for a JIRA plugin?\n\nWho has used jQuery?\n\nHow many people know what the term &#x201C;single page app&#x201D; means?\n
JIRA < 5.0 - all elements were always on the page\n\nrender on the server\n
elements may not be on the page when it&#x2019;s first loaded!\n
Solution: listen for NEW_CONTENT_ADDED events\n
Contract going forward any or no HTML may be in the present on page load, or when your javascript is brought into the page\n\nfor example: may choose to completely reimplement view issue, and not cause a page reload to open view issue from search\nor vice versa\n\nnever assume jQuery onReady(), always use NEW_CONTENT_ADDED\n\nwill get to examples later\n
Editing\n\nCustom field: do nothing\n\nCustom field type: what do I need to do to make my custom fields play nice with:\n(next slides) quick edit, inline edit\n
quick edit\n
inline edit\n
nothing. (this slide is intentionally left blank)\n\ngone to great lengths to ensure that exact same html which works in old edit works in quick edit and inline edit. As a developer i can tell you.\n\n(mostly)\n
Save on blur\n\nWhen I open a field for edit - click on it.\nWhen I want to finish - I can press enter or click save; OR I can press esc or click cancel or exit\n\nOR I can click anywhere else on the page - &#x201C;blur&#x201D; implies save\n\nwhat if my field opens a layer (eg date picker), or a dropdown, or even a popup window?\n(TODO: images for these)\n\nOpt in\n
\n
Or write your own\n\nNext: fields. Single Select component. How to turn this crusty old HTML <select> into one of our Sing\n
TODO: would be good to get actual priority field here\n
Principles: progressive enhancement. still render HTML on the server, javascript on the client runs\n
HTML for this:\n
If HTML is already on page:\n\nitemAttrDisplayed: should be default\n
AJAX version\n
Eg for labels field\n
JIRA 4.4+\n
Search\n\nagain: custom field that is searchable, do nothing\n\nCustom field type: what do I need to do to make my custom fields play nice with:\n(next slides) new issue search\n
\n
again, nothing. (this slide is intentionally left blank). same as inline edit\n\nagain, we have gone to great lengths to ensure that exact same html which works in old issue navigator works in classic mode\n\nIntroduce the checkbox multi select\n
How can you turn this html list ...\n
Into this\n\nAnd more:\n- General principles of frontend dev\n- Working with inline edit\n- Working with the new search interface\n
That&#x2019;s actually it. no javascript.\n
When you leave here:\n\nuse this kickass stuff. i&#x2019;ve focussed on custom fields but is is it just for custom fields. no. you can use it anywhere.\n\nbackwards compatibility. we want your plugin to be compatible for all of 5.x. we go to great lengths. i do personally. in fact i personally have put so much work into this that if someone in this room doesn&#x2019;t, i&#x2019;m going to be really upset\n
The shape of things to come ... JIRA 6.0\n\n- more progressive enhancement (a la checkbox multi select). less javascript for specify base actions.\n\n- on the other hand, when js is required, more commitment to a hard front end similar to server side (no regressions).\n- &#x2018;nicer&#x2019; api than NEW_CONTENT_ADDED\n\n- Think of JIRA 5.x as the birth and adolescence of the frontend API, JIRA 6 will be the \n