Customize the Jira work item collector
Customizing the Jira work item collector
The Jira work item collector can be used without any additional JavaScript beyond the single line generated in the work item collector administration screens in Jira. However, you can also customize the Jira work item collector in a number of different ways:
パッケージ化されたトリガーで提供されるものとは別のリンクやボタンからフィードバック フォームを起動するように、カスタム・トリガーを設定します。
ユーザーの便宜のため、JavaScript を使用して、フィールドの既定値を設定します。
Specify the values of fields on the work item, which are not shown in the feedback form.
This page assumes you are already familiar with using the work item collector.
Warning: The JavaScript exposed by the work item collector is not considered a stable API and may change with new Jira releases.
カスタムトリガーの設定
コレクターを設定して、カスタムトリガーを使用する
If you want to use a different trigger, or button, to launch the work item collector on your website, configure your collector as described below:
Add a new work item collector, or edit an existing work item collector.
[トリガー] セクションまで下にスクロールし、[カスタム] オプションを選択します。
[トリガー テキスト] はカスタム トリガーで上書きされるため、設定する必要はありません。
Adding the work item collector script for a custom trigger
カスタム スクリプトの作成やデバッグは、アトラシアン サポートの範囲には含まれません。支援が必要な場合は、アトラシアン コミュニティのフォーラムに質問を投稿してください。
The work item collector script generated by Jira for adding a custom trigger is slightly different to the script generated for the standard triggers because it includes the JavaScript function for the custom trigger.
Customization of the work item collector is done by creating/extending the global object ATL_JQ_PAGE_PROPS. This allows you to add a custom trigger, set default values for fields and more.
Note: In Jira 5.1 (and version 1.1 of the Issue Collector plugin), the work item collector administrative interface lets you define the custom trigger function UI, and you did not need to include it in the JavaScript on the page. In version 1.2 of the Issue Collector, the custom trigger JavaScript is a part of the generated JavaScript that you should copy and paste into your web page.
The code snippet below shows a sample HTML page with the generated work item collector JavaScript.
In the example below, we've added a simple button in HTML and made that button launch the work item collector. This is done simply by replacing myCustomTrigger in the generated JavaScript with the HTML id of the button ('feedback-button')
<head>
<!-- We pasted the generated code from the Issue Collector here, after choosing a custom trigger -->
<!-- This is the script for the issue collector feedback form -->
<script type="text/javascript" src="<JIRA URL>/s/en_US-ydn9lh-418945332/803/1088/1.2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=d03d7bd1"></script>
<!-- This is the script for specifying the custom trigger. We've replaced 'myCustomTrigger' with 'feedback-button' -->
<script type="text/javascript">
window.ATL_JQ_PAGE_PROPS = {
"triggerFunction": function(showCollectorDialog) {
//Requries that jQuery is available!
jQuery("#feedback-button").click(function(e) {
e.preventDefault();
showCollectorDialog();
});
}
};
</script>
</head>
<body>
<h2>JIRA Issue Collector Demo</h2>
<a href="#" id="feedback-button" class='btn btn-primary btn-large'>Report feedback</a>
</body>
手動によるカスタム トリガー機能の追加
The custom trigger JavaScript will be included in the JavaScript generated by the work item collector. However, this section provides details on how you could do it without pasting in the additional lines of generated JavaScript.
To add a custom trigger, add the property triggerFunction in the global object ATL_JQ_PAGE_PROPS. triggerFunction needs to be defined as a function and takes one argument which is the function for displaying the work item collector.
You can invoke the work item collector from any element on your page by adding a click handler in triggerFunction as shown below. In this example, we will be calling the work item collector from our #feedback-button anchor tag defined in the above HTML markup. You can assign multiple triggers for the same work item collector by adding more click handlers.
window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
// ==== custom trigger function ====
triggerFunction : function( showCollectorDialog ) {
$('#feedback-button').on( 'click', function(e) {
e.preventDefault();
showCollectorDialog();
});
// add any other custom triggers for the issue collector here
}
});
The triggerFunction will be invoked by the work item collector after the $(document).ready() phase.
JavaScript からフィールド値を設定する
フィールド値の設定
The work item collector gives you the option to set field values for any of the fields on the work type. This is done by adding the property fieldValues in the global object ATL_JQ_PAGE_PROPS. There are different methods for setting default values for different field types. The code samples below show a visual representation of a field in Jira and its relevant markup, and how to set a default value for that field type. Use a DOM inspection tool such as Firebug in the Jira Work Item Create Screen to extract the field names and values relevant to your issue collector. Please note that the Issue Collector is not supposed to be a replacement for the Jira REST API. If you require a more customized solution, make use of the Jira REST API to create Jira work items from external websites.
可視フィールド（既定のフィールド値の設定）
If you set the value of a field that is visible on the work item collector feedback form, the fields will already be filled in with that value when the form opens.
非表示フィールド
There might be cases where you might want to set a field value without actually displaying the field on the work item collector. In this case, simply use the same method as above to set the field values via JavaScript. The fields will not be shown as they were not added in the form template but their values will still be present in work itemd created with the work item collector.
フィールド値を設定する JavaScript
フィールド値を設定するには、window.ATL_JQ_PAGE_PROPS の fieldValues ブロック内でキーと値のペアを指定します。すでにカスタム トリガーを定義している場合は、以下の例のように、window.ATL_JQ_PAGE_PROPS の定義に追加するだけで済みます。
Note the names of the fields are always the names of the field in the Jira Create Work Item Screen, not any overridden names you may have provided in the work item collector form.
window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
// ==== custom trigger function ====
triggerFunction : function( showCollectorDialog ) {
$('#feedback-button').on( 'click', function(e) {
e.preventDefault();
showCollectorDialog();
});
},
// ==== we add the code below to set the field values ====
fieldValues: {
summary : 'Feedback for new website designs',
description : 'The font doesn\'t quite look right',
priority : '2'
}
});
特定のフィールド タイプを設定する方法の例
テキスト フィールドの例
Setting the value for a text field, like the summary of the work item, is straightforward. Here's the markup for a text field like Summary in the work item collector (you do not need to add this, this is simply to show the representation that the issue collector contains):
<div class="field-group">
...
<input class="text long-field" id="summary" name="summary" type="text" value="">
...
</div>
そして、次は JavaScript でフィールドの値を設定する方法です。
fieldValues : {
summary : 'This is the default summary value'
}
Select list example with work item priority
Setting the value for a select list field, such as the work item priority, requires a little more effort because you need to know the HTML element id for the choice you want to select. Here's the markup for the Priority field in the work item collector (you do not need to add this, this is simply to show the representation that the work item collector contains):
<div class="field-group">
...
<input id="priority-field" class="text aui-ss-field ajs-dirty-warning-exempt" autocomplete="off">
...
<select class="select" id="priority" name="priority" style="display: none; " multiple="multiple">
<option class="imagebacked" data-icon="/images/icons/priority_blocker.gif" value="1">Blocker</option>
<option class="imagebacked" data-icon="/images/icons/priority_critical.gif" value="2">Critical</option>
...
</select>
...
</div>
そして、次は JavaScript でフィールドの値を設定する方法です。
fieldValues : {
'priority' : '2'
}
複数選択またはチェックボックスの例
Setting the value for a multi-select (like the Browser field) or checkbox requires that you provide an array of values. Like the select list, you need to know the values to set, by looking at the markup on the Create Work Item Screen.
<div class="field-group">
...
<select class="select" id="customfield_10110" multiple="multiple" name="customfield_10110" size="5">
<option value="-1" selected="selected">None</option>
<option value="10039">All Browsers</option>
<option value="10037">Chrome</option>
...
</select>
...
</div>
そして、次は JavaScript でフィールド値を設定する方法です。フィールド値が 1 つだけの場合でも、値の配列として設定する必要があります。
fieldValues : {
'customfield_10110' : [ '10039', '10037' ]
}
カスタム フィールド
Setting a value for a custom field is exactly the same as any other field in Jira. Since multiple custom fields can share the same name, custom fields will be referenced by "customfield_" + the Id of the custom field in Jira. This ID can be seen in the HTML markup for the Create Work Item Screen in Jira, but can also be determine by looking at the URLs on the custom fields screen in Jira administration. Here's what the JavaScript would look like for setting a custom field whose id in Jira was 11111:
fieldValues : {
'customfield_11111' : 'San Francisco'
}
カスケード選択
カスケード選択の設定は 2 つの手順で行います。親値用の手順と子値用の手順です。以下は、カスケード選択フィールドの値を設定する例です。
fieldValues : {
'customfield_12345' : 'Australia',
'customfield_12345:1' : 'Sydney'
}
特殊なフィールド
環境フィールド
By default, the work item collector puts user context such as the URL, User-Agent and screen resolution in the environment field. There might be cases where you wish to include more information in the environment field. In this case, you can add the property environment in the global object ATL_JQ_PAGE_PROPS. This allows you to add key-value pairs that will appear in the environment field in the Jira work item.
window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
// ==== custom trigger function ====
triggerFunction : function( showIssueCollector ) {
...
},
// ==== default field values ====
fieldValues : {
...
},
// ==== Special field config for environment ====
environment : {
'Custom env variable' : $('#build-no').text(),
'Another env variable' : '#007'
}
});
制限付きフィールド
Jira へのログインを必要とするフィールドがあり、その設定には JavaScript を使用できません。担当者は、JavaScript を使用した設定ができないフィールドの例です。
動的関数
Environment と fieldValues プロパティは、JSON オブジェクトを返す関数でもあり、この関数は (コレクター フォームを開く直前ではなく) コレクター トリガーが表示されたときに、直ちに実行されます。これは、ユーザーに関するコンテキスト情報を取得する際に役立つ場合があります。
window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
// ==== custom trigger function ====
triggerFunction : function( showIssueCollector ) {
...
}
// ==== Special field config for environment ====
, environment : function() {
var env_info = {};
if ( window.ADDITIONAL_CUSTOM_CONTEXT ) {
env_info[ 'Additional Context Information' ] = window.ADDITIONAL_CUSTOM_CONTEXT;
}
return env_info;
}
// ==== default field values ====
, fieldValues : function() {
var values = {};
var error_message = $('.error_message');
if ( error_message.length !== 0 ) {
// record error message from the page context rather than asking the user to enter it
values[ 'summary' ] = error_message.children('.summary').text();
values[ 'description' ] = error_message.children('.description').text();
}
return values;
}
});
Embedding multiple work item collectors
If you want to have two different forms appear on the same web page, you will need to create two different work item collectors in Jira. To set custom triggers, or set field values on those work item collectors requires a few changes to your page:
Include the generated JavaScript for both of your work item collectors in the page.
各コレクターの ID を検索します。これには 2 つの方法があります。
スクリプトのパラメーターは、"collectorId=<8 character id> です。それが必要な ID です。
Go to the work item collector page in the Admin section and click on the Work Item Collector you wish to embed. Copy the
collectorIdfrom the URL.
https://<JIRA_URL>/secure/ViewCollector!default.jspa?projectKey=<PROJECT_KEY>&collectorId=<copy this part here>
Then, create separate namespaces for each of the work item collectors in the ATL_JQ_PAGE_PROPS object.
window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
'<collectorId_1>' : {
triggerFunction:
// define trigger function
fieldValues: {
// define field values here
}
},
'<collectorId_2>' : {
triggerFunction:
// define trigger function
fieldValues: {
//define field values here
}
}
});
Embedding the work item collector
Embedding the work item collector in your Confluence Site
The work item collector can be embedded into Confluence using the HTML Include Macro. Note that using the HTML Include Macro would require you to embed the work item collector code separately on each page.
The work item collector was previously embeddable in Confluence via a User Macro, allowing you to create a re-usable work item collector macro that other Confluence users can embed into their pages. This option is currently unavailable due to a known bug: CONF-26104.
Embedding the work item collector is not currently supported in Confluence Cloud.
完全なソースコード
This source code shows how to embed two different work item collectors on the same page with custom triggers.
<body>
<h2>JIRA Issue Collector Demo</h2>
<a href="#" id="feedback_button" class='btn btn-primary btn-large'>Report feedback</a><br />
<a href="#" id="bug_button" class='btn btn-primary btn-large'>Report bug</a>
<!-- JIRA Issue Collector - append this at the bottom of <body> -->
<script type="text/javascript" src="https://<JIRA URL>/s/en_US-ydn9lh-418945332/803/1088/1.2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=<collectorId_1>"></script>
<script type="text/javascript" src="https://<JIRA URL>/s/en_US-ydn9lh-418945332/803/1088/1.2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=<collectorId_2>"></script>
<!-- We will customize JIRA in the following script tag -->
<script type="text/javascript">
// safely use jquery here since the issue collector will load it for you
$(document).ready(function() {
window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
// ==== feedback collector ====
'<collectorId_1>' : {
// === custom trigger function ===
triggerFunction : function( showCollectorDialog ) {
$('#feedback_button').click( function(e) {
e.preventDefault();
showCollectorDialog();
});
}
// === default and hidden field values ===
, fieldValues : {
// default values
summary : 'Feedback for new website designs'
, description : 'The font doesn\'t quite look right'
// hidden field value
, priority : '2'
}
}
// ==== bug collector ====
, '<collectorId_2>' : {
// === custom trigger function ===
triggerFunction : function( showCollectorDialog ) {
$('#bug_button').click( function(e) {
e.preventDefault();
showCollectorDialog();
});
}
// === additional environment details ===
, environment : function() {
var env_info = {};
if ( window.ADDITIONAL_CUSTOM_CONTEXT ) {
env_info[ 'Additional Context Information' ] = window.ADDITIONAL_CUSTOM_CONTEXT;
}
return env_info;
}
// === default field values ===
, fieldValues : function() {
var values = {};
var error_message = $('.error_message');
if ( error_message.length !== 0 ) {
// record error message from the page context rather than asking the user to enter it
values[ 'summary' ] = error_message.children('.summary').text();
values[ 'description' ] = error_message.children('.description').text();
}
return values;
}
}
});
});
</script>
</body>
Is localization of a work item collector possible?
You can create a work item collector 100% localized to the default language of your Jira instance. Beyond that, complete localization of the work item collector is not possible.
The strings and text in the work item collector feedback form of the work item collector is a combination of:
The work item collector strings set by the Jira Administrator
Jira の既定の言語設定、またはユーザーが Jira にログインしている場合はユーザーの言語選択。
すべてのユーザーに、Jira 管理者が設定した方法でフィールドの名前が表示されます。この表示は Jira の既定の言語に影響を受けることも、ログインした Jira ユーザーの既定の言語に影響を受けることもありません。
フィールドの説明は、JIRA 管理 UI で設定された方法で、すべてのユーザーに表示されます。
他のすべての項目の場合：
匿名ユーザーには、他のすべての項目が既定の JIRA 言語で表示されます。
ログインしたユーザーには、フィードバック フォーム内の他のすべての項目が Jira プロファイルで指定された言語で表示されます。
Because of the above, you cannot create a single work item collector that will present itself entirely in the language of the end-user.
However, if you want to create a work item collector that will present itself to anonymous users in the default language of your Jira instance, you should:
Use the custom feedback template for the work item collector
Jira のフィールド ラベルおよび名前とメールのラベルを、既定の JIRA 言語で使用したい単語に変更します。
ブラウザの言語設定は、フィードバック フォームのテキストには影響しません。
この内容はお役に立ちましたか?