User Format Plugin Module

User Format plugin modules are implemented in the JIRA 3.13 release. They are not available in previous releases.

User Format plugin modules are used to display user details in JIRA. JIRA ships with a number of default user format implementations that are used to render the full names for users system wide. You can use User Format plugin modules to implement custom behaviours for these user details. Here are some examples:

Display a profile picture next to the user.
Link to an external profile page.
Display special avatars for users in certain groups.

For more information about plugins in general, read JIRA Plugin Guide. To learn how to install and configure plugins (including macros), read Installing and Configuring Plugins.

The User Format Plugin Module

Here is an example atlassian-plugin.xml file containing a single user format plugin module:

<atlassian-plugin name='User Format' key='jira.user.format' i18n-name-key="user.format.plugin.name">
    <plugin-info>
        <description key="user.format.plugin.desc">This plugin renders a user in JIRA.</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <application-version min="4.0" max="4.0"/>
        <version>1.0</version>
    </plugin-info>

    <user-format key="profile-link-user-format" i18n-name-key="user.format.plugin.profile.link.name" name="Profile Link User Format"
            class="com.atlassian.jira.plugin.profile.ProfileLinkUserFormat" system="true">
        <description key="user.format.plugin.profile.link.desc">Simple link to a user's profile page displaying the user's full name.</description>
        <type i18n-name-key="user.format.type.profile.link">profileLink</type>
        <resource type="velocity" name="view" location="templates/plugins/userformat/profileLink.vm"/>
    </user-format>
</atlassian-plugin>

* the class attribute of user-format needs to implement com.atlassian.jira.plugin.profile.UserFormat.

the resource elements (one or more) can be used to implement complicated rendering using velocity.

The type attribute defines where the user format will be used. The system types that are pre-defined include:

タイプ	説明
profileLink	Simple link to a user's profile page displaying the user's full name.
fullName	Safely displays the user's full name.
profileLinkSearcher	Simple link to a user's profile page displaying the user's full name from the issue navigator.
profileLinkExternal	Simple link to a user's profile used in emails, word documents, excel downloads etc.
profileLinkActionHeader	Simple link to a user's profile in issue action headers such as comments.
fullProfile	Full user description including user operation links and report links.

Choosing your User Format

Once you've added your own user format, JIRA's 'Look and Feel' administration allows you to select the User Format that will be used across JIRA:
Screenshot: View Look and Feel Configuration

Screenshot: Edit Look and Feel Configuration - User Format

Sample Implementation

The following example demonstrates how to implement a user format that prints a user's full name with a link to the user's profile page in JIRA.

1. First, you will need an implementation of the UserFormat interface:

ProfileLinkUserFormat.java

package com.atlassian.jira.plugin.profile;

import com.atlassian.core.util.map.EasyMap;
import com.atlassian.jira.user.util.UserUtil;
import com.opensymphony.user.User;

import java.util.Map;

/**
 * Very simple implementation that only renders the users full name with a link to the user's profile page. If the
 * username is null, it will display 'Anonymous'.  If no user matching the username can be found, ony the username
 * will be printed.
 *
 * @since v4.0
 */
public class ProfileLinkUserFormat implements UserFormat
{
    private UserFormatModuleDescriptor moduleDescriptor;
    private UserUtil userUtil;
    private final UserFormatManager userFormatManager;

    public ProfileLinkUserFormat(UserFormatModuleDescriptor moduleDescriptor, UserUtil userUtil, UserFormatManager userFormatManager)
    {
        this.moduleDescriptor = moduleDescriptor;
        this.userUtil = userUtil;
        this.userFormatManager = userFormatManager;
    }

    public String format(String username, String id)
    {
        final Map params = getInitialParams(username, id);
        return moduleDescriptor.getHtml(VIEW_TEMPLATE, params);
    }

    public String format(String username, String id, Map params)
    {
        final Map velocityParams = getInitialParams(username, id);
        velocityParams.putAll(params);

        return moduleDescriptor.getHtml(VIEW_TEMPLATE, velocityParams);
    }

    private Map getInitialParams(final String username, final String id)
    {
        final User user = userUtil.getUser(username);
        final String fullName = userFormatManager.formatUser(username, FullNameUserFormat.TYPE, id);
        return EasyMap.build("username", username, "user", user, "fullname", fullName, "id", id);
    }
}

2. You will then need to implement the view velocity template that used to display the user:

profileLink.vm

#if ($username)
    #set ($quote = '"')
    #if($user)
        #set($author = "<a id=${quote}$!{id}_${textutils.htmlEncode($username)}${quote} href=${quote}${baseurl}/secure/ViewProfile.jspa?name=${velocityhelper.urlencode($username)}${quote}>$textutils.htmlEncode($fullname)</a>")
    #else
        #set($author = $textutils.htmlEncode($username))
    #end
#else
    #set($author = $i18n.getText('common.words.anonymous'))
#end
${author}

3. Finally, you can use this plugin to print the user's details, as shown below:

$userformat.formatUser($worklog.author, 'profileLink', "worklog_${worklog.id}_header")

In this case, profileLink the type and worklog_${worklog.id}_header is the id that is passed to the UserFormat.format method for rendering.

Child pages

User Format Plugin Module

The User Format Plugin Module

Choosing your User Format

Sample Implementation