How can my Bitbucket Server Plugin display the same avatars as other parts of Bitbucket Server?

[Graham Lea]

In Stash 3.x, I could use:

<dependency>com.atlassian.stash.stash-web-plugin:avatar</dependency>

in the plugin XML and

{call stash.widget.avatar}

in a server-side soy template to display the same avatars that Stash displayed. (See my previous question.)

How can I achieve the same in Bitbucket Server 4.0+ ?

[Felix · Accepted solution]

Hi @Graham Lea,

the templates Bitbucket Server uses have been renamed to "bitbucket.internal.widget.avatar"; as the name suggests, they are not considered public API and should not be used by plugins. 

Instead, we'd recommend using AUI Avatars  in your plugin. If you are using soy, you can easily write your own template: 

/**
 * @param person
 * @param size either 'xsmall', 'small', 'medium', 'large', 'xlarge', 'xxlarge' or 'xxxlarge'
 */
{template .avatar}
<span class="aui-avatar aui-avatar-{$size}">
    <span class="aui-avatar-inner">
        <img src="{$person.avatarUrl}">
    </span>
</span>
{/template}

[Graham Lea]

Thanks for your answer, Felix. I thought that (hiding the internal API) might be the case. Now that I'm trying to follow your advice, I have to generate the avatar URL in my code, and I've bumped into another issue. Do you have any insight into this other one? https://answers.atlassian.com/questions/32968436/why-wont-the-bitbucket-server-avatarservice-get-auto-wired-into-my-plugin For what it's worth, I think it would be great if that Stash Avatar template was part of the public API.

[Graham Lea]

So, 'bitbucket.internal.widget.avatar' works. :) What are the consequences of my plugin using it, other than that it might break again in the future without it being recorded in the API?

[Felix]

Using the internal template basically only means we don't guarantee compatibility between releases. So your plugin could break in a minor version change.

[Henrik Heimbuerger]

@Felix Haehnel Thanks for your answer! I'm struggling with a similar issue as Graham and for me, the AUI Avatars might actually be sufficient. However, the documentation doesn't mention at all where to get the image URL from, and your example conjures a $person out of thin air. ;) Could you shed some light on where to get either of these from? For context: I'm in JS and I have an email address or an ID of what's guaranteed to be an AuthenticatedUser. Is there a way to do this without using the AvatarService on the backend? Thanks!

[Felix]

@Henrik Heimbuerger You can get the avatarUrl by calling a REST endpoint that returns a user and adding an "avatarSize=32" (replace 32 with the avatar size you need) query parameter to the REST URL. For example: https://example.com/rest/api/1.0/users/{userSlug}?avatarUser=32 That will add an "avatarUrl" field to the response. You can also check out the small sample plugin I wrote that uses the AvatarService and UserService directly: https://bitbucket.org/fhaehnel/avatar-list-plugin-sample/src

[Henrik Heimbuerger]

@Felix Haehnel That's great information, thanks! I don't see the 'avatarSize' parameter or 'avatarUrl' field mentioned in the REST Browser on that endpoint, might make sense to add this to the documentation! For the record, the correct example REST URL would be: https://example.com/rest/api/1.0/users/{userSlug}?avatarSize=32 I'm gonna use the AvatarService as shown in your example for now. I already got that working and it fits my workflow. Thanks!

[Henrik Heimbuerger]

For anyone else reading this: you might want to also set the `title` attribute on the `<img>` (to the `displayName` you can retrieve from the `UserService`) and then call `.tooltip({gravity: 'n'})` to get the same kind of tooltip that Bitbucket core is using.