注:阅读此篇时,请确保你的开发环境已经正常配置,可以正常使用命令行工具创建插件demo
简介
经过上四篇介绍,我们创建一个基本插件后端服务,有时我们的后台功能期望能在页面上方便配置不必要每次调整参数发版上线,给运营人员提供一个方便的配置界面。本篇描述如何创建一个最基本的管理员配置界面,帮助我们控制插件功能。
Let’s start
首先我们需要创建一个rest接口提供页面数据,这里我们使用【Confluence插件开发 - 4 - 给插件增加rest接口】中的接口,访问地址:/rest/plugin-demo/1.0/demo,GET请求返回{“code”:0,“msg”:“SUCCESS”},我们期望将msg数据展示到我们的管理员页面上。
创建静态资源文件
使用atlas-create-confluence-plugin命令创建一个空插件时候,配置文件atlassian-plugin.xml中默认会有如下类似的静态资源配置信息,系统默认将js和css文件创建好并帮你配置到web-resource中。
<!-- add our web resources -->
<web-resource key="plugin-demo-resources" name="plugin-demo Web Resources">
<dependency>com.atlassian.auiplugin:ajs</dependency>
<resource type="download" name="plugin-demo.css" location="/css/plugin-demo.css"/>
<resource type="download" name="plugin-demo.js" location="/js/plugin-demo.js"/>
<resource type="download" name="images/" location="/images"/>
<context>plugin-demo</context>
除了上述默认配置,我们在项目工程resources目录中创建demo.vm作为我们的配置管理页面,并修改atlassian-plugin.xml web-resource中增加配置
<resource type="velocity" name="template" location="/demo.vm"/>
最终配置:
<!-- add our web resources -->
<web-resource key="plugin-demo-resources" name="plugin-demo Web Resources">
<dependency>com.atlassian.auiplugin:ajs</dependency>
<resource type="download" name="plugin-demo.css" location="/css/plugin-demo.css"/>
<resource type="download" name="plugin-demo.js" location="/js/plugin-demo.js"/>
<resource type="download" name="images/" location="/images"/>
<resource type="velocity" name="template" location="/demo.vm"/>
<context>plugin-demo</context>
</web-resource>
编辑我们创建好的demo.vm文件粘贴如下内容,主要打印一个“Hello World”并且增加一些简单的html标签,期望通过点击测试按钮在span标签内展示结果。内容中的meta标签表示告诉confluence要把body装饰一下包裹成admin页面样式,$webResourceManager.requireResourcesForContext(“plugin-demo”)表示从配置文件中读取plugin-demo名字的web资源文件配置,此配置需要放置到title后面。
<html>
<head>
<title>Plugin demo</title>
## This tells the application that it needs to use the admin decorator around the body of this page
<meta name="decorator" content="atl.admin"/>
$webResourceManager.requireResourcesForContext("plugin-demo")
</head>
<body>
Hello World
<div>
<p>Get请求结果展示:</p>
<span id="get-result"></span>
<button id="get-result-btn" type="submit">测试</button>
</div>
</body>
</html>
在/resources/s/plugin-demo.js文件中增加如下内容,注册按钮click事件
(function ($) { // this closure helps us keep our variables to ourselves.
// This pattern is known as an "iife" - immediately invoked function expression
// form the URL
var url = AJS.contextPath() + "/rest/plugin-demo/1.0/";
// wait for the DOM (i.e., document "skeleton") to load. This likely isn't necessary for the current case,
// but may be helpful for AJAX that provides secondary content.
$(document).ready(function () {
$("#get-result-btn").bind("click", getResult);
});
})(AJS.$ || jQuery);
function getResult() {
var url = AJS.contextPath() + "/rest/plugin-demo/1.0/demo";
AJS.$.ajax({
url: url,
dataType: "json"
}).then(function (resultMsg) {
AJS.$("#get-result").text(resultMsg["msg"])
});
}
在站点管理页面增加管理员左侧菜单
主要页面已经创建好了,我们需要增加一个入口方便运营人员进入设置,这里可以在站点管理增加左侧菜单。
在atlassian-plugin.xml配置文件中增加如下内容
<web-item name="plugin-admin-web" key="plugin-admin-web" section="system.admin/configuration" weight="10" application="confluence">
<description>a plugin admin configuration web demo</description>
<label key="plugin.demo.configuration.web" />
<link linkId="plugin-demo-configuration-web-link">/plugins/servlet/plugin-demo/admin</link>
</web-item>
web-item模块允许自定义插件增加写连接或者菜单连接等,注意观察web-item元素内section属性,这里指定增加link连接的位置,这里设置system.admin/configuration表示我们将在整个系统设置的页面增加左侧菜单链接。label标签定义了连接的展示文本展示内容(效果见下面截图),link指定了链接跳转位置。
更多子元素或者属性参考web-item-plugin-module,在plugin-demo.properties配置文件中增加一条:plugin.demo.configuration.web=plugin-demo
增加一个servlet
直接上代码:
主要功能提供模板数据返回、判断用户是否登录,如果未登录跳转到登录页面
package cn.idocode.confluence.controller;
import com.atlassian.plugin.spring.scanner.annotation.component.Scanned;
import com.atlassian.plugin.spring.scanner.annotation.imports.ComponentImport;
import com.atlassian.sal.api.auth.LoginUriProvider;
import com.atlassian.sal.api.user.UserManager;
import com.atlassian.templaterenderer.TemplateRenderer;
import javax.inject.Inject;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.net.URI;
@Scanned
public class StaticResourceServlet extends HttpServlet {
@ComponentImport
private UserManager userManager;
@ComponentImport
private LoginUriProvider loginUriProvider;
@ComponentImport
private TemplateRenderer templateRenderer;
@Inject
public StaticResourceServlet(UserManager userManager,
LoginUriProvider loginUriProvider,
TemplateRenderer templateRenderer) {
this.userManager = userManager;
this.loginUriProvider = loginUriProvider;
this.templateRenderer = templateRenderer;
}
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
String username = userManager.getRemoteUsername(request);
if (username == null || !userManager.isSystemAdmin(username)) {
redirectToLogin(request, response);
return;
}
response.setContentType("text/html;charset=utf-8");
templateRenderer.render("demo.vm", response.getWriter());
}
private void redirectToLogin(HttpServletRequest request, HttpServletResponse response) throws IOException {
response.sendRedirect(loginUriProvider.getLoginUri(getUri(request)).toASCIIString());
}
private URI getUri(HttpServletRequest request) {
StringBuffer builder = request.getRequestURL();
if (request.getQueryString() != null) {
builder.append("?");
builder.append(request.getQueryString());
}
return URI.create(builder.toString());
}
}
在项目atlassian-plugin.xml配置文件中注册我们的servlet
<servlet key="plugin-demo-servlet" class="cn.idocode.confluence.controller.StaticResourceServlet">
<url-pattern>/plugin-demo/admin</url-pattern>
<description>plugin demo static resource servlet</description>
</servlet>
运行demo
本地运行测试demo后进入管理界面,在左侧菜单就可以看到plugin-demo链接,点击后页面如下图片显示:
点击测试按钮,访问rest接口获取返回值展示到页面上:
示例代码
https://github.com/chaoyz/plugin-demo
参考
creating-an-admin-configuration-form
atlassian-plugin-xml-element-reference
web-item-plugin-module