Введение в плагины Atlassian Confluence
Если вы знакомы с набором продуктов Atlassian, то знаете, насколько мощным инструментом может быть Confluence для командного взаимодействия и управления знаниями. Однако иногда стандартных функций недостаточно. Здесь на помощь приходят плагины, позволяющие настроить и расширить Confluence в соответствии с вашими потребностями. В этой статье мы погрузимся в мир разработки плагинов для Atlassian Confluence с использованием Java.
Настройка среды разработки
Прежде чем приступить к написанию кода, необходимо настроить среду разработки. Вот несколько шагов, которые помогут вам начать:
Установка SDK плагина Atlassian
SDK плагина Atlassian — ваш лучший друг, когда дело доходит до разработки плагинов. Вот как его можно установить:
# Скачать и установить SDK
wget https://www.atlassian.com/software/sdk/downloads/binary/atlassian-plugin-sdk-8.0.2.tar.gz
tar -xzf atlassian-plugin-sdk-8.0.2.tar.gz
cd atlassian-plugin-sdk-8.0.2
# Настроить SDK
./bin/atlas-setup
# Проверить настройку
./bin/atlas-version
Использование Maven для разработки плагинов
Maven — это важный инструмент для управления зависимостями и сборки вашего плагина. Вот пример того, как настроить файл pom.xml
для плагина Confluence:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example.plugins</groupId>
<artifactId>my-confluence-plugin</artifactId>
<version>1.0</version>
<packaging>atlassian-plugin</packaging>
<dependencies>
<dependency>
<groupId>com.atlassian.confluence</groupId>
<artifactId>confluence</artifactId>
<version>8.0.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>com.atlassian.maven.plugins</groupId>
<artifactId>confluence-maven-plugin</artifactId>
<version>8.0.2</version>
<extensions>true</extensions>
<configuration>
<productVersion>8.0.0</productVersion>
<productDataVersion>8.0.0</productDataVersion>
</configuration>
</plugin>
</plugins>
</build>
<properties>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
</project>
Обновление до Java 11
Если вы переходите со старой версии Confluence на Confluence 8 или более позднюю версию, вам потребуется обновить Java до версии 11. Вот совет от сообщества:
# Использовать последнюю версию Maven
mvn --version
# Убедитесь, что ваш pom.xml настроен для Java 11
<properties>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
Создание вашего первого плагина
Описание плагина
Основой любого плагина Confluence является файл atlassian-plugin.xml
, который служит описанием плагина. Вот пример того, как это может выглядеть:
<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
<plugin-info>
<description>Это мой первый плагин Confluence.</description>
<vendor-name>Максим Жирнов</vendor-name>
<vendor-url>https://example.com</vendor-url>
</plugin-info>
<!-- Определите свои модули плагина здесь -->
<module type="macro" key="my-macro">
<name>Мой макрос</name>
<class>com.example.plugins.MyMacro</class>
</module>
</atlassian-plugin>
Написание простого плагина макроса
Макросы — отличное место для начала, поскольку они обеспечивают немедленную визуальную обратную связь. Вот пример простого макроса:
import com.atlassian.confluence.content.render.xhtml.ConversionContext;
import com.atlassian.confluence.macro.Macro;
import com.atlassian.confluence.macro.MacroExecutionException;
import com.atlassian.confluence.renderer.radeox.macros.MacroUtils;
import com.atlassian.confluence.util.velocity.VelocityUtils;
public class MyMacro implements Macro {
@Override
public String execute(Map<String, String> parameters, String body, ConversionContext context) throws MacroExecutionException {
// Простой макрос, который возвращает приветствие
return "Привет, мир!";
}
@Override
public BodyType getBodyType() {
return BodyType.NONE;
}
@Override
public OutputType getOutputType() {
return OutputType.INLINE;
}
}
Добавление ресурсов и конфигурации
Добавление ресурсов плагина
Ресурсы — это не-Java файлы, которые могут понадобиться вашему плагину. Вот как вы можете добавить ресурс:
<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
<!-- ... -->
<resource type="download" name="my-resource" location="/path/to/my/resource.txt"/>
</atlassian-plugin>
Добавление пользовательского интерфейса конфигурации
Если вашему плагину требуется настройка, вы можете добавить пользовательский интерфейс конфигурации:
<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
<!-- ... -->
<module type="web" key="my-config-ui">
<name>Мой пользовательский интерфейс настройки</name>
<url>/plugins/servlet/my-config-ui</url>
<class>com.example.plugins.MyConfigUI</class>
</module>
</atlassian-plugin>
Расширенная разработка плагинов
Использование стандартных декораторов страниц
Если вы разрабатываете плагин, который должен работать в нескольких продуктах Atlassian, вы можете использовать стандартные декораторы страниц:
<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
<!-- ... -->
<module type="web-panel" key="my-web-panel">
<name>Моя веб-панель</name>
<url>/plugins/servlet/my-web-panel</url>
<class>com.example.plugins.MyWebPanel</class>
<location>system.header</location>
</module>
</atlassian-plugin>
Доступ к компонентам Confluence
Чтобы взаимодействовать с компонентами Confluence, вам необходимо следовать соглашениям об именах пакетов Java, чтобы избежать конфликтов:
import com.atlassian.confluence.core.ContentEntityObject;
import com.atlassian.confluence.core.ContentEntityManager;
import com.atlassian.confluence.user.ConfluenceUser;
import com.atlassian.confluence.user.UserAccessor;
public class MyPlugin {
public void doSomething(ContentEntityManager contentEntityManager, UserAccessor userAccessor) {
// Доступ к компонентам Confluence здесь
ConfluenceUser user = userAccessor.getCurrentUser();
// ...
}
}
Пример рабочего процесса: создание задачи Jira из Confluence
Вот пример того, как вы можете создать плагин для генерации задач Jira из Confluence, распространённый вариант использования:
Пошаговый процесс
Настройте каркас плагина: Используйте шаблон Maven для создания базового каркаса плагина.
Определите описание плагина: Добавьте необходимые модули в свой
atlassian-plugin.xml
.Создайте макрос или веб-элемент: Напишите код Java для вашего макроса или веб-элемента, который будет инициировать создание задачи Jira.
Используйте REST API или веб-хуки: Используйте Jira REST API или веб-хуки для создания задачи.
Пример кода
Вот упрощённый пример использования Jira REST API:
import com