Расширение справочных ссылок JIRA

Доступность: JIRA 6.2.5 и более поздние.

На этой странице описывается, как JIRA связывается с внешними справочными ресурсами. Эти методы позволяют JIRA использовать локаль пользователя и версию JIRA, чтобы решить, к какой документации обращаться, без необходимости жесткого кода URL. Они также позволяют разработчикам плагинов настраивать URL-адреса справки JIRA и создавать собственные URL-адреса справки.

HelpUrls и HelpUrlsParser

В Java-коде вы можете сделать что-то вроде этого.


this.helpUrls.getHelpUrl("jira101").getUrl();

На странице JavaServer (JSP) вы можете просто использовать теги Webwork, чтобы избежать необходимости добавлять геттеры к вашему действию.


<a href="<ww:help-url key='jira101'/>" title="<ww:help-title key='jira101'/>">JIRA 101</a>

Основные справочные ссылки JIRA

Этот раздел предназначен для сценаристов, использующих или изменяющих ядро URL-адресов JIRA (которые укажут на основную справочную документацию JIRA). Разработчики плагинов, желающие иметь свои собственные независимые URL-адреса, должны смотреть на использование внутри плагинов.

Чтобы использовать основные справочные ресурсы JIRA по URL-адресам , вам просто нужно ввести следующий код в свой компонент, и вы можете начать его использовать.


@Inject
HelpUrls urls;
...
return urls.getUrl("jira101").getTitle();

Названия ссылок, заголовки и URL-адреса вытягиваются из ресурсов, предоставляемых плагинами. Например, system-helppaths-plugin.xml определяет справочный ресурс help-paths.properties:

help-paths.properties


# Prefixes
url-prefix=https://docs.atlassian.com/jira/docs-${docs.version}/
url-prefix.ondemand=https://confluence.atlassian.com/display/Cloud/

# Section: JIRA 101
jira101.url=JIRA 101
jira101.url.ondemand=Get+a+feel+for+JIRA
jira101.title=JIRA 101
jira101.title.ondemand=JIRA+Cloud

Свойства, заканчивающиеся на .ondemand, используются для переопределения значений, которые используются в автономных установках (размещенных на вашем собственном сервере, а переменная docs.version соответствует версии JIRA, которая запущена. Поэтому, когда вы запрашиваете HelpUrls для jira101 вы получите одно из следующего.

Где	URL	Заголовок	Версия JIRA
Сервер	Почувствуйте JIRA	jira101	6.2.x
Облако	Облако JIRA	jira101	Не применимо

Плагины позволяют расширять и адаптировать URL-адреса справки, используемые в ядре JIRA. Например:

atlassian-plugin.xml


<atlassian-plugin key="example" name="Brenden's Example" plugins-version="2">
    <resource type="helpPaths" location="HelpPaths" name="help"/>
</atlassian-plugin>

help-paths_ja_JP.properties


# Prefixes
url-prefix=https://docs.atlassian.jp/jira/docs-${docs.version}/

# Section: JIRA 101
jira101.title=JIRAをはじめ
jira101.title.ondemand=JIRAのメーカーの紹介

Когда этот плагин установлен, JIRA создаст следующие URL-адреса справки:

Местонахождение пользователя- Locale.ROOT

URL BTF - рttps://docs.atlassian.com/jira/docs-062/JIRA+101

Заголовок BTF - Получите интерактивную справку о JIRA 101

URL OD - https://confluence.atlassian.com/display/AOD/JIRA+Studio+101

Заголовок OD - Получите интерактивную справку о JIRA Studio 101

Заметки

Свойство url-prefix изменит URL-адрес каждого пути справки в JIRA. Это полезно для переноса документации на разные домены или на внутренний JIRA-сервер.
Файлы HelpPaths.properties должны быть закодированы в ISO-8859-1 с нелатинскими символами, закодированными с использованием native2ascii или какого-либо подобного инструмента. Это требование языковых пакетов JIRA.
У url-prefix будет $ {docs.version} или $ {doc.version} заменена текущей версией документации JIRA. Это версия, которую JIRA использует для ссылки на свою документацию (например, 6.2.1, 6.2.2, 6.2.x == 062; 6.3.1, 6.3.2, 6.3.x == 063).
Свойства, которые заканчиваются на .ondemand, будут видны только при запуске в экземпляре облака JIRA.
Заголовок URL-адреса не отображается напрямую. Он передается через перевод online.help.for.topic.

Использование в плагинах

В этом разделе рассказывается о плагинах, предоставляющих собственные URL-адреса справки независимо от основных URL-адресов поддержки JIRA. См. Основные справочные ссылки JIRA, если вы хотите использовать или настроить основные URL-адреса JIRA.

Плагин, возможно, пожелает предоставить свои собственные HelpUrls в свою собственную документацию. HelpUrlsParser принимает экземпляр Properties и возвращает HelpUrls. Например:


@Inject
HelpUrlsParser parser;
...
HelpUrls urls = parser.load(loadHelpProperties());
...
return urls.getUrl("servicedesk.intro").getTitle();

Для плагинов, которые версируются независимо от JIRA (JIRA Agile, ServiceDesk и т. д.), имеет смысл использовать ваш собственный экземпляр HelpUrls, чтобы ваши ссылки справки указывали на документацию для конкретной версии вашего плагина. Вот пример файла свойств в таком плагине.

sd-help-links.properties


# Prefixes
url-prefix=https://docs.atlassian.com/servicedesk/docs-${servicedesk.docs.version}/
url-prefix.ondemand=https://confluence.atlassian.com/display/Cloud-SD/

# Section: Intro pages
servicedesk.intro.url=ServiceDesk+Intro
servicedesk.intro.title=Introduction to ServiceDesk

Обратите внимание на использование свойства $ {serviceDesk.docs.version}, используемого для ссылки на версию плагина, которая в настоящее время запущена. Чтобы убедиться, что свойство будет заменено правильной версией плагина во время сборки, потребуется немного гимнастики Maven:

Настройте docsversion-maven-plugin в вашем pom.xml, чтобы значение свойства было правильно установлено.

pom.xml


<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>docsversion-maven-plugin</artifactId>
    <version>1.0</version>
    <executions>
        <execution>
            <id>set-docs-version-property</id>
            <phase>initialize</phase>
            <goals>
                <goal>set-property</goal>
            </goals>
            <configuration>
                <!-- name of property used in sd-help-links.properties -->
                <property>servicedesk.docs.version</property>
            </configuration>
        </execution>
    </executions>
</plugin>

Включите фильтрацию ресурсов, чтобы заставить Maven интерполировать файлы ресурсов, добавив это в свой pom.xml (вы можете включить / исключить определенные файлы. См. документацию Maven по фильтрации).


<resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
</resource>

После создания этой инфраструктуры вы можете использовать свои HelpUrls для создания ссылок, которые версируются для вашего плагина. Используя приведенный выше пример, вы получите следующие справочные ссылки.

Где	URL	Заголовок	Версия JIRA
Сервер	ServiceDesk Intro	ServiceDesk Intro	1.x
Облако	ServiceDesk Intro	ServiceDesk Intro	Не применимо

HelpUtil

HelpUrls и HelpUrlsParser были представлены в JIRA 6.2.4. До этого класс HelpUtil предоставлял аналогичную функциональность. Например:

getInstance () или новый HelpUtil (): возвращает основные URL-адреса справки JIRA.
new HelpUtil (Свойства): возвращает URL-адреса справки в переданных свойствах.

HelpUtil теперь делегирует всю функциональность в HelpUrls и HelpUrlsParser, если это необходимо.

По материалам Atlassian JIRA Server Developer Extending JIRA help links