建立一個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教程