创建一个Hello World的Confluence宏

本教程在Set Up the Atlassian SDK and Build a Project 引入的概念基础上进行构建。为了能成功完成本教程，你要对SDK环境的研究深入一点。你应该已经完成了SDK的安装，并创建过一个插件工程。

关于本教程

提前准备：

Atlassian Plugin SDK 6.2.x
Oracle Java JDK 8
最好已经完成Set Up the Atlassian SDK and Build a Project
对Java, javascripts和css的基础有所了解

经验水平：初级

建议环境：

Atlassian Plugin SDK 6.2.9
AMPS Version 6.2.6
Confluence Version

源码：https://bitbucket.org/serverecosystem/myconfluencemacro/src

创建插件框架

类似于上一个教程，你要使用Atlassian SDK为插件创建一个框架。这次，你将会使用atlas-create-confluence-plugin命令，因为你要创建的插件是运行在Confluence上的。

你可以在Command reference上找到所有atlas-命令的一个列表

打开一个命令行窗口，进入你想要创建插件的目录中。

运行命令 atlas-create-confluence-plugin，并像下边这样填写插件信息：

 
     Define value for groupId: : com.atlassian.tutorial
Define value for artifactId: : myConfluenceMacro
Define value for version:  1.0.0-SNAPSHOT: : 
Define value for package:  com.atlassian.tutorial: : 
Confirm properties configuration:
groupId: com.atlassian.tutorial
artifactId: myConfluenceMacro
version: 1.0.0-SNAPSHOT
package: com.atlassian.tutorial
 Y: : Y 
    

插件框架将会被自动创建，你会收到如下的确认信息：

 
     [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 02:53 min
[INFO] Finished at: 2016-10-10T15:39:56+10:00
[INFO] Final Memory: 16M/309M
[INFO] ------------------------------------------------------------------------ 
    

现在，进入上一步由Atlassian SDK创建出来的myConflunceMacro目录中。
在pom.xml文件中为你的插件更新组织信息 (如果你卡住了，参考“修改插件”的第一步).

扫描二维码关注公众号，回复： 110857 查看本文章
通过执行atlas-run命令启动安装了你的插件的Confluence（会下载所有所需文件）。
访问 localhost:1990/confluence/plugins/servlet/upm/manage/all 来查看安装了你的插件的Confluence（你可以使用用户名：admin,密码：admin来登录，这跟你在上一个教程中做的一样）
现在离开Confluence。

在Confluence中创建一个宏元素

在前面的教程中，我们使用atlas-create-jira-plugin-module命令创建了一个JIRA菜单模块，并对其做了定制。这个命令其实是通过修改插件目录下的/src/main/resources/atlassian-plugin.xml文件来在JIRA中新建一些额外的元素。

在本教程中，你将会手动创建一个插件元素而不在使用SDK命令。这是因为atlas-create-confluence-plugin-module命令没有包含你需要用到的模块选项。

使用你喜欢的编辑器打开atlassian-plugin.xml 文件。

定位到该文件中<web-resource>…</web-resource> 的末尾，输入如下信息：

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

保存修改。注意：宏的name和key都应该小写。

打开/src/main/resources/myConfluenceMacro.properties，在文件末尾追加如下信息：
```
helloworld.macro.desc="Hello World"
```
保存修改。
下一步，你需要创建一个java类，这个类你在第二步中做了引用。因为你将会在本教程中创建很多的宏，所以你可以创建一个宏目录来保持整洁。
打开一个新的命令行窗口，在 /src/main/java/com/atlassian/tutorial目录下创建一个名为macro的文件夹：
```
cd /src/main/java/com/atlassian/tutorial
mkdir macro
cd macro
```
在该文件夹中，新建一个名为helloworld.java的文件并在编辑器中打开它。

在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<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
        return "<h1>Hello World</h1>";
    }

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

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

这是个最小框架，你的宏需要实现 confluence Macro class ，然后会在Confluence上显示一个宏对象。

在命令行窗口中，将目录切换到你插件的顶层目录中 (如 cd <home>/AtlassianTutorial/myConfluenceMacro)

执行命令 atlas-mvn package来re-package你的插件，并通过QuickReloaded重新安装它。你应该能看到一个确认信息：

 
     [INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.656 s
[INFO] Finished at: 2016-10-10T18:33:09+10:00
[INFO] Final Memory: 37M/433M
[INFO] ------------------------------------------------------------------------ 
    

查看最新运行Confluence的窗口，确认QuickReload完成了加载。你应该能看到一个确认信息：

 
     [INFO] [talledLocalContainer] 2016-10-10 18:33:16,082 INFO [QuickReload - Plugin Installer] [atlassian.plugin.manager.DefaultPluginManager] updatePlugin Updating plugin 'com.atlassian.tutorial.myConfluenceMacro-tests' from version '1.0.0-SNAPSHOT' to version '1.0.0-SNAPSHOT'
[INFO] [talledLocalContainer] 2016-10-10 18:33:16,083 INFO [QuickReload - Plugin Installer] [atlassian.plugin.manager.DefaultPluginManager] broadcastPluginDisabling Disabling com.atlassian.tutorial.myConfluenceMacro-tests
[INFO] [talledLocalContainer] 2016-10-10 18:33:17,512 INFO [QuickReload - Plugin Installer] [plugins.quickreload.install.PluginInstallerMechanic] installPluginImmediately 
[INFO] [talledLocalContainer]                       ^
[INFO] [talledLocalContainer]                       |
[INFO] [talledLocalContainer]                       |
[INFO] [talledLocalContainer]                       |
[INFO] [talledLocalContainer]                       |
[INFO] [talledLocalContainer]                       |
[INFO] [talledLocalContainer] 
[INFO] [talledLocalContainer]       A watched plugin never boils!
[INFO] [talledLocalContainer] 
[INFO] [talledLocalContainer] Quick Reload Finished (5954 ms) - 'myConfluenceMacro-1.0.0-SNAPSHOT-tests.jar' 
    

现在你可以尝试一个宏到Confluence的测试页面了（在你测试之前，你需要创建一个新的Confluence空间和页面）

注意：Confluence宏浏览器可能需要一点时间才能识别到有一个新的可见宏，所以如果它没有正常显示出来，给它一点时间然后重试。

 
  <img src="/server/framework/atlassian-sdk/images/confluence-macro-browser-showing-helloworld-macro.png" title="Macro Browser" alt="Confluence macro browser showing helloworld macro" width="500" height="305" />  
<img src="/server/framework/atlassian-sdk/images/helloworld-macro-on-page-in-edit-view.png" title="Helloworld Macro - Edit Mode" alt="Helloworld macro showing on confluence page in edit mode" width="500" height="268" />

<img src="/server/framework/atlassian-sdk/images/helloworld-macro-showing-message-after-saving-page.png" title="Helloworld Macro - Confluence Page" alt="Helloworld Macro shown on Confluence page that has been saved" width="880" height="250" />

定制Hello World宏

现在，通过允许用户使用参数来指定他们自己的名字来学习如何设置和使用参数。

在编辑器中打开atlassian-plugin.xml文件。
定位到你在本教程第一部分中创建的<xhtml-macro>中的<parameters/> 元素。
使用如下替换 <parameters/> 元素：
```
<parameters>
    <parameter name="Name" type="string" />
</parameters>
```
它指定了参数名字叫Name，类型是string。你可以在macro module documentation中看到所有参数类型的列表。
保存并关闭atlassian-plugin.xml文件。
打开helloworld.java ( 它在 /src/main/java/com/atlassian/tutorial/macro目录)

按如下修改execute方法：

 
     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>";
    }
} 
    

保存你的修改。
在命令行窗口，确认你处于插件的顶层目录(如 <home>/AtlassianTutorial/myConfluenceMacro)，然后执行如下命令：
```
atlas-mvn package
```
查看正在运行Confluence的命令行窗口，确认插件已经被QuickReload加载完成。
登录并检查你的修改是否已经生效：

使用CSS美化宏的外观

此刻，所有的格式话动作都会在execute方法中完成。在本节中，你会初始化一个Web Resource Plugin Module 模块，来允许css控制你宏的外观。

打开atlassian-plugin.xml 文件

会发现<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> 
    

在本教程中，你不需要对web-resource模块做任何修改。

在你的 <parameter name="Name" type="string" /> 下面添加一个新的 <parameter name="Color" type="enum"> ，如下：
```
<parameter name="Color" type="enum">
    <value name="red"/>
    <value name="green"/>
    <value name="blue"/>
</parameter>
```
这会在你的宏编辑器里为用户添加一个下拉菜单，用户可以选择他自己的颜色，红，绿或蓝。
保存并关闭文件。
下一步，打开 src/main/resources/css/myConfluenceMacro.css 文件。
在css文件中添加如下：
```
.blue h1 {
    color: blue;
}

.red h1 {
    color: red;
}

.green h1 {
    color: green;
}
```
这个css将会根据.bule, .breen和.red h1元素修改文本的颜色（当然是在你更新了你的helloword.java之后）
保存并关闭myConfluenceMacro.css
现在，打开src/main/java/com/atlassian/tutorial/macro/helloworld.java文件

按照下面修改execute方法创建一个<div>元素：

 
     public String execute(Map<String, String> map, String s, ConversionContext conversionContext) throws MacroExecutionException {
    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;
} 
    

注意，你现在新建了一个<div/>元素，它有一个可以匹配用户指定颜色的class。

下一步，在java文件中已经存在的imports语句下添加如下：

 
     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; 
    

这些所需让你可以使用 spring scanner。与PageBuilderService一起，确认你创建的css会被包含到Confluence中。

在 public class helloworld implements Macro 定义上面，加上如下Spring注解：
```
@Scanned
```
这个 @scanned 注解是spring scanner的一个指令。在本教程中，我们使用了spring scanner 1.2.13 - 所以我们需要告诉spring scanner 来扫描这个类。

现在，在helloworld类定义内部，添加一个 PageBuilderService 变量，下面是helloworld类的构造方法：

 
     public class helloworld implements Macro {

    private PageBuilderService pageBuilderService;

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

Web Resource Plugin Module 会用到pageBuilderService。

最后，在你的execute方法中，添加如下一行：
```
pageBuilderService.assembler().resources().requireWebResource("com.atlassian.tutorial.myConfluenceMacro:myConfluenceMacro-resources");
```
注意，你在使用pageBuilderService 来获取web-resource key，候着是被自动生成的(看第二步)。
保存修改，执行atlas-mvn package来更新插件。
确保你的插件已经带有新修改运行：

注意：在加载页面时，你可能需要按下shift键才能看到对这个页面的修改。

 
  <img src="/server/framework/atlassian-sdk/images/final-changes-with-css.png" width="502" height="250" /> 
 

需要帮助？

教程的源码在 on Bitbucket

或者，在 Atlassian Answers 查找问题，或者在我们的 Developer Technical Support Portal提问题。

资源

本教程源码在 on Bitbucket 可以看到
你可以在 bitbucket.org/atlassian/atlassian-spring-scanner找到关于Spring Scanner的相关文档
了解更多关于 Web Resource Plugin Module的信息
了解更多Macro Module的信息