confluence添加用户_玩转Confluence插件开发插件模块配置文件介绍(04)

上一章节我们介绍了测试模块的配置文件,这一 章节我们介绍插件本身的配置文件,这个是我们部署插件真正用到的. 文件的位置位于项目主目录中的 /src/main/resources目录中.

插件配置文件介绍

插件描述文件的根元素

<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
atlassian-plugin>

属性名称	描述
key	用来标识插件模块.此属性是必须的,并且在插件中必须是唯一的,相当于插件的身份证号码.默认使用构建插件时填写的groupId和artifactId组成.
name	插件的名称.用于在应用程序的菜单中显示.默认通过引用pom.xml文件的name来加载.(不应该在该值中使用单词 “plugin” 或 “add-on” )

接下来是plugin-info元素

包含插件信息,父元素是,支持多个嵌套元素.

<plugin-info>
        <description>${project.description}description>
        <version>${project.version}version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
        <param name="plugin-icon">images/pluginIcon.pngparam>
        <param name="plugin-logo">images/pluginLogo.pngparam>
plugin-info>

嵌套元素	描述
description	插件说明
version	插件版本
vendor	提供插件开发人员的信息
param	插件参数(示例中的两个参数分别提供了插件图标的位置和插件logo的位置)

vendor元素

插件供应商.在插件管理中提供链接地址.父元素是.

属性名称	描述
name	提供开发人员的姓名或公司的名称
url	提供一个网站地址

---

文件其余部分是组成插件的所有模块,首先来看下插件本身的.里面有resource元素和web-resource元素.

国际化资源配置

location填写的名称,代表必须有一个叫hello-world.properties的配置文件

<resource type="i18n" name="i18n" location="hello-world"/>

Web资源插件模块

该模块允许插件定义可下载的资源.如果插件中需要引用JavaScript或CSS文件,则需要依赖该模块,将Web资源添加到页面顶部.另外,也可以将指定的Web资源包含在应用程序的特定上下文中.

web资源模块的根元素web-resource

<web-resource key="hello-world-resources" name="hello-world Web Resources">
web-resource>

属性名称	描述
key	模块的唯一标识符,可以通过它使用模块中包含的资源
name	模块的名称

依赖项

示例中的这个依赖项可以理解为增强版的jQuery,Atlassia在jQuery之上提供了一些其他功能

<dependency>com.atlassian.auiplugin:ajsdependency>

资源

代表该模块包含的静态资源

<resource type="download" name="hello-world.css" location="/css/hello-world.css"/>
<resource type="download" name="hello-world.js" location="/js/hello-world.js"/>
<resource type="download" name="images/" location="/images"/>

属性名称	描述
type	download代表可下载的资源类型,它使资源可以从特定的URL下载
name	资源的名称,如果location参数指定的不是单个资源(例如图片存放目录),应该在名称后面加上“/”,对于CSS/ Javascript 资源,他们的名称必须具有适当的文件扩展名
location	资源的位置,告诉插件在哪个位置可以找到资源

如果要在CSS中引用图片,使用基于图片定义的资源名称的相对路径,如该插件的imageshello-world.css

.my-class {
   background-image: url(images/mypicture.gif);
}

要引用Confluence中已经可用的图片,需要指定三个父级目录,如下所示

.my-class {
   background-image: url(../../../images/icons/confluence-logo.gif);
}

Web资源上下文

可以在Confluence中特定类型的页面上自动包含Web资源.默认是artifactId的名称,属于自定义上下文,相对应的还有一些Confluence自带的上下文

1. 自定义上下文

<context>hello-worldcontext>

2. Confluence自带上下文

上下文	描述
atl.general	除了管理页面之外的任意页面
main	除了管理页面之外的任意页面
atl.admin	管理页面,请谨慎使用,因为格式不正确的CSS或JavaScript可能会阻止访问该Confluence
admin	管理页面,请谨慎使用,因为格式不正确的CSS或JavaScript可能会阻止访问该Confluence
atl.userprofile	用户个人资料页面
atl.popup	弹出窗口
dashboard	仪表板
editor	出现编辑的页面
editor-context	页面编辑器内
macro-browser	宏浏览器,在editor之后
page	任何与页面相关的页面，例如查看，编辑，附件，信息；但不包括博客文章，空间或全局页面
preview	在宏浏览器的预览窗格中
blogpost	任何与博客相关的页面，例如查看，编辑，附件，信息；而不是页面，空间或全局页面
space	任何与空间相关的页面

如果要将Web资源配置在空间和页面的上下文中可以如下配置

<web-resource key="hello-world-resources" name="hello-world Web Resources">
        <dependency>com.atlassian.auiplugin:ajsdependency>
        <resource type="download" name="hello-world.css" location="/css/hello-world.css"/>
        <resource type="download" name="hello-world.js" location="/js/hello-world.js"/>
        <resource type="download" name="images/" location="/images"/>
        <context>spacecontext> 
        <context>pagecontext>
web-resource>

引用Web资源

要将自定义Web资源包含在使用插件的页面中，请使用#requireResource Velocity宏

#requireResource("com.jenseny.atlassian.tutorial.hello-world:hello-world-resources")

内容格式为${atlassian.plugin.key}:${web-resource-key}

如果Confluence中添加了许多页面,这些页面都依赖一个Web资源,我们可以新建一个Web资源上下文,然后在Velocity中引入新的上下文,引入方法如下

#webResourceManager.requireResourcesForContext("hello-worlds")

以上就是关于插件配置文件的介绍,下一章节我们正式开始开发自定义插件,先以自定义Confluence主题为例.