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」進行添加了。