Advanced Use of the JIRA Issue Collector

Using the Issue Collector

このページの内容

関連コンテンツ

  • 関連コンテンツがありません

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

JIRA 課題コレクターのカスタマイズ

JIRA 課題コレクターは、JIRA 課題コレクター管理画面で生成される 1 行の他には JavaScript を追加することなく使用できます。しかし、いくつか他の方法を使って JIRA 課題コレクターをカスタマイズすることもできます。

  • パッケージ化されたトリガーで提供されるものとは別のリンクやボタンからフィードバック フォームを起動するように、カスタム・トリガーを設定します。
  • ユーザーの便宜のため、JavaScript を使用して、フィールドの既定値を設定します。  
  • フィードバック フォームに表示されない、課題のフィールド値を指定します。

This page assumes you are already familiar with Using the Issue Collector.

(warning) Warning: The JavaScript exposed by the issue collector is not considered a stable API and may change with new JIRA releases.

On this page:

関連ページ

カスタムトリガーの設定

コレクターを設定して、カスタムトリガーを使用する

別のトリガーやボタンを使用して、ウェブサイト上で課題コレクターを起動する場合は、以下の説明のように、課題コレクターを設定します。

  1. 新しい課題コレクターを追加するか、既存の課題コレクターを編集します。
  2. トリガーのセクションまで下にスクロールし、「カスタム」オプションを選択します。
  3. トリガー テキストはカスタム トリガーによって上書きされるため、設定する必要はありません

Screenshot: Using a custom trigger for an issue collector

 

 

 



カスタム トリガー用の課題コレクター スクリプトの追加

カスタム スクリプトの作成やデバッグは、アトラシアン サポートの範囲には含まれません。サポートが必要な場合は、https://answers.atlassian.com  に質問を投稿してください。

カスタム トリガーの追加用に JIRA で生成される課題コレクター スクリプトは、カスタムトリガー向けの JavaScript 機能が含まれているため、標準のトリガー用に生成されたスクリプトとは若干異なります。

課題コレクターのカスタマイズは、グローバルオブジェクト ATL_JQ_PAGE_PROPS の作成または拡張によって行います。これによって、カスタムトリガーの追加、フィールド既定値の設定、その他が可能になります。

注意 ：JIRA5.1 （および課題コレクター プラグインのバージョン1.1）の場合、課題コレクターの管理インターフェースでカスタムトリガー機能の UI を定義できるため、UI をページの JavaScript に含める必要はありませんでした。課題コレクターのバージョン1.2 では、カスタムトリガーの JavaScript は、生成される JavaScript の一部であり、コピーして Web ページに貼り付ける必要があります。

以下のコード スニペットは、課題コレクター用に生成される JavaScript を貼り付けたサンプル HTML ページを示しています。

In the example below, we've added a simple button in HTML, and made that button launch the issue 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>

Custom issue collector screenshot


手動によるカスタム トリガー機能の追加

The custom trigger JavaScript will be included in the JavaScript generated by the Issue Collector.  However, this section provides details on how you could do it without pasting in the additional lines of generated JavaScript.

カスタム トリガーを追加するには、グローバル オブジェクト ATL_JQ_PAGE_PROPS に triggerFunction プロパティを追加します。triggerFunction は関数として定義し、課題コレクターを表示する関数を示す引数を 1 つ取る必要があります。

以下に示すように、triggerFunction にクリック ハンドラを追加することにより、ページ上の任意の要素から課題コレクターを呼び出すことができます。この例では、上記の HTML マークアップで定義された #feedback-button アンカー タグから課題コレクターを呼び出します。クリック ハンドラをさらに追加することにより、同じ課題コレクターに複数のトリガーを割り当てることができます。

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 Issue Collector after the $(document).ready() phase.

JavaScript からフィールド値を設定する

フィールド値の設定

課題コレクターによって、課題タイプの任意のフィールドにフィールド値を設定するオプションを利用できます。これを実行するには、グローバル オブジェクト ATL_JQ_PAGE_PROPS に fieldValues プロパティを追加します。異なるフィールド タイプの既定値を設定するには、それぞれ別の方法を使用します。下記のコードサンプルでは、​​JIRA フィールドと関連するマークアップの視覚表現と、そのフィールド タイプの既定値を設定する方法を示しています。JIRA 課題作成画面で Firebug のような DOM 検査ツールを使用して、課題コレクターに関連するフィールド名と値を抽出します。課題コレクターは JIRA REST API の代替と想定されているわけではないことに注意してください 。カスタマイズされたソリューションがさらに必要な場合は、JIRA REST API を利用して、外部のウェブサイトから JIRA 課題を作成します。JIRA Travel App は、JIRA をバックエンドとしてフロントエンド インターフェースを構築する方法のよい例です。

可視フィールド（既定のフィールド値の設定）

課題コレクターのフィードバック フォーム上に表示されるフィールドの値を設定すると、フォームが開いたときに、フィールドにはすでにその値が入力されています。  

非表示フィールド

There might be cases where you might want to set a field value without actually displaying the field on the Issue 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 issues created with the Issue Collector.

JavaScript for Setting field values

フィールド値を設定するには、window.ATL_JQ_PAGE_PROPS の "FieldValues" ​​ブロック内のフィールド名とフィールド値のペアを指定します。すでにカスタム トリガーを定義している場合は、以下の例のように、window.ATL_JQ_PAGE_PROPS の定義に追加するだけですみます。

フィールドの名前は常に JIRA 課題作成画面のフィールド名であり、課題コレクター フォームで与えられる上書き名ではないことに注意してください。

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 issue Summary, is straightforward.  Here's the markup for a text field like Summary in the issue 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'
}
課題優先度の選択リストの例

Setting the value for a select list field, such as the issue 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 issue 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 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 Issue 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 Issue 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'
}

Special Case Fields

環境フィールド

By default the Issue 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 on the environment field in the JIRA issue.

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'
	}
});
制限付きフィールド

Some fields that require a user to be logged into JIRA cannot be set through JavaScript.  Assignee is an example of a field that cannot be set via JavaScript.

動的関数

Environment and fieldValues properties can also be a function returning a JSON object that will be executed immediately when the collector trigger is shown (not just before opening the collector form).  This might come in handy when you might wish to capture contextual information relevant to the user.

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;
 
	}
});

複数の課題コレクターの埋め込み

If you want to have two different forms appear on the same web page, you will need to create two different issue collectors in JIRA.  To set custom triggers, or set field values on those issue collectors requires a few changes to your page:

  1. 課題コレクターのそれぞれに対して生成された JavaScript をページに含めます。
  2. 各コレクタの ID を検索します。これには 2 つの方法があります。
    1. スクリプトのパラメーターは、 "collectorId=<8 character id> です。 それが必要な ID です。

    2. Go to the Issue Collector page in the Admin section and click on the Issue Collector you wish to embed.  Copy the collectorId from the URL.

https://<JIRA_URL>/secure/ViewCollector!default.jspa?projectKey=<PROJECT_KEY>&collectorId=<copy this part here>

次に、ATL_JQ_PAGE_PROPS オブジェクト内に課題コレクターごとの名前空間を別々に作成します。

 

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 Issue Collector

Embedding the Issue Collector in your Confluence Site

The Issue Collector can be embedded into Confluence using the HTML Macro. Note that using the HTML Macro would require you to embed the Issue Collector code separately on each page.

The Issue Collector was previously embeddable in Confluence via a User Macro, allowing you to create a re-usable Issue Collector macro that other Confluence users can embed into their pages. This option is currently unavailable due to a known bug:  CONF-26104 - Getting issue details... STATUS

Embedding the Issue Collector is not currently supported in Confluence Cloud.

Jira

The Issue Collector can be embedded in the Announcement Banner on a JIRA page by embedding the above script and HTML markup for your custom trigger in the Announcement Banner configuration screen. If you wish to change the location of your custom trigger, this can be easily done via jQuery. The following snippet shows how you can add the custom trigger onto the footer of all JIRA pages.

You cannot embed an Issue Collector in your JIRA Cloud instance since HTML markup is disabled for the Announcement Banner.

window.ATL_JQ_PAGE_PROPS = $.extend(window.ATL_JQ_PAGE_PROPS, {
	// ==== custom trigger function ====
	triggerFunction : function( showIssueCollector ) {
		// button markup - relevant css can be added via the style attribute
		var feedbackButton = "<a id='feedback-button'>Got Feedback?</a>";
		// embed the button in the footer
		$('.footer-link').append(feedbackButton);
		
		$('#feedback-button').click(function(e) {
			...
		});
	}

});

Please note that embedding the Issue Collector requires you to enable HTML markup for the Announcement Banner.

Full Source Code

このソースコードは、2 つの異なる課題コレクターをカスタム トリガーとともに同じページに埋め込む方法を示しています。

<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>

課題コレクターのローカライズは可能ですか？

You can create an issue collector 100% localized to the default language of your JIRA instance.  Beyond that, complete localization of the issue collector is not possible.

課題コレクターの課題コレクター フィードバック フォーム内の​​文字列とテキストは、次の組み合わせになっています。

  1. JIRA 管理者が設定した課題コレクター文字列
  2. JIRA の既定の言語設定、またはユーザーが JIRA にログインしている場合、ユーザーの言語選択のいずれか.
  • All users will see the names of the fields as they are set by the JIRA Administrator.  These are not affected by the default language of JIRA, and are not affected by the default language of logged in JIRA users.
  • フィールドの説明は、JIRA 管理 UI で設定された方法で、すべてのユーザーに表示されます。
  • 他のすべての項目の場合：
    • 匿名ユーザーには、他のすべての項目が既定の JIRA 言語で表示されます。
    • ログインしたユーザーには、フィードバック フォーム内の他のすべての項目が JIRA プロファイルで指定された言語で表示されます。

以上のことから、すべてがエンドユーザーの使用する言語で表示される課題コレクターを作成することはできません。  

しかし、匿名ユーザーに対して JIRA インスタンスの既定の言語で表示される課題コレクターを作成したい場合、次のような方法をとります。

  1. Use the custom feedback template for the Issue Collector
  2. JIRA のフィールド ラベルおよび名前とメールのラベルを、既定の JIRA 言語で使用したい単語に変更します。

ブラウザの言語設定は、フィードバック フォームのテキストには影響しません。

最終更新日 2016 年 11 月 21 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

関連コンテンツ

  • 関連コンテンツがありません
Powered by Confluence and Scroll Viewport.