Jira项目设置自定义按钮跳转新页面，如何实现同页渲染？

问题说明 #

在Jira项目设置中添加了自定义按钮，期望点击后像原生功能（如“用户和角色”）一样在页面右侧内嵌渲染内容，但当前点击会跳转到无左侧导航的全新页面，不符合预期。

问题根源 #

当前配置直接将Web项链接指向独立Servlet，而Jira项目设置页面采用单页内嵌架构，需要通过Project Config Module注册内嵌内容，而非直接跳转Servlet。

修复步骤 #

1. 修改Atlassian插件配置文件（atlassian-plugin.xml） #

替换原有的Web项和Servlet配置，改用project-config-module实现内嵌注册：

<!-- 保留原自定义区段 -->
<web-section key="custom-project-settings-section" location="atl.jira.proj.config">
    <label key="custom.project.settings.section.label"/>
</web-section>

<!-- 注册项目配置模块，关联Servlet -->
<project-config-module key="custom-project-settings-module" i18n-name-key="custom.project.settings.module.name">
    <description key="custom.project.settings.module.desc"/>
    <!-- 配置Servlet，指定路径 -->
    <servlet class="com.yourpackage.jira.servlet.EntryPointServlet" key="custom-project-settings-servlet">
        <url-pattern>/custom-project-settings</url-pattern>
    </servlet>
    <!-- 将模块关联到自定义区段 -->
    <item-section location="atl.jira.proj.config/custom-project-settings-section" weight="1000"/>
</project-config-module>

<!-- 更新Web项链接，指向项目配置模块路径 -->
<web-item key="custom-project-settings-item" section="atl.jira.proj.config/custom-project-settings-section" weight="1000">
    <label key="custom.project.settings.item.label"/>
    <link linkId="custom-project-settings-link">/plugins/servlet/project-config/${project.key}/custom-project-settings</link>
</web-item>

2. 调整Servlet逻辑 #

Servlet无需渲染完整HTML页面，只需输出内容片段（Jira会自动将其嵌入项目设置框架），同时保留权限检查逻辑：

@Override
protected void doGet(HttpServletRequest request, HttpServletResponse response) 
throws ServletException, IOException {
    ApplicationUser currUser = authenticationContext.getLoggedInUser();
    ProjectManager manager = ComponentAccessor.getComponent(ProjectManager.class);
    ProjectRoleManager projectRoleManager = ComponentAccessor.getComponent(ProjectRoleManager.class);
    ProjectRole role = projectRoleManager.getProjectRole("Administrators");
    String projectKey = request.getParameter("projectKey");
    Project project = manager.getProjectByCurrentKeyIgnoreCase(projectKey);

    if (projectRoleManager.isUserInProjectRole(currUser, role, project)) {
        // 渲染内容片段模板，无需完整HTML结构
        templateRenderer.render("templates/custom-project-settings-content.vm", map, response.getWriter());
    } else {
        redirectToLogin(request, response);
    }
}

3. 优化Velocity模板 #

模板仅保留内容部分，去掉完整HTML结构，适配Jira项目设置页面样式：

<div class="aui-page-panel">
    <div class="aui-page-panel-header">
        <h2>$i18n.getText("custom.project.settings.title")</h2>
    </div>
    <div class="aui-page-panel-content">
        <!-- 你的自定义设置内容 -->
        <p>这是自定义项目设置内容</p>
    </div>
</div>

原理说明 #

Jira的project-config-module会自动将Servlet输出的内容嵌入到项目设置页面的右侧区域，保留左侧导航栏，实现与原生功能一致的内嵌渲染效果。直接跳转Servlet会绕过这个框架，导致页面脱离项目设置上下文。

内容的提问来源于stack exchange，提问作者Rizwan Pochi