confluence 插件开发(二)：创建一个"Hello World"宏

该教程环境参数如下：

OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
Java version: 1.8.0_201, vendor: Oracle Corporation
Apache Maven 3.5.4 (1edded0938998edf8bf061f1ceb3cfdeccf443fe; 2018-06-18T02:33:14+08:00)
ATLAS Version:    8.0.16
AMPS Version:     8.0.2

在confluence里创建一个宏元素

示例1：创建宏元素

1. 添加配置
打开 atlassian-plugin.xml文件，在 atlassian-plugin 标签下加入以下内容（宏名称和宏键都应为小写）

<xhtml-macro name="helloworld" class="com.atlassian.tutorial.macro.helloworld" key='helloworld-macro'> 
    <description key="helloworld.macro.desc"/> 
    <category name="formatting"/> 
    <parameters/> 
</xhtml-macro>

其中class类填写自己项目中类的地址，在本教程中是com.atlassian.tutorial.macro.helloworld；
description中填写的key值需要与properties文件中对应

2. 加入宏描述
打开 /src/main/resources/下的.properties文件，底部加入以下内容：

helloworld.macro.desc="Hello World"

3. 创建在步骤二中引用到的java类
在本教程中我们需要创建一个宏文件夹，来保持文件的整洁：
然后在macro文件夹下创建一个 helloworld.java文件，输入以下代码：

package com.atlassian.tutorial.macro;

import com.atlassian.confluence.content.render.xhtml.ConversionContext;
import com.atlassian.confluence.macro.Macro;
import com.atlassian.confluence.macro.MacroExecutionException;

import java.util.Map;

public class helloworld implements Macro {
    public String execute(Map map, String s, ConversionContext conversionContext) throws MacroExecutionException {
        return "Hello World";
    }

    public BodyType getBodyType() { return BodyType.NONE; }

    public OutputType getOutputType() { return OutputType.BLOCK; }
}

这是Macro实现 Confluence Macro类并在Confluence中显示Macro对象所需的最小骨架。

4. 打包
重新打包并等待quickload加载完成（参考插件开发一中的操作）。

5. 查看结果
创建一个测试空间和测试页面。在页面中添加HelloWorld宏。

将宏添加到页面：

保存并查看结果：

自定义"Hello World"宏

示例2：设置和使用参数

1. 修改插件配置文件
打开 atlassian-plugin.xml文件，将示例:1中的<parameters/> 标签用下列内容替换

<parameters>
  <!-- 指定参数名称为Name并且类型为字符串 -->
  <parameter name="Name" type="string" />
</parameters>

2.修改java类文件的excute方法

public String execute(Map<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
	if (map.get("Name") != null) {
		return ("<h1>Hello " + map.get("Name") + "!</h1>");
	} else {
		return "<h1>Hello World!<h1>";
	}
}

3. 查看结果

示例3：使用css格式化宏外观

1. 确认<web-resource>标签已存在

<web-resource key="myConfluenceMacro-resources" name="myConfluenceMacro Web Resources">
    <dependency>com.atlassian.auiplugin:ajs</dependency>

    <resource type="download" name="myConfluenceMacro.css" location="/css/myConfluenceMacro.css"/>
    <resource type="download" name="myConfluenceMacro.js" location="/js/myConfluenceMacro.js"/>
    <resource type="download" name="images/" location="/images"/>

    <context>myConfluenceMacro</context>
</web-resource>

一般情况下，创建项目时改标签就已经有内容，在这个示例中不需要特意修改。

2. 修改插件配置文件
打开 atlassian-plugin.xml文件，将示例:2中的<parameter/> 标签用以下内容替换：

<parameters>
  <!-- 指定参数名称为Name并且类型为字符串 -->
  <parameter name="Name" type="string" />
  <!-- 指定参数名称为Color并且类型为枚举，这将创建下拉菜单 -->
      <parameter name="Color" type="enum">
        <value name="red"/>
        <value name="green"/>
        <value name="blue"/>
</parameters>

3.修改css文件
打开src/main/resources/css/myConfluenceMacro.css文件，加入以下内容：

.blue h1 {
    color: blue;
}

.red h1 {
    color: red;
}

.green h1 {
    color: green;
}

4.修改java类文件
a. 引入依赖：
这里用到了spring的scanner，并且使用PageBuilderService来保证css文件被confluence用到

import com.atlassian.plugin.spring.scanner.annotation.component.Scanned;
import com.atlassian.plugin.spring.scanner.annotation.imports.ComponentImport;
import com.atlassian.webresource.api.assembler.PageBuilderService;
import org.springframework.beans.factory.annotation.Autowired;

b. 加入scanned注解
在类public class helloworld implements Macro上加上注解，这样类才会被spring扫描到

@Scanned

c. 在类中加入成员变量：PageBuilderService

public class helloworld implements Macro {

    private PageBuilderService pageBuilderService;

    @Autowired
    public helloworld(@ComponentImport PageBuilderService pageBuilderService) {
        this.pageBuilderService = pageBuilderService;
    }

d. 修改excute方法
使用pageBuilderService
组装返回值：获取颜色，设置外观，然后获取名称，进行拼接，这里用到了div块：

public String execute(Map<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
        pageBuilderService.assembler().resources().requireWebResource("com.atlassian.tutorial.myConfluenceMacro:myConfluenceMacro-resources");

        String output = "<div class =\"helloworld\">";
        output = output + "<div class = \"" + map.get("Color") + "\">";

        if (map.get("Name") != null) {
            output = output + ("<h1>Hello " + map.get("Name") + "!</h1>");
        } else {
            output = output + "<h1>Hello World!<h1>";
        }
        output = output + "</div>" + "</div>";
        return output;
    }

5. 查看结果

源码

该项目的源码已更新在github上：confluence-user-plugin
可以通过代码提交记录来查看每个示例修改的内容

参考文档

Create a Confluence ‘Hello World’ macro