JIRA 6.3.1定制字段小结

背景：因业务需要，需要添加一个文本字段，要求该字段支持权限控制，对指定用户可编辑，其他用户只读。

创建插件的过程不做赘述，需要的请参考：创建HelloWorld插件工程。下述步骤基于一个已经创建好的插件工程展开，基于Jira 6.3.1。

该总结基于官方教程：创建一个新的定制字段类型

创建实现类

添加一个新类，命名为EditPermissionControllableTextField，继承TextAreaCFType。其构造方法如下：

    public EditPermissionControllableTextField(
            @ComponentImport CustomFieldValuePersister customFieldValuePersister,
            @ComponentImport GenericConfigManager genericConfigManager) {
        super(customFieldValuePersister, genericConfigManager);
    }

 

上述构造方法基于JIRA 6.3.1，根据JIRA官方关于7.0以上的API介绍，TextAreaCFType参数发生了变化，如7.6.1：

public TextAreaCFType(CustomFieldValuePersister customFieldValuePersister,
                      GenericConfigManager genericConfigManager,
                      TextFieldCharacterLengthValidator textFieldCharacterLengthValidator,
                      JiraAuthenticationContext jiraAuthenticationContext)

 因此对于不同的JIRA版本，构造方法可能不同，以实际情况为准。可以查阅JIRA官方对于指定版本的API介绍，不过JIRA对于旧版本API维护的不好，查阅不太容易。所以本地下载一套对应版本的SDK，然后直接源码查询更便捷一些，上述6.3.1版本就是通过SDK查询到的。

构造方法可以构造自己的各种变量或组织逻辑，在本需求中不需要，所以不做任何实现。

新建模版文件

在resouces/template文件夹下，添加vm模板文件，用于定义该字段的显示、编辑和xml格式显示，注意确保文件名的唯一性。

其中view模板，支持折叠显示，直接参考了JIRA的Description的view模板：

#disable_html_escaping()
#if ($value)
  #if (${displayParams.excel_view})
    $textutils.br($textutils.htmlEncode($!value.toString(), false))
  #else
    #if ($value && $value.length() > 255)
        <div id="field-${field.id}" class="twixi-block#if($invertedCollapsedState) twixi-block-inverted collapsed #else expanded#end">
            <div Class="twixi-wrap verbose">
                <a href="#" class="#if($invertedCollapsedState)twixi #else twixi#end"><span class="icon twixi-opened"><span>$i18n.getText("admin.common.words.hide")</span></span></a>
                <div class="flooded">
                    $!value.toString()
                </div>
            </div>
            <div Class="twixi-wrap concise">
                <a href="#" class="#if($invertedCollapsedState)twixi #else twixi#end"><span class="icon twixi-closed"><span>$i18n.getText("admin.common.words.show")</span></span></a>
                <div class="flooded">
                    #if ($value)
                        $velocityhelper.removeHtmlTags($value.toString())
                    #end
                </div>
            </div>
        </div>
    #else
        $!value.toString()
    #end
  #end
#end

在 edit模板实现权限的控制，直接上实现：

#disable_html_escaping()
#customControlHeader ($action $customField.id $i18n.getText($customField.nameKey) $fieldLayoutItem.required $displayParameters $auiparams)
#if ($jiraUserUtils.getGroupNamesForUser($authcontext.loggedInUser.name).contains('editable_group'))
    $!rendererParams.put("class", "long-field")
    $!rendererParams.put("rows", "5")
    $!rendererParams.put("wrap", "virtual")
    $rendererDescriptor.getEditVM($!value, $!issue.key, $!fieldLayoutItem.rendererType, $!customField.id, $!customField.name, $rendererParams, false)
#else
    #if($value && ! $value.equals(""))
        #set ($displayValue = ${value})
    #else
        #set ($displayValue = 'N/A')
    #end
    <span title="This field is editable only by editable_group">$!displayValue</span>
    <input type="hidden"
           name="$customField.id"
           value="$!value" />
#end
#customControlFooter ($action $customField.id $fieldLayoutItem.getFieldDescription() $displayParameters $auiparams)

#disable_html_escaping()   这一句很重要，它决定了字段的内容是纯文本还是html格式，在有HTML格式需求时，需要添加该句。
tips：在filed configurations中对应的字段上，选择Renderers，然后选择Wiki Style Renderer，那该字段即支持WIKI编辑选项了，类似Description字段，可以实现一些格式化输出，对于较大篇幅的内容，有更好的阅读性。

其中，editable_group为群组名，即在JIRA中创建 一个editable_group的群组，然后将需要编辑权限的人员加到群组中，而非该群组的人员就只读了。

配置atlassian-plugin.xml

atlassian-plugin.xml是插件的配置文件，在这里声明一个customfield-type标签，标签中表明该模块的实现类以及模板文件的信息。

    <customfield-type name="Edit Permission Controllable Text Field" key="editPermissionControllableTextField"
                      class="com.lxd.reallytek.customfield.EditPermissionControllableTextField">
        <description>The custom text field can be edited by specified group only. Group name is "editable_group"</description>
        <resource name="view" type="velocity" location="/templates/view-collapsible_lxd.vm"/>
        <resource name="edit" type="velocity" location="/templates/edit-by_jira_admin_only_text_lxd.vm"/>
        <resource name="xml" type="velocity" location="templates/plugins/fields/xml/xml-basictext.vm"/>
    </customfield-type>

在上边这段配置中，name是指在JIRA中添加这个类型时显示的名称，key是唯一识别码，class即实现类。resource配置了三个类型的模板，除了view和edit外，还配置了xml显示模板，因为在本次需求中不需要考虑xml显示的问题，直接指向了JIRA系统模板。

总结

上述三步完成后，编译并安装插件，即可在custom field页面中，通过add Fields来选择“Edit Permission Controllable Text Field”进行添加了。