Extensions:User Banners

User Banners

Description	Allows users to upload a custom profile banner
Author(s)	Min
Status	stable
Github	extension/user-banners
LK Version	3.0.0
Contains a Migration

NOTE: Hi! If you're looking to install this extension I recommend either waiting until I make an actual in-Discord announcement about it or contact me directly; there's a pending feature for it still that I'm in the process of polishing up that I'd like to complete before I announce an actual release, but I have this wiki page up for the time being so I can keep all the information documented on one page.

This extension gives the ability for users to upload a custom banner image via account settings, as well as define styling for their banner. Admins are also able to delete banner images via the admin panel user index in the case of inappropriate images. Admins may also upload a default banner image to the site via site images in the admin panel.

This extension can also be repurposed to decorate profile UI in other ways! See configuration for some notes.

Image file formats supported are png, gif, jpg, bmp, and webp. Currently supported units for numerical values are px, em, rem, vw, vh, and %. See configuration for adding others.

Installation

Pull the branch and resolve any merge conflicts. Afterwards, you can run the following commands:

php artisan migrate

php artisan optimize (x2)

Configuration

This extension does not need to be exclusively used for a header banner on a user profile and can be repurposed for other components.

The banner image URL is called with {{ $user->bannerUrl }} (note that it is only the URL, and is not wrapped in url(), in the case that any site owners wanted to use it in a <img> tag and so forth), while its styling is called via {{ $user->bannerStyling }} - if you want to apply the background image and styling to a different element, you can add style="background-image: url('{{ $user->bannerUrl }}'); {{ $user->bannerStyling }}" to the element.

By default the banner displays on the top of the user profile with a height of 150px, if the banner (or default banner) is set. The banner itself is a widget _user_banner.blade.php, which is called on the user profile, user settings page, and admin panel user page for display and previewing - it is recommended to edit this widget so previewing works correctly on both the user settings page and admin panel user page. The banner has a class of user-banner, so it can be further edited in CSS sheets.

Users are able to define a background-attachment, background-repeat, background-position, and background-size. Background position and background size can both accept keyword values or up to two numerical values. If you would like to disable any of these, you can remove the form codes from the user settings page.

If you would like to add more options for user styling, you would be looking at the code in the user settings page, function postBannerStyling in AccountController.php, function updateBannerStyling in UserService.php, and function getBannerStylingAttribute in the User.php model. The styling is stored in encoded JSON, so you do not need to make another column in the database table for it.

If you would like to add more units for numerical values, such as cm or in, you will need to modify the regex expression in function updateBannerStyling in UserService.php. For example, if you would like to add cm to the list of units allowed by the second size value, you would be modifying the regex expression /auto|\d+(px|em|rem|vw|vh|%)/i to be /auto|\d+(px|em|rem|vw|vh|%|cm)/i.

This extension can be referenced to add further user-customizable images. See changed files on Github to inspect how it's set up and duplicate the code for whatever other user-customizable images you'd like.

Images

(Coming soon)

Troubleshooting

You can find me in the Lorekeeper Discord!