建立一个Hello World的Confluence宏

时间  2019-11-08
标签 建立 一个 hello world confluence 繁體版
原文   原文链接

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

关于本教程

提早准备：css

经验水平：初级html

建议环境：java

  • Atlassian Plugin SDK 6.2.9
  • AMPS Version 6.2.6
  • Confluence Version

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

建立插件框架

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

你能够在Command reference上找到全部atlas-命令的一个列表 api

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

  2. 运行命令 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

  3. 插件框架将会被自动建立，你会收到以下的确认信息：app

    [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] ------------------------------------------------------------------------

  4. 如今，进入上一步由Atlassian SDK建立出来的myConflunceMacro目录中。框架

  5. 在pom.xml文件中为你的插件更新组织信息 (若是你卡住了，参考“修改插件”的第一步).

  6. 经过执行atlas-run命令启动安装了你的插件的Confluence（会下载全部所需文件）。

  7. 访问 localhost:1990/confluence/plugins/servlet/upm/manage/all 来查看安装了你的插件的Confluence（你可使用用户名：admin,密码：admin来登陆，这跟你在上一个教程中作的同样）

  8. 如今离开Confluence。

在Confluence中建立一个宏元素

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

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

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

  2. 定位到该文件中<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都应该小写。

  3. 打开/src/main/resources/myConfluenceMacro.properties，在文件末尾追加以下信息：

    helloworld.macro.desc="Hello World"

    保存修改。

  4. 下一步，你须要建立一个java类，这个类你在第二步中作了引用。由于你将会在本教程中建立不少的宏，因此你能够建立一个宏目录来保持整洁。

  5. 打开一个新的命令行窗口，在 /src/main/java/com/atlassian/tutorial目录下建立一个名为macro的文件夹：

    cd /src/main/java/com/atlassian/tutorial
mkdir macro
cd macro

  6. 在该文件夹中，新建一个名为helloworld.java的文件并在编辑器中打开它。

  7. 在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上显示一个宏对象。

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

  9. 执行命令 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] ------------------------------------------------------------------------

  10. 查看最新运行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'

  11. 如今你能够尝试一个宏到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宏

如今，经过容许用户使用参数来指定他们本身的名字来学习如何设置和使用参数。

  1. 在编辑器中打开atlassian-plugin.xml文件。
  2. 定位到你在本教程第一部分中建立的<xhtml-macro>中的<parameters/> 元素。

  3. 使用以下替换 <parameters/> 元素：

    <parameters>
    <parameter name="Name" type="string" />
</parameters>

    它指定了参数名字叫Name，类型是string。你能够在macro module documentation中看到全部参数类型的列表。

  4. 保存并关闭atlassian-plugin.xml文件。

  5. 打开helloworld.java ( 它在 /src/main/java/com/atlassian/tutorial/macro目录)

  6. 按以下修改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>";
    }
}

  7. 保存你的修改。

  8. 在命令行窗口，确认你处于插件的顶层目录(如 <home>/AtlassianTutorial/myConfluenceMacro)，而后执行以下命令：

    atlas-mvn package

  9. 查看正在运行Confluence的命令行窗口，确认插件已经被QuickReload加载完成。

  10. 登陆并检查你的修改是否已经生效：


使用CSS美化宏的外观

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

  1. 打开atlassian-plugin.xml 文件

  2. 会发现<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模块作任何修改。

  3. 在你的 <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>

    这会在你的宏编辑器里为用户添加一个下拉菜单，用户能够选择他本身的颜色，红，绿或蓝。

  4. 保存并关闭文件。

  5. 下一步，打开 src/main/resources/css/myConfluenceMacro.css 文件。

  6. 在css文件中添加以下：

    .blue h1 {
    color: blue;
}

.red h1 {
    color: red;
}

.green h1 {
    color: green;
}

    这个css将会根据.bule, .breen和.red h1元素修改文本的颜色（固然是在你更新了你的helloword.java以后）

  7. 保存并关闭myConfluenceMacro.css

  8. 如今，打开src/main/java/com/atlassian/tutorial/macro/helloworld.java文件

  9. 按照下面修改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。

  10. 下一步，在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中。

  11. 在 public class helloworld implements Macro 定义上面，加上以下Spring注解：

    @Scanned

    这个 @scanned 注解是spring scanner的一个指令。在本教程中，咱们使用了spring scanner 1.2.13 - 因此咱们须要告诉spring scanner 来扫描这个类。

  12. 如今，在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。

  13. 最后，在你的execute方法中，添加以下一行：

    pageBuilderService.assembler().resources().requireWebResource("com.atlassian.tutorial.myConfluenceMacro:myConfluenceMacro-resources");

    注意，你在使用pageBuilderService 来获取web-resource key，候着是被自动生成的(看第二步)。

  14. 保存修改，执行atlas-mvn package来更新插件。

  15. 确保你的插件已经带有新修改运行：

 注意：在加载页面时，你可能须要按下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提问题。

资源

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程