class Theme implements ExtenderInterface

Methods

overrideLessImport(string $file, string $newFilePath, string|null $extensionId = null)

This can be used to override `LESS` files that are imported within the code.

overrideFileSource(string $file, string $newFilePath, string|null $extensionId = null)

This method allows overriding LESS file sources.

addCustomLessFunction(string $functionName, callable $callable)

This method allows you to add custom Less functions.

addCustomLessVariable(string $variableName, callable $value)

Defines a new Less variable to be accessible in all Less files.

logoSize(int|null $height = null, int|null $quality = null)

Sets how the forum logo and the dark mode logo are stored.

logo(string|callable $file)

Sets the forum logo. Admins see it on the Appearance page but can't change it.

logoDarkMode(string|callable $file)

Sets the logo shown in dark mode. Admins can't change it.

emailLogo(string|callable $file)

Sets the logo shown in emails. Admins can't change it.

favicon(string|callable $file, string|callable|null $svg = null)

Sets the favicon. Admins can't change it.

appIcon(string|callable $file, string|callable|null $background = null)

Sets the app icon that phones show for the forum on their home screen.

splashScreen(string|callable $file, string|callable|null $landscape = null)

Sets the splash screen iPhones and iPads show while the forum opens from the home screen, in place of the one drawn from the app icon. Android can only show the app icon, so it keeps showing that.

manifest(callable $callback)

Changes the forum's web app manifest, which phones read when the forum is added to a home screen.

void
extend( Container $container, Extension|null $extension = null)

No description

Details

Theme overrideLessImport(string $file, string $newFilePath, string|null $extensionId = null)

This can be used to override `LESS` files that are imported within the code.

For example, core's `forum.less` file imports a `forum/DiscussionListItem.less` file. The contents of this file can be overridden with this method.

Parameters

string $file : Relative path of the file to override, for example: `forum/Hero.less`
string $newFilePath : Absolute path of the new file.
string|null $extensionId : If overriding an extension file, specify its ID, for example: `flarum-tags`.

Return Value

Theme

Theme overrideFileSource(string $file, string $newFilePath, string|null $extensionId = null)

This method allows overriding LESS file sources.

For example `forum.less`, `admin.less`, `mixins.less` and `variables.less` are file sources, and can therefore be overridden using this method.

Parameters

string $file : Name of the file to override, for example: `admin.less`
string $newFilePath : Absolute path of the new file.
string|null $extensionId : If overriding an extension file, specify its ID, for example: `flarum-tags`.

Return Value

Theme

Theme addCustomLessFunction(string $functionName, callable $callable)

This method allows you to add custom Less functions.

All custom Less functions may only return numbers, strings or booleans. **Example usage:** ```php (new Extend\Theme) ->addCustomLessFunction('is-flarum', function (mixed $text) { return strtolower($text) === 'flarum' }), ```

Parameters

string $functionName Name of the function identifier.
callable $callable The PHP function to run when the Less function is called.

Return Value

Theme

See also

https://leafo.net/lessphp/docs/#custom_functions

Theme addCustomLessVariable(string $variableName, callable $value)

Defines a new Less variable to be accessible in all Less files.

If you want to expose a setting from your database to Less, you should use the `registerLessConfigVar` extender from `Extend\Settings` instead. Please note the value returned from the callable will be inserted directly into the Less source. If it is unsafe in some way (e.g., contains a semi-colon), this will result in potential security issues with your stylesheet. Likewise, if you need your variable to be a string, you should surround it with quotes yourself. ```php (new Extend\Theme()) ->addCustomLessVariable('my-extension__asset_path', function () { $url = resolve(UrlGenerator::class); $assetUrl = $url->to('forum')->base().'/assets/extensions/my-extension/my-asset.jpg'; return "\"$assetUrl\""; }) ```

Parameters

string $variableName Name of the variable identifier.
callable $value The PHP function to run, which returns the value for the variable.

Return Value

Theme

Theme logoSize(int|null $height = null, int|null $quality = null)

Sets how the forum logo and the dark mode logo are stored.

The header shows the logo at most 30px tall. By default it is stored 90px tall, so it stays sharp on screens with three times the pixel density, as WebP at quality 90. A theme that shows the logo larger can store it taller. An animated logo is stored as GIF, which has no quality setting, and an SVG logo set with logo() is used as it is. A logo that has already been uploaded keeps its size and quality until it is uploaded again. ```php (new Extend\Theme()) ->logoSize(height: 120, quality: 95) ```

Parameters

int|null $height The height to store the logo at, in pixels.
int|null $quality The WebP quality, from 1 to 100.

Return Value

Theme

Sets the forum logo. Admins see it on the Appearance page but can't change it.

An SVG is used as it is. Any other image is stored like an uploaded logo. Instead of a path, any image can be given a callable that returns one, to choose it on each request. Its parameters are resolved from the container. While it returns null, the image is the admin's to set. Returning a different file draws the image again, so it should return the same file for every visitor. ```php (new Extend\Theme()) ->logo(fn (SettingsRepositoryInterface $settings) => __DIR__."/logos/{$settings->get('acme.season')}.svg") ```

Parameters

string|callable $file Absolute path of a PNG, JPEG, WebP, GIF or SVG file.

Return Value

Theme

Theme logoDarkMode(string|callable $file)

Sets the logo shown in dark mode. Admins can't change it.

Parameters

string|callable $file Absolute path of a PNG, JPEG, WebP, GIF or SVG file.

Return Value

Theme

Sets the logo shown in emails. Admins can't change it.

Mail clients can't be relied on to show SVG, so this must be another format. Without it, emails use a copy of a logo set with logo(), if that isn't an SVG.

Parameters

string|callable $file Absolute path of a PNG, JPEG, WebP or GIF file.

Return Value

Theme

Theme favicon(string|callable $file, string|callable|null $svg = null)

Sets the favicon. Admins can't change it.

The .ico and PNG versions browsers need are drawn from the image, which should be at least 48px square. Browsers that support SVG favicons use the SVG, if one is given, instead.

Parameters

string|callable $file Absolute path of a PNG, JPEG, WebP or GIF file.
string|callable|null $svg Absolute path of an SVG version.

Return Value

Theme

Theme appIcon(string|callable $file, string|callable|null $background = null)

Sets the app icon that phones show for the forum on their home screen.

Admins can't change it. The icon should be square and at least 512px. Apple's touch icon and Android's maskable icon are drawn on the background colour.

Parameters

string|callable $file Absolute path of a PNG, JPEG, WebP or GIF file.
string|callable|null $background A CSS hex colour. Defaults to the one set on the Appearance page.

Return Value

Theme

Theme splashScreen(string|callable $file, string|callable|null $landscape = null)

Sets the splash screen iPhones and iPads show while the forum opens from the home screen, in place of the one drawn from the app icon. Android can only show the app icon, so it keeps showing that.

The image is scaled to cover each screen and cropped from the middle, so keep what matters near the centre. Screens held sideways get the landscape image, if one is given. Images at least 1320 by 2868 pixels, or 2868 by 1320 for landscape, stay sharp on every screen. It's only shown with an app icon, set by an admin or with appIcon(), as the forum only opens as an app with one. Admins can still turn the splash screen off on the Appearance page.

Parameters

string|callable $file Absolute path of a PNG, JPEG, WebP or GIF file.
string|callable|null $landscape Absolute path of a PNG, JPEG, WebP or GIF file.

Return Value

Theme

Theme manifest(callable $callback)

Changes the forum's web app manifest, which phones read when the forum is added to a home screen.

```php (new Extend\Theme()) ->manifest(fn (array $manifest) => ['short_name' => 'Acme'] + $manifest) ```

Parameters

callable $callback Receives the manifest and returns it changed.

Return Value

Theme

void extend( Container $container, Extension|null $extension = null)

Parameters

Container $container
Extension|null $extension

Return Value

void