Configuring Renderers
概要
JIRA currently ships with the following renderers:
- For text fields:
- The Default Text Renderer, which displays plain text; and
- The Wiki Style Renderer (utilising the Confluence wiki engine), which displays rich text (HTML).
To see how a 'Wiki Style Renderer' field will look when it is displayed to a user, please see Editing Rich-Text Fields.
- For multi-select fields:
- The Autocomplete Renderer, which allows the user to start typing text which is then 'autocompleted', or to select from a dropdown list of options; and
- The Select List Renderer, which simply provides a dropdown list of options. For custom fields of type Multi Select, only the Select List Renderer is available. Furthermore, when modifying a field configuration, you will not be able to configure a Multi Select custom field's renderer.
Renderers are configured on a per field basis. To configure a renderer for a particular field, see Specifying Field Behavior. Note that you can configure the same field differently for different projects and issue types — see Associating Field Behavior with Issue Types.
Renderers are implemented as JIRA plugins, meaning that any renderer can be easily added to or removed from use within JIRA. This includes any custom renderers that may be developed. For details see configuring.
レンダラーを設定する前に、「JIRA アプリケーションに関する情報」をお読みください。
レンダラーはフィールドの値のレンダリング (ビュー) に影響を与えます。つまり、課題データに影響を与えずに異なるレンダラーに移行できます。ビューのみが変更されます。つまり、新しいレンダラーを使用した課題の表示方法が気に入らない場合は、課題データに影響を与えずに元に戻すことができます。
Renderable Fields
Potentially any field within JIRA can be a renderable field, but this only really makes sense in the case of text-based fields (for the Default Text Renderer and the Wiki Style Renderer) and multi-select fields (for the Autocomplete Renderer and the Select List Rendered). The following table shows the JIRA fields that are renderable out-of-the-box:
フィールド | 利用可能なレンダラー |
|---|---|
説明 | Wiki Style Renderer (default), Default Text Renderer. |
コメント | Wiki Style Renderer (default), Default Text Renderer. |
環境 | Wiki Style Renderer (default), Default Text Renderer. |
コンポーネント | Autocomplete Renderer (default), Select List Renderer. |
影響バージョン | Autocomplete Renderer (default), Select List Renderer. |
修正対象バージョン | Autocomplete Renderer (default), Select List Renderer. |
カスタムのフィールドタイプ「フリーテキストフィールド (無制限のテキスト)」 | |
カスタムのフィールドタイプ「テキストフィールド」 | |
カスタムのフィールドタイプ「マルチ選択」 | |
カスタムのフィールドタイプ「バージョンピッカー」 | Autocomplete Renderer (default), Select List Renderer. |
Renderer Types
JIRA には次のレンダラーが付属しています。
- for text fields: Wiki Style Renderer and Default Text Renderer
- for multi-select fields: Autocomplete Renderer and Select List Renderer
Default Text Renderer
The Default Text Renderer renders a field's content as plain text, with the following additional auto-linking features:
| コンテンツ | 説明 | サンプル |
|---|---|---|
| JIRA 課題 | テキストに、JIRA 課題キーを解決するテキストが含まれている場合、その課題を示す HTML リンクが生成されます。 |  |
| Web リンク | テキストに Web サイト上の Web ページを解決するテキストが含まれている場合、その Web リンクを示す HTML リンクが生成されます。 |  |
It is not possible to disable the Default Text Renderer plugin as it is required for the system to function properly. If a text field is setup to use a renderer that is later disabled, the field will revert to using the Default Text Renderer.
Wiki Style Renderer
The Wiki Style Renderer allows a user to enter wiki markup to produce html content, as described in 'Editing Rich-Text Fields' in the JIRA User's Guide.
このレンダラーは Confluence Wiki レンダラーエンジンを使用しているため、Confluence Wiki 記法を使用します。Confluence 記法は学びやすく、以下が可能です。
- Italic, bold and underlined text.
- Multiple levels of headings to organize your document.
- Bullets, numbering, tables and quotations.
- Images, screenshots, and emoticons.
- Powerful mini-applications using macros.
A full notation guide can be found here.
The Wiki Style Renderer can only be used with JDK 1.4 and up. The renderer will not run on JDK 1.3.
Please note that some fields may require further field behavior configurations to be enabled — see Choosing a Renderer.
Wiki Style Renderer Macro Support
The Wiki Style Renderer supports pluggable macros in the same way that Confluence does. Macros provide an easy and powerful extension point to the wiki markup language. JIRA ships with a number of macros as described in the JIRA User's Guide.
JIRA and Confluence can share macros, but keep in mind that many Confluence macros are very specific to the Confluence application and will therefore not run within JIRA. For example, the Children macro in Confluence shows links to all of a Page's child pages. JIRA has no concept of 'page' and therefore this macro will not function in JIRA.
Autocomplete and Select List Renderers
The Autocomplete and Select List Renderers let you start typing text, which is then autocompleted, or to select from a dropdown list of options.
JIRA オペレーションに関する情報
The fact that JIRA allows you to configure different renderers across different projects/issue types for the same field has implications for bulk operations. Also, since the Wiki Style Renderer inherently creates HTML as its end product, there are implications as to how this will behave when issue data is viewed outside JIRA's web front-end.
一括移動
When performing a bulk move operation you can either move issues to an environment (project/issue type) where the renderer types for the fields are the same or where they will be different.
レンダラーのタイプが同じ場合
移動先のレンダラーのタイプが同じ場合、移動後の課題タイプの表示方法に変化はなく、警告メッセージは表示されません。
レンダラーのタイプが異なる場合
移動によって影響を受けるフィールドのイオずれかの定義とレンダラーのタイプが異なる環境 (プロジェクト/課題タイプ) へ課題を一括し、いずれかのフィールドにフィールドと関連付られた空白でない値があった場合、移動操作を行うと警告が表示され、変更を認識できます。警告は移動操作には影響しませんが、移動された課題の影響を受けたフィールドの外観が、新しいプロジェクト/課題タイプで異なる可能性があります。
一括編集
When performing a bulk edit operation the only renderable fields you may be able to bulk edit are instances of the Text Field, and Free Text Field (unlimited text) custom fields. The bulk edit operation does not allow you to bulk edit the description, environment, or comment fields.
編集対象として選択したすべての課題が同じレンダラータイプを使用している場合にのみ、レンダリング可能なフィールドの一括編集を実行できます。選択した課題のいずれかでレンダリングタイプが異なる場合、エラーメッセージが表示されます。
This is best illustrated with an example. Let's say you have two global custom fields, 'Custom text area' and 'Custom text field', whose types are as their names imply. Let's say you have project 'A' which is configured to use the Wiki Style Renderer for both of the fields. Let's say you also have a project 'B' which is configured to use the Default Text Renderer for the 'Custom text area' field and the Wiki Style Renderer for the 'Custom text field'. Let's also say that you have one issue in each project. If you were to perform a bulk edit operation on the two issues in these projects you will be presented with the screenshot below:
メール通知
JIRA allows for extensive configuration in relation to email notifications. JIRA can send out two types of emails, HTML and text (see Email Formatting).
HTML Emails
When using the Atlassian Wiki Renderer, the rendered content (i.e. exactly what you see on the 'View Issue' page) will be sent out in the emails. This will create emails which are as rich as the content makes it. If using the Wiki Style Renderer, this is the preferred type of email since it is a real representation of the wiki markup.
Text Emails
When using the Atlassian Wiki Renderer, the actual wiki markup (unrendered) will be displayed in text emails for fields that use the Wiki Style Renderer. This is obviously less readable than the rendered version of the markup, but because the markup's syntax is quite simple the text does remain easy to read.
Excel View
JIRA allows the Issue Navigator view to be exported to an Excel spreadsheet. If any of the fields being exported to Excel are using the Wiki Style Renderer, the value exported to the cell in Excel will be the original wiki markup. Attempting to display complex HTML within a cell in Excel adds rows and columns that make using the data for formulas very difficult.
The unrendered wiki markup will be shown in Excel cells for fields that use the Wiki Style Renderer.
RSS/XML View
JIRA allows the Issue Navigator view to be exported to RSS/XML. If a field is using the Default Text Renderer its values will be exported in a CDATA section within the generated XML. If a field is using the Wiki Style Renderer, its rendered value will be XML escaped and included in the generated XML. If the XML view is being used as an RSS feed, most RSS readers will render the generated HTML so you will see the rich content within your RSS reader.
このビューで生の値 (レンダリングされていない) のフィードを使用したい場合、追加のパラメーター 'rssMode=raw' を送信できます。元のリンクが次のようになった場合:
http://localhost:8080/browse/AAA-1?decorator=none&view=rss次に、CDATA 内に配置された生データを持たせる URL は次のようになります。
http://localhost:8080/browse/AAA-1?decorator=none&view=rss&rssMode=rawEditing a Renderable Custom Field's Default Value
When editing a renderable custom field's default value, even if it is only ever configured to use the Wiki Style Renderer you will not be presented with the Edit and Preview options. Unfortunately, in this context it is not possible to tell which renderer should be used for editing. However, if you enter a default value using wiki markup, then this will render correctly in environments (project/issue type) where the field has been configured to use the Wiki Style Renderer.
Configuring Renderers
Applying a Renderer to a Field
To enable a renderer for a particular field, edit the Field Configuration and choose the appropriate renderer for the field. For details, see Specifying Field Behavior.
Enabling a Renderer Plugin
Renderers within JIRA are implemented as JIRA plugins. The macros that the Wiki Style Renderer uses are also implemented as JIRA plugins. For general information on plugins please see the JIRA Plugin Guide.
Note that plugins are configured at a site-wide level — it is not possible to configure plugins at a project/issue type level.
Configuring a Renderer Plugin
Renderers and their dependant components, except for the Default Text Renderer, can be enabled/disabled as follows.
- Choose
> Add-ons. The 'Find add-ons' screen shows add-ons available via the Atlassian Marketplace. Choose Manage Add-ons to view the plugins currently installed on your JIRA site. - Select Manage Add-ons and then search for 'renderer', filtering for System Add-ons, as shown here:
この画面には、JIRA 内で設定されているすべてのレンダラーが表示されます。
- 「無効化」ボタンをクリックし、JIRA のインスタンス全体のレンダラーを無効化します。
無効化されたレンダラーを使用するよう設定されているフィールドがあれば、既定のテキストレンダラーに戻されます。フィールドを編集し用とすると、利用できないレンダラーを使用するよう設定していることを示す警告メッセージが表示されます。
レンダラーが無効化されている場合、フィールドのレンダラーを変更する際には選択できません。レンダラーを有効化するには、「有効化」ボタンをクリックします。レンダラーを有効化/無効化してもフィールド設定のレンダラー設定には影響しません。そのため、データに影響を与えずに、レンダラーを無効化してから再度有効化することができます。
Configuring Macro Plugins for the Wiki Style Renderer
The macros used by the Wiki Style Renderer can be enabled/disabled as follows.
- Choose > Add-ons. The 'Find add-ons' screen shows add-ons available via the Atlassian Marketplace. Choose Manage Add-ons to view the plugins currently installed on your JIRA site.
- Select Manage Add-ons and then search for 'renderer', filtering for System Add-ons.
- Expand the Wiki Renderer Macros Plugin to display the following screen.
From this screen you will see all the configured macros within JIRA. If a macro is disabled then it will not be available to the wiki renderer. If you deploy any additional macros that you wish to use, they must be enabled here to be available to the wiki renderer. For more information on writing plugins please see the documentation on Writing Macros.