Skip to main content


Cover Photo Add-On for Friendica


Screenshot of the Cover Photo Add-On User Interface

I got a little sidetracked from working on a new theme and ended up making this add-on that finally creates a user interface for setting/changing/showing Friendica's built-in profile Cover Photo. Every other social media platform out there shows these, it's about time Friendica did too. I'm looking for any server admins who want to test this on a live server.

Okay, you might know them as a "Header Image" (Mastodon, Tumblr), "Banner" (Bluesky), or "Cover Photo" (Facebook). I'm sticking with "Cover Photo" because that's what I called it in my Bookface scheme for Frio, and because the words "header" and "banner" are used in Friendica's code to refer to half a dozen different things. For example the back-end functions are things like "uploadBanner" and "getDefaultBanner" but the data is stored in the profile's "header" key because the "banner" key is for something else. So "Cover Photo" it is!

Until now the only way to set/change/see this image in Friendica was if you were using one of the third-party mobile apps that supports Friendica it could be (somewhat) managed through the API. But there was no interface for doing it through the Friendica website/webapp and none of the available themes would show it. I've been working on a new theme for Friendica that would support showing it and ended up making this add-on to show it in every theme.

I have tested this in both the 2024.12 stable release and the 2025.07 release candidate. So far as I can tell it works equally well in either of them. This is how it shows the "Cover Photo" on the profile in all of the main themes:

Cover Photo displayed on Profile page in diffrent Friendica themes


It will also show the image across ALL the top of the Profile sub-pages
* /profile/username/
* /profile/username/profile
* /profile/username/conversations
* /profile/username/photos (but none of the photo sub-pages)
* /profile/username/media
* /profile/username/calendar
* /profile/username/notes
* /profile/username/schedule
* /profile/username/contacts (and all sub-pages)
* /contact/00 (where "00" is the contact ID number)
* /contact/00/conversations
* /contact/00/posts
* /contact/00/media
* /contact/00/contacts (and all sub-pages)

You can paste a public image URL into the box if you're pulling it from elsewhere or you can browse for an image in your Photos library. Either way Friendica makes a copy and puts it in a "Banner Photos" album. On submission the add-on will check whether it is a local image or not, and if it is local it will check the permissions and warn you if you selected a non-public image.

You will likely also want to go into your Friendica Settings > Account > Security and Privacy and tick the box for "Make all posted pictures accessible". Other platforms don't know how to handle Friendica's photo permissions. What this does is make sure if you posted a publicly accessible image that it is actually publicly accessible to other platforms.

On my development server I have my stable and RC Friendica installs connected to a WordPress install sharing over ActivityPub. In my testing it successfully shows the Cover Photos for the ActivityPub users. I'm assuming it will show "Header Images" from Mastodon as well but I have not been able to test this. I'm also not sure if you set a Cover Photo with this add-on whether or not it propagates to other platforms.

I included translations for a dozen languages, but these are AI translations so I can't say if they're nonsense or not. I only know English.

Oh, and another important thing is it won't show you any Cover Photos for anyone, including yourself, if you don't at the very least tick the "Enable Cover Photos on Profiles" checkbox in the add-on!

Lastly, if you already set up a Cover Photo using the [class=coverphoto]…[/class] method in Bookface you can also use the add-on, but on some Profile pages your BBcoded one will override the Friendica-native one. You could also set them to the same image and nobody would notice.

@Friendica Admins @Friendica Developers

DOWNLOAD FROM GITLAB
gitlab.com/randompenguin/cover…

in reply to Random Penguin

Ok, I don't know what's going on here. I did not see this on my Dev Server but am seeing it on a live server:
Empthy Thumbnail

I see a flash of the thumbnail image and then it's replaced with this. The thumbnail image is there if I switch themes from "Frio" to "Vier." I also had to set a coverphoto more than once and refresh my "Photos" multiple times to get it to show the "Banner Photos" album at all.

My add-on does not create the "Banner Photos" album nor does it generate the thumbnails. I believe those are handled by the Photo::uploadBanner() function. Or it's something in how "Frio" generates the Photo albums since "Vier" isn't doing this. I don't know. I can't reproduce this on my Dev Server.

Edit: I've been able to reproduce it on my Dev Server. Am investigating cause...

This entry was edited (2 weeks ago)

reshared this

in reply to Random Penguin

This is only happening in "Frio" and has something to do with the jQuery justifiedGallery framework and to do with a dash and number added to the end of the thumbnail image URL. It looks like the thumbnails for those cover photos already have the that in the filename and then something is trying to add another one and then the URL doesn't point to an actual file anymore. I need to figure out where that URL is getting altered or why the URL is coming into the page already appended.

The good news is this doesn't affect the actual cover photos, just the thumbnails in your photo albums and only in the Frio theme.

reshared this

in reply to Random Penguin

Except the thumbnails actually show in the Photo modal, just not in the Photos page. Very frustrating to debug!

reshared this

in reply to Random Penguin

MISSING THUMBNAILS FIX FOR FRIO

Okay, I've figured out a fix for the missing Banner Photo album thumbnails. It is being caused by the jQuery justifiedGallery script, which is adding a sizing suffix to the image when there is already one there. So I just added a check for the suffix before adding it and that fixed it.

Admins who want to patch it right now just replace the script at /view/theme/frio/frameworks/justifiedGallery with this one:

github.com/randompenguin1/frie…

I have also submitted a PR for this change.

This only addresses the missing thumbnail issue. It does not fix any of the other image gallery issues.

I think this may have something to do with Banner/Cover Photos not going through the normal image upload process when Friendica generates the image copy? Not sure about that.

reshared this

in reply to Random Penguin

Awesome! This is something I have really anticipated!

Am not sure whether I'll get around to testing it on my instance though. Am not sure how involved that is? But will definitely use it once it has been tested

reshared this

in reply to Random Penguin

It isn't instant, it takes a bit of time to propagate, but these DO go through to Mastodon and presumably any other ActivityPub platform that shows cover photos.

reshared this

in reply to Random Penguin

ok, that was easier to test than I feared..
In the same go I also installed the Bookface scheme, because I wanted to have the cover photo shown as banner in the background.
It works as I expected, so that is great! However, I tested with three different images with different dimensions (one panorama, two normal-size) and all of them are getting blurred on the profile page. Is this something you are aware of? Or is it because I should you specific dimensions on the image?
This entry was edited (2 weeks ago)

reshared this

in reply to ᏇᎥᏇᎥᏋ

If you select an image from the Photo gallery modal it's apparently grabbing the URL for a version of the image resized to 640 pixels wide. I need to fix the script that gets the URL.

In the meantime if you go to your Photos page in your profile, find the image there and drill down until it shows you the raw image in the browser all by itself, copy that URL (it should end in something like "-0.jpeg" or "-0.png" - the zero is the important part - except it might be "-3" if it got resized), paste that into the add-on and submit and it should only resize it if it was larger than 960 pixels wide (and the Photo::uploadBanner() scales it down to 960 if not).

That's the only work-around I have at the moment.

This entry was edited (1 week ago)

reshared this

in reply to Random Penguin

Thanks for the reply!
I'll try your workaround later.

Btw are you also the developer of the Bookface scheme?

reshared this

in reply to Random Penguin

ok, tried your workaround and it did not work.

but then I reread your message and it sounds like, that images wider than 960 will be scaled down. Does that mean that screens wider than 960px will use a stretched version of the 960px image? if so, that could explain why my image is blurred?

reshared this

in reply to ᏇᎥᏇᎥᏋ

The downsizing is hard-coded into the Friendica core Photo::uploadBanner() function. There's nothing I can do about that. Bookface scales the image up to 1920px wide which would make it look a little blurry. If it's the 640 pixel wide image it will look really blurry.

In a future update to Bookface I'm likely going to limit the width of the cover photo to 960px instead of 1920px to prevent the blurring issue.

The workaround should work if the image is publicly visible. It should work with image URLs from anywhere actually. But you have to make sure you are all the way to the raw image where it is the only thing in the browser window and the URL in the address bar ends in ".jpeg" or ".png"

reshared this

in reply to Random Penguin

I would also recommend server admins either leave this Admin Setting at "-1" or if you do wish to limit the dimensions don't set it any lower than 960.

reshared this

in reply to Random Penguin

Ugh! And yet *another* problem I just discovered with the Photo gallery modal. If the image you select has a caption stored it will fail to get the URL properly. I need to fix the JS code that extracts the image URL. That never occurred to me because on my Dev Server I never enter captions for the images I upload. But I do on a live server and it just bit me.

Stay tuned for an update soon. I want to see if I can fix another issue with the modal image browser before I push an update.

reshared this

in reply to Random Penguin

I never noticed this before but apparently you never could navigate to sub-albums in the Photo Browser modal in Vier? I just tried it on 3 different servers. The problem is the links go to "#" (nowhere) instead of the sub-albums. If they're supposed to have JS listeners attached to them they don't.

Anyway, that's a separate problem that has nothing to do with my Add-on.

Edit: found the problem, have submitted a PR for that fix too. Here's my fixed file if you want to patch your server now, it goes in /view/js/module/media/.:
github.com/randompenguin1/frie…

This entry was edited (1 week ago)

reshared this

in reply to Random Penguin

UPDATE TO VERSION 1.1

DOWNLOAD HERE: gitlab.com/randompenguin/cover…

Thanks to all the great feedback here I've already got some fixes in place:

  • Improved client-side JS error handling
  • Normalized the script to all be in jQuery (instead of a mix of vanilla JS and jQuery)
  • Added handling for image URL data from Frio version of browser.js script.
  • Fixed the regex that extracts the image URL in other themes so it now handles a caption having been set on the image.
  • Preview now shows the image you just selected from Photo Browser modal.

Some of the other issues can only be fixed in Friendica itself. I've already submitted these as PRs and some are already merged into the dev branch, but Admins can also go grab these scripts and manually replace the files on their server to get the fixes right now:

1. /view/js/module/media/browser.js fixes the inability to navigate to albums in the photo browser modal in themes other than Frio. It also makes the script data returned from selecting an image consistent between Frio and non-Frio themes, which in turn reduces potential errors in Cover Photo retrieving the selected image URL.

2. /view/theme/frio/frameworks/justifiedGallery/jquery.justifiedGallery.min.js fixes the missing Cover Photo thumbnail images on the Photo pages when using the Frio theme.

This entry was edited (1 week ago)

reshared this

in reply to Random Penguin

@Random Penguin Hmm, still not seeing it, I set it up on my personal blog @🌴 Seph 💭 👾 but its not showing up. Assuming @#SpaceHost Help installed the most current version, not sure what's going on. I did have a little trouble selecting a pic, uploaded it, clicked on it, and nothing happened, but when I closed the window, it was there, which is not how pic selection usually works. Once I got the pic properly set as public, it installed, or at least said it did, but I can't see it on my profile nor via my Mastodon.

reshared this

in reply to Kāpitan

I don't know if it makes any difference that server is running Friendica 2024.08, I only tested the add-on in 2024.12 and 2025.07-rc.

Try setting it again. In my experience it doesn't always succeed in creating the "Banner Photos" album on the first try. No clue why. My add-on doesn't actually do that part, it's in the Friendica code.

Also make sure you actually ticked the "Enable" checkbox in the add-on and that other platforms can directly access your Friendica public photos, go to Settings > Account > Security and Privacy > Make all posted pictures accessible and tick that checkbox if you haven't done already.

It took a couple hours before my Cover Photo would show up on Mastodon.

reshared this

in reply to Random Penguin

@vextaur @capitan
We did the theme installation.

However, we will go ahead to update your server to the latest version. Kindly note that it will be down for about an hour for the update. Thanks.

reshared this

in reply to #SpaceHost Help

@vextaur @capitan

We have updated your Friendica to 2024.12-1, which is the latest stable release.

You will also need to follow all the guidelines in the link you shared- dillyofapickle.com/display/8aa…

Kindly let us know if there is any other way we could help.
[share author='Random Penguin' profile='https://dillyofapickle.com/profile/randompenguin' avatar='https://blog.taursnd.haus/photo/21136510996887bd2d08e72639483327-5.jpeg?ts=1756818017' link='https://dillyofapickle.com/display/8aa28c03-1768-b221-56e5-e89517846698' posted='2025-08-29 21:53:26' guid='8aa28c03-1768-b221-56e5-e89517846698' message_id='https://dillyofapickle.com/objects/8aa28c03-1768-b221-56e5-e89517846698']

Cover Photo Add-On for Friendica


Screenshot of the Cover Photo Add-On User Interface

I got a little sidetracked from working on a new theme and ended up making this add-on that finally creates a user interface for setting/changing/showing Friendica's built-in profile Cover Photo. Every other social media platform out there shows these, it's about time Friendica did too. I'm looking for any server admins who want to test this on a live server.

Okay, you might know them as a "Header Image" (Mastodon, Tumblr), "Banner" (Bluesky), or "Cover Photo" (Facebook). I'm sticking with "Cover Photo" because that's what I called it in my Bookface scheme for Frio, and because the words "header" and "banner" are used in Friendica's code to refer to half a dozen different things. For example the back-end functions are things like "uploadBanner" and "getDefaultBanner" but the data is stored in the profile's "header" key because the "banner" key is for something else. So "Cover Photo" it is!

Until now the only way to set/change/see this image in Friendica was if you were using one of the third-party mobile apps that supports Friendica it could be (somewhat) managed through the API. But there was no interface for doing it through the Friendica website/webapp and none of the available themes would show it. I've been working on a new theme for Friendica that would support showing it and ended up making this add-on to show it in every theme.

I have tested this in both the 2024.12 stable release and the 2025.07 release candidate. So far as I can tell it works equally well in either of them. This is how it shows the "Cover Photo" on the profile in all of the main themes:

Cover Photo displayed on Profile page in diffrent Friendica themes


It will also show the image across ALL the top of the Profile sub-pages
* /profile/username/
* /profile/username/profile
* /profile/username/conversations
* /profile/username/photos (but none of the photo sub-pages)
* /profile/username/media
* /profile/username/calendar
* /profile/username/notes
* /profile/username/schedule
* /profile/username/contacts (and all sub-pages)
* /contact/00 (where "00" is the contact ID number)
* /contact/00/conversations
* /contact/00/posts
* /contact/00/media
* /contact/00/contacts (and all sub-pages)

You can paste a public image URL into the box if you're pulling it from elsewhere or you can browse for an image in your Photos library. Either way Friendica makes a copy and puts it in a "Banner Photos" album. On submission the add-on will check whether it is a local image or not, and if it is local it will check the permissions and warn you if you selected a non-public image.

You will likely also want to go into your Friendica Settings > Account > Security and Privacy and tick the box for "Make all posted pictures accessible". Other platforms don't know how to handle Friendica's photo permissions. What this does is make sure if you posted a publicly accessible image that it is actually publicly accessible to other platforms.

On my development server I have my stable and RC Friendica installs connected to a WordPress install sharing over ActivityPub. In my testing it successfully shows the Cover Photos for the ActivityPub users. I'm assuming it will show "Header Images" from Mastodon as well but I have not been able to test this. I'm also not sure if you set a Cover Photo with this add-on whether or not it propagates to other platforms.

I included translations for a dozen languages, but these are AI translations so I can't say if they're nonsense or not. I only know English.

Oh, and another important thing is it won't show you any Cover Photos for anyone, including yourself, if you don't at the very least tick the "Enable Cover Photos on Profiles" checkbox in the add-on!

Lastly, if you already set up a Cover Photo using the [class=coverphoto]…[/class] method in Bookface you can also use the add-on, but on some Profile pages your BBcoded one will override the Friendica-native one. You could also set them to the same image and nobody would notice.

@Friendica Admins @Friendica Developers

DOWNLOAD FROM GITLAB
gitlab.com/randompenguin/cover…

reshared this

in reply to #SpaceHost Help

@#SpaceHost Help @🌴 Seph 💭 👾 @Random Penguin No worries, I'd known it was behind, but hadn't been worrying about it as it didn't seem like it came with any important updates

reshared this

in reply to Random Penguin

@Random Penguin Does it create the space on the profile for it, or is that supposed to already be there, as my profile looks like this:

No space for a profile image unlike your sample images.

reshared this

in reply to Kāpitan

Yes it creates it using the page_content_top hook. It first checks the page name and if it's on one of the profile pages it next checks that the Cover Photo add-on is enabled. If it is then it checks whether the profile array's "header" key has a value or not. If it has a value it inserts a span with the image in it plus a link button to the add-on settings.

(My add-on specifically does not use either User::getBannerUrl() nor Contact::getDefaultBanner() because those will show the default platform banner if you don't have a cover photo of your own set and I only want to show the image if you've set one).

If it is not showing up it means either the "Enable" checkbox is not ticked in the add-on settings or it never set the "header" image in the profile array. The only solution I can offer is to just try and set an image again.

This entry was edited (1 week ago)

reshared this

in reply to Random Penguin

@Random Penguin
Thank you very much for this add-on. It's love at first sight :)

A note: if a remote profile is called up, the banner sticks directly to the first post. I created a little space with this code in line 68.

$html = $cover_photo = '<span class="coverphoto" style="display:block;width:100%;margin:0 auto;margin-bottom:10px;"><img src="'.$profile['header'].'" style="width:100%;max-width:100%;"/></span>' . $edit_button . $html;

Perhaps this will be of interest to you.

reshared this

in reply to Matthias

I guess the seamlessness of it didn't bother me, but I can see how it makes the image look like it's part of that first post.

Rather than always adding a 10px margin I made it add it only on other people's profiles, because on your own there will be the edit button - and exactly how much space there is (if any) between that button and the image depends on what theme you are using and how it styles that button type.

So that section now looks like this:

if ($owner == $uid && !preg_match($regex,$_REQUEST['pagename']) ) { // person is looking at their own profile
	$margin = "0 auto";
	$edit_button = '<a href="'.DI::baseUrl().'/settings/addons/coverphoto" class="btn settings-submit btn-sm" style="margin-bottom: 5px;"><i class="fa fa-camera" aria-hidden="true"></i> '.DI::l10n()->t('Change Cover Photo').'</a>';
} else {
	margin = "0 auto 10px auto";
	$edit_button = '';
}
// build coverphoto code
$html .= $cover_photo = '<span class="coverphoto" style="display:block;width:100%;margin:'.$margin.';"><img src="'.$profile['header'].'" style="width:100%;max-width:100%;"/></span>' . $edit_button . $html;

You may also notice it is now $html .= instead of just $html = in case there are any other add-ons or functions that hook into page_content_top. Otherwise the coverphoto add-on would overwrite them.

reshared this