Jira 課題コレクターの高度利用
カスタムトリガーの設定
コレクターを設定してカスタム トリガーを使用する
別のトリガーやボタンを使用して、ウェブサイト上で課題コレクターを起動する場合は、以下の説明のように、課題コレクターを設定します。
- 新しい課題コレクターを追加するか、既存の課題コレクターを編集します。
- トリガーのセクションまで下にスクロールし、「カスタム」オプションを選択します。
- トリガー テキストはカスタム トリガーによって上書きされるため、設定する必要はありません
カスタム トリガー用の課題コレクター スクリプトを追加する
カスタム スクリプトの作成やデバッグは、アトラシアン サポートの範囲には含まれません。サポートが必要な場合は、https://answers.atlassian.com に質問を投稿してください。
カスタム トリガーの追加用に Jira で生成される課題コレクター スクリプトは、カスタムトリガー向けの JavaScript 機能が含まれているため、標準のトリガー用に生成されたスクリプトとは若干異なります。
課題コレクターのカスタマイズは、グローバルオブジェクト ATL_JQ_PAGE_PROPS の作成または拡張によって行います。これによって、カスタムトリガーの追加、フィールド既定値の設定、その他が可能になります。
Jira 5.1 (ならびに課題コレクター プラグインのバージョン 1.1) の場合、課題コレクターの管理インターフェイスでカスタム トリガー機能の UI を定義できるため、そのページの JavaScript に含める必要はありませんでした。課題コレクターのバージョン 1.2 では、カスタム トリガーの JavaScript は生成される JavaScript の一部であり、これをコピーして Web ページに貼り付ける必要があります。
以下のコード スニペットは、生成された課題コレクターの JavaScript を貼り付けたサンプル HTML ページを示しています。
以下の例では、HTML に簡単なボタンを追加し、そのボタンで課題コレクターを起動するようにしています。これは、生成された JavaScript の 「myCustomTrigger」をボタン（「フィードバックボタン」）の HTML ID で置き換えることにより、簡単に実行できます。
<head>
<!-- We pasted the generated code from the Issue Collector here, after choosing a custom trigger -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css"
integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<!-- 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>
手動によるカスタム トリガー機能の追加
カスタム トリガー JavaScript は課題コレクターによって生成される JavaScript に含まれています。しかし、このセクションでは、生成される 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
}
});triggerFunction は、$(document).ready() 部分の後で、課題コレクターによって呼び出されます
JavaScript からフィールド値を設定する
フィールド値の設定
課題コレクターによって、課題タイプの任意のフィールドにフィールド値を設定するオプションを利用できます。これを実行するには、グローバル オブジェクト ATL_JQ_PAGE_PROPS に fieldValues プロパティを追加します。異なるフィールド タイプの既定値を設定するには、それぞれ別の方法を使用します。下記のコード例では、Jira フィールドと関連するマークアップの実際の例と、そのフィールド タイプの既定値を設定する方法を示しています。Jira 課題作成画面で DOM 検査ツール (Firebug など) を使用すると、課題コレクターに関連するフィールド名と値を抽出できます。課題コレクターは Jira REST API の代替として想定されているわけではないことに注意してください。さらにカスタマイズされたソリューションが必要な場合、Jira REST API を利用して、外部のウェブ サイトから Jira 課題を作成できます。Jira をバックエンドとするフロントエンド インターフェイスを構築する例として、Jira Travel App をご参照ください。
表示フィールド (既定のフィールド値の設定)
課題コレクターのフィードバック フォーム上に表示されるフィールドの値を設定すると、フォームが開いたときに、フィールドにはすでにその値が入力されています。
非表示のフィールドを設定する
課題コレクターでフィールドを実際に表示しないで、フィールド値を設定したい場合があります。この場合は、上記と同様の方法で、JavaScript を使用してフィールド値を設定するだけです。そのフィールドはフォーム テンプレートに追加されておらず、表示されませんが、フィールド値は課題コレクターによって作成された課題に含まれます。
フィールド値を設定する JavaScript
フィールド値を設定するには、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'
}
});特定のフィールド タイプを設定する方法の例
テキスト フィールドの例
課題サマリのような、テキスト フィールドの値を設定するのは簡単です。以下は、課題コレクターのサマリなど、テキスト フィールドのマークアップです。（これは課題コレクターに含まれる表現を表示しているだけなので、追加する必要はありません。）。
<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'
}課題優先度の選択リストの例
課題の優先度など、選択リスト フィールドの値を設定するには、選択項目の HTML 要素 ID を知っている必要があるため、もう少し努力が必要になります。以下は、課題コレクターの優先度フィールドのマークアップです。（これは課題コレクターに含まれる表現を表示しているだけなので、追加する必要はありません）。
<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'
}複数選択またはチェックボックスの例
複数選択（ブラウザのフィールドなど）またはチェックボックスの値を設定するには、値の配列を入力する必要があります。選択リストと同様に、課題作成画面のマークアップを見て、設定する値を知っている必要があります。
<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' ]
}カスタム フィールド
カスタム フィールドの値を設定する方法は、Jira の他のフィールドとまったく同じです。複数のカスタム フィールドは同じ名前を共有することが可能であるため、カスタムフィールドは、"customfield_" + Jira のカスタム フィールドの ID によって参照されます。この ID は、Jira の課題作成画面の HTML マークアップに表示されるだけでなく、Jira 管理のカスタム フィールド画面の URL を見て確認することもできます。Jira での ID が 11111 であるカスタム フィールドを設定する場合、JavaScript は次のようになります。
fieldValues : {
'customfield_11111': 'San Francisco'
}カスケード選択
カスケード選択の設定は 2 つの手順で行います。親値用の手順と子値用の手順です。以下は、カスケード選択フィールドの値を設定する例です。
fieldValues : {
'customfield_12345': 'Australia',
'customfield_12345:1': 'Sydney'
}特殊なフィールド
環境フィールド
既定では、課題コレクターは、URL、ユーザー エージェント、画面解像度などのユーザー コンテキストを環境フィールドに置いています。環境フィールドにもっと多くの情報を含めたい場合があります。この場合は、グローバル オブジェクト ATL_JQ_PAGE_PROPS に environment プロパティを追加します。これによって、JIRA 課題の環境フィールドに表示されるキー値のペアを追加できます。
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;
}
});複数の課題コレクターの埋め込み
2 つの異なるフォームを同じ Web ページ上に表示したい場合、Jira で 2 つの異なる課題コレクターを作成する必要があります。カスタム トリガーの設定、または課題コレクターのフィールド値の設定を行うには、ページにいくつか変更を加える必要があります。
- 課題コレクターのそれぞれに対して生成された JavaScript をページに含めます。
- 各コレクタの ID を検索します。これには 2 つの方法があります。
- スクリプトのパラメーターは、 "collectorId=<8 character id> です。 それが必要な ID です。
管理セクションの課題コレクター ページに移動し、埋め込みたい課題コレクターをクリックします。URL から collectorId をコピーします。
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
}
}
});課題コレクターの埋め込み
Confluence サイトへの課題コレクターの埋め込み
HTML マクロを使用して、課題コレクターを Confluence に埋め込むことができます 。HTML マクロを使用する際、各ページに課題コレクター コードを個別に埋め込む必要がある点に注意してください。
以前は、ユーザー マクロを使用して Confluence に課題コレクターを埋め込むことができたため、他の Confluence ユーザーが自身ページに埋め込むことができる再利用可能な課題コレクター マクロを作成できました。このオプションは、以下の既知のバグのため、現在は利用できません: CONF-26104 - 課題詳細を取得中... ステータス
現在、課題コレクターの埋め込みは、Confluence クラウドではサポートされていません。
Jira
上記のカスタム トリガー用のスクリプトと HTML マークアップを通知バナー設定画面に埋め込むことによって、課題コレクターを Jira ページの通知バナーに埋め込むことができます。カスタム トリガーの位置を変更したい場合、jQuery を使用して簡単に変更できます。次のスニペットは、すべての Jira ページのフッターにカスタム トリガーを追加する方法を示しています。
通知バナーの HTML マークアップがで無効になっているため、Jira クラウ ド サイトに課題コレクターを埋め込むことはできません。
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) {
...
});
}
});課題コレクターを埋め込むには、通知バナーの HTML マークアップを有効にする必要があるので、注意してください。
完全なソースコード
このソースコードは、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>課題コレクターのローカライズは可能ですか？
Jira インスタンスの既定の言語に 100％ローカライズされた課題コレクターを作成できます。それ以上に、課題コレクターの完全なローカライズを行うのは不可能です。
課題コレクターの課題コレクター フィードバック フォーム内の文字列とテキストは、次の組み合わせになっています。
- Jira 管理者が設定した課題コレクター文字列
- Jira の既定の言語設定、またはユーザーが Jira にログインしている場合、ユーザーの言語選択のいずれか.
- フィールドの名前は、Jira 管理者が設定した方法で、すべてのユーザーに表示されます。この表示は Jira の既定の言語に影響を受けることも、ログインした Jira ユーザーの既定の言語に影響を受けることもありません。
- フィールドの説明は、JIRA 管理 UI で設定された方法で、すべてのユーザーに表示されます。
- 他のすべての項目の場合：
- 匿名ユーザーには、他のすべての項目が既定の JIRA 言語で表示されます。
- ログインしたユーザーには、フィードバック フォーム内の他のすべての項目が Jira プロファイルで指定された言語で表示されます。
以上のことから、すべてがエンドユーザーの使用する言語で表示される課題コレクターを作成することはできません。
しかし、匿名ユーザーに対して Jira インスタンスの既定の言語で表示される課題コレクターを作成したい場合、次のような方法をとります。
- 課題コレクター用のカスタム フィードバック テンプレートを使用します。
- Jira のフィールド ラベルおよび名前とメールのラベルを、既定の JIRA 言語で使用したい単語に変更します。
ブラウザの言語設定は、フィードバック フォームのテキストには影響しません。