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

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

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

  • パッケージ化されたトリガーで提供されるものとは別のリンクやボタンからフィードバック フォームを起動するように、カスタム・トリガーを設定します。

  • ユーザーの便宜のため、JavaScript を使用して、フィールドの既定値を設定します。  

  • フィードバック フォームに表示されない、課題のフィールド値を指定します。

このページでは、課題コレクターの使用にすでに習熟しているユーザーを前提にしています。

警告: 課題コレクターが公開する JavaScript は安定的な API とはみなされておらず、新しい Jira リリースで変更される可能性があります。

カスタムトリガーの設定

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

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

  1. 新しい課題コレクターを追加するか、既存の課題コレクターを編集します。

  2. [トリガー] セクションまで下にスクロールし、[カスタム] オプションを選択します。

  3. [トリガー テキスト] はカスタム トリガーで上書きされるため、設定する必要はありません。

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

カスタム スクリプトの作成やデバッグは、アトラシアン サポートの範囲には含まれません。サポートが必要な場合は、アトラシアン コミュニティ フォーラムに質問を投稿してください。

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

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

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

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

以下の例では、HTML で簡単なボタンを追加して、そのボタンで課題コレクターを起動するようにしています。これは、生成された JavaScript の myCustomTrigger をボタン (「feedback-button」) の HTML ID で置き換えることによって簡単に実行できます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 <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>
Jira 課題コレクターのデモ

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

カスタム トリガー JavaScript は、課題コレクターによって生成される JavaScript に含まれています。しかし、このセクションでは、生成された JavaScript に追加の行を貼り付けずに行う方法について説明します。

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 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 の 1 つのフィールドとそれに関連するマークアップの実際の例と、そのフィールド タイプの既定値を設定する方法を示しています。Jira の課題作成画面で Firebug などの DOM 検査ツールを使用して、課題コレクターに関連するフィールド名と値を抽出します。課題コレクターは Jira REST API に代わるものとして想定されている訳ではないことにご注意ください。よりカスタマイズされたソリューションが必要な場合は、Jira REST API を利用して外部の web サイトから Jira 課題を作成できます。

可視フィールド(既定のフィールド値の設定)

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

非表示フィールド

課題コレクターでフィールドを実際に表示しないで、フィールド値を設定したい場合があります。この場合は、上記と同様の方法で、JavaScript を使用して、フィールド値を設定するだけですみます。そのフィールドはフォーム テンプレートに追加されていないため、表示されませんが、フィールド値は課題コレクターによって作成された課題に含まれます。

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

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 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' } });

特定のフィールド タイプを設定する方法の例 

テキスト フ​​ィールドの例

課題サマリのような、テキスト フ​​ィールドの値を設定するのは簡単です。以下は、課題コレクターのサマリなど、テキスト フ​​ィールドのマークアップです。(これは課題コレクターに含まれる表現を表示しているだけなので、追加する必要はありません。)。

 

1 2 3 4 5 6 7 8 <div class="field-group"> ... <input class="text long-field" id="summary" name="summary" type="text" value=""> ... </div>

そして、次は JavaScript でフィールドの値を設定する方法です。

1 2 3 4 5 6 fieldValues : { summary : 'This is the default summary value' }

課題優先度の選択リストの例

課題の優先度などの選択リスト フィールドの値を設定したい場合、選択肢の HTML 要素 ID を知っている必要があるため、少し複雑になります。以下は、課題コレクターの優先度フィールドのマークアップです (これは課題コレクターが含む表現を表示しているだけなので、これを追加する必要はありません)。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 <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 でフィールドの値を設定する方法です。

1 2 3 4 5 6 fieldValues : { 'priority' : '2' }

複数選択またはチェックボックスの例

複数選択(ブラウザのフィールドなど)またはチェックボックスの値を設定するには、値の配列を入力する必要があります。選択リストと同様に、課題作成画面のマークアップを見て、設定する値を知っている必要があります。

1 2 3 4 5 6 7 8 9 10 11 12 13 <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 つだけの場合でも、値の配列として設定する必要があります。

1 2 3 4 5 6 fieldValues : { 'customfield_10110' : [ '10039', '10037' ] }

カスタム フィールド

カスタム フィールドの値を設定する方法は、Jira の他のフィールドとまったく同じです。複数のカスタム フィールドは同じ名前を共有することが可能であるため、カスタム フィールドは、"customfield_" + Jira のカスタム フィールドの ID によって参照されます。この ID は、Jira の課題作成画面の HTML マークアップに表示されるだけでなく、Jira 管理のカスタム フィールド画面の URL を見て確認することもできます。Jira での ID が 11111 であるカスタム フィールドを設定する場合、JavaScript は次のようになります。

1 2 3 4 5 6 fieldValues : { 'customfield_11111' : 'San Francisco' }

カスケード選択

カスケード選択の設定は 2 つの手順で行います。親値用の手順と子値用の手順です。以下は、カスケード選択フィールドの値を設定する例です。

1 2 3 4 5 6 7 fieldValues : { 'customfield_12345' : 'Australia', 'customfield_12345:1' : 'Sydney' }

特殊なフィールド

環境フィールド

初期設定では、課題コレクターは、URL、ユーザー エージェント、画面解像度などのユーザー コンテキストを環境フィールドに配置します。環境フィールドにもっと多くの情報を含める場合は、グローバル オブジェクト [ATL_JQ_PAGE_PROPS] に [environment] プロパティを追加します。これによって、Jira 課題の環境フィールドに表示されるキーと値のペアを追加できます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 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 を使用した設定ができないフィールドの例です。

動的関数

EnvironmentfieldValues の各プロパティは JSON オブジェクトを返す関数でもあり、この関数は (コレクター フォームを開く直前ではなく) コレクター トリガーが表示されたときに直ちに実行されます。これは、ユーザーに関するコンテキスト情報を取得する際に役立つ場合があります。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 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 つの異なる課題コレクターを作成する必要があります。カスタム トリガーの設定、または課題コレクターのフィールド値の設定を行うには、ページにいくつか変更を加える必要があります。

  1. 課題コレクターのそれぞれに対して生成された JavaScript をページに含めます。

  2. 各コレクターの ID を検索します。これには 2 つの方法があります。

    1. スクリプトのパラメーターは、"collectorId=<8 character id> です。それが必要な ID です。

    2. 管理セクションの課題コレクター ページに移動して、埋め込む課題コレクターをクリックします。URL から collectorId をコピーします。

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 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 クラウドではサポートされていません。

完全なソースコード

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 <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% ローカライズされた課題コレクターを作成できます。それ以上に、課題コレクターの完全なローカライズを行うのは不可能です。

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

  1. Jira 管理者が設定した課題コレクター文字列

  2. Jira の既定の言語設定、またはユーザーが Jira にログインしている場合はユーザーの言語選択。

  • すべてのユーザーに、Jira 管理者が設定した方法でフィールドの名前が表示されます。この表示は Jira の既定の言語に影響を受けることも、ログインした Jira ユーザーの既定の言語に影響を受けることもありません。

  • フィールドの説明は、JIRA 管理 UI で設定された方法で、すべてのユーザーに表示されます。

  • 他のすべての項目の場合:

    • 匿名ユーザーには、他のすべての項目が既定の JIRA 言語で表示されます。

    • ログインしたユーザーには、フィードバック フォーム内の他のすべての項目が Jira プロファイルで指定された言語で表示されます。

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

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

  1. 課題コレクター用のカスタム フィードバック テンプレートを使用します。

  2. Jira のフィールド ラベルおよび名前とメールのラベルを、既定の JIRA 言語で使用したい単語に変更します。

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

その他のヘルプ